Updated to be Android 2.0.1 compatible.
The first part of this series will give you a short introduction to the OpenGL terminology and the first step in your 3D programming.
The series itself will be about a 3D game called Vortex.
The tutorial will focus on 3D programming, stuff like menu or life cycle may be part of the code but will not be introduced.
Lets start with the terminology of OpenGL.

Vertex
A vertex is a point in 3D space and is the building block for many objects. In OpenGL you can specify as few as two coordinates (X,Y) and as many as four (X,Y,Z,W). The w-axis is optional, the default value is set to 1.0. The z-axis is also optional, the default value is set to 0. In this series, we will use the three main coordinates X, Y, and Z, since the W is generally used as a placeholder. The plural of vertex is vertices (mainly important for non native speakers, because it may create confusion). All objects are drawn using vertices as their points, so a point will refer to a vertex.
Triangle
A triangle requires three points to be created. So in OpenGL, we use three vertices to create one.
Polygon
A polygon is an object which has at least three connected points. Therefor a triangle is also a polygon.
Primitives
A primitive is a three-dimensional object created using either triangles or polygons. A bit ironic: A detailed model with 50.000 vertices is also a primitive like a low detailed model with 500 vertices.
Now we can start with the programming.
We create a new project called Vortex, our activity will be named so, too.
Our activity will look familiar:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

package com.droidnova.android.games.vortex;
 
import android.app.Activity;
import android.os.Bundle;
 
public class Vortex extends Activity {
    private static final String LOG_TAG = Vortex.class.getSimpleName();
    private VortexView _vortexView;
 
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        _vortexView = new VortexView(this);
        setContentView(_vortexView);
    }
}
As you see, we already added our own view. Lets take a look right on our VortexView class.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package com.droidnova.android.games.vortex;
 
import android.content.Context;
import android.opengl.GLSurfaceView;
 
public class VortexView extends GLSurfaceView {
    private static final String LOG_TAG = VortexView.class.getSimpleName();
    private VortexRenderer _renderer;
 
    public VortexView(Context context) {
        super(context);
        _renderer = new VortexRenderer();
        setRenderer(_renderer);
    }
}
As you see, we inherit GLSurfaceView because it will help us manage the drawing. The next thing you should see is our VortexRenderer class.
A renderer has the task to perform anything thats needed to draw a frame. Quote fromreferences:
The renderer is responsible for making OpenGL calls to render a frame.
So lets take a look at this class:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

package com.droidnova.android.games.vortex;
 
import javax.microedition.khronos.egl.EGLConfig;
import javax.microedition.khronos.opengles.GL10;
 
import android.opengl.GLSurfaceView;
 
public class VortexRenderer implements GLSurfaceView.Renderer {
    private static final String LOG_TAG = VortexRenderer.class.getSimpleName();
 
    private float _red = 0.9f;
    private float _green = 0.2f;
    private float _blue = 0.2f;
 
    @Override
    public void onSurfaceCreated(GL10 gl, EGLConfig config) {
        // Do nothing special.
    }
 
    @Override
    public void onSurfaceChanged(GL10 gl, int w, int h) {
        gl.glViewport(0, 0, w, h);
    }
 
    @Override
    public void onDrawFrame(GL10 gl) {
        // define the color we want to be displayed as the "clipping wall"
        gl.glClearColor(_red, _green, _blue, 1.0f);
        // clear the color buffer to show the ClearColor we called above...
        gl.glClear(GL10.GL_COLOR_BUFFER_BIT);
    }
}
Ok what do we have here?
First we implemented the interface GLSurfaceView.Renderer which forces us to implement 3 methods calles onSurfaceCreated(), onSurfaceChanged() and onDrawFrame().
These methods are easily to understand, the first one is called after the surface was created, the second if the surface changed, e.g. you switch from portrait to landscape and the last one anytime a drawing is requested.
From line 11 to 13 we have floats defining each color of the RGB color system.
On line 28 we define the the color of our “clipping wall” with the method glClearColor(). The “clipping wall” covers everything that is behind the distance we can see, so every object behind this “wall” is invisible. Imagine the wall as something like fog. Later we will set the distance to show how it works. At the moment it is absolutely sufficient that you know it exists.
To make our color changes visible, we have to call glClear() with the mask for the color buffer to clear the buffer and use the new color for our “clipping wall”.
To see that it is working, we will create a response to a MotionEvent which changes the color we set.
First lets create a set for the color in our VortexRenderer class:
1
2
3
4
5

public void setColor(float r, float g, float b) {
    _red = r;
    _green = g;
    _blue = b;
}
Now the method in our VortexView class to handle the MotionEvent:
1
2
3
4
5
6
7
8

public boolean onTouchEvent(final MotionEvent event) {
    queueEvent(new Runnable() {
        public void run() {
            _renderer.setColor(event.getX() / getWidth(), event.getY() / getHeight(), 1.0f);
        }
    });
    return true;
}
We create a new anonymous object of Runnable where the run() method call the setColor() method of the renderer with a bit of calculation depending on the MotionEvent coordinates.
We now have a little app which uses OpenGL to change the background color :)
In Germany we say in this case “Mit Kanonen auf Spatzen schießen”, you would say “He breaks a fly on the wheel.”. Thats absolute correct but it is the minimalistic example of working with OpenGL and you are now prepared for more!
The last hint in this part is a documentation for OpenGL. The usability is nonexistent but at least it is a documentation.
Sources as Eclipse project: Vortex Part I
Screenshots:
3d-part-one-turquoise3d-part-one-purple3d-part-one-blue






