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.

Width, height and depth.

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.

Segments.

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:

I soon came to understand that I would not be able to take advantage of all the wonderful possibilities that instrumentation offers. The reason for that is quite simple; the application that we are in the process of developing is not only extensive but also complicated with multiple activities, self-defined intents, and hundreds of views that also include scrollable lists. It would not make sense for me to spend a month writing one single test case that would only take 20 seconds to test manually. That is how Robotium-Solo was born. I needed a test framework that would help me write good and powerful test cases that emulated real users. The test case should be able to do what a real user does: click on anything that is clickable, look for irregularities, automatically move from activity to activity, etc. More importantly, I should not have to spend more than 10 minutes writing a test case that involves more then one activity.

With the help of Robotium-Solo a test case spanning over multiple activities could look like this:

public void testTextIsSaved() throws Exception {
   solo.clickOnText("Other");
   solo.clickOnButton("Edit");
   assertTrue(solo.searchText("Edit Window"));
   solo.enterText(0, "Some text for testing purposes")
   solo.clickOnButton("Save");
   assertTrue(solo.searchText("Changes have been made successfully"));
   solo.clickOnButton("Ok");
   assertTrue(solo.searchText("Some text for testing purposes"));
}

As you can see, I don’t have to specify any technical details or tell Robotium-Solo where to look for something, such as scrolling down a list when needed. It handles the above and more all on its own.

If you are interested in writing test cases of similar nature have a look at http://www.robotium.org. It makes writing powerful test cases a breeze.

There's a few reasons when to use JNI in a Java program

• Wrap lower level functionality - Classes in the Android Application Framework uses JNI to interface with the underlying platform and hardware like Camera, Sensors and GPS.
• Interface native legacy code - You might have some old legacy code written in C/C++ and you don't want to waste your time porting the code to Java. With JNI you can create an interface class in Java that exposes the functionality of your legacy code.
• Bypass performance bottlenecks - Execute heavy number crunching in native code and get rid of the overhead that the instruction interpretation in the JVM introduces.

On Android, in order to prevent fragmentation, we are only allowed to use the following libraries in our native code.

• libc (C library) headers
• libm (math library) headers
• JNI interface headers
• libz (Zlib compression) headers
• liblog (Android logging) header
• OpenGL ES 1.1 (3D graphics library) headers (since 1.6)
• A Minimal set of headers for C++ support

In this blog I will demonstrate how to transform a time consuming Java method with a lot of number crunching into a native declared method where the real work is performed in native code. Here's the time consuming Java method

public double compare(int[] sourceData,int[] targetData, double targetError) {
  double error = 0.0D;
  for (int index = 0; index < targetData.length; index++) {
    int c1 = sourceData[index];
    int c2 = targetData[index];
    int b = (c1 >> 16 & 255) - (c2 >> 16 & 255);
    int g = (c1 >> 8 & 255) - (c2 >> 8 & 255);
    int r = (c1 & 255) - (c2 & 255);
    error += r * r + g * g + b * b;
    if (error > targetError)
      return error;
  }
  return error;
}

The sourceData and targetData arguments represents the pixels of two Bitmaps. In short the method calculates the sum of the square distance in color between two images, pixel by pixel. If we compare two 200x200 pixels images the for-loop will run 40000 times! This is a typical candidate for when to use JNI.

What to do in Native

You can use the boilerplate.c file as boilerplate code for all your native c functions.

Implement the native function

This is what the function will look like when written in C.

static jdouble compareNative(JNIEnv *env, jobject thiz, jintArray sourceArr,
                                                jintArray targetArr, jdouble targetError){
  jdouble error = 0.0;
  int index, c1, c2, b, g, r  = 0;
  jint *sarr, *tarr;

  sarr = (*env)->GetIntArrayElements(env, sourceArr, NULL);
  tarr = (*env)->GetIntArrayElements(env, targetArr, NULL);

  if (sarr == NULL || tarr == NULL) {
         return targetError; /* exception occurred */
  }

  int size = (*env)->GetArrayLength(env, sourceArr);

  for (index = 0; index < size; index++) {
    c1 = sarr[index];
    c2 = tarr[index];
    b = (c1 >> 16 & 255) - (c2 >> 16 & 255);
    g = (c1 >> 8 & 255) - (c2 >> 8 & 255);
    r = (c1 & 255) - (c2 & 255);
    error += r * r + g * g + b * b;
    if (error > targetError){
      (*env)->ReleaseIntArrayElements(env, sourceArr, sarr, 0);
      (*env)->ReleaseIntArrayElements(env, targetArr, tarr, 0);
      return error;
    }
  }
 (*env)->ReleaseIntArrayElements(env, sourceArr, sarr, 0);
 (*env)->ReleaseIntArrayElements(env, targetArr, tarr, 0);
 return error;
}

All native functions must have the JNIEnv (a reference to the virtual machine itself) and the jobject (a reference to the "this pointer" of the Java object where the native method call comes from) as the first two arguments. Then we can add our own arguments. For more information on how to write native code for JNI see the JNI Reference Documentation.

Register your native functions

We need a way to make the virtual machine direct the calls to the native declared Java method to our native C function. This is done using the registerNatives function of the JNIEnv. If you use the boilerplate C code from above you only have to do two things.

1. Set the classpath variable to the full class name of your Java class (including package name). Replace the dots with slashes.
2. For each native declared method in Java, insert a JNINativeMethod struct into the methods[] array.

For our example it will look like this

static const char *classPathName = "com/jayway/MyComparator";

