I have several apps myself through Mobclix’s service. However, developer beware. You may never receive you money, and you may be getting screwed on the exact amount you are supposed to receive.

First, the statistics may or may not be accurate. Mobclix is at the mercy of the ad networks they distribute. There has been several times since I’ve been a developer with them that they have went back and ‘adjusted’ the payment amounts. What I mean by adjusted is that they have lowered the amount that my application earned. They have claimed several times in their blog that this is due to the ad networks disputing payments across their entire network. This would be fine if they gave you a detailed statistics panel that gave you an in depth breakdown of how much you were receiving per ad network and per app. However, their interface is generally a joke. If it feels like loading on that particular day then it only displays broad numbers with absolutely no breakdown at all.

So accidents happen. I can accept that. I can definitely accept that the technology may have flubbed once or twice causing thousands of users to report higher earnings then they were actually receiving, but what I CANNOT accept is late payment.

I’ve been with Mobclix for almost a year with my applications. It takes quite awhile to receive your first payment, since checks are sent out net 30 AFTER the ad network pays Mobclix. So according to Mobclix all payments come at net 90. In short it takes three months to receive that months payment. January advertising will come in May 15th. That is a long time to wait.

So why is it that of the 11 months I have been with Mobclix I have had to personally e-mail and call them 6 of those months asking for my payment. Right now my payments are 3 months behind. Yes that’s right I haven’t received a payment in 3 months. I was supposed to receive 3. They will never send a payment unless you bother them. Then sometimes they still won’t.

If you advertise with Mobclix in my humble opinion you are throwing your advertising money away. If you value your time at all then the amount of harassment and trouble you have to go through to get $1000 or $100 is not worth it.

If you have any questions or comments about Mobclix or my experience with them then please leave a comment!

Jumping right into the code, here is the layout xml file:

Spinner
android:id="@+id/Spinner01"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:drawSelectorOnTop = "true"></Spinner>

Nothing special. It just consists of one element.

Now in the main activity, I create an array of android books:

String[] androidBooks =
{
"Hello, Android - Ed Burnette",
"Professional Android 2 App Dev - Reto Meier",
"Unlocking Android - Frank Ableson",
"Android App Development - Blake Meike",
"Pro Android 2 - Dave MacLean",
"Beginning Android 2 - Mark Murphy",
"Android Programming Tutorials - Mark Murphy",
"Android Wireless App Development - Lauren Darcey",
"Pro Android Games - Vladimir Silva",
};

Then in the onCreate() method, I create an ArrayAdapter that I can pass to this Spinner as the data Source.

ArrayAdapter<String> adapter =
        new ArrayAdapter<String> (this,
        android.R.layout.simple_spinner_item,androidBooks);

Then, I get a handle to the Spinner, and set the ArrayAdapter to it

sp = (Spinner)findViewById(R.id.Spinner01);
sp.setAdapter(adapter);

Now, on selecting one of the items in the spinner, I want to be able to toast a message on the book that was selected. It is done as follows:

sp.setOnItemSelectedListener(new OnItemSelectedListener() {
    @Override
    public void onItemSelected(AdapterView<?> arg0, View arg1, int arg2, long arg3) {
        int item = sp.getSelectedItemPosition();
        Toast.makeText(getBaseContext(),
            "You have selected the book: " + androidBooks[item],
            Toast.LENGTH_SHORT).show();
    }

    @Override
    public void onNothingSelected(AdapterView<?> arg0) {
    }
});

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.

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

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 200×200 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.

Set the classpath variable to the full class name of your Java class (including package name). Replace the dots with slashes.

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. In short, you create a folder named jni in your Android Eclipse project. Here you put all the c-files together with an Android.mk file. In the Android.mk you specify which c-files to compile. In the Android NDK/apps folder you create a directory named after your project (perhaps my-app). In this directory you add an Application.mk file. In the Application.mk, set the APP_PROJECT_PATH to the path of your Eclipse project. To create the lib simply type make APP=my-app from the console in your Android NDK folder. If everything goes well you will see a libs folder in your Eclipse 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.

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.

First step would be to get a bitmap to generate a texture from. You can get hold of a bitmap in many different ways from downloading, generating or simply just load one from the resources. I’m going with the simplest one for this example witch is loading from the resources.