You are new to this series? Please start with the first part.
The second part of this series will show you how to add a triangle and how to rotate it a bit.
The first thing we have to do is to initialize the triangle we want to display. We have to create a function named initTriangle() in our VortexRenderer class.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// new object variables we need
// a raw buffer to hold indices
private ShortBuffer _indexBuffer;
 
// a raw buffer to hold the vertices
private FloatBuffer _vertexBuffer;
 
private short[] _indicesArray = {0, 1, 2};
private int _nrOfVertices = 3;
 
// code snipped
 
private void initTriangle() {
    // float has 4 bytes
    ByteBuffer vbb = ByteBuffer.allocateDirect(_nrOfVertices * 3 * 4);
    vbb.order(ByteOrder.nativeOrder());
    _vertexBuffer = vbb.asFloatBuffer();
 
    // short has 2 bytes
    ByteBuffer ibb = ByteBuffer.allocateDirect(_nrOfVertices * 2);
    ibb.order(ByteOrder.nativeOrder());
    _indexBuffer = ibb.asShortBuffer();
 
    float[] coords = {
        -0.5f, -0.5f, 0f, // (x1, y1, z1)
        0.5f, -0.5f, 0f, // (x2, y2, z2)
        0f, 0.5f, 0f // (x3, y3, z3)
    };
 
    _vertexBuffer.put(coords);
    _indexBuffer.put(_indicesArray);
 
    _vertexBuffer.position(0);
    _indexBuffer.position(0);
}

Lets start with the new object variables. The _vertexBuffer will be filled with the coordinates for our triangle. The _indexBuffer stores the indices. The variable _nrOfVertices defines how many vertices are required. For a triangle we have three vertices.
The method itself allocate the needed memory for both buffer (line 14 – 22). Than we define some coordinates (line 24 – 28) and the comments behind each row explains you, how you can read the coordinates.
In line 30 we fill the _vertexBuffer with the coordinates stored on the coords array. The same with the indices array and the _indexBuffer on line 31. Finally we set both buffer to position 0.
To prevent the initialization of the triangle for every frame, we just do it once in a function that will be called before onDrawFrame(). On choice could be the method onSurfaceCreated().
1
2
3
4
5
6

@Override
public void onSurfaceCreated(GL10 gl, EGLConfig config) {
    // preparation
    gl.glEnableClientState(GL10.GL_VERTEX_ARRAY);
    initTriangle();
}
glEnableClientState() set OpenGL to use vertex arrays to draw. Thats important to enable because otherwise OpenGL don’t know how to handle our data. Than we will initialize our triangle.
Why do we have to work with different buffers? Lets take a look at the new onDrawFrame() method where we have to add some new OpenGL calls.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

@Override
public void onDrawFrame(GL10 gl) {
    // define the color we want to be displayed as the "clipping wall"
    gl.glClearColor(_red, _green, _blue, 1.0f);
 
    // clear the color buffer to show the ClearColor we called above...
    gl.glClear(GL10.GL_COLOR_BUFFER_BIT);
 
    // set the color of our element
    gl.glColor4f(0.5f, 0f, 0f, 0.5f);
 
    // define the vertices we want to draw
    gl.glVertexPointer(3, GL10.GL_FLOAT, 0, _vertexBuffer);
 
    // finally draw the vertices
    gl.glDrawElements(GL10.GL_TRIANGLES, _nrOfVertices, GL10.GL_UNSIGNED_SHORT, _indexBuffer);
}
Ok now step for step:
glClearColor() and glClear() should be known by the first part of the series.
On line 10 we set the color for our triangle to a darker red using glColor4f(red, green, blue, alpha).
On line 13 we initialize the vertex pointer using glVertexPointer(). The first parameter is for the size, also known as dimension of our vertices. Are we using just x and y or also z? We use all three dimensions. The second parameter, GL_FLOAT, defines the data type used in the buffer. The third parameter is 0 because our coordinates are tightly packed in the array, no offset used. And finally the fourth parameter is the buffer in which we have our vertices stored.
The last call, glDrawElements(), will draw the elements. First parameter defines what kind of primitives have to rendered. The second element defines the number of elements and the third parameter the type of the values used for the indices. The last one is the index buffer which will be used to render the vertices.
When you finally test the application, you will see a static triangle in the middle of your screen. The change of the color of your background should still work if you touch the screen.
Lets add some rotation to the triangle. The following code must be implemented in our VortexRenderer class.
1
2
3
4
5

private float _angle;
 
public void setAngle(float angle) {
    _angle = angle;
}
The glRotatef() method will be called in our onDrawFrame() right above glColor4f().
1
2
3
4
5
6
7
8

@Override
public void onDrawFrame(GL10 gl) {
    // set rotation
    gl.glRotatef(_angle, 0f, 1f, 0f);
 
    gl.glColor4f(0.5f, 0f, 0f, 0.5f);
    // code snipped
}
We rotate at the moment just around the y-axis. If you want to change this, simply change the 0f of the glRotatef() method call. The value of this parameter are for a vector which represent the axis on which the triangle will rotate.
To make this work, we have to add a call to the onTouchEvent() method in our VortexView class.
1
2
3
4
5
6
7
8
9

public boolean onTouchEvent(final MotionEvent event) {
    queueEvent(new Runnable() {
        public void run() {
            _renderer.setColor(event.getX() / getWidth(), event.getY() / getHeight(), 1.0f);
            _renderer.setAngle(event.getX() / 10);
        }
    });
    return true;
}
The division through 10 is to reduce the speed of angle changing.
Now compile and run the application. If you touch the screen at the most left side, you should see the triangle rotate slightly. If you move your finger to the right, the speed of the rotation should increase dramatically.
Source as Eclipse project: Vortex Part II
3d-part-two-triangle3d-part-two-triangle13d-part-two-triangle2