Here’s the effect I was trying to achieve:

What we have here is the iPunt playing box suspended in mid-air. The floor is a broken mirror (although that’s a little hard to see from this angle.) The camera is allowed to move freely around the inside of the skybox. When the camera is below the foor, the floor appears transparent (like broken glass.) The walls of the playbox are fractured glass.

The problem, really, is the reflection. Without any stenciling, you get this…

We somehow need to prevent the reflected scene that is not viewed through the mirrored floor from showing. A stencil buffer would have worked well for this purpose. Without a stencil buffer, you have to rely on depth culling and transparency to achieve the desired result.

In brief, what I did was to create a stencil shape (a planar shape made up of triangles) that had a hole in the middle where the mirrored floor was going to be and was large enough to obscure the reflected scene from all camera angles above the plane of the floor. This shape will be drawn transparent (alpha = 0) so that the skybox will show through, but the draw order and the depth culling will prevent the unwanted portions of the reflected scene from showing through.

Here’s a picture of the skybox, reflection, and stencil (with the alpha turned up so that it can be seen.)

Because the draw order is skybox, then stencil, then reflected scene, those portions of the reflected scene that are occluded by the stencil are depth-culled and won’t be drawn. The real scene and floor can then be drawn.

Here is the code, with comments, that does this…

First, the definition of the stencil and floor triangles.

// The shape here is a large plane
// with a hole in it where the mirror will be.
const GLfloat stencilVerts[] = {
-100.0, -15.0, 100.0,
-10.0, -15.0, 10.0,
100.0, -15.0, 100.0,
10.0, -15.0, 10.0,
100.0, -15.0, -100.0,
10.0, -15.0, -10.0,
-100.0, -15.0, -100.0,
-10.0, -15.0, -10.0,
-100.0, -15.0, 100.0,
-10.0, -15.0, 10.0
};

const GLfloat floorVerts[] = {
-10.0, -15.0, 10.0,
10.0, -15.0, 10.0,
10.0, -15.0, -10.0,
-10.0, -15.0, -10.0,
};

const GLfloat floorUV[] = {
0.0, 0.0,
0.0, 1.0,
1.0, 1.0,
1.0, 0.0
};

Then in my render() function…

  glEnable(GL_DEPTH_TEST);
  glEnable(GL_TEXTURE_2D);
  glShadeModel(GL_SMOOTH);
  glBlendFunc (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);

  // Clear the space
  glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
  glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
  CHECK_ERR

  // Draw the skybox
  _pSkyBox->draw();
  CHECK_ERR

  // Only draw the reflection if the view is above the plane of the floor.
  if (pWorld->camera()->location().y() > -14.5) {

    // Draw the stencil.  Anything that is drawn after this that is occluded by the
    // stencil will not be drawn because it fails the depth test.  The skybox, which
    // has already been drawn, will show through everywhere because of the transparency.
    pWorld->material("StencilMaterial")->installMaterial();  // Sets the material properties, including alpha
    glEnableClientState(GL_VERTEX_ARRAY);
    glVertexPointer(3, GL_FLOAT, 0, stencilVerts);
    glDrawArrays(GL_TRIANGLE_STRIP, 0, 10);
    glDisableClientState(GL_VERTEX_ARRAY);
    pWorld->material("StencilMaterial")->uninstallMaterial();

    // Draw reflection w/out floor -- Reflection will be depth culled everwhere but hole
    // Draw everything else normally (including the mirrored floor)
    glPushMatrix ();
    // Mirror lies in XZ plane, so scale by -1.0 in Y axis
    glScalef(1.0, -1.0, 1.0);
    // Mirror is 15.0 units from origin, so translate by 30.0 units
    glTranslatef(0.0, 30.0, 0.0);
    pWorld->draw();
    glPopMatrix();
  }
  CHECK_ERR

  // Draw the real scene
  pWorld->draw();
  CHECK_ERR

  // Draw the floor
  BMWLight::disableLighting();
  pWorld->material("Material_010")->installMaterial(); // Sets the material properties
  glEnableClientState(GL_VERTEX_ARRAY);
  glVertexPointer(3, GL_FLOAT, 0, floorVerts);
  glEnableClientState(GL_TEXTURE_COORD_ARRAY);
  glClientActiveTexture(GL_TEXTURE0);
  glTexCoordPointer(2, VERTTYPEENUM, 0, floorUV);
  glDrawArrays(GL_TRIANGLE_FAN, 0, 4);
  glDisableClientState(GL_TEXTURE_COORD_ARRAY);
  glDisableClientState(GL_VERTEX_ARRAY);
  pWorld->material("Material_010")->uninstallMaterial();
  BMWLight::enableLighting();

Note that the BMW functions are functions in our framework that encapsulate OpenGL functionality. You can pretty much treat them as pseudo-code in this example.

So, there you have it. A use of depth culling and transparency to implement functionality that I originally though required a stencil buffer. I’d be intereste in hearing about any examples you have of similar effects!

The cause is the following code in SoundEngineEffect::PlaybackProc()

  if (THIS->HasAttackBuffer())
  {
    ALint numBuffersProcessed = 0;
    while (numBuffersProcessed < 1)
    {
       alGetSourcei(THIS->GetEffectID(), AL_BUFFERS_PROCESSED, &numBuffersProcessed);
         AssertNoOALError("Error getting processed buffer number", end)
    }

While the attack buffer is playing, you’re in a tight polling loop waiting for it to complete.  This is no problem if the preamble is really short, but for OpenGL games, it’s going to cause problems for any sound longer than a fraction of a frame.

The fix, fortunately, is simple.  Sleep this thread for a few milliseconds each iteration of the polling loop in order to give the rest of your application a chance to run.

The modified code is:

  if (THIS->HasAttackBuffer())
  {
    ALint numBuffersProcessed = 0;
    while (numBuffersProcessed < 1)
    {
       alGetSourcei(THIS->GetEffectID(), AL_BUFFERS_PROCESSED, &numBuffersProcessed);
         AssertNoOALError("Error getting processed buffer number", end)
       usleep(5000);  // Sleep for 5 mS each polling loop
    }

This little change makes all the difference for this bit of code and makes it suitable for long (> 1second) preambles.

I’ve found SoundEngine to work pretty well, although I have had to make a number of modifications to it for my specific application.  However, I think I’m at the point where I need to write my own OpenAL sound processing class library.  I’d be interested to hear from some of you to see what you’re using for game sound.

I want to apologize in advance for the lack of polish in this post.  It’s kind-of a hodge-podge of information, but it’s been in the womb too long.  Time to get it out, even if it’s rough!

I’ve had a lot of trouble getting my head around texturing.  I know what I want to do, and I understand the "how to" do it for OpenGL, but there are a bunch of issues that make translating the theory to practice on the iPhone challenging:

• The iPhone uses OpenGL-ES 1.x which is not OpenGL when it comes to texturing.  (News flash, the iPhone 3G S will support OpenGL-ES 2.0.)
• The PowerVR MBX chipset doesn’t support all of the OpenGL-ES functionality (particularly the stencil buffer.)  It will be interesting to see what the new SGX chipset provides.
• If you’re using Blender for your modeling, as I’m trying to do, making the translation from a texturing strategy in Blender to something that will work on the device may not be obvious.

I found myself doing a lot of googling and reading books, then trying things out only to find that the methods provided required an API call or technique that doesn’t work on the platform.  So, I’ve compiled a little list of resources and hints that perhaps will make the going easier for those that are also trying to climb the mountain.

The Basics of Texturing

There are some great tutorials on OpenGL texturing out there.  Here are a few to get you started, but there are many more that are worth mentioning:

• Zeus Texture Mapping Tutorial
• Flipcode Advanced OpenGL Texture Mapping

These and others will get you the basics.  Please don’t waste time writing loaders for different graphics file types, generating textures and so-on.  Oolong and PowerVR have a solution for that which is much quicker and better.  Simply load your texture bitmap (in whatever format is convenient) into the PowerVR TexTool and generate the PVRTC (.pvr) compressed texture file.  A few easy calls and the .pvr file is loaded into your app and ready to use.  I’ll provide a more complete recipe for this a little later in this post.

One of the things that I struggled with in a big way was understanding and generating texture coordinates.  This is something that all of the tutorials make short shrift of.  Most of them provide a static array of 0’s and 1’s and leave it at that.  Those that go a bit deeper (the Red Book and Super Bible go into more detail) rely heavily on glTexGen().  Well, guess what, there is no glTexGen() for OpenGL-ES and I have found very little  help in working around that.  The one bright light is this article on "The Mathematics of glTexGen() " from the OpenGL wiki.  With this information, you can write your own procedural texture coordinate generation code.  One of the best explanations of what each of these generation "modes" does is found here , from the OpenGL Super Bible.

More than likely, the main reason that these resources don’t help much with procedural texture mapping is because most texture mapping is performed in a modeling tool.  The funny thing is that, with all my searching, it took a while before I discovered how to do this in Blender.  There is actually a very good, comprehensive tutorial in the Blender manual that explains all:  Blender UV Texture Mapping .  The relevant documentation is several web pages long, so stick with it to the end.  Note that in the currently available iPhones (the PowerVR MBX chip) there are only two texture units, so don’t plan on deep multi-texturing for this device.

The Blender->PVR->Oolong Procedure At A Glance

Here’s a high level overview of the entire procedure at a glance.  Note that I have left out many details that are covered in the Blender documentation, only including those steps that are either structural or I have additional details for.

In Blender:

1. Create your mesh.
2. Select the Material window configuration which puts the UV/Image Editor and 3D View up simultaneously (see image below.)
3. Put the 3D window in texture mapped mode so that you can see the effects of texturing in real-time.
4. Create or select a material for the object or faces.
5. Create a UVTex mapping for the object or faces.
6. Unwrap the mesh.  This will probably take some experimentation with the many unwrapping algorithms Blender provides, along with some manual editing of the faces in the UV window.
7. Export the face layout to a .tga file using the Blender script UVs->Scripts->Save UV Face Layout .  Be sure to set the size to the final size of the texture (for a 256×256 texture, set the size to 256.)  Be sure size is a power of 2.

In GIMP or the image editing / paint tool of your choice…

1. Open the .tga file and copy the layout to a semi-transparent, top layer (overlay).
2. "Color" the texture on layers underneath it.
3. Turn off the overlay and export to .png format

In Blender

1. Load the texture image and assign to the mesh faces to which it applies.
2. Use texture paint to touch up any areas where appropriate.  (Be sure to load the changed version into your image editor if you go back!)
3. Adjust vertices and mapping as necessary and iterate.

For the most part, the result on the device will look the same as in Blender, so you can just stay in Blender and GIMP until you have it looking right.  I noticed that I occasionally had to flip normals on some faces in Blender, particularly when I manually added faces or reduced the face count during optimization.  Faces with the normal facing in the wrong direction will look transparent in Blender.

Note that the mapping is extremely flexible.  It is not necessary for faces in the UV window to have proportional area to the actual faces on the mesh.  In fact, it is a monumental waste of pixels to map faces that are a solid color or have low resolution data to large UV areas.  Devote most of the area in your texture to the high resolution content and put low resolution faces in smaller areas.  Also, remember that it’s OK if UV faces overlap as long as the result is what you want.  I sometimes just create a color splotch and put all the faces that are that color higgledy-piggledy in the splotch.

When the object looks the way you want, use the PVRTexTool to convert the texture image to .pvr format…

1. Open the texture image produced above in the PVRTexTool (comes with the PowerVR SDK.)
2. Generate all MipMaps.  They should automatically show up.  If they don’t, your texture may not be square and a power of 2.
3. Use Save As to save the texture as a .pvr
4. In the encoding dialog that pops up, select 2bpp or 4bpp as needed, turn YFlip OFF, and export all mipmaps.  Many other encodings are supported, but I have found that the PVRTC 2bpp and 4bpp encodings work very well with the Oolong kit.  Use 4bpp where you need better image quality, 2bpp where the quality is not as important.  Experiment to get what you need.

You can now load the POD and texture, apply the texturing during rendering in Oolong and it should look the same as it did in Blender.  I used the Shadows example to get me started.

Here are some examples from iPunt:

Procedural Texturing

Once I figured out how to use Blender to map an image to an object by "unwrapping" it, I didn’t have as much need for procedural texturing, but for certain things (like cube mapping and projections) procedural texturing is still useful.  Here’s what I learned.

One of the conceptual things that I struggled with is that I kept trying to think of wrapping my texture around an object.  The way these algorithms work is backwards from that, and much easier.  They work backwards from the point on the object to be textured to the pixel in the texture bitmap to be used.  I don’t know if that helps anyone else, but it was an epiphany for me!

One little trick that you need to be aware of is that you’ll need to "adjust" your texture coordinates after the chosen glTexGen() algorithm has generated them.  The algorithm will generate values in some range, such as -n .. +n and you’ll want to re-map that range to 0..1 or 0..r (for repeated textures.)  Otherwise, you’ll get garbage.  I call this "re-boxing" the coordinates instead of "normalization" since normalization tends to refer to reducing vectors to unit-length in OpenGL.  Here are some code fragments that do all of the above in an Oolong environment:

Here’s an implementation of glTxGen() OBJECT_LINEAR:

// Note that these algorithms come from:
// http://www.opengl.org/wiki/Mathematics_of_glTexGen

void texGenObjectLinear(GLfloat* buf, unsigned int stride, const btVector3 &sPlane, const btVector3 &tPlane) {
  // Loop through the vertices and operate on each one
  unsigned char* p = (unsigned char*)buf;

  for (unsigned int i=0; i < numVertices(); i++, p+=stride) {
    buf = (GLfloat*)p;
    const btVector3 vtx(vertex(i)[0], vertex(i)[1], vertex(i)[2]);
    buf[0] = vtx.dot(sPlane);
    buf[1] = vtx.dot(tPlane);
  }
} // computeTexObjectLinear()

As you can see, this is just a direct translation of the pseudo-code in the Mathematics of glTexGen() article, using the Bullet vector dot product.

Here is the implementation of the vertex() method for SPOD meshes:

virtual GLfloat* vertex(unsigned int i) {
  if (_pMesh->pInterleaved != NULL)
    return (GLfloat*)(_pMesh->pInterleaved+(size_t)_pMesh->sVertex.pData+i*_pMesh->sVertex.nStride);
  else
    return &((GLfloat*)(_pMesh->sVertex.pData))[i*_pMesh->sVertex.nStride];
} // vertex()

If you’ve loaded your meshes from a POD file, you can just call this as below (note that _pMesh is an SPODMesh* and texGenObjectLinearInPlace() will compute the new texcoords in-place, over-writing the texture coords in the SPOD data structure.)

GLfloat* uvArray() {
  if (_pMesh->pInterleaved != NULL)
    return (GLfloat*)(_pMesh->pInterleaved+(size_t)_pMesh->psUVW[0].pData);
  else
    return (GLfloat*)_pMesh->psUVW[0].pData;
} // uvArray()

// Recompute text coords in-place
void texGenObjectLinearInPlace(const btVector3 &sPlane, const btVector3 &tPlane) {
  this->texGenObjectLinear(uvArray(), _pMesh->psUVW[0].nStride, sPlane, tPlane);
} // texGenObjectLinearInPlace()

I ended up writing a general-purpose routine to "re-box" vertices.  Not pretty, and my brain tells me that it could be more elegant, but I haven’t figured out how yet.  Perhaps after I’m rested up…

void BMWDrawableObject::reBoxVertices(GLfloat* buf, unsigned int stride, unsigned int numVtx,
       unsigned int coordsPerVert, const btVector4 &min, const btVector4 &max) {
  // Calculate (in-place) the new vertices based on the min and max vertices passed in.
  GLfloat* pStart = buf;
  btVector4 minAccum(FLT_MAX, FLT_MAX, FLT_MAX, FLT_MAX);
  btVector4 maxAccum(FLT_MIN, FLT_MIN, FLT_MIN, FLT_MIN);

  // Compute the current nD bounding box
  unsigned char* p = (unsigned char*)pStart;
  for (unsigned int i=0; i < numVtx; i++, p+=stride) {
    buf = (GLfloat*)p;
    for (unsigned int j=0; j < coordsPerVert; j++) {
      minAccum[j] = (buf[j] < minAccum[j]) ? buf[j] : minAccum[j];
      maxAccum[j] = (buf[j] > maxAccum[j]) ? buf[j] : maxAccum[j];
    }
  }

  // Compute scale and offset to be used on each vertex.
  btVector4 offset(min[0]-minAccum[0], min[1]-minAccum[1], min[2]-minAccum[2], min[3]-minAccum[3]);
  btVector4 oD(maxAccum[0]-minAccum[0], maxAccum[1]-minAccum[1], maxAccum[2]-minAccum[2], maxAccum[3]-minAccum[3]);
  btVector4 nD(max[0]-min[0], max[1]-min[1], max[2]-min[2], max[3]-min[3]);
  btVector4 scale(nD[0]/oD[0], nD[1]/oD[1], nD[2]/oD[2], nD[3]/oD[3]);

  // Loop through and set the values.
  p = (unsigned char*)pStart;
  for (unsigned int i=0; i < numVtx; i++, p+=stride) {
    buf = (GLfloat*)p;
    for (unsigned int j=0; j < coordsPerVert; j++)
      buf[j] = (buf[j]+offset[j])*scale[j];
  }
} // reBoxVertices()

Putting it all together, imagine that I want to map a texture to a hemisphere.  The texture is projected from the XY plan. Here’s how I would call the above routines to accomplish that:

    // Generate new texcoords based on OBJECT_LINEAR algorithm
    // We are going to put the data right back into the Mesh's UV array.
    // (pDef is a pointer to an object with the SPODMesh* _pMesh.)
    pDef->texGenObjectLinearInPlace(btVector3(1,0,0), btVector3(0,1,0));
    // Normalize the UV coords such that the texture wraps all the way around.
    reBoxVertices(pDef->uvArray(), pDef->mesh()->psUVW[0].nStride, pDef->numVertices(),
                                   pDef->mesh()->psUVW[0].n, btVector4(0,0,0,0), btVector4(1,1,1,1));
    // Re-load the VBO since we've changed the data
    pDef->loadVBO();

Additional Texturing Resources

Cube Mapping

http://developer.nvidia.com/object/cube_map_ogl_tutorial.html (Uses OpenGL extensions not available to us, but explains the process.)

http://www.opengl.org/discussion_boards/ubbthreads.php?ubb=showflat&Number=247684

Spherical Mapping

http://nehe.gamedev.net/data/lessons/lesson.asp?lesson=23

Bump Mapping Tutorial

http://www.paulsprojects.net/tutorials/simplebump/simplebump.html

Sky Boxes in Blender

http://en.wikibooks.org/wiki/Blender_3D:_Noob_to_Pro/Build_a_skybox

Texture Sources

http://www.cgtextures.com/

What I was hoping for was a way to register a call-back with a rigid body such that my function or method would get called whenever the body collided with something.  Further, after working with the ray testing functionality, I was hoping for the same kind of filtering capabilities that the ray testing interface provides. Unfortunately, that functionality doesn’t quite exist, so you have to "roll your own" from what is provided.

The best reference on collision detection in Bullet is, I believe, this one .  After reading through this carefully and considering the options, I decided to use the first strategy, which is to simply loop through the manifolds at the end of each simulation cycle.  I quickly discovered that there were several issues I needed to deal with:

• A manifold will appear in the list and contain objects when there are no points of collision (getNumContacts() == 0) between the objects.  This surprised me!  Therefore, even though I didn’t care about the actual points of contact in my application, I needed to check the number of points and only register a collision if there were one or more.
• Objects may remain in contact for a number of cycles.  The behavior I wanted was to be notified when objects came into contact and again when they separated.  In order to achieve this, I had to implement some state in my objects that indicated what other objects they were in contact with.  I used STL sets for this purpose, as shown below…  (4/24/2009 — I have noticed that the B-Tree implementation underlying the STL set is showing up in profiling with lots of calls for allocation.  While this is not hurting the performance of my app yet, I expect that it will at some point.  I will probably end up optimizing the set implementation, probably through the use of a custom allocator.)

Here is the code for the collision detection method, which is called after each simulation cycle:

void BMWWorld::_detectCollisions() {
  // For information on collision detection using Bullet, see:
  // http://www.bulletphysics.com/mediawiki-1.5.8/index.php?title=Collision_Callbacks_and_Triggers
  //
  // Detect collisions and notify the objects involved.
  int numManifolds = this->numManifolds();
  BMWObjectSet *pNewNotifications = NULL;
  for (int i=0; i < numManifolds; i++) {
    btPersistentManifold* contactManifold = this->contactManifold(i);
    int numContacts = contactManifold->getNumContacts();
    if (numContacts > 0) {
      // We only notify the collision if there is a point of contact.  I suppose it's possible
      // to have really rapid, transient collisions that occurred during the simulation but
      // are still not in contact when the simulation step comes to an end.  I think our system
      // is slow enough that we can ignore these safely, but might want to keep an eye on this
      // as a future enhancement.
      // Call collision handlers for each object.
      btCollisionObject* obA = static_cast<btCollisionObject*>(contactManifold->getBody0());
      BMWObject* pObA = static_cast<BMWObject*>(obA->getUserPointer());
      btCollisionObject* obB = static_cast<btCollisionObject*>(contactManifold->getBody1());
      BMWObject* pObB = static_cast<BMWObject*>(obB->getUserPointer());
      pObA->_notifyCollision(pObB);
      pObB->_notifyCollision(pObA);
      if (pNewNotifications == NULL)
        pNewNotifications = new BMWObjectSet;
      pNewNotifications->insert(pObA);
      pNewNotifications->insert(pObB);
    }

    // The following code allows you to find out where the objects are in contact
    // with other.
//    	for (int j=0; j < numContacts; j++) {
//    		btManifoldPoint& pt = contactManifold->getContactPoint(j);
//
//    		btVector3 ptA = pt.getPositionWorldOnA();
//    		btVector3 ptB = pt.getPositionWorldOnB();
//    	}
//
//	// Clear all contact points out of the manifold cache
//    	contactManifold->clearManifold();
  }

  // All collisions reported.  Notify all objects in the previous notification set that we're done with
  // collision processing.  That way they can notify any handlers that collisions are complete.
  if (_pLastNotifySet != NULL) {
    BMWObjectSet::iterator itr;
    for (itr=_pLastNotifySet->begin(); itr != _pLastNotifySet->end(); itr++)
      (*itr)->_collisionDetectionComplete();
    delete _pLastNotifySet;
  }

  // Replace the notification set with the new notification set.
  _pLastNotifySet = pNewNotifications;
} // _detectCollisions()

I then simply created a pure virtual collision handler interface and implemented it for objects for which I need to be notified about collisions.  Here it is:

// Objects that need to handle collisions should derive from this and set
// the handler in the BMWObject.
class BMWCollision {
public:
  BMWCollision() {};
  virtual ~BMWCollision() {};

  // pObj is the object with which the collision has occurred.  This is called when
  // contact is first detected with the other object.
  virtual void handleCollision(BMWObject* pOther) = 0;

  // Called with the set of objects that we were in contact with that we're no longer
  // in contact with.  May be null or empty!
  virtual void collisionComplete(BMWObjectSet* pCollSet) = 0;
}; // class BMWCollision

This interface is used by the objects when they determine that a collision has occurred or been completed, as shown here:

void BMWObject::_notifyCollision(BMWObject* pObj) {
  if (_pCollHandler == NULL)
    return;

  // No collision processing if there is not a handler defined.
  // Do screening of collision notifications.  The handler is
  // only called if the "other" object is not in the LastCollSet.
  // The "other" object is always added to the NewCollSet.  When
  // all notifications are complete (the collisionDetectionComplete()
  // method is called), the objects that are in the LastCollSet but
  // not in the NewCollSet are sent to the handler.  This way the
  // handler can be appropriately called for both the detection of a
  // collision and also when the collision is complete.
  if (_pNewCollSet == NULL)
    _pNewCollSet = new BMWObjectSet;
  _pNewCollSet->insert(pObj);

  if ((_pLastCollSet == NULL) || (_pLastCollSet->count(pObj) == 0))
    _pCollHandler->handleCollision(pObj);
} // notifyCollision()

void BMWObject::_collisionDetectionComplete() {
  if (_pCollHandler == NULL)
    return;

  // Remove objects in the new collision set from the last collision set
  BMWObjectSet::iterator itr;
  if ((_pNewCollSet != NULL) && (_pLastCollSet != NULL)) {
    for (itr=_pNewCollSet->begin(); itr != _pNewCollSet->end(); itr++)
        _pLastCollSet->erase(*itr);
  }

  // Notify collision handler about objects we're no longer colliding with
  // (those remaining in the last set.)
  _pCollHandler->collisionComplete(_pLastCollSet);

  // Delete the old set and swap in the new set.
  delete _pLastCollSet;
  _pLastCollSet = _pNewCollSet;
  _pNewCollSet = NULL;
} // collisionDetectionComplete()

Again, if you see problems or improvements, please share with the rest of us!  This is definitely a learning process on my part!

I’m having so much fun coding, I’m having trouble finding the time to blog.  I promised the folks over on the Oolong list that I’d post some info on setting up an Xcode workspace for an Oolong project, though, so here it is.  Keep in mind that I’m new to XCode, so you guys that have been around longer please straighten me out on anything that looks incorrect.

First, let me explain why this matters.  Oolong is currently organized as a source tree with the examples embedded.  The examples simply refer directly to the Oolong files of interest by relative paths.  One would naturally like to use the examples as templates for new projects, but it’s difficult to get it to work unless you embed your project within Oolong alongside the examples.  Further, we’d like to put Oolong into our own SCM system (this makes managing updates easier, especially when local changes to Oolong are required) and we might have other "libraries" that we want to use as well.  Ideally, we’d like to create a project organization that looks something like this:

• Sandbox
  • Oolong
  • MyLibrary
  • MyProj1
  • MyProj2
  • OtherLibrary

Where MyLibrary and MyProj1 & 2 are dependent on the shared Oolong and possibly OtherLibrary, all of this managed in our SCM.

Here’s what I did, in a nutshell, with a few details to follow:

• First, I put Oolong and MyLibrary into our SCM alongside each other, as shown above.
• I pointed Xcode to these two "Source Trees", which effectively adds the equivalent of good old "environment variables" which can be referenced by your projects.  More on how to do this in a moment as it was not obvious.
• I created a project template from one of the Oolong examples, modifying it such that Oolong and MyLibrary are referenced through the environment variables.

There are several benefits to this approach.  First, my project isn’t in the Oolong tree, which is important to me.  Secondly, I can create any number of projects from my template and put them anywhere on my system and they’ll still be able to find Oolong and MyLibrary via the Source Tree references.  Thirdly, it makes setting up a new team member very easy.  They just check out the source to whatever folders they like, setup the Source Trees in Xcode, and away they go.

Here’s how to setup your Source Trees in Xcode.

1. Open XCode->Preferences and then click on the Source Trees button at the top.
2. Add (’+’ button under list box)
3. Choose a name for the tree (this name is a string that will be used an identifier, like an environment variable, I used "OOLONG_ROOT"), then "Oolong Root" as the Display Name (a human friendly name), then the path to your Oolong tree (/Users/paul/Sandbox/Oolong in my case.)  Note that these settings are available to all your projects as they’re part of the Xcode preferences, not project settings.  Each team member will have to set these up in their Xcode preferences as they are not shared.
4. Do the same thing for any other libraries (like MyLibrary in my example.)

Now that you’ve set up your source trees, you can reference them from your project.  There are two places where you’ll want to do this.  The first is in the folders (Xcode calls them "Groups") containing the sources.  The second is in the build settings where you’ll use them in header and, if necessary, library search paths.

Note that in the following, I’m assuming you’re starting with an Oolong example, such as "skeleton."

1. I would start by changing the Oolong folder name from "Classes" to "Oolong" or something.
2. Select the Oolong folder/group and click on the info button.  On the General tab, select the "Relative to Oolong Root" item from the Path Type chooser.
3. Click on "Choose" for the Path and select the folder where Oolong resides.  If everything is setup correctly, the path setting should change to "None" (because the path is relative to Oolong.)
4. The folders under the Oolong folder should be corrected as necessary.  I found that the "group" organization in the examples didn’t always match the organization on the file system, so I changed it to match the file system.  As a result, each folder and file path can be "Relative to Enclosing Group" and the Path will then match the file system folder name.  It just seems cleaner to me.

Note that as an alternative to these steps, you could also just delete the Classes folder in the example and use Add Existing Files to re-add it (choose recurse and set the reference relative to the OOLONG_ROOT source tree.)  If you use this approach, you will need to go through the Oolong hierarchy and delete stuff you don’t want in there (the compiler will help you identify this…)

Now, change the header search path:

1. From the Project menu select Edit Project Settings .
2. On the Build tab, select "All Configurations" and "All Settings".
3. Scroll down to "Search Paths"
4. In the Header Search Path field, change all the search paths that reference the Oolong location (probably by relative path, like ../../..) to "$(OOLONG_ROOT)" .  Here’s what mine looks like "$(OOLONG_ROOT)" "$(OOLONG_ROOT)/Bullet/src" "$(OOLONG_ROOT)/Math" "$(OOLONG_ROOT)/Include"
5. There really aren’t any libraries in Oolong that are used (currently everything’s just compiled together), but you could make similar changes to the Library Search Path.
6. Note that you’ll need to do the same thing for the Target.  What I would recommend is to set these at the Project level (as described), and for the target, simply use the value $(inherited).

Now, for the moment of truth: Build and see what smokes.  I would highly recommend starting with a project that you’ve already built successfully within Oolong (like one of the simpler examples.)  Build it and satisfy yourself that it works, then pull it out to the side and make the changes described above and build again.  (Be sure to do a Clean before you build so that there’s no old junk lying around.)  It’s hard for me to predict what kinds of problems you might run into, but hopefully you’ll be able to sort it out based on the error messages.  If not, leave a comment to this post with the question and I (or some other kind soul) will try to help.

Once you’ve got the project working, clean everything up and use it as a template from which to create other projects.  I’ve found that I can quickly create a new project from such a template by:

• Copying the template and renaming the copy to newProjName.
• Rename the *.xcodeproj file to newProjName.xcodeproj.
• In Xcode, open the new project, edit the build settings and for all configurations change the Product Name (under Packaging ) to newProjName.
• Edit the build settings for the target and make the same change.
• Under the Groups & Files window, rename the Targets as appropriate.

4/7/2009:  I have created a template from the FallingCubes example.  This template follows the rules above and can be used as a starting point for your projects.  The template also includes the necessary additional frameworks for audio.  Instructions for using the template are contained in the ReadMe.txt file.  I hope this will save you some time mucking with Xcode.

Download the template by clicking here.

4/27/2009: Updated template, removing the Graphics Services framework from the Frameworks group.  The Graphics Services framework is a private framework and may not be used in applications released to the AppStore.  Fortunately, it’s not needed!

4/30/2009: After some great discussion on performance tuning on the Oolong mailing list, I’ve updated the template with the "right" (or is it "better"?) compiler flags.  Be sure to check out the Oolong Performance thread for the last two days.  Also, if you’re interested in iPhone performance, be sure to check out this thread on the DevForum .

It would be best if Oolong were built as a "Framework" (pre-compiled sources in .a files with accompanying header files like the Apple frameworks) but I haven’t gone that far yet.  For the moment, the approach above is sufficient for my needs.  However, if the internal source organization of upcoming Oolong releases change, we’re  toast.  We’ll have to monkey with the structure of all of the projects that use Oolong.  Therefore, a logical "next step" is to make Oolong a Framework.  In fact, it would be great if the next release of Oolong was setup to build itself as a framework.  I’m willing to help…

I feel like I’ve probably made some errors and left things out.  Please don’t hesitate to correct me or let me know when there’s yet a better way!

Before I go on, I need to state that I’m a real noob myself and my needs at this point only include the creation of some meshes that I’m going to import into my application and then manage entirely there.  I haven’t yet had a need or chance to try out boned meshes or any of the animation features.  That being said, here are a few guidelines for developing your meshes in Blender with the intenion of importing them into an Oolong (PowerVR ) application as POD files.

• Go ahead and create your meshes in Blender, but recognize that rendering is going to be performed in your application, so don’t spend a lot of time trying to get it to look "just right" in the Blender renderer.
• You can set up initial light and camera locations in Blender.  These are imported in the POD file.
• Create and apply your materials in Blender.  Materials will be imported in the POD file (although I can’t find the Emission component yet.)
• Note that meshes with different materials on different faces will be split up into multiple meshes (with a single parent mesh.)  For instance, a cube with a different material on each face will be split up into 6 different meshes, one for each face.  Each of these "child" meshes will have a pointer to the parent node.  More on how to deal with this in Oolong later.
• Right now, I’m applying textures to textured surfaces as place-holders only.  This ensures that the UV coordinates are included in the interleaved vertex data.  In Oolong, textures are imported from PVR files, and I haven’t yet figured out a path from Blender texture to PVR.  If you can help out with this, please chime in!  The result is that you will have to figure out the right texture settings through experimentation.

Once you have your meshes built, you’ll want to do the export/import dance to get to POD.  Right now, it appears that the best path is from Blender to Collada 1.4 (via the Blender Export menu) then from Collada to POD via the PowerVR Collada2POD tool.  (Collada2POD is in the utilities folder of the PowerVR SDK distribution.)  Sorry, I couldn’t find a Mac OS-X version of the SDK, so I have to use a Windows PC for this step.  Here are the settings I’ve come up with for the export and import.

Export to Collada 1.4 Settings

• Set the geometry type to triangles.
• Don’t set anything else.  I tried messing with the "UV Image Materials" but didn’t find that useful.

That’s all.

Collada2POD Settings

• Under geometry options select (not all of these may be required, I didn’t experiment with dropping any out.):
  • Normals
  • Vertex Colors
  • Mapping Channels
  • Flip V
  • Interleave Vectors
• PowerVR documentation recommends sorted, indexed, triangle strips for performance, so I turned on
  • Sort vertices with PVRTTriStrip
  • Indexed Triangle List
• I haven’t selected anything special in the Vertex vector formats.
• The resulting POD file can be automatically opened in PVR Shaman for examination by simply setting up the path on the Post-Export tab.

I used the Shadowing example as the template for how to load POD and PVR texture files.  Here are a few notes on what I’ve discovered:

• A "SPODNode" is created for each instance of a mesh, the camera and light, and each parent node (for composite meshes.)  The Node has a link to it’s defining mesh, a transform, and a link to it’s SPODMaterial.
• A "SPODMesh" is created for each mesh and contains the interleaved, indexed, vertex data.
• You can draw the children of  "composite" nodes ad-hoc if you like, because the GetWorldMatrix( ) methods automatically multiply by the parent’s transform matrix.  However, if you’re doing physics, you’ll want to treat them as a unit (a single btCollisionShape for the composite node.)
• As mentioned before the Emission component of materials doesn’t come through, so I’m having handle that manually in my application.
• Again, I haven’t figured out how to get textures directly from Blender to PVR.  I’m handling them separately.  Create your texture externally, use it in Blender and convert it to PVR for use in your application and fiddle to get things right.  (If you’ve got a better way, please tell us noobs about it!)
• April 24, 2009 — Discovered that if you have a material assigned to an object, and you have also assigned materials to faces, but the material assigned to the object is not used on any of the faces, the Collada exporter will crash.  Make sure that all materials assigned to an object in blender are actually used.  Delete any that are unused before attempting to export.

Note that there has been some recent discussion of this same topic on the Oolong mailing list, so I really recommend getting hooked up to that.  In particular, there is someone there working on a direct Blender reader (into the ModelPOD structures), and mention of a blender reader in the Bullet physics toolkit.  So, there may be more direct methods of using your Blender models in Oolong soon.

I’d really like to thank Wolfgang Engel, the PowerVR folks, the Bullet Physics team, and the rest of the Oolong contributors.  My early efforts are showing excellent performance on the device and I’m having a blast with the programming.  I don’t know where things are headed next for Oolong, but it can only get better!

It’s definitely been a new frontier for me.  After years and years of large application development in the computer aided engineering fields on *NIX and Windows platforms, much is new:

• The Mac development platform
• Objective-C
• 3D Graphics
• Small, lightweight programs
• Touch UI
• A different kind of user

My bookshelves are full of books that are not relevant.  My office has 4 Windows machines and 2 Sun Ultra-Sparc Solaris computers.  I obviously have a major transition to make.  But, I know how to develop quality software.

To bootstrap ourselves, Dean and I did a lot of up-front reading.  There are many helpful blogs out there for newbs like ourselves.  One we found particularly useful is by Craig Hockenberry over on furbo.org .

Step 1 — Sign up on the Apple iPhone developer site and start reading.

This step was easy.  There is a wealth of information on the Apple Developer Connection web site.  I spent some serious time with the materials on the web site relevant to the Cocoa SDK, the iPhone software architecture, Objective-C, and XCode.  I’ve spent 20 years with C++ so Objective-C looks pretty weird, but I can certainly understand the motivation for some of the differences.  Apple has definitely built themselves an island with this one!  (Later I learned that I can use Objective-C++ and I now feel right at home.)

Step 2 — Buy a Mac.

After spending some serious time on eBay, I found a Buy It Now Macbook with 13" display, 2GHz, and 1GB of RAM for $650 with shipping.  I’m used to buying cheap Windows laptops, so the cost of a Macbook was a bit shocking (I saw a Macbook Pro that had had Gatorade spilled in it go at auction for over $700!) but $650 was certainly acceptable.  When I received the Macbook, it was nearly pristine.  In fact, I am so happy with the quality and rapid service that I want to put in a plug for Beta Macs in Denver.  Check out their eBay store as well if you’re looking for a Macbook to get started with.

I read that for development at least 2GB of memory was advised, so I picked up 4GB of RAM from Tiger Direct for $50 along with a 250GB 2.5" USB drive for extra storage and backups.

The Macbook was instantly loved at our house.  My 12 year old daughter now wants one, even though she has a Gateway dual-core X64 Windows laptop that she uses.  My 16 yr old son thinks it’s cool and likes Garage Band.  I like it, and I especially like having the Bash command-line and *NIX functionality at my fingertips without loading CygWin.  In fact, I’m totally in love with Mac OS-X for that reason.  Basing it on UNIX was brilliant.

Step 3 — Download the iPhone SDK and watch videos.

Downloading and installing the iPhone SDK was a breeze.  I also spent most of a day watching the iPhone tutorial videos on iTunes.  This is time well spent just to learn all the new terminology.

Step 4 — More Research.

One of the first applications I want to develop is a game where I’ll be employing some 3D graphics.  As I looked at OpenGL-ES and the rest of the SDK, it became apparent that the graphics SDK was pretty primitive (Cocoa has lots of the stuff you need for UI programming, but OpenGL is just a ‘C’ API and definitely needs some OO stuff around it.)  Before I tore off and re-invented the wheel, I did some research to see what others have done.  Here’s what I found:

• OpenGL C++ Toolkit – A C++ library and toolkit for OpenGL.  Probably couldn’t be used "out of the box" but could probably be ported without too much trouble (if it hasn’t happened already).
• Open Scene Graph – An Open Source scene graph SDK for OpenGL.  Looks very powerful and, again, could probably be ported in whole or in part.  Significant overkill for the applications I’m currently imagining.
• Oolong iPhone Game Engine — Now we’re talking.  A 3D graphics toolkit over OpenGL ES, based on the PowerVR SDK , with the Bullet physics library integrated.  (Note that this effort is still pretty young, so there isn’t a lot of documentation with the kit, but it is usable.  Be sure to also download the PowerVR SDK for both the tools and documentation.)  The jury is out as to the performance of this beast on the device, but it is a great starting point.  I hope to contribute to the project over time.

With Oolong, I think I’ve found the giant I want to stand on.  I’d much rather contribute to an infant effort than re-invent the wheel.

Step 5 — Setup a web site.

This obviously doesn’t get us any closer to having an iPhone app, but Dean and I felt it important to get a blog, web site, and source code management system setup as early as possible.  We’re both most familiar with CVS (I’ve used it for over 15 years) but decided to go with Subversion for it’s features.  I can setup a CVS repository on a server in about 5 minutes.  Setting up Subversion took me a long time.  It seems to be working well, however, and we’ll see how things go long term.  We can always fall back to CVS if we need to.  If you need pointers on setting up Subversion on a Plesk managed server, maybe I can help.  It wasn’t as hard as I made it!  The XCode integration looks pretty good, and I dowloaded a trial copy of the SmartSVN client as well for it’s tag and branch features.

The web site is simple at this point.  We’ll be expanding it as we have applications to push and things to share.  This blog will be our primary means of communication.

Step 6 — Start coding.

Yeah!  Finally.  After some serious coding, I’ve decided I really like XCode.  I haven’t poked into everything yet, but I’m getting the hang of it and it’s working really well.  Most of the coding I’m doing right now is in C++ around OpenGL and Oolong.  Results are coming fast now, although I still have a whole lot to learn before I’ve got a complete application.

Next Step — Acquire a device.

Yep, haven’t done that yet.  Right now I’m running in the simulator which works pretty well but doesn’t give you the feel of the device at all, especially for accelerometer stuff.  Even the touch interactions are very different.  I’m particularly concerned about the performance of Oolong given all the floating point computations.  I should have a device (I’m starting with an iPod Touch) next weekend, and then I’ve got to pay my $99 and get the provisioning stuff together.

Lots to do, but I’m having a lot of fun!  Makes me feel young again.

paul