OpenGL ES Tutorial for Android – Part V – More on Meshes

I have a feeling that some of you have tried my tutorials and then thought "This is a 3D tutorial, but why is everything in 2D?". So in this tutorial we will make some real 3D meshes. This is also necessary for the following tutorials.

When I started I had problems with finding out how to programmatic make different meshes like cubes, cones and so on. I needed this so I easy easy could put my scenes together. So this tutorial will show how to make some of the basic primitives. They might not be the most effective way of creating them but it is a way of doing them.

Starting point will be from the source of the second tutorial. I will show you plane and cube and then give you a couple of hint for additional primitives.

Design

A good place to start when designing an OpenGL framework is to use the composite pattern. This is a start of how I would proceed:

Let's start making out pattern.

Mesh

It's a good idea to have a common base for your meshes. So let us start by creating a class called Mesh.

package se.jayway.opengl.tutorial.mesh;
public class Mesh {
 
}

We add the draw function from previous example, since I when over this function in a previous tutorial I just show it here:

    // Our vertex buffer.
    private FloatBuffer verticesBuffer = null;
 
    // Our index buffer.
    private ShortBuffer indicesBuffer = null;
 
    // The number of indices.
    private int numOfIndices = -1;
 
    // Flat Color
    private float[] rgba = new float[]{1.0f, 1.0f, 1.0f, 1.0f};
 
    // Smooth Colors
    private FloatBuffer colorBuffer = null;
 
    public void draw(GL10 gl) {
        // Counter-clockwise winding.
	gl.glFrontFace(GL10.GL_CCW);
	// Enable face culling.
	gl.glEnable(GL10.GL_CULL_FACE);
	// What faces to remove with the face culling.
	gl.glCullFace(GL10.GL_BACK);
	// Enabled the vertices buffer for writing and to be used during
	// rendering.
	gl.glEnableClientState(GL10.GL_VERTEX_ARRAY);
	// Specifies the location and data format of an array of vertex
	// coordinates to use when rendering.
	gl.glVertexPointer(3, GL10.GL_FLOAT, 0, verticesBuffer);
        // Set flat color
        gl.glColor4f(rgba[0], rgba[1], rgba[2], rgba[3]);
        // Smooth color
        if ( colorBuffer != null ) {
            // Enable the color array buffer to be used during rendering.
            gl.glEnableClientState(GL10.GL_COLOR_ARRAY);
            // Point out the where the color buffer is.
            gl.glColorPointer(4, GL10.GL_FLOAT, 0, colorBuffer);
        }
	gl.glDrawElements(GL10.GL_TRIANGLES, numOfIndices,
		GL10.GL_UNSIGNED_SHORT, indicesBuffer);
	// Disable the vertices buffer.
	gl.glDisableClientState(GL10.GL_VERTEX_ARRAY);
	// Disable face culling.
	gl.glDisable(GL10.GL_CULL_FACE);
    }

We need functions where the subclasses can set the vertices and the indices. These function contains nothing new and are pretty much the same as you seen in earlier tutorials.

    protected void setVertices(float[] vertices) {
	// a float is 4 bytes, therefore we multiply the number if
	// vertices with 4.
	ByteBuffer vbb = ByteBuffer.allocateDirect(vertices.length * 4);
	vbb.order(ByteOrder.nativeOrder());
	verticesBuffer = vbb.asFloatBuffer();
	verticesBuffer.put(vertices);
	verticesBuffer.position(0);
    }
 
    protected void setIndices(short[] indices) {
	// short is 2 bytes, therefore we multiply the number if
	// vertices with 2.
	ByteBuffer ibb = ByteBuffer.allocateDirect(indices.length * 2);
	ibb.order(ByteOrder.nativeOrder());
	indicesBuffer = ibb.asShortBuffer();
	indicesBuffer.put(indices);
	indicesBuffer.position(0);
	numOfIndices = indices.length;
    }
 
    protected void setColor(float red, float green, float blue, float alpha) {
        // Setting the flat color.
        rgba[0] = red;
        rgba[1] = green;
        rgba[2] = blue;
        rgba[3] = alpha;
    }
 
    protected void setColors(float[] colors) {
	// float has 4 bytes.
	ByteBuffer cbb = ByteBuffer.allocateDirect(colors.length * 4);
	cbb.order(ByteOrder.nativeOrder());
	colorBuffer = cbb.asFloatBuffer();
	colorBuffer.put(colors);
	colorBuffer.position(0);
    }

We need to add a couple of things. When we start working with multiple meshes we need to be able to move and rotate them individual so let us add translation and rotation parameters:

    // Translate params.
    public float x = 0;
    public float y = 0;
    public float z = 0;
 
    // Rotate params.
    public float rx = 0;
    public float ry = 0;
    public float rz = 0;

And use them in the draw function add this lines just before the gl.glDrawElements call.

    gl.glTranslatef(x, y, z);
    gl.glRotatef(rx, 1, 0, 0);
    gl.glRotatef(ry, 0, 1, 0);
    gl.glRotatef(rz, 0, 0, 1);

Plane

Let us start making a plane an quite easy task you might think and it kinda is. But to make it more interesting and more useful we need to be able to create it with some different settings like: width, depth, how many width segments and how many depth segments.

Just so we have the same terminology, width is the length over the x-axis, depth is over the z-axis and height is over the y-axis. Look at the image below as a visual input.

Segments is how many parts the length should be divided by. This is useful if you need to make a surface that is not total even. If you create a plane over x, y and make z not all be 0 say you give z a random span from -0.1 to 0.1 you will get something you could use as a ground plane in a game just put a nice texture on it.

Looking at the image above you see that the different segments gives you squares. Since we like it to be triangles so just split them up into 2 triangles.

I hate frameworks and classes that don't have a default setup and easy class constructors I try to always have more then one constructor. The constructors I will put in this plane is:

For an easy and quick setup:

// Gives you a plane that is 1 unit wide and 1 unit high with just one segment over width and height.
public Plane()

An easy one just to change the size:

 // Let you decide the size of the plane but still only one segment.
public Plane(float width, float height)

And finally one for setting up the plane with different segments:

// For alla your settings.
public Plane(float width, float height, int widthSegments, int heightSegments)

If I in theory would construct a plane that is 1 unit wide and 1 units high with 4 segments in both width and height direction it would look like this images:

The one to the left shows the segments and the one to the right show us the faces we need to create.

package se.jayway.opengl.tutorial.mesh;
 
public class Plane extends Mesh {
 
    public Plane() {
	this(1, 1, 1, 1);
    }
 
    public Plane(float width, float height) {
	this(width, height, 1, 1);
    }
 
    public Plane(float width, float height, int widthSegments,
		int heightSegments) {
	float[] vertices = new float[(widthSegments + 1) * (heightSegments + 1)
			* 3];
	short[] indices = new short[(widthSegments + 1) * (heightSegments + 1)
			* 6];
 
	float xOffset = width / -2;
	float yOffset = height / -2;
	float xWidth = width / (widthSegments);
	float yHeight = height / (heightSegments);
	int currentVertex = 0;
	int currentIndex = 0;
	short w = (short) (widthSegments + 1);
	for (int y = 0; y < heightSegments + 1; y++) {
            for (int x = 0; x < widthSegments + 1; x++) {
	        vertices[currentVertex] = xOffset + x * xWidth;
		vertices[currentVertex + 1] = yOffset + y * yHeight;
		vertices[currentVertex + 2] = 0;
		currentVertex += 3;
 
		int n = y * (widthSegments + 1) + x;
 
		if (y < heightSegments && x < widthSegments) {
		    // Face one
		    indices[currentIndex] = (short) n;
		    indices[currentIndex + 1] = (short) (n + 1);
		    indices[currentIndex + 2] = (short) (n + w);
		    // Face two
		    indices[currentIndex + 3] = (short) (n + 1);
		    indices[currentIndex + 4] = (short) (n + 1 + w);
		    indices[currentIndex + 5] = (short) (n + 1 + w - 1);
 
		    currentIndex += 6;
		}
	    }
	}
 
	setIndices(indices);
	setVertices(vertices);
    }
}

Cube

The next step I think a cube will be nice. I will only make a cube that you can set: height, width and depth on but I suggest you as a practice make it with segments just as we did with the plane.

The constructor will look like this:

public Cube(float width, float height, float depth)

And since I'm not doing this with any segments the constructor will be quite easy.

package se.jayway.opengl.tutorial.mesh;
 
public class Cube extends Mesh {
    public Cube(float width, float height, float depth) {
        width  /= 2;
        height /= 2;
        depth  /= 2;
 
        float vertices[] = { -width, -height, -depth, // 0
                              width, -height, -depth, // 1
                              width,  height, -depth, // 2
                             -width,  height, -depth, // 3
                             -width, -height,  depth, // 4
                              width, -height,  depth, // 5
                              width,  height,  depth, // 6
                             -width,  height,  depth, // 7
        };
 
        short indices[] = { 0, 4, 5,
                            0, 5, 1,
                            1, 5, 6,
                            1, 6, 2,
                            2, 6, 7,
                            2, 7, 3,
                            3, 7, 4,
                            3, 4, 0,
                            4, 7, 6,
                            4, 6, 5,
                            3, 0, 1,
                            3, 1, 2, };
 
        setIndices(indices);
        setVertices(vertices);
    }
}

If you like to make it with segments the constructor could look like this:

public Cube(float width, float height, float depth,
                 int widthSegments, int heightSegments, int depthSegments)

Since we now have a plane that replaces the Square class ( in the code from tutorial II ) I will just remove it and in OpenGLRenderer change the square to a cube...

public OpenGLRenderer() {
    // Initialize our cube.
    cube = new Cube(1, 1, 1);
    cube.rx = 45;
    cube.ry = 45;
}

... and render it.

public void onDrawFrame(GL10 gl) {
    ...
    // Draw our cube.
    cube.draw(gl);
}

Group

A group is really good to have when setting up and controlling your 3D scene. What a group really do is to distribute all commands sent to the group to all it's children. You can see the implementation of a simple group here:

package se.jayway.opengl.tutorial.mesh;
 
import java.util.Vector;
 
import javax.microedition.khronos.opengles.GL10;
 
public class Group extends Mesh {
    private Vector<Mesh> children = new Vector<Mesh>();
 
    @Override
    public void draw(GL10 gl) {
        int size = children.size();
        for( int i = 0; i < size; i++)
            children.get(i).draw(gl);
    }
 
    public void add(int location, Mesh object) {
        children.add(location, object);
    }
 
    public boolean add(Mesh object) {
        return children.add(object);
    }
 
    public void clear() {
        children.clear();
    }
 
    public Mesh get(int location) {
        return children.get(location);
    }
 
    public Mesh remove(int location) {
        return children.remove(location);
    }
 
    public boolean remove(Object object) {
        return children.remove(object);
    }
 
    public int size() {
        return children.size();
    }
}

Make the renderer work with a group as a root node and add your cube to it.

Group group = new Group();
Cube cube = new Cube(1, 1, 1);
cube.rx = 45;
cube.ry = 45;
group.add(cube);
root = group;

And draw our scene:

public void onDrawFrame(GL10 gl) {
    ...
    // Draw our scene.
    root.draw(gl);
}

Suggestions

It's always a good idea to have different primitives ready to use when you starting up a new project. My experience tell me that in 9 times of 10 you won't have any meshes from the graphic people when you start coding so it's really good to have some meshes to work with as place holders. I'll give you a hint of the way to start with your own meshes library by giving you an idea of how I would do it.

Creating your own meshes is a really good way of getting to know vertices and indices really close up.

Cone

After you have gotten your cube up and ready to go my suggestion is that you move onto a cone. A cone with the right settings could be more then just a cone. if you give is 3-4 sides it will be a pyramid. If you give it the same base and top radius it becomes a cylinder. So you can see why it is so useful. Take a look at this image and see what the this cone can do.

public Cone(float baseRadius, float topRadius, float height, int numberOfSides)

Pyramid

public class Pyramid extends Cone {
    public Pyramid(float baseRadius, float height)  {
        super(baseRadius, 0, height, 4);
    }
}

Cylinder

public class Cylinder extends Cone {
    public Cylinder(float radius, float height)  {
        super(radius, radius, height, 16);
    }
}

One more thing

Dividing up surfaces is a good thing to know about and by now you know how to divide up a regular square. To divide up a triangle look at the images below. It is a bit different and it might be a bit harder to implement.

References

The info used in this tutorial is collected from:
Android Developers
OpenGL ES 1.1 Reference Pages

You can download the source for this tutorial here: Tutorial_Part_V

Previous tutorial: OpenGL ES Tutorial for Android – Part IV – Adding colors
Next tutorial:

Per-Erik Bergman
Consultant at Jayway