Bitmap bitmap = BitmapFactory.decodeResource(contect.getResources()
                                             R.drawable.icon);

One other thing about textures is that some hardware requires that the height and width are in the power of 2 (1, 2, 4, 8, 16, 32, 64…). If you run a texture with a size of 30x30pixels on a hardware that don’t support it you will just get a white square (unless you change the default color).

Generating a texture

After we have loaded the bitmap we need to tell OpenGL to actually create the texture.

First thing we need to do is to let OpenGL generate some texture id’s that we will use as handles to the textures later on. In this example we will only have one texture.

// Create an int array with the number of textures we want,
// in this case 1.
int[] textures = new int[1];
// Tell OpenGL to generate textures.
gl.glGenTextures(1, textures, 0);

With the same parameters you can delete the textures:

// Delete a texture.
gl.glDeleteTextures(1, textures, 0)

Now when the texture id’s are generated we need to just like everything else tell OpenGL what to work with. With textures we use the command glBindTexture:

gl.glBindTexture(GL10.GL_TEXTURE_2D, textures[0]);

From this point all commands we call on regarding textures will be applied on to your texture with the generated id.

glTexParameter

There is a couple of parameters we need to set on the texture, the first one is to tell OpenGL what to do if the texture need to be shrunk or magnified to match the rendered image.
If the texture is smaller it needs to be magnified that is done with the magnification function:

// Scale up if the texture if smaller.
gl.glTexParameterf(GL10.GL_TEXTURE_2D,
                   GL10.GL_TEXTURE_MAG_FILTER,
                   GL10.GL_LINEAR);

And how to scale if the texture needs to be scaled down using the minification function.

// scale linearly when image smalled than texture
gl.glTexParameterf(GL10.GL_TEXTURE_2D,
                   GL10.GL_TEXTURE_MIN_FILTER,
                   GL10.GL_LINEAR);

You need to pass an argument to these functions. I’m only going to show you two of them the rest you can investigate your self

If you want a crisp and clean rendering like this image you need to use the GL10.GL_NEAREST parameter.

If you rather want a blurred image you should use the GL10.GL_LINEAR parameter.

UV Mapping

We will also need to tell OpenGL how to map this image onto the mesh this is done in two steps, fist we need to assign UV coordinates

UV mapping is the way we map the pixels on the bitmap to the vertices in our mesh. The UV coordinates are 0,0 in the upper left and 1,1 is the bottom right, like the left image below. The right image below illustrates how our plane is built. To get the texture mapped correctly we need to map the lower left part of the texture (0,1) to the lower left vertex (0) in our plane and we need to map the the bottom right (1,1) in the texture to the bottom right (1) to the bottom right in our plane and… you get the idea.

We put this mapping into a float array like this:

float textureCoordinates[] = {0.0f, 1.0f,
                              1.0f, 1.0f,
                              0.0f, 0.0f,
                              1.0f, 0.0f };

If we instead used 0.5 instead of 1.0 like this:

float textureCoordinates[] = {0.0f, 0.5f,
                              0.5f, 0.5f,
                              0.0f, 0.0f,
                              0.5f, 0.0f };

The texture will be mapped so the plane will have the upper left part of it.
Back to the glTexParameterf, if we go the other way and uses values higher then 1.0 like this:

float textureCoordinates[] = {0.0f, 2.0f,
                              2.0f, 2.0f,
                              0.0f, 0.0f,
                              2.0f, 0.0f };

We actually tell OpenGL to use part of the texture that does not exist so we need to tell OpenGL what to do with the part that does not exist.

We use the glTexParameterf function to tell OpenGL what to do with the texture. By default OpenGL uses something called GL_REPEAT.

GL_REPEAT means that OpenGL should repeat the texture beyond 1.0.
GL_CLAMP_TO_EDGE means that OpenGL only will draw the image once and after that just repeat the last pixel line the rest of the image.

Since we are working with a 2D texture so we need to tell OpenGL what to do in two directions: GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T.

Below you see a chart with the 4 combinations of GL_REPEAT and GL_CLAMP_TO_EDGE.

This is how we use the glTexParameterf function:

gl.glTexParameterf(GL10.GL_TEXTURE_2D,
                   GL10.GL_TEXTURE_WRAP_S,
                   GL10.GL_REPEAT);