static JNINativeMethod methods[] = {
  // nameOfNativeMethod, methodSignature, methodPointer
  {"compare", "([I[ID)D", (void*)compareNative },
};

The first parameter is the name of the native declared Java method, the second is the signature of the native declared Java method and the last parameter is the function pointer to the C function to execute when the native declared Java function is executed.

The signature of a Java method can be determined using the javap tool from SUN's Java SDK or you can create it yourself using the following table, Java VM Type Signatures.

Build using Android NDK

To make things really simple when developing JNI code Google has released the Android Native Development Kit (NDK). It's easy to setup and use. Just setup a new project according to the NDK documentation and build your project. The resulting libs folder should be included into your Android project.

What to do in Java

In order to transform our Java method into a native declared method simply add the word native in the method signature and remove the implementation of the method.

 
public native double compare(int[] sourceData, int[] targetData,
			double targetError);
 

To make sure that the virtual machine loads our library into memory and register our native functions we have to add the following code.

static{
  System.loadLibrary("comparejni");
}

This tells the virtual machine to load the library libcomparejni.so from the underlying operating system. The OnLoad function is executed on the library and our native functions gets registered with the virtual machine.

The Result

After some simple benchmarking I found that the native declared method executed about 2-3 times faster than the original method executing within Dalvik. For larger images the improvement might be even bigger since a call to a native declared method takes more time than calling a normal Java method. Eventually, when Dalvik supports JIT compilation, we would probably get the above performance boost for free without calling native functions. But bear in mind, most devices on the market today will never get an upgraded Dalvik with JIT.

Dependency injection and early validation is crucial for an enterprise application, and Spring is a boon in this regard. But do not fool yourself, Spring is good, but it is not a universal cure. Especially not in mobile space where startup times, low memory consumption, and avoiding interfaces are virtues.

The bottleneck in an enterprise application is most probably the database, spending a few extra milliseconds here and there seldom matters. On much less performant mobile device those clock cycles are not only time the user has to spend waiting, it will drain the battery. A simple thing as using an interface instead of an abstract superclass will perform at least twice as slow. Even passing an extra argument in the constructors a few nestings deep will have an impact.

Lazy Singeltons by Choice

Class loading in Java is lazy, the Java VM will not load classes until they are referenced. Odds are that the user will not trigger a full coverage of all classes in your app for a short time running mobile app. If the user just checks for incoming messages and quits, then every class involved in composing messages do not need to be loaded. Early dependency injection breaks this, as all classes will be referenced at startup. Most components will be initialized in vain, as they are never actually used.

So what we should do in mobile application is to work more like the Java VM, and less like Spring. If possible do not create a component until it is requested. The best way to do this is using a singleton pattern. Not a normal enforced singleton pattern, but rather a singleton by choice. Let the constructor be public, trust your users, and name the getter getSharedFoo(), not getInstance(). Let me show you using a example of an URL cache component:

public class URLCache {
  private static URLCache sharedCache;

  public static URLCache getSharedURLCache() {
    synchronized (URLCache.class) {
      if (sharedCache == null) {
        sharedCache = new URLCache();
      }
    }
    return sharedCache;
  }

  public URLCache() {
    // More code...
  }
  // Allot more code here...

}

Using this shared URL cache component from our imaginary HTTP provider would then be super easy, but not mandatory:

public class HTTPProvider {

  public InputStream inputStreamForURL(String url) {
    URLCache cache = URLCache.getSharedURLCache();
    // Use the cache...
  }

}

The big win here is that if the code path of this run of the application never tries to open an input stream then the URL cache never has to be created. Saving several hundred milliseconds of reading cache indexes, validation, etc.

But What About Testing?

Are not singletons bad for unit tests and mocking components? They used to be. These days we have PowerMock, you really should use it. Turns out that not even PowerMock is really required, if we just change our singleton pattern very slightly, and allows the outside to set the shared component as well:

public class URLCache {
  private static URLCache sharedCache;

  public static void setSharedURLCache(URLCache cache) {
    synchronized (URLCache.class) {
      sharedCache = cache;
    }
  }

  public static URLCache getSharedURLCache() {
    synchronized (URLCache.class) {
      if (sharedCache == null) {
        sharedCache = new URLCache();
      }
    }
    return sharedCache;
  }

  // Allot more code here...

}

This small addition allows us for setup up our own mock cache in the setup of our unit tests. With something as simple as this:

public class SomeTest extends TestCase {

  public void setUp() {
    URLCache.setSharedURLCache(new NoOpURLCache());
  }

  public void testRemoteResource() {
    assertNotNull(HTTPProvider.getSharedHTTPProvider().inputStreamForURL(TEST_URL));
  }
}

It also allows us for explicitly override a singleton if our application has special needs, perhaps a more aggressive cache on a low bandwidth mobile data connection, or special implementation on a buggy Java ME platform. But most importantly for the normal case it will not waste time creating the component until it is actually needed, vastly improving the user experience for your mobile users.

Take Aways

Do not fear singletons, it is a great way of lazy creations that will greatly improve startup times and memory consumption on mobile applications.

Avoid using interfaces, they are at least twice as slow as classes, and can not have static methods for acquiring the lazy created components.

Do not enforce the singleton pattern, always use singleton by choice. To allow for testing and easy implementation of special cases.

Adding color

3D models with no colors are pretty boring so let's add some color to it. In general colors need no explanation. OpenGL ES uses a color model called RGBA ( Red, Green, Blue and Alpha ). The first three are self explained. The fourth is transparency, how solid the color should be. If you like to read more about colors go to: RGB color model - Wikipedia, the free encyclopedia

You might be familiar with defining colors with hex (#FF00FF) or with decimals (255, 0, 255) we will use 0..1 where 0 map to 0 (#00) and 1 map against 255 (#FF).

The easiest way of coloring meshes is called vertex coloring and I am going to show you two different ways of doing that. Flat coloring that gives one solid color and smooth coloring that will blend colors specified for each vertex. Texturing is also a way of giving your mesh colors but it is not vertex coloring so I will show you how to do that in a later tutorial.

Flat coloring

Flat coloring is really easy just tell OpenGL ES what color to use when it is going to render. One thing to remember is that when you set the color OpenGL ES uses this color until you change the color. This means that if you have two different squares and you tell OpenGL ES to change the color right before the second square the first frame the two squares will have different color but the next rendered frame both squares will have the same color.

To tell OpenGL ES what color to work with you use this command:

public abstract void glColor4f(float red, float green, float blue, float alpha)

The default values are: red = 1, green = 1, blue = 1 and alpha = 1. Those values are white, and that's why all the squares we previous made has a white color.

Create a new class called FlatColoredSquare it should be identical to the Square class. Then in the FlatColoredSquare function draw, add this line:

gl.glColor4f(0.5f, 0.5f, 1.0f, 1.0f); // 0x8080FFFF

I usually add a comment like the one above ( // 0x8080FFFF ) because I am used to read that. It makes it easier for me when reviewing the code.

It should now look like this:

public void draw(GL10 gl) {
        gl.glColor4f(0.5f, 0.5f, 1.0f, 1.0f);
        ...

Then change in the renderer so it uses the FlatColoredSquare instead of the Square.

public class OpenGLRenderer implements Renderer {
	private FlatColoredSquare flatSquare; // CHANGED

	public OpenGLRenderer() {
		// Initialize our square.
		flatSquare = new FlatColoredSquare(); // CHANGED
	}

        public void onDrawFrame(GL10 gl) {
                ...
		flatSquare.draw(gl); // Don't forget to change this one.
                ...
	}

Remember that anything rendered after you set a color uses the same color and that this spans over frames and will not be reset in-between.

If you compile and run the application you will see one big flat colored blue square.

Just to give place to the smooth colored square coming up we move the flat square up.

public void onDrawFrame(GL10 gl) {
	gl.glLoadIdentity();
	// Translates 7 units into the screen and 1.5 units up.
	gl.glTranslatef(0, 1.5f, -7);
        // Draw our flat square.
	flatSquare.draw(gl);
}

Notice that with flat coloring you don't need to tell OpenGL ES to turn it on or off. OpenGL ES uses flat coloring as a default way of coloring the meshes.

Smooth coloring

Smooth coloring is gained when you give each vertex its own color. OpenGL ES will interpolate the colors between the vertices and you will gain a smooth coloring effect. Just as with the flat coloring you tell OpenGL ES what to work with and it will be used as long as you don't say anything else.

Create a new class called SmoothColoredSquare it should be identical to the Square class just as you did with the FlatColoredSquare. Modify the new class with this:

Define the colors you like your vertices to have.

public class SmoothColoredSquare {
        ...
        // The colors mapped to the vertices.
        float[] colors = {
                1f, 0f, 0f, 1f, // vertex 0 red
                0f, 1f, 0f, 1f, // vertex 1 green
                0f, 0f, 1f, 1f, // vertex 2 blue
                1f, 0f, 1f, 1f, // vertex 3 magenta
        };
        ...

The order of defining the colors are important since they map against the vertices so in this example above the first color (1f, 0f, 0f, 1f ) map against the top left vertex ( -1.0f, 1.0f, 0.0f ) the green against the bottom left vertex and the rest you can figure out. Hint: Look at the image above.

And put them in a buffer just as we did with the vertices and indices.

public SmoothColoredSquare() {
	...

	// float has 4 bytes, colors (RGBA) * 4 bytes
	ByteBuffer cbb = ByteBuffer.allocateDirect(colors.length * 4);
	cbb.order(ByteOrder.nativeOrder());
	colorBuffer = cbb.asFloatBuffer();
	colorBuffer.put(colors);
	colorBuffer.position(0);
	}

Don't forget to add colorBuffer as a variable to the class as well.

        // Our color buffer.
	private FloatBuffer colorBuffer;

We also need to enable the color buffer and tell openGL where it is.

public void draw(GL10 gl) {
        ...
	gl.glVertexPointer(3, GL10.GL_FLOAT, 0, vertexBuffer);

	// Enable the color array buffer to be used during rendering.
	gl.glEnableClientState(GL10.GL_COLOR_ARRAY); // NEW LINE ADDED.
	// Point out the where the color buffer is.
	gl.glColorPointer(4, GL10.GL_FLOAT, 0, colorBuffer); // NEW LINE ADDED.

	gl.glDrawElements(GL10.GL_TRIANGLES, indices.length,
				GL10.GL_UNSIGNED_SHORT, indexBuffer);
	...
        // Disable the color buffer.
	gl.glDisableClientState(GL10.GL_COLOR_ARRAY);
        ...
	}

Don't forget to disable the use of the color array. If you don't disable the color array both squares will be smooth colored. Try it.

Let's use this new smooth square as well. Start by adding it to your renderer.

public class OpenGLRenderer implements Renderer {
	private FlatColoredSquare flatSquare;
	private SmoothColoredSquare smoothSquare; // NEW LINE ADDED.

	public OpenGLRenderer() {
		// Initialize our squares.
		flatSquare = new FlatColoredSquare();
		smoothSquare = new SmoothColoredSquare(); // NEW LINE ADDED.
	}

We need to move the square down a bit so they don't collide.

public void onDrawFrame(GL10 gl) {
	...
        // Translate to end up under the flat square.
	gl.glTranslatef(0, -3f, 0);
	// Draw our smooth square.
	smoothSquare.draw(gl);
}

Now if you compile and run the application you will see two squares, one solid blue and one smooth with different colors.

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_IV

Previous tutorial: OpenGL ES Tutorial for Android – Part III – Transformations
Next tutorial: OpenGL ES Tutorial for Android – Part V – More on Meshes

I am not going to bore you with a lot of mathematics but I believe it is important to know that when OpenGL render a mesh it multiplies all vertices with a matrix. All the transformations you do are about manipulating the vertices in different ways by modifying this matrix. You can think of the matrix as a paper and that you never move the pen before you start to draw. You always draw in the center. But by doing a translation on the matrix you are moving the paper and also the center. A rotation is like rotating the paper around the center. And a scale is a bit harder to visualize with the paper view but it is like changing the unit size regarding to how you translate your meshes. Usually you talk about transformations according to the mesh not the world, but it is still important to know about.

Coordinate System

OpenGL uses a so called right-handed coordinate system. A system is called right-handed if you look from the positive end towards the origin of the axis the counter-clockwise rotation is considered to be a positive rotation. When you have started up your view and haven't applied any transformations the axis are aligned like this: The x-axis goes from left to right, the y-axis comes from the bottom and goes up and the z-axis is moving from the back of the screen towards the front of the screen.

Translate

public abstract void glTranslatef (float x, float y, float z) //OpenGL docs.

A translations added to the matrix makes the mesh appear as it has been moved. Translations are made along the axis and with no rotation added the axis are in there default state. Translation affects all the vertices in a polygon the same amount over the same axis. Translations are simply additions and subtractions to a current value. The image to the right shows a translation in 2 dimensions.
The start point is {x:-2, y:1} we like to go to {x:1, y:3} so we add {x:3, y:2}.

A simple addition: {x:-2, y:1} + {x:3, y:2} = {x:-2 + 3, y:1 + 2} = {x:1, y:3}.

In 3 dimensions we do the same, if we are located at position: {x:1, y:1, z:0} and we like to move 3 units into the screen we add {x:0, y:0, z:-3} and end up at: {x:1, y:1, z:-3}.

In the last tutorial we moved the square 4 units into the screen just to be able to see the square. What we did was that we added {x:0, y:0, z:-4} to the current position. This is the code we used for the translation:

// Translates 4 units into the screen.
gl.glTranslatef(0, 0, -4); OpenGL docs.

If you do several translations after each other the order of the movement is along the X, Y and Z axis, in that order. On translate the order isn't so important but when we do a rotation it's really important.

It can be quite tricky to remember how the axis are aligned. Fortunate there is a good trick to remember the direction of the axis. Hold your left hand like the photo below. The point on each finger represents the positive direction on one axis. Your thumb is y-axis, index finger is x-axis and your middle finger would represent the z-axis. When I first started with 3D programming I actually wrote the letters, x, y and z on my fingers

Rotate

public abstract void glRotatef(float angle, float x, float y, float z)//OpenGL docs.

Rotating is what it sounds like. You add a rotation to the matrix making it appears like the mesh are rotated. With no translation before the rotation is around the origo. The x, y and z values defines the vector to rotate around. The angle value is the number of degrees to rotate.

If you remember these three things you will manage rotation quite easy.

1. The rotation value are in degrees.
Most frameworks and math functions on computers use radians but OpenGL use degrees.

2. When doing several rotations the order are important.
If you like to restore a rotation you negate the angle or all the axis like this: glRotatef(angle, x, y, z) is restored with glRotatef(angle, -x, -y, -z) or glRotatef(-angle, x, y, z).

But if you do several rotations after each other like this:

gl.glRotatef(90f, 1.0f, 0.0f, 0.0f); // OpenGL docs.
gl.glRotatef(90f, 0.0f, 1.0f, 0.0f); // OpenGL docs.
gl.glRotatef(90f, 0.0f, 0.0f, 1.0f); // OpenGL docs.

And want to restore the mesh to it's original position you can't just negate the angle like this:

gl.glRotatef(90f, -1.0f, 0.0f, 0.0f); // OpenGL docs.
gl.glRotatef(90f, 0.0f, -1.0f, 0.0f); // OpenGL docs.
gl.glRotatef(90f, 0.0f, 0.0f, -1.0f); // OpenGL docs.

You have to revert the order of the rotations as well like this:

gl.glRotatef(90f, 0.0f, 0.0f, -1.0f); // OpenGL docs.
gl.glRotatef(90f, 0.0f, -1.0f, 0.0f); // OpenGL docs.
gl.glRotatef(90f, -1.0f, 0.0f, 0.0f); // OpenGL docs.

The order of several rotations is important.

3. If you look from the positive end towards the origin of the axis the positive rotation is counter-clockwise.
If you take a pencil in your hand, let the point be in the same direction as your thumb, as in the picture below, then aligns the pencil with the x-axis. Let the pencil's point be aligned with the positive direction of the axis. Your other fingers will now point in the positive direction of the rotation over that axis.

Translate & Rotate

Since both rotation and translations are made within each mesh own coordinate system it is important to remember that the order you do the translation and rotation are very important.

If you do a translation on the mesh first and then rotate it, the translation is made on the current state of the mesh coordinate system and then rotated at the new location.

Scale

public abstract void glScalef (float x, float y, float z) // OpenGL docs.

Scaling is just as it sounds and it is possible to scale over each axis separately. Scaling is the same as multiplying all vertexes with the same scalar. In the image below we scale with: gl.glScalef(2f, 2f, 2f). That means that we multiply all vertixes with 2.

Translate & Scale

The order of scaling and translating does matter. If you translate before scaling the transformation is intact. Like this example, first a translation of 2 units and then scale it by 0.5.

gl.glTranslatef(2, 0, 0); // OpenGL docs.
gl.glScalef(0.5f, 0.5f, 0.5f); // OpenGL docs.

gl.glScalef(0.5f, 0.5f, 0.5f); // OpenGL docs.
gl.glTranslatef(2, 0, 0); // OpenGL docs.

Load Identity, push and pop matrix

When you translate, rotate or scaling you are not applying the transformation from the same preconditions, you are applying them to the previous transition. You need to be able to reset the position.

glLoadIdentity

public abstract void glLoadIdentity() // OpenGL docs.

glLoadIdentity replaces the current matrix with the identity matrix. It is the same as calling glLoadMatrix with the identity matrix:

1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1

There are situations where you don't want to reset the model matrix, you rather want to go back to how it was just before your latest transformation.

glPushMatrix

public abstract void glPushMatrix() // OpenGL docs.

glPushMatrix makes a copy of the current matrix and put it on the stack. This means that when you do any kind of translations after glPushMatrix you are doing them on a copy.

glPopMatrix

public abstract void glPopMatrix() // OpenGL docs.

To get back to the previous matrix you use the glPushMatrix command.

A good practice can be to have one glLoadIdentity in the begining of each frame and after that use glPushMatrix and glPopMatrix.

Putting it all togetter

So to make something with this new knowlege let us do 3 squares call them A, B and C. Scale them so that B is 50% smaller then A and C is 50% smaller then B. Then let A rotate counter-clockwise in the center of the screen. B should rotate clockwise around A and finaly C rotating clockwise around B and counter-clockwise in a high speed around it's own center.

public void onDrawFrame(GL10 gl) {
	// Clears the screen and depth buffer.
	gl.glClear(GL10.GL_COLOR_BUFFER_BIT | GL10.GL_DEPTH_BUFFER_BIT);
	// Replace the current matrix with the identity matrix
	gl.glLoadIdentity();
	// Translates 10 units into the screen.
	gl.glTranslatef(0, 0, -10); 

	// SQUARE A
	// Save the current matrix.
	gl.glPushMatrix();
	// Rotate square A counter-clockwise.
	gl.glRotatef(angle, 0, 0, 1);
	// Draw square A.
	square.draw(gl);
	// Restore the last matrix.
	gl.glPopMatrix();

	// SQUARE B
	// Save the current matrix
	gl.glPushMatrix();
	// Rotate square B before moving it, making it rotate around A.
	gl.glRotatef(-angle, 0, 0, 1);
	// Move square B.
	gl.glTranslatef(2, 0, 0);
	// Scale it to 50% of square A
	gl.glScalef(.5f, .5f, .5f);
	// Draw square B.
	square.draw(gl);			

	// SQUARE C
	// Save the current matrix
	gl.glPushMatrix();
	// Make the rotation around B
	gl.glRotatef(-angle, 0, 0, 1);
	gl.glTranslatef(2, 0, 0);
	// Scale it to 50% of square B
	gl.glScalef(.5f, .5f, .5f);
	// Rotate around it's own center.
	gl.glRotatef(angle*10, 0, 0, 1);
	// Draw square C.
	square.draw(gl);

	// Restore to the matrix as it was before C.
	gl.glPopMatrix();
	// Restore to the matrix as it was before B.
	gl.glPopMatrix();

	// Increse the angle.
	angle++;
}

And don't forget to add angel as a variable as well. Thanks Tim!

public class OpenGLRenderer implements Renderer {
	private Square square;
	private float angle; // Don't forget to add this.
        ...

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_III

Previous tutorial: OpenGL ES Tutorial for Android – Part II – Building a polygon
Next tutorial: OpenGL ES Tutorial for Android – Part IV – Adding colors

Building a polygon

In this tutorial we will render our first polygon.

3D models are built up with smaller elements (vertices, edges, faces, and polygons) which can be manipulated individually.

Vertex

A vertex (vertices in plural) is the smallest building block of 3D model. A vertex is a point where two or more edges meet. In a 3D model a vertex can be shared between all connected edges, paces and polygons. A vertex can also be a represent for the position of a camera or a light source. You can see a vertex in the image below marked in yellow.

To define the vertices on android we define them as a float array that we put into a byte buffer to gain better performance. Look at the image to the right and the code below to match the vertices marked on the image to the code.

private float vertices[] = {
      -1.0f,  1.0f, 0.0f,  // 0, Top Left
      -1.0f, -1.0f, 0.0f,  // 1, Bottom Left
       1.0f, -1.0f, 0.0f,  // 2, Bottom Right
       1.0f,  1.0f, 0.0f,  // 3, Top Right
};

// 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());
FloatBuffer vertexBuffer = vbb.asFloatBuffer();
vertexBuffer.put(vertices);
vertexBuffer.position(0);

Don't forget that a float is 4 bytes and to multiply it with the number of vertices to get the right size on the allocated buffer.

OpenGL ES have a pipeline with functions to apply when you tell it to render. Most of these functions are not enabled by default so you have to remember to turn the ones you like to use on. You might also need to tell these functions what to work with. So in the case of our vertices we need to tell OpenGL ES that it’s okay to work with the vertex buffer we created we also need to tell where it is.

// Enabled the vertex buffer for writing and to be used during rendering.
gl.glEnableClientState(GL10.GL_VERTEX_ARRAY);// OpenGL docs.
// Specifies the location and data format of an array of vertex
// coordinates to use when rendering.
gl.glVertexPointer(3, GL10.GL_FLOAT, 0, vertexBuffer); // OpenGL docs.

When you are done with the buffer don't forget to disable it.

// Disable the vertices buffer.
gl.glDisableClientState(GL10.GL_VERTEX_ARRAY);// OpenGL docs.

Edge

Edge is a line between two vertices. They are border lines of faces and polygons. In a 3D model an edge can be shared between two adjacent faces or polygons. Transforming an edge affects all connected vertices, faces and polygons. In OpenGL ES you don't define the edges, you rather define the face by giving them the vertices that would build up the three edges. If you would like modify an edge you change the two vertices that makes the edge. You can see an edge in the image below marked in yellow.

Face

Face is a triangle. Face is a surface between three corner vertices and three surrounding edges. Transforming a face affects all connected vertices, edges and polygons.

The order does matter.

When winding up the faces it's important to do it in the right direction because the direction defines what side will be the front face and what side will be the back face. Why this is important is because to gain performance we don't want to draw both sides so we turn off the back face. So it's a good idea to use the same winding all over your project. It is possible to change what direction that defines the front face with glFrontFace.

 gl.glFrontFace(GL10.GL_CCW); // OpenGL docs

To make OpenGL skip the faces that are turned into the screen you can use something called back-face culling. What is does is determines whether a polygon of a graphical object is visible by checking if the face is wind up in the right order.

 gl.glEnable(GL10.GL_CULL_FACE); // OpenGL docs

It's ofcource possible to change what face side should be drawn or not.

 gl.glCullFace(GL10.GL_BACK); // OpenGL docs

Polygon

Time to wind the faces, remember we have decided to go with the default winding meaning counter-clockwise. Look at the image to the right and the code below to see how to wind up this square.

private short[] indices = { 0, 1, 2, 0, 2, 3 };

To gain some performance we also put this ones in a byte buffer.

// short is 2 bytes, therefore we multiply the number if vertices with 2.
ByteBuffer ibb = ByteBuffer.allocateDirect(indices.length * 2);
ibb.order(ByteOrder.nativeOrder());
ShortBuffer indexBuffer = ibb.asShortBuffer();
indexBuffer.put(indices);
indexBuffer.position(0);

Don't forget that a short is 2 bytes and to multiply it with the number of indices to get the right size on the allocated buffer.

Render

Time to get something on the screen, there is two functions used to draw and we have to decide which one to use.

The two functions are:

public abstract void glDrawArrays(int mode, int first, int count) // OpenGL docs

glDrawArrays draws the vertices in that order they are specified in the construction of our verticesBuffer.

public abstract void glDrawElements(int mode, int count, int type, // OpenGL docs
                                    Buffer indices) 

glDrawElements need a little bit more to be able to draw. It needs to know the order which to draw the vertices, it needs the indicesBuffer.

Since we already created the indicesBuffer I'm guessing that you figured out that's the way we are going.

What is common for this functions is that they both need to know what it is they should draw, what primitives to render. Since there is some various ways to render this indices and some of them are good to know about for debugging reasons. I'll go through them all.

What primitives to render

GL_POINTS

Draws individual points on the screen.

GL_LINE_STRIP

Series of connected line segments.

GL_LINE_LOOP

Same as above, with a segment added between last and first vertices.

GL_LINES

Pairs of vertices interpreted as individual line segments.

GL_TRIANGLES

Triples of vertices interpreted as triangles.

GL_TRIANGLE_STRIP

Draws a series of triangles (three-sided polygons) using vertices v0, v1, v2, then v2, v1, v3 (note the order), then v2, v3, v4, and so on. The ordering is to ensure that the triangles are all drawn with the same orientation so that the strip can correctly form part of a surface.

GL_TRIANGLE_FAN

Same as GL_TRIANGLE_STRIP, except that the vertices are drawn v0, v1, v2, then v0, v2, v3, then v0, v3, v4, and so on.

I think the GL_TRIANGLES is the easiest to use so we go with that one for now.

Putting it all togetter

So let's putting our square together in a class.

package se.jayway.opengl.tutorial;

import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.nio.FloatBuffer;
import java.nio.ShortBuffer;

import javax.microedition.khronos.opengles.GL10;

public class Square {
	// Our vertices.
	private float vertices[] = {
		      -1.0f,  1.0f, 0.0f,  // 0, Top Left
		      -1.0f, -1.0f, 0.0f,  // 1, Bottom Left
		       1.0f, -1.0f, 0.0f,  // 2, Bottom Right
		       1.0f,  1.0f, 0.0f,  // 3, Top Right
		};

	// The order we like to connect them.
	private short[] indices = { 0, 1, 2, 0, 2, 3 };

	// Our vertex buffer.
	private FloatBuffer vertexBuffer;

	// Our index buffer.
	private ShortBuffer indexBuffer;

	public Square() {
		// 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());
		vertexBuffer = vbb.asFloatBuffer();
		vertexBuffer.put(vertices);
		vertexBuffer.position(0);

		// short is 2 bytes, therefore we multiply the number if
		// vertices with 2.
		ByteBuffer ibb = ByteBuffer.allocateDirect(indices.length * 2);
		ibb.order(ByteOrder.nativeOrder());
		indexBuffer = ibb.asShortBuffer();
		indexBuffer.put(indices);
		indexBuffer.position(0);
	}

	/**
	 * This function draws our square on screen.
	 * @param gl
	 */
	public void draw(GL10 gl) {
		// Counter-clockwise winding.
		gl.glFrontFace(GL10.GL_CCW); // OpenGL docs
		// Enable face culling.
		gl.glEnable(GL10.GL_CULL_FACE); // OpenGL docs
		// What faces to remove with the face culling.
		gl.glCullFace(GL10.GL_BACK); // OpenGL docs

		// Enabled the vertices buffer for writing and to be used during
		// rendering.
		gl.glEnableClientState(GL10.GL_VERTEX_ARRAY);// OpenGL docs.
		// Specifies the location and data format of an array of vertex
		// coordinates to use when rendering.
		gl.glVertexPointer(3, GL10.GL_FLOAT, 0, // OpenGL docs
                                 vertexBuffer);

		gl.glDrawElements(GL10.GL_TRIANGLES, indices.length,// OpenGL docs
				  GL10.GL_UNSIGNED_SHORT, indexBuffer);

		// Disable the vertices buffer.
		gl.glDisableClientState(GL10.GL_VERTEX_ARRAY); // OpenGL docs
		// Disable face culling.
		gl.glDisable(GL10.GL_CULL_FACE); // OpenGL docs
	}

}

We have to initialize our square in the OpenGLRenderer class.

// Initialize our square.
Square square = new Square();

And in the draw function call on the square to draw.

public void onDrawFrame(GL10 gl) {
		// Clears the screen and depth buffer.
		gl.glClear(GL10.GL_COLOR_BUFFER_BIT | // OpenGL docs.
                           GL10.GL_DEPTH_BUFFER_BIT);

		// Draw our square.
		square.draw(gl); // ( NEW )
}

If you run the application now the screen is still black. Why? Because OpenGL ES render from where the current position is, that by default is at point: 0, 0, 0 the same position that the view port is located. And OpenGL ES don’t render the things that are too close to the view port. The solution to this is to move the draw position a few steps into the screen before rendering the square:

// Translates 4 units into the screen.
gl.glTranslatef(0, 0, -4); // OpenGL docs

I will talk about the different transformations in the next tutorial.

Run the application again and you will see that the square is drawn but quickly moves further and further into the screen. OpenGL ES doesn’t reset the drawing point between the frames that you will have to do yourself:

// Replace the current matrix with the identity matrix
gl.glLoadIdentity(); // OpenGL docs

Now if you run the application you will see the square on a fixed position.

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_II

Previous tutorial: OpenGL ES Tutorial for Android – Part I – Setting up the view
Next tutorial: OpenGL ES Tutorial for Android – Part III – Transformations

I can't always remember where I found particular info so I might not always be able to give you the right reference. If you feel that I have borrowed stuff from you but have forgotten to add you as a reference, please e-mail me.

In the code examples I will have two different links for each function. The actual function will be linked to the android documentation and after that I will also link the OpenGL documentations. Like this:

gl.glClearColor(0.0f, 0.0f, 0.0f, 0.5f);  // OpenGL docs.

So, let's start.

In this tutorial I will show you how to set up your OpenGL ES view that’s always a good place to start.

Setting up an OpenGL ES View

Setting up a OpenGL view has never been hard and on Android it is still easy. There really are only two things you need to get started.

GLSurfaceView

GLSurfaceView is a API class in Android 1.5 that helps you write OpenGL ES applications.

• Providing the glue code to connect OpenGL ES to the View system.
• Providing the glue code to make OpenGL ES work with the Activity life-cycle.
• Making it easy to choose an appropriate frame buffer pixel format.
• Creating and managing a separate rendering thread to enable smooth animation.
• Providing easy-to-use debugging tools for tracing OpenGL ES API calls and checking for errors.

If you want to get going fast with your OpenGL ES application this is where you should start.

The only function you need to call on is:

public void  setRenderer(GLSurfaceView.Renderer renderer)

Read more at: GLSurfaceView

GLSurfaceView.Renderer

GLSurfaceView.Renderer is a generic render interface. In your implementation of this renderer you should put all your calls to render a frame.
There are three functions to implement:

// Called when the surface is created or recreated.
public void onSurfaceCreated(GL10 gl, EGLConfig config) 

// Called to draw the current frame.
public void onDrawFrame(GL10 gl)

// Called when the surface changed size.
public void onSurfaceChanged(GL10 gl, int width, int height)

onSurfaceCreated

Here it's a good thing to setup things that you don't change so often in the rendering cycle. Stuff like what color to clear the screen with, enabling z-buffer and so on.

onDrawFrame

Here is where the actual drawing take place.

onSurfaceChanged

If your device supports flipping between landscape and portrait you will get a call to this function when it happens. What you do here is setting upp the new ratio.
Read more at: GLSurfaceView.Renderer

Putting it together

First we create our activity, we keep it clean and simple.

package se.jayway.opengl.tutorial;

import android.app.Activity;
import android.opengl.GLSurfaceView;
import android.os.Bundle;

public class TutorialPartI extends Activity {
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
    	super.onCreate(savedInstanceState);
 		GLSurfaceView view = new GLSurfaceView(this);
   		view.setRenderer(new OpenGLRenderer());
   		setContentView(view);
    }
}

Our renderer takes little bit more work to setup, look at it and I will explain the code a bit more.

package se.jayway.opengl.tutorial;

import javax.microedition.khronos.egl.EGLConfig;
import javax.microedition.khronos.opengles.GL10;

import android.opengl.GLU;
import android.opengl.GLSurfaceView.Renderer;

public class OpenGLRenderer implements Renderer {
	/*
	 * (non-Javadoc)
	 *
	 * @see
	 * android.opengl.GLSurfaceView.Renderer#onSurfaceCreated(javax.
         * microedition.khronos.opengles.GL10, javax.microedition.khronos.
         * egl.EGLConfig)
	 */
	public void onSurfaceCreated(GL10 gl, EGLConfig config) {
		// Set the background color to black ( rgba ).
		gl.glClearColor(0.0f, 0.0f, 0.0f, 0.5f);  // OpenGL docs.
		// Enable Smooth Shading, default not really needed.
		gl.glShadeModel(GL10.GL_SMOOTH);// OpenGL docs.
		// Depth buffer setup.
		gl.glClearDepthf(1.0f);// OpenGL docs.
		// Enables depth testing.
		gl.glEnable(GL10.GL_DEPTH_TEST);// OpenGL docs.
		// The type of depth testing to do.
		gl.glDepthFunc(GL10.GL_LEQUAL);// OpenGL docs.
		// Really nice perspective calculations.
		gl.glHint(GL10.GL_PERSPECTIVE_CORRECTION_HINT, // OpenGL docs.
                          GL10.GL_NICEST);
	}

	/*
	 * (non-Javadoc)
	 *
	 * @see
	 * android.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.
         * microedition.khronos.opengles.GL10)
	 */
	public void onDrawFrame(GL10 gl) {
		// Clears the screen and depth buffer.
		gl.glClear(GL10.GL_COLOR_BUFFER_BIT | // OpenGL docs.
                           GL10.GL_DEPTH_BUFFER_BIT);
	}

	/*
	 * (non-Javadoc)
	 *
	 * @see
	 * android.opengl.GLSurfaceView.Renderer#onSurfaceChanged(javax.
         * microedition.khronos.opengles.GL10, int, int)
	 */
	public void onSurfaceChanged(GL10 gl, int width, int height) {
		// Sets the current view port to the new size.
		gl.glViewport(0, 0, width, height);// OpenGL docs.
		// Select the projection matrix
		gl.glMatrixMode(GL10.GL_PROJECTION);// OpenGL docs.
		// Reset the projection matrix
		gl.glLoadIdentity();// OpenGL docs.
		// Calculate the aspect ratio of the window
		GLU.gluPerspective(gl, 45.0f,
                                   (float) width / (float) height,
                                   0.1f, 100.0f);
		// Select the modelview matrix
		gl.glMatrixMode(GL10.GL_MODELVIEW);// OpenGL docs.
		// Reset the modelview matrix
		gl.glLoadIdentity();// OpenGL docs.
	}
}

Fullscreen

Just add this lines in the OpenGLDemo class and you will get fullscreen.

    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        this.requestWindowFeature(Window.FEATURE_NO_TITLE); // (NEW)
        getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,
            WindowManager.LayoutParams.FLAG_FULLSCREEN); // (NEW)
        ... // Previous code.
    }

This is pretty much all you need to get your view up and running. If you compile and run it you will see a nice black screen.

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_I.zip

Next tutorial: OpenGL ES Tutorial for Android – Part II – Building a polygon

Failed to get the adb version: Cannot run program "/home/johan/devtools/android/android-sdk-linux_x86-1.6_r1/tools/adb": java.io.IOException: error=2, No such file or directory

I opened the terminal and tried to manually run an Android executable but even here it said that the file couldn't be found! The problem seemed to be that the Android executables requires 32 bit libraries that are not available in Ubuntu 64 by default. To solve this I downloaded the execellent getlibs application which is a utility for automatically resolving dependencies for 32-bit programs on a 64 bit system. So I went into platforms/android-1.6/tools in the Android SDK installation folder and executed:

 
getlibs aapt
 

which installed and upgraded the following libraries:

 
The following NEW packages will be installed:
  ia32-libs lib32asound2 lib32gcc1 lib32ncurses5 lib32stdc++6 lib32z1
  libc6-i386
The following packages will be upgraded:
  libc6 libc6-dev
 

After this was done I went back into Eclipse, did a project clean and refresh and after that I was able to start the Android emulator successfully. Hopefully this may help someone who's in the same situation.

Clicking on the first link you expect your browser to start a new tab and navigate to the url that was specified in the href. If you click on the second link you would expect that the browser opens up your favourite email client. The third link would probably just give you an error message since the browser has no idea how to react on a link like foo://my.test.com

On Android we can control how the device should react when the user clicks on a link in the web browser, or more specific control which Activity should be started. Every time the user clicks on a link the browser sends an intent to the platform with the following content.

action = android.intent.action.VIEW
category = android.intent.category.BROWSABLE
data = the text from the href tag

If we navigate to a web page with the following page source on our Andoid device we could expect a few interesting things to happen when we click on the links.

The first link will generate an intent with the following information

action = android.intent.action.VIEW
category = android.intent.category.BROWSABLE
data = "tel:123456"

This will start the Dialer application and preset the phone number to 123456.

Clicking on the second link will not surprisingly open up the email client in your device with a preset receiver address. What about clicking on the third link? Well, by default it would just return a "page not available" error message in the browser. The intent sent from the browser will look like this

action = android.intent.action.VIEW
category = android.intent.category.BROWSABLE
data = "foo://my.test.com"

This means that if we install an Activity with the following IntentFilter

this Activity will start when the user clicks on the third link. Pretty cool, isn't it?