Indexed Vertices: Because Re-use is Good for You
Up until this point, we have always defined lists of triangles, where each triangle has its own set of vertices. We have actually only ever drawn a single triangle, but adding more would not have been a big deal.
There are cases, however, where two or more triangles can share some vertices. Let's think about how we'd render a rectangle with our current knowledge. We'd simply define two triangles that would have two vertices with the same positions, colors, and texture coordinates. We can do better. Figure 7–14 shows the old way and the new way of rendering a rectangle.
Figure 7–14. Rendering a rectangle as two triangles with six vertices (left), and rendering it with four vertices (right)
Instead of duplicating vertex v1 and v2 with vertex v4 and v6, we only define these vertices once. We still render two triangles in this case, but we tell OpenGL ES explicitly which vertices to use for each triangle (that is, use v1, v2, and v3 for the first triangle and v3, v4, and v1 for the second one)—which vertices to use for each triangle are defined via indices in our vertices array. The first vertex in our array has index 0, the second vertex has index 1, and so on. For the preceding rectangle, we'd have a list of indices like this:
short[] indices = { 0, 1, 2,
2, 3, 0 };
Incidentally, OpenGL ES wants us to specify the indices as shorts (which is not entirely correct; we could also use bytes). However, as with the vertex data, we can't just pass a short array to OpenGL ES. It wants a direct ShortBuffer. We already know how to handle that.
ByteBuffer byteBuffer = ByteBuffer.allocate(indices.length * 2);
byteBuffer.order(ByteOrder.nativeOrder());
ShortBuffer shortBuffer = byteBuffer.asShortBuffer();
shortBuffer.put(indices);
shortBuffer.flip();
A short needs 2 bytes of memory, so we allocate indices.length × 2 bytes for our ShortBuffer. We set the order to native again and get a ShortBuffer view so that we can handle the underlying ByteBuffer more easily. All that's left is putting our indices into the ShortBuffer and flipping it so the limit and position are set correctly.
If we wanted to draw Bob as a rectangle with two indexed triangles, we could define our vertices like this:
ByteBuffer byteBuffer = ByteBuffer.allocateDirect(4 * VERTEX_SIZE);
byteBuffer.order(ByteOrder.nativeOrder());
vertices = byteBuffer.asFloatBuffer();
vertices.put(new float[] { 100.0f, 100.0f, 0.0f, 1.0f,
228.0f, 100.0f, 1.0f, 1.0f,
228.0f, 229.0f, 1.0f, 0.0f,
100.0f, 228.0f, 0.0f, 0.0f });
vertices.flip();
The order of the vertices is exactly the same as in the right part of Figure 7–13. We tell OpenGL ES that we have positions and texture coordinates for our vertices and where it can find these vertex attributes via the usual calls to glEnableClientState() and glVertexPointer()/glTexCoordPointer(). The only difference is the method we call to draw the two triangles.
gl.glDrawElements(GL10.GL_TRIANGLES, 6, GL10.GL_UNSIGNED_SHORT, indices);
This method is actually very similar to glDrawArrays(). The first parameter specifies the type of primitive we want to render—in this case, a list of triangles. The next parameter specifies how many vertices we want to use, which equals six in our case. The third parameter specifies what type the indices have—we specify unsigned short. Note that Java has no unsigned types; however, given the one-complement encoding of signed numbers, it's OK to use a ShortBuffer that actually holds signed shorts. The last parameter is our ShortBuffer holding the six indices.
So, what will OpenGL ES do? It knows that we want to render triangles; it knows that we want to render two triangles, as we specified six vertices; but instead of fetching six vertices sequentially from the vertices array, OpenGL ES goes sequentially through the index buffer and uses the vertices it has indexed.
Putting It Together
When we put it all together, we arrive at the code in Listing 7–9.
Listing 7–9. Excerpt from IndexedTest.java; Drawing Two Indexed Triangles
class IndexedScreen extends Screen {
final int VERTEX_SIZE = (2 + 2) * 4;
GLGraphics glGraphics;
FloatBuffer vertices;
ShortBuffer indices;
Texture texture;
public IndexedScreen(Game game) {
super(game);
glGraphics = ((GLGame) game).getGLGraphics();
ByteBuffer byteBuffer = ByteBuffer.allocateDirect(4 * VERTEX_SIZE);
byteBuffer.order(ByteOrder.nativeOrder());
vertices = byteBuffer.asFloatBuffer();
vertices.put(new float[] { 100.0f, 100.0f, 0.0f, 1.0f,
228.0f, 100.0f, 1.0f, 1.0f,
228.0f, 228.0f, 1.0f, 0.0f,
100.0f, 228.0f, 0.0f, 0.0f });
vertices.flip();
byteBuffer = ByteBuffer.allocateDirect(6 * 2);
byteBuffer.order(ByteOrder.nativeOrder());
indices = byteBuffer.asShortBuffer();
indices.put(new short[] { 0, 1, 2,
2, 3, 0 });
indices.flip();
texture = new Texture((GLGame)game, "bobrgb888.png");
}
@Override
public void present(float deltaTime) {
GL10 gl = glGraphics.getGL();
gl.glViewport(0, 0, glGraphics.getWidth(), glGraphics.getHeight());
gl.glClear(GL10.GL_COLOR_BUFFER_BIT);
gl.glMatrixMode(GL10.GL_PROJECTION);
gl.glLoadIdentity();
gl.glOrthof(0, 320, 0, 480, 1, -1);
gl.glEnable(GL10.GL_TEXTURE_2D);
texture.bind();
gl.glEnableClientState(GL10.GL_TEXTURE_COORD_ARRAY);
gl.glEnableClientState(GL10.GL_VERTEX_ARRAY);
vertices.position(0);
gl.glVertexPointer(2, GL10.GL_FLOAT, VERTEX_SIZE, vertices);
vertices.position(2);
gl.glTexCoordPointer(2, GL10.GL_FLOAT, VERTEX_SIZE, vertices);
gl.glDrawElements(GL10.GL_TRIANGLES, 6, GL10.GL_UNSIGNED_SHORT, indices);
}
Note the use of our awesome Texture class, which brings down the code size considerably. Figure 7–15 shows the output, and Bob in all his glory.
Now, this is pretty close to how we worked with Canvas. We have a lot more flexibility as well, since we are not limited to axis-aligned rectangles anymore.
This example has covered all we need to know about vertices for now. We saw that every vertex must have at least a position, and can have additional attributes, such as a color, given as four RGBA float values and texture coordinates. We also saw that we can reuse vertices via indexing in case we want to avoid duplication. This gives us a little performance boost, since OpenGL ES does not have to multiply more vertices by the projection and model-view matrices than absolutely necessary (which, again, is not entirely correct, but let's stick to this interpretation).
A Vertices Class
Let's make our code easier to write by creating a Vertices class that can hold a maximum number of vertices and, optionally, indices to be used for rendering. It should also take care of enabling all the states needed for rendering, as well as cleaning up the states after rendering has finished, so that other code can rely on a clean set of OpenGL ES states. Listing 7–10 shows our easy–to–use Vertices class.
Listing 7–10.Vertices.java; Encapsulating (Indexed) Vertices
package com.badlogic.androidgames.framework.gl;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.nio.FloatBuffer;
import java.nio.ShortBuffer;
import javax.microedition.khronos.opengles.GL10;
import com.badlogic.androidgames.framework.impl.GLGraphics;
public class Vertices {
final GLGraphics glGraphics;
final boolean hasColor;
final boolean hasTexCoords;
final int vertexSize;
final FloatBuffer vertices;
final ShortBuffer indices;
The Vertices class has a reference to the GLGraphics instance, so we can get ahold of the GL10 instance when we need it. We also store whether the vertices have colors and texture coordinates. This gives us great flexibility as we can choose the minimal set of attributes we need for rendering. Additionally, we store a FloatBuffer that holds our vertices and a ShortBuffer that holds the optional indices.
public Vertices(GLGraphics glGraphics, int maxVertices, int maxIndices, boolean hasColor, boolean hasTexCoords) {
this.glGraphics = glGraphics;
this.hasColor = hasColor;
this.hasTexCoords = hasTexCoords;
this.vertexSize = (2 + (hasColor?4:0) + (hasTexCoords?2:0)) * 4;
ByteBuffer buffer = ByteBuffer.allocateDirect(maxVertices * vertexSize);
buffer.order(ByteOrder.nativeOrder());
vertices = buffer.asFloatBuffer();
if(maxIndices > 0) {
buffer = ByteBuffer.allocateDirect(maxIndices * Short.SIZE / 8);
buffer.order(ByteOrder.nativeOrder());
indices = buffer.asShortBuffer();
} else {
indices = null;
}
}
In the constructor, we specify how many vertices and indices our Vertices instance can hold maximally, as well as whether the vertices have colors or texture coordinates. Inside the constructor, we then set the members accordingly and instantiate the buffers. Note that the ShortBuffer will be set to null if maxIndices is zero. Our rendering will be performed non-indexed in that case.
public void setVertices(float[] vertices, int offset, int length) {
this.vertices.clear();
this.vertices.put(vertices, offset, length);
this.vertices.flip();
}
public void setIndices(short[] indices, int offset, int length) {
this.indices.clear();
this.indices.put(indices, offset, length);
this.indices.flip();
}
Next up are the setVertices() and setIndices() methods. The latter will throw a NullPointerException in case the Vertices instance does not store indices. All we do is clear the buffers and copy the contents of the arrays.
public void draw(int primitiveType, int offset, int numVertices) {
GL10 gl = glGraphics.getGL();
gl.glEnableClientState(GL10.GL_VERTEX_ARRAY);
vertices.position(0);
gl.glVertexPointer(2, GL10.GL_FLOAT, vertexSize, vertices);
if(hasColor) {
gl.glEnableClientState(GL10.GL_COLOR_ARRAY);
vertices.position(2);
gl.glColorPointer(4, GL10.GL_FLOAT, vertexSize, vertices);
}
if(hasTexCoords) {
gl.glEnableClientState(GL10.GL_TEXTURE_COORD_ARRAY);
vertices.position(hasColor?6:2);
gl.glTexCoordPointer(2, GL10.GL_FLOAT, vertexSize, vertices);
}
if(indices!=null) {
indices.position(offset);
gl.glDrawElements(primitiveType, numVertices, GL10.GL_UNSIGNED_SHORT, indices);
} else {
gl.glDrawArrays(primitiveType, offset, numVertices);
}
if(hasTexCoords)
gl.glDisableClientState(GL10.GL_TEXTURE_COORD_ARRAY);
if(hasColor)
gl.glDisableClientState(GL10.GL_COLOR_ARRAY);
}
}
The final method of the Vertices class is draw(). It takes the type of the primitive (for example, GL10.GL_TRIANGLES), the offset into the vertices buffer (or the indices buffer if we use indices), and the number of vertices to use for rendering. Depending on whether the vertices have colors and texture coordinates, we enable the relevant OpenGL ES states and tell OpenGL ES where to find the data. We do the same for the vertex positions, of course, which are always needed. Depending on whether indices are used, we either call glDrawElements() or glDrawArrays() with the parameters passed to the method. Note that the offset parameter can also be used in case of indexed rendering: we simply set the position of the indices buffer accordingly so that OpenGL ES starts reading the indices from that offset instead of the first index of the indices buffer. The last thing we do in the draw() method is clean up the OpenGL ES state a little. We call glDisableClientState() with either GL10.GL_COLOR_ARRAY or GL10.GL_TEXTURE_COORD_ARRAY in case our vertices have these attributes. We need to do this, as another instance of Vertices might not use those attributes. If we rendered that other Vertices instance, OpenGL ES would still look for colors and/or texture coordinates.
We could replace all the tedious code in the constructor of our preceding example with the following snippet:
Vertices vertices = new Vertices(glGraphics, 4, 6, false, true);
vertices.setVertices(new float[] { 100.0f, 100.0f, 0.0f, 1.0f,
228.0f, 100.0f, 1.0f, 1.0f,
228.0f, 228.0f, 1.0f, 0.0f,
100.0f, 228.0f, 0.0f, 0.0f }, 0, 16);
vertices.setIndices(new short[] { 0, 1, 2, 2, 3, 0 }, 0, 6);
Likewise, we could replace all the calls for setting up our vertex attribute arrays and rendering with a single call to the following:
vertices.draw(GL10.GL_TRIANGLES, 0, 6);
Together with our Texture class, we now have a pretty nice basis for all of our 2D OpenGL ES rendering. In order to reproduce all our Canvas rendering abilities completely, however, we are still missing blending. Let's have a look at that.