gl.glTexParameterf(GL10.GL_TEXTURE_2D,
                   GL10.GL_TEXTURE_WRAP_T,
                   GL10.GL_REPEAT);

The last thing we need to do is to bind the bitmap we loaded to the texture id we created.

GLUtils.texImage2D(GL10.GL_TEXTURE_2D, 0, bitmap, 0);

Using the texture

To be able to use the texture we need just like with everything else create a byte buffer with the UV coordinates:

FloatBuffer byteBuf = ByteBuffer.allocateDirect(texture.length * 4);
byteBuf.order(ByteOrder.nativeOrder());
textureBuffer = byteBuf.asFloatBuffer();
textureBuffer.put(textureCoordinates);
textureBuffer.position(0);

Rendering

// Telling OpenGL to enable textures.
gl.glEnable(GL10.GL_TEXTURE_2D);
// Tell OpenGL where our texture is located.
gl.glBindTexture(GL10.GL_TEXTURE_2D, textures[0]);
// Tell OpenGL to enable the use of UV coordinates.
gl.glEnableClientState(GL10.GL_TEXTURE_COORD_ARRAY);
// Telling OpenGL where our UV coordinates are.
gl.glTexCoordPointer(2, GL10.GL_FLOAT, 0, textureBuffer);

// ... here goes the rendering of the mesh ...

// Disable the use of UV coordinates.
gl.glDisableClientState(GL10.GL_TEXTURE_COORD_ARRAY);
// Disable the use of textures.
gl.glDisable(GL10.GL_TEXTURE_2D);

Putting it all together

I’m using a modified version of the code from the previous tutorial. The different is mostly that I renamed some variables and functions and added more comments and all code is now under Apache License. To make the code easier to understand I removed the previous plane and added a new easier one called SimplePlane.

Updating the Mesh class

The first thing we need to do is to update the Mesh class (se.jayway.opengl.tutorial.mesh.Mesh). We need to add the functionality to load and render a texture.

We need to be able to set and store the UV coordinates.

// Our UV texture buffer.
private FloatBuffer mTextureBuffer;

/**
 * Set the texture coordinates.
 *
 * @param textureCoords
 */
protected void setTextureCoordinates(float[] textureCoords) {
	// float is 4 bytes, therefore we multiply the number if
        // vertices with 4.
	ByteBuffer byteBuf = ByteBuffer.allocateDirect(
                                           textureCoords.length * 4);
	byteBuf.order(ByteOrder.nativeOrder());
	mTextureBuffer = byteBuf.asFloatBuffer();
	mTextureBuffer.put(textureCoords);
	mTextureBuffer.position(0);
}

We also need to add functions to set the bitmap and create the texture.

// Our texture id.
private int mTextureId = -1;

// The bitmap we want to load as a texture.
private Bitmap mBitmap;

/**
 * Set the bitmap to load into a texture.
 *
 * @param bitmap
 */
public void loadBitmap(Bitmap bitmap) {
	this.mBitmap = bitmap;
	mShouldLoadTexture = true;
}

/**
 * Loads the texture.
 *
 * @param gl
 */
private void loadGLTexture(GL10 gl) {
	// Generate one texture pointer...
	int[] textures = new int[1];
	gl.glGenTextures(1, textures, 0);
	mTextureId = textures[0];

	// ...and bind it to our array
	gl.glBindTexture(GL10.GL_TEXTURE_2D, mTextureId);

	// Create Nearest Filtered Texture
	gl.glTexParameterf(GL10.GL_TEXTURE_2D, GL10.GL_TEXTURE_MIN_FILTER,
			GL10.GL_LINEAR);
	gl.glTexParameterf(GL10.GL_TEXTURE_2D, GL10.GL_TEXTURE_MAG_FILTER,
			GL10.GL_LINEAR);

	// Different possible texture parameters, e.g. GL10.GL_CLAMP_TO_EDGE
	gl.glTexParameterf(GL10.GL_TEXTURE_2D, GL10.GL_TEXTURE_WRAP_S,
			GL10.GL_CLAMP_TO_EDGE);
	gl.glTexParameterf(GL10.GL_TEXTURE_2D, GL10.GL_TEXTURE_WRAP_T,
			GL10.GL_REPEAT);

	// Use the Android GLUtils to specify a two-dimensional texture image
	// from our bitmap
	GLUtils.texImage2D(GL10.GL_TEXTURE_2D, 0, mBitmap, 0);
}

And finally we need to add the call to the texture loading and to actually tell OpenGL to render with this texture. I removed some code so the page would not be so long but you will find the code complete in the attached zip file.

// Indicates if we need to load the texture.
private boolean mShouldLoadTexture = false;

/**
 * Render the mesh.
 *
 * @param gl
 *            the OpenGL context to render to.
 */
public void draw(GL10 gl) {
	...

	// Smooth color
	if (mColorBuffer != null) {
		// Enable the color array buffer to be used during rendering.
		gl.glEnableClientState(GL10.GL_COLOR_ARRAY);
		gl.glColorPointer(4, GL10.GL_FLOAT, 0, mColorBuffer);
	}

	if (mShouldLoadTexture) {
		loadGLTexture(gl);
		mShouldLoadTexture = false;
	}
	if (mTextureId != -1 && mTextureBuffer != null) {
		gl.glEnable(GL10.GL_TEXTURE_2D);
		// Enable the texture state
		gl.glEnableClientState(GL10.GL_TEXTURE_COORD_ARRAY);

		// Point to our buffers
		gl.glTexCoordPointer(2, GL10.GL_FLOAT, 0, mTextureBuffer);
		gl.glBindTexture(GL10.GL_TEXTURE_2D, mTextureId);
	}

	gl.glTranslatef(x, y, z);

	...

	// Point out the where the color buffer is.
	gl.glDrawElements(GL10.GL_TRIANGLES, mNumOfIndices,
			GL10.GL_UNSIGNED_SHORT, mIndicesBuffer);

	...

	if (mTextureId != -1 && mTextureBuffer != null) {
		gl.glDisableClientState(GL10.GL_TEXTURE_COORD_ARRAY);
	}

	...

}

Creating the SimplePlane class

We also need to create the SimplePlane.java. The code is pretty simple and self-explaining if you have read my previous tutorials. The new element is the textureCoordinates variable.

package se.jayway.opengl.tutorial.mesh;

/**
 * SimplePlane is a setup class for Mesh that creates a plane mesh.
 *
 * @author Per-Erik Bergman (per-erik.bergman@jayway.com)
 *
 */
public class SimplePlane extends Mesh {
	/**
	 * Create a plane with a default with and height of 1 unit.
	 */
	public SimplePlane() {
		this(1, 1);
	}

	/**
	 * Create a plane.
	 *
	 * @param width
	 *            the width of the plane.
	 * @param height
	 *            the height of the plane.
	 */
	public SimplePlane(float width, float height) {
		// Mapping coordinates for the vertices
		float textureCoordinates[] = { 0.0f, 2.0f, //
				2.0f, 2.0f, //
				0.0f, 0.0f, //
				2.0f, 0.0f, //
		};

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

                float[] vertices = new float[] { -0.5f, -0.5f, 0.0f,
                                                  0.5f, -0.5f, 0.0f,
                                                 -0.5f,  0.5f, 0.0f,
                                                  0.5f, 0.5f, 0.0f };

		setIndices(indices);
		setVertices(vertices);
		setTextureCoordinates(textureCoordinates);

You can download the source for this tutorial here: Tutorial_Part_VI

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.

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.

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:

 1="1.0f," 2="0.0f," 3="0.0f);" 4="//" 5="OpenGL" 6="docs." 7="gl.glRotatef(90f," 8="0.0f," 9="1.0f," 10="0.0f);" 11="//" 12="OpenGL" 13="docs." 14="gl.glRotatef(90f," 15="0.0f," 16="0.0f," 17="1.0f);" 18="//" 19="OpenGL" 20="docs." language="[gl.glRotatef(90f,"

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.

If you first rotate and the move the mesh it will be moved accordingly to its own rotated coordinate system.

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.

But if you scale before the translation you get a different result. Since you scale the mesh coordinate system then do the translation you will not move the mesh the same amount as you would before the scaling. So if you first scale with 0.5 and then do a translation of 2 units the result will appear as a translation of 1 unit.

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

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

11 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.

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

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 of cource 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 };

// 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.