Figure 5.1. Textured Model Viewer

Our final enhancement to Model Viewer wraps a simple grid texture around each of the surfaces in the parametric gallery, as seen in Figure 5.1, “Textured Model Viewer”. We only need to store one cell of the grid in an image file; OpenGL can repeat the source pattern as many times as desired.

The image file can be in a number of different file formats, but we'll go with PNG for now. It's popular because it supports an optional alpha channel, lossless compression, and variable color precision. (Another common format on the iPhone platform is PVR, which we'll cover later in the chapter.)

You can either download the image file for the grid cell from the book's companion site, or create one using your favorite paint or graphics program. I used a tiny 16x16 white square with a 1-pixel black border. Save the file as Grid16.png.

Since we'll be loading a resource file from an external file, let's use the OBJ-loading sample from the last chapter as the starting point. To keep things simple, the first step is rewinding a bit and using parametric surfaces exclusively. Simply revert the ApplicationEngine::Initialize() method so that it uses the sphere and cone shapes. To do this, find the following code:

string path = m_resourceManager->GetResourcePath();
surfaces[0] = new ObjSurface(path + "/micronapalmv2.obj");
surfaces[1] = new ObjSurface(path + "/Ninja.obj");

And replace it with:

surfaces[0] = new Cone(3, 1);
surfaces[1] = new Sphere(1.4f);

Keep everything else the same. We'll enhance the IResourceManager interface later to support image loading.

Next you need to add the actual image file to your Xcode project. As with the OBJ files in the previous chapter, Xcode automatically deploys these resources to your iPhone. Even though this example has only a single image file, I recommend creating a dedicated group anyway. Right-click the ModelViewer root in the Overview pane, choose Add→New Group, and call it "Textures". Right-click the new group, and choose Get Info. To the right of the "Path" label on the General tab, click Choose and create a New Folder called Textures. Click Choose and close the group info window.

Right-click the new group and choose Add→Existing Files. Select the PNG file, click Add, and in the next dialog box, make sure the "Copy items" checkbox is checked and click Add.

struct IResourceManager {
    virtual string GetResourcePath() const = 0;
    virtual void LoadPngImage(const string& filename) = 0;virtual void* GetImageData() = 0;virtual ivec2 GetImageSize() = 0;virtual void UnloadImage() = 0;
    virtual ~IResourceManager() {}
};

// ...
namespace ES1 { IRenderingEngine* 
                CreateRenderingEngine(IResourceManager* resourceManager); }
namespace ES2 { IRenderingEngine* 
                CreateRenderingEngine(IResourceManager* resourceManager); }

class ResourceManager : public IResourceManager {
public:
    string GetResourcePath() const
    {
        NSString* bundlePath =[[NSBundle mainBundle] resourcePath];
        return [bundlePath UTF8String];
    }
    void LoadPngImage(const string& name)
    {
        NSString* basePath = [NSString stringWithUTF8String:name.c_str()];
        NSString* resourcePath = [[NSBundle mainBundle] resourcePath];
        NSString* fullPath = [resourcePath stringByAppendingPathComponent:basePath];
        UIImage* uiImage = [UIImage imageWithContentsOfFile:fullPath];
        CGImageRef cgImage = uiImage.CGImage;
        m_imageSize.x = CGImageGetWidth(cgImage);
        m_imageSize.y = CGImageGetHeight(cgImage);
        m_imageData = CGDataProviderCopyData(CGImageGetDataProvider(cgImage));
    }
    void* GetImageData()
    {
        return (void*) CFDataGetBytePtr(m_imageData);
    }
    ivec2 GetImageSize()
    {
        return m_imageSize;
    }
    void UnloadImage()
    {
        CFRelease(m_imageData);
    }
private:
    CFDataRef m_imageData;
    ivec2 m_imageSize;
};

m_resourceManager = CreateResourceManager();

if (api == kEAGLRenderingAPIOpenGLES1) {
    NSLog(@"Using OpenGL ES 1.1");
    m_renderingEngine = ES1::CreateRenderingEngine(m_resourceManager);
} else {
    NSLog(@"Using OpenGL ES 2.0");
    m_renderingEngine = ES2::CreateRenderingEngine(m_resourceManager);
}

m_applicationEngine = CreateApplicationEngine(m_renderingEngine, 
                                              m_resourceManager);

#include "Interfaces.hpp"

struct ParametricInterval {
    ivec2 Divisions;
    vec2 UpperBound;
    vec2 TextureCount;
};

class ParametricSurface : public ISurface {
...
private:
    vec2 ComputeDomain(float i, float j) const;
    ivec2 m_slices;
    ivec2 m_divisions;
    vec2 m_upperBound;
    vec2 m_textureCount;
};

#include "ParametricSurface.hpp"

class Cone : public ParametricSurface {
public:
    Cone(float height, float radius) : m_height(height), m_radius(radius)
    {
        ParametricInterval interval = { ivec2(20, 20), vec2(TwoPi, 1), vec2(30,20) };
        SetInterval(interval);
    }
    ...
};

class Sphere : public ParametricSurface {
public:
    Sphere(float radius) : m_radius(radius)
    {
        ParametricInterval interval = { ivec2(20, 20), vec2(Pi, TwoPi), vec2(20, 35) };
        SetInterval(interval);
    }
    ...
};

void ParametricSurface::SetInterval(const ParametricInterval& interval)
{
    m_divisions = interval.Divisions;
    m_slices = m_divisions - ivec2(1, 1);
    m_upperBound = interval.UpperBound;
    m_textureCount = interval.TextureCount;
}

...

void ParametricSurface::GenerateVertices(vector<float>& vertices,
                                         unsigned char flags) const
{
    int floatsPerVertex = 3;
    if (flags & VertexFlagsNormals)
        floatsPerVertex += 3;
    if (flags & VertexFlagsTexCoords)
        floatsPerVertex += 2;

    vertices.resize(GetVertexCount() * floatsPerVertex);
    float* attribute = &vertices[0];

    for (int j = 0; j < m_divisions.y; j++) {
        for (int i = 0; i < m_divisions.x; i++) {

            // Compute Position
            vec2 domain = ComputeDomain(i, j);
            vec3 range = Evaluate(domain);
            attribute = range.Write(attribute);

            // Compute Normal
            if (flags & VertexFlagsNormals) {
                ...
            }
            
            // Compute Texture Coordinates
            if (flags & VertexFlagsTexCoords) {
                float s = m_textureCount.x * i / m_slices.x;
                float t = m_textureCount.y * j / m_slices.y;
                attribute = vec2(s, t).Write(attribute);
            }
        }
    }
}

float s = m_textureCount.x * i / m_slices.x;
float t = m_textureCount.y * j / m_slices.y;

class RenderingEngine : public IRenderingEngine {
public:
    RenderingEngine(IResourceManager* resourceManager);
    void Initialize(const vector<ISurface*>& surfaces);
    void Render(const vector<Visual>& visuals) const;
private:
    vector<Drawable> m_drawables;
    GLuint m_colorRenderbuffer;
    GLuint m_depthRenderbuffer;
    mat4 m_translation;
    GLuint m_gridTexture;
    IResourceManager* m_resourceManager;
};
    
IRenderingEngine* CreateRenderingEngine(IResourceManager* resourceManager)
{
    return new RenderingEngine(resourceManager);
}

RenderingEngine::RenderingEngine(IResourceManager* resourceManager)
{
    m_resourceManager = resourceManager;
    glGenRenderbuffersOES(1, &m_colorRenderbuffer);
    glBindRenderbufferOES(GL_RENDERBUFFER_OES, m_colorRenderbuffer);
}

void RenderingEngine::Initialize(const vector<ISurface*>& surfaces)
{
    vector<ISurface*>::const_iterator surface;
    for (surface = surfaces.begin(); surface != surfaces.end(); ++surface) {

        // Create the VBO for the vertices.
        vector<float> vertices;
        (*surface)->GenerateVertices(vertices, VertexFlagsNormals
                                     |VertexFlagsTexCoords);

    // ...

    // Load the texture.
    glGenTextures(1, &m_gridTexture);glBindTexture(GL_TEXTURE_2D, m_gridTexture);
    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);

    m_resourceManager->LoadPngImage("Grid16.png");void* pixels = m_resourceManager->GetImageData();
    ivec2 size = m_resourceManager->GetImageSize();
    glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, size.x, 
                 size.y, 0, GL_RGBA, GL_UNSIGNED_BYTE, pixels);m_resourceManager->UnloadImage();

    // Set up various GL state.
    glEnableClientState(GL_VERTEX_ARRAY);
    glEnableClientState(GL_NORMAL_ARRAY);
    glEnableClientState(GL_TEXTURE_COORD_ARRAY);
    glEnable(GL_LIGHTING);
    glEnable(GL_LIGHT0);
    glEnable(GL_DEPTH_TEST);
    glEnable(GL_TEXTURE_2D);

    ...
}

void glTexImage2D(GLenum target, GLint level, GLint internalformat,
                  GLsizei width, GLsizei height, GLint border,
                  GLenum format, GLenum type, const GLvoid* pixels); 

void RenderingEngine::Render(const vector<Visual>& visuals) const
{
    glClearColor(0.5f, 0.5f, 0.5f, 1);
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
    
    vector<Visual>::const_iterator visual = visuals.begin();
    for (int visualIndex = 0; 
         visual != visuals.end(); 
         ++visual, ++visualIndex) 
    {

        // ...

        // Draw the surface.
        int stride = sizeof(vec3) + sizeof(vec3) + sizeof(vec2);
        const GLvoid* texCoordOffset = (const GLvoid*) (2 * sizeof(vec3));
        const Drawable& drawable = m_drawables[visualIndex];
        glBindBuffer(GL_ARRAY_BUFFER, drawable.VertexBuffer);
        glVertexPointer(3, GL_FLOAT, stride, 0);
        const GLvoid* normalOffset = (const GLvoid*) sizeof(vec3);
        glNormalPointer(GL_FLOAT, stride, normalOffset);
        glTexCoordPointer(2, GL_FLOAT, stride, texCoordOffset);
        glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, drawable.IndexBuffer);
        glDrawElements(GL_TRIANGLES, drawable.IndexCount, GL_UNSIGNED_SHORT, 0);
    }
}

glDeleteTextures(1, &m_gridTexture)

attribute vec4 Position;
attribute vec3 Normal;
attribute vec3 DiffuseMaterial;
attribute vec2 TextureCoord;

uniform mat4 Projection;
uniform mat4 Modelview;
uniform mat3 NormalMatrix;
uniform vec3 LightPosition;
uniform vec3 AmbientMaterial;
uniform vec3 SpecularMaterial;
uniform float Shininess;

varying vec4 DestinationColor;
varying vec2 TextureCoordOut;

void main(void)
{
    vec3 N = NormalMatrix * Normal;
    vec3 L = normalize(LightPosition);
    vec3 E = vec3(0, 0, 1);
    vec3 H = normalize(L + E);

    float df = max(0.0, dot(N, L));
    float sf = max(0.0, dot(N, H));
    sf = pow(sf, Shininess);

    vec3 color = AmbientMaterial + df * DiffuseMaterial + sf * SpecularMaterial;
    
    DestinationColor = vec4(color, 1);
    gl_Position = Projection * Modelview * Position;
    TextureCoordOut = TextureCoord;
}

TextureCoordOut = gl_Position.xy * 2.0;

varying lowp vec4 DestinationColor;
varying mediump vec2 TextureCoordOut;

uniform sampler2D Sampler;

void main(void)
{
    gl_FragColor = texture2D(Sampler, TextureCoordOut) * DestinationColor;
}

glBindTexture(GL_TEXTURE_2D, textureHandle);
GLint location = glGetUniformLocation(programHandle, "Sampler");

glUniform1i(location, textureHandle); // incorrect
glUniform1i(location, 0); // correct

struct AttributeHandles {
    GLint Position;
    GLint Normal;
    GLint Ambient;
    GLint Diffuse;
    GLint Specular;
    GLint Shininess;
    GLint TextureCoord;
};

...

void RenderingEngine::Initialize(const vector<ISurface*>& surfaces)
{

    vector<ISurface*>::const_iterator surface;
    for (surface = surfaces.begin(); surface != surfaces.end(); ++surface) {

        // Create the VBO for the vertices.
        vector<float> vertices;
        (*surface)->GenerateVertices(vertices, VertexFlagsNormals|VertexFlagsTexCoords);

    // ...
    
    m_attributes.TextureCoord = glGetAttribLocation(program, "TextureCoord");

    // Load the texture.
    glGenTextures(1, &m_gridTexture);
    glBindTexture(GL_TEXTURE_2D, m_gridTexture);
    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);

    m_resourceManager->LoadPngImage("Grid16.png");
    void* pixels = m_resourceManager->GetImageData();
    ivec2 size = m_resourceManager->GetImageSize();
    glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, size.x, 
                 size.y, 0, GL_RGBA, GL_UNSIGNED_BYTE, pixels);
    m_resourceManager->UnloadImage();

    // Initialize various state.
    glEnableVertexAttribArray(m_attributes.Position);
    glEnableVertexAttribArray(m_attributes.Normal);
    glEnableVertexAttribArray(m_attributes.TextureCoord);
    glEnable(GL_DEPTH_TEST);

    ...
}

void RenderingEngine::Render(const vector<Visual>& visuals) const
{
    glClearColor(0.5f, 0.5f, 0.5f, 1);
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

    vector<Visual>::const_iterator visual = visuals.begin();
    for (int visualIndex = 0; 
         visual != visuals.end(); 
         ++visual, ++visualIndex) 
    {

        // ...

        // Draw the surface.
        int stride = sizeof(vec3) + sizeof(vec3) + sizeof(vec2);
        const GLvoid* normalOffset = (const GLvoid*) sizeof(vec3);
        const GLvoid* texCoordOffset = (const GLvoid*) (2 * sizeof(vec3));
        GLint position = m_attributes.Position;
        GLint normal = m_attributes.Normal;
        GLint texCoord = m_attributes.TextureCoord;
        const Drawable& drawable = m_drawables[visualIndex];
        glBindBuffer(GL_ARRAY_BUFFER, drawable.VertexBuffer);
        glVertexAttribPointer(position, 3, GL_FLOAT, GL_FALSE, stride, 0);
        glVertexAttribPointer(normal, 3, GL_FLOAT, GL_FALSE, stride, normalOffset);
        glVertexAttribPointer(texCoord, 2, GL_FLOAT, GL_FALSE, stride, texCoordOffset);
        glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, drawable.IndexBuffer);
        glDrawElements(GL_TRIANGLES, drawable.IndexCount, GL_UNSIGNED_SHORT, 0);
    }
}

Recall that texture coordinates are defined such that (0,0) is the lower-left corner and (1,1) is the upper-right corner. So what happens when a vertex has texture coordinates that lie outside this range? The sample code is actually already sending coordinates outside this range. For example, the TextureCount parameter for the sphere is (20,35).

By default, OpenGL simply repeats the texture at every integer boundary; it lops off the integer portion of the texture coordinate before sampling the texel color. If you want to make this behavior explicit, you can add something like this to the rendering engine code:

glBindTexture(GL_TEXTURE_2D, m_gridTexture);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_REPEAT);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_REPEAT);

The wrap mode passed in to the third argument of glTexParameteri can be one of the following:

The three wrap modes are depicted in Figure 5.2, “Four Texture Wrap Configurations”. From left to right: repeat, clamp-to-edge, and mirrored. The figure on the far right uses GL_REPEAT for the S coordinate and GL_CLAMP_TO_EDGE for the T coordinate.

Figure 5.2. Four Texture Wrap Configurations

What would you do if you wanted to animate your texture coordinates? For example, say you want to gradually move the grasshoppers in Figure 5.2, “Four Texture Wrap Configurations” so that they scroll around the Möbius strip. You certainly wouldn't want to upload a new VBO at every frame with updated texture coordinates; that would detrimental to performance. Instead you would set up a texture matrix. Texture matrices were briefly mentioned in the section called “Saving and Restoring Transforms with Matrix Stacks”, and they're configured much the same way as the model-view and projection matrices. The only difference is that they're applied to texture coordinates rather than vertex positions. The following snippet shows how you'd set up a texture matrix with ES 1.1 (with ES 2.0, there's no built-in texture matrix, but it's easy to create one with a uniform variable).

glMatrixMode(GL_TEXTURE);
glTranslatef(grasshopperOffset, 0, 0);

In this book, we use the convention that (0,0) maps to the upper-left of the source image (Figure 5.3, “Texture Coordinates in a 4x4 Texture”), and that the Y coordinate increases downwards.

By the way, saying that (1,1) maps to a texel at the far corner of the texture image isn't a very accurate statement; the corner texel's center is actually a fraction, as seen in Figure 5.3, “Texture Coordinates in a 4x4 Texture”. This may seem pedantic, but you'll see how it's relevant when we cover filtering, which comes next.

Figure 5.3. Texture Coordinates in a 4x4 Texture

Is a texture a collection of discrete texels, or is it a continuous function across [0, 1]? This is a dangerous question to ask a graphics geek; it's a bit like asking a physicist if a photon is a wave or a particle.

When you upload a texture to OpenGL using glTexImage2D, it's a collection of discrete texels. When you sample a texture using normalized texture coordinates, it's a bit more like a continuous function. You might recall these two lines from the rendering engine:

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);

What's going on here? The first line sets the minification filter; the second line sets the magnification filter. Both of these tell OpenGL how to map those discrete texels into a continuous function.

More precisely, the minification filter specifies the scaling algorithm to use when the texture size in screen space is smaller than the original image; the magnification filter tells OpenGL what to do when the texture size is screen space is larger than the original image.

The magnification filter can be one of two values:

Figure 5.4. Bilinear Texture Filtering. From left to right: original, minified, magnified.

The minification filter supports the same filters as magnification, and adds four additional filters that rely on mipmaps, which are "pre-shrunk" images that you need to upload separately from the main image. More on mipmaps soon.

The available minification modes are:

A comparison of various filtering schemes is shown in Figure 5.5, “Texture filters. From top to bottom: nearest, bilinear, and trilinear.”.

Figure 5.5. Texture filters. From top to bottom: nearest, bilinear, and trilinear.

Deciding on a filter is a bit of a black art; personally I often start with trilinear filtering (GL_LINEAR_MIPMAP_LINEAR), and I try cranking down to a lower-quality filter only when I'm optimizing my frame rate. Note that GL_NEAREST is perfectly acceptable in some scenarios; for example, when rendering 2D quads that have the same size as the source texture.

First and second generation devices have some restrictions on the filters:

This isn't a big deal since you'll almost never want a different same-level filter for magnification and minification. Nevertheless it's important to note that the iPhone simulator and newer devices do not have these restrictions.

Boosting Quality and Performance with Mipmaps

Mipmaps help with both quality and performance. They can help with performance especially when large textures are viewed from far away. Since the graphics hardware performs sampling on an image potentially much smaller than the original, it's more likely to have the texels available in a nearby memory cache. Mipmaps can improve quality for several reasons; most importantly, they effectively cast a wider net, so the final color is less likely to be missing contributions from important nearby texels.

In OpenGL, mipmap zero is the original image, and every following level is half the size of the preceding level. If a level has an odd size, then the floor function is used, as in Equation 5.1, “Mipmap Sizes”.

Equation 5.1. Mipmap Sizes

Watch out though, sometimes you need to ensure that all mipmap levels have an even size. In another words, the original texture must have dimensions that are powers of two. We'll discuss this further later in the chapter. Figure 5.6, “Mipmap visualization.” depicts a popular way of neatly visualizing mipmaps levels into an area that's 1.5 times the original width.

Figure 5.6. Mipmap visualization.

To upload the mipmaps levels to OpenGL, you need to make a series of separate calls to glTexImage2D, from the original size all the way down to the 1x1 mipmap:

glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, 16, 16, 0, GL_RGBA, GL_UNSIGNED_BYTE, pImageData0);
glTexImage2D(GL_TEXTURE_2D, 1, GL_RGBA, 8, 8, 0, GL_RGBA,
             GL_UNSIGNED_BYTE, pImageData1);
glTexImage2D(GL_TEXTURE_2D, 2, GL_RGBA, 4, 4, 0, GL_RGBA,
             GL_UNSIGNED_BYTE, pImageData2);
glTexImage2D(GL_TEXTURE_2D, 3, GL_RGBA, 2, 2, 0, GL_RGBA,
             GL_UNSIGNED_BYTE, pImageData3);
glTexImage2D(GL_TEXTURE_2D, 4, GL_RGBA, 1, 1, 0, GL_RGBA,
             GL_UNSIGNED_BYTE, pImageData4);

Usually code like this occurs in a loop. Many OpenGL developers like to use a right-shift as a sneaky way of halving the size at each iteration. I doubt it really buys you anything, but it's great fun:

for (int level = 0; 
     level < description.MipCount; 
     ++level, width >>= 1, height >>= 1, ppData++)
{
    glTexImage2D(GL_TEXTURE_2D, level, GL_RGBA, width, height, 
                 0, GL_RGBA, GL_UNSIGNED_BYTE, *ppData);
}

If you'd like to avoid the tedium of creating mipmaps and loading them in individually, OpenGL ES can generate mipmaps on your behalf:

// OpenGL ES 1.1
glTexParameteri(GL_TEXTURE_2D, GL_GENERATE_MIPMAP, GL_TRUE);
glTexImage2D(GL_TEXTURE_2D, 0, ...);

// OpenGL ES 2.0
glTexImage2D(GL_TEXTURE_2D, 0, ...);
glGenerateMipmap(GL_TEXTURE_2D);

In ES 1.1, mipmap generation is part of the OpenGL state associated with the current texture object, and you should enable it before uploading level zero. In ES 2.0, mipmap generation is an action that you take after you upload level zero.

You might be wondering why you'd ever want to provide mipmaps explicitly when you can just have OpenGL generate them for you. There are actually a couple reasons for this:

• There's a performance hit for mipmap generation at upload time. This could prolong your application's startup time, which is something all good iPhone developers obsess about.

• When OpenGL performs mipmap generation for you, you're (almost) at the mercy of whatever filtering algorithm it chooses. You can often produce higher-quality results if you provide mipmaps yourself, especially if you have a very high-resolution source image, or a vector-based source.

Later we'll learn about a couple free tools that make it easy to supply OpenGL with ready-made, pre-shrunk mipmaps.

By the way, you do have some control over the mipmap generation scheme that OpenGL uses. The following lines are valid with both ES 1.1 and 2.0:

glHint(GL_GENERATE_MIPMAP_HINT, GL_FASTEST);
glHint(GL_GENERATE_MIPMAP_HINT, GL_NICEST);
glHint(GL_GENERATE_MIPMAP_HINT, GL_DONT_CARE); // this is the default

Tweaking Which Levels Are Sampled

If you're a control freak and you'd like to tweak the way OpenGL chooses mipmap levels to sample from, you'll be glad to hear the iPhone supports an extension that can shift which mipmap level(s) get sampled. This is useful for intentional blurring or pseudo-sharpening. For more information, head over to the extension registry on the Khronos site:

http://www.khronos.org/registry/gles/extensions/EXT/texture_lod_bias.txt

This is an ES 1.1 extension only; it's not necessary for ES 2.0 because you can bias the mipmap level from within the fragment shader using an optional third argument to texture2D. The full function signature looks like this:

vec4 texture2D(sampler2D sampler, vec2 coord, float bias = 0)

Incidentally, don't confuse texture2D, which is a shader function for sampling, and glTexImage2D, which a C function for uploading.

glGenTextures(1, &m_gridTexture);
glBindTexture(GL_TEXTURE_2D, m_gridTexture);
glTexParameteri(GL_TEXTURE_2D, GL_GENERATE_MIPMAP, GL_TRUE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR_MIPMAP_LINEAR); 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
// ...
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, size.x,
             size.y, 0, GL_RGBA, GL_UNSIGNED_BYTE, pixels);

glGenTextures(1, &m_gridTexture);
glBindTexture(GL_TEXTURE_2D, m_gridTexture);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR_MIPMAP_LINEAR); 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
// ...
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, size.x, 
             size.y, 0, GL_RGBA, GL_UNSIGNED_BYTE, pixels);
glGenerateMipmap(GL_TEXTURE_2D);

Recall that two of the parameters to glTexImage2D stipulate format, and one stipulates type, highlighted in bold here:

glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, 16, 16, 0, 
             GL_RGBA, GL_UNSIGNED_BYTE, pImageData0);

The allowed formats are:

Don't dismiss the non-RGB formats; if you don't need color, you can save significant memory with the one or two-component formats.

The type parameter in glTexImage2D can be one of these:

It's also interesting to note the various formats supported by the PNG file format, even though this has nothing to do with OpenGL:

enum TextureFormat {
    TextureFormatGray,
    TextureFormatGrayAlpha,
    TextureFormatRgb,
    TextureFormatRgba,
};

struct TextureDescription {
    TextureFormat Format;
    int BitsPerComponent;
    ivec2 Size;
};

struct IResourceManager {
    virtual string GetResourcePath() const = 0;
    virtual TextureDescription LoadPngImage(const string& filename) = 0;
    virtual void* GetImageData() = 0;
    virtual void UnloadImage() = 0;
    virtual ~IResourceManager() {}
};

TextureDescription LoadPngImage(const string& file)
{
    NSString* basePath = [NSString stringWithUTF8String:file.c_str()];
    NSString* resourcePath = [[NSBundle mainBundle] resourcePath];
    NSString* fullPath = [resourcePath stringByAppendingPathComponent:basePath];

    NSLog(@"Loading PNG image %s...", fullPath);

    UIImage* uiImage = [UIImage imageWithContentsOfFile:fullPath];
    CGImageRef cgImage = uiImage.CGImage;
    m_imageData = CGDataProviderCopyData(CGImageGetDataProvider(cgImage));

    TextureDescription description;
    description.Size.x = CGImageGetWidth(cgImage);
    description.Size.y = CGImageGetHeight(cgImage);
    bool hasAlpha = CGImageGetAlphaInfo(cgImage) != kCGImageAlphaNone;
    CGColorSpaceRef colorSpace = CGImageGetColorSpace(cgImage);
    switch (CGColorSpaceGetModel(colorSpace)) {
        case kCGColorSpaceModelMonochrome:
            description.Format = 
              hasAlpha ? TextureFormatGrayAlpha : TextureFormatGray;
            break;
        case kCGColorSpaceModelRGB:
            description.Format = 
              hasAlpha ? TextureFormatRgba : TextureFormatRgb;
            break;
        default:
            assert(!"Unsupported color space.");
            break;
    }
    description.BitsPerComponent = CGImageGetBitsPerComponent(cgImage);

    return description;
}

private:
    void SetPngTexture(const string& name) const;
    // ...
    
void RenderingEngine::SetPngTexture(const string& name) const
{
    TextureDescription description = m_resourceManager->LoadPngImage(name);
    
    GLenum format;
    switch (description.Format) {
        case TextureFormatGray:      format = GL_LUMINANCE;       break;
        case TextureFormatGrayAlpha: format = GL_LUMINANCE_ALPHA; break;
        case TextureFormatRgb:       format = GL_RGB;             break;
        case TextureFormatRgba:      format = GL_RGBA;            break;
    }

    GLenum type;
    switch (description.BitsPerComponent) {
        case 8: type = GL_UNSIGNED_BYTE; break;
        case 4:
            if (format == GL_RGBA) {
                type = GL_UNSIGNED_SHORT_4_4_4_4;
                break;
            }
            // intentionally fall through
        default:
            assert(!"Unsupported format.");
    }

    void* data = m_resourceManager->GetImageData();
    ivec2 size = description.Size;
    glTexImage2D(GL_TEXTURE_2D, 0, format, size.x, size.y, 
                 0, format, type, data);
    m_resourceManager->UnloadImage();
}

m_resourceManager->LoadPngImage("Grid16");
void* pixels = m_resourceManager->GetImageData();
ivec2 size = m_resourceManager->GetImageSize();
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, size.x, size.y, 0, GL_RGBA, GL_UNSIGNED_BYTE, pixels);
m_resourceManager->UnloadImage();

SetPngTexture("Grid16.png");

Textures are often the biggest memory hog in graphically intense applications. Block compression is a technique that's quite popular in real-time graphics, even on desktop platforms. Like JPEG compression, it can cause a loss of image quality, but unlike JPEG, its compression ratio is constant and deterministic. If you know the width and height of your original image, then it's simple to compute the number of bytes in the compressed image.

Block compression is particularly good at photographs, and in some cases it's difficult to notice the quality loss. The noise is much more noticeable when applied to images with regions of solid color, like vector-based graphics and text.

I strongly encourage you to use block compression when it doesn't make a noticeable difference in image quality. Not only does it reduce your memory footprint, it can boost performance as well, due to increased cache coherency. The iPhone supports a specific type of block compression called PVRTC, named after the PowerVR chip that serves as the iPhone's graphics processor. PVRTC has four variants, as seen in Table 5.1, “PVRTC Formats”.

The iPhone SDK comes with a command line program called texturetool that you can use to generate PVRTC data from an uncompressed image, and it's located here:

/Developer/Platforms/iPhoneOS.platform/Developer/usr/bin

It's possible Apple has modified the path since the time of this writing, so I recommend verifying the location of texturetool using the spotlight feature in Mac OS X. By the way, there actually several command line tools at this location (including a rather cool one called pngcrush). They're worth a closer look!

Here's how you could use texturetool to convert Grid16.png into a compressed image called Grid16.pvr:

texturetool -m -e PVRTC -f PVR -p Preview.png -o Grid16.pvr Grid16.png 

Some of the parameters are explained below.

The encoding argument can be tweaked with optional arguments. Some examples:

Rather than executing texturetool from the command line, you can make it an automatic step in Xcode's build process. Go ahead and perform the following steps:

Before moving on to the implementation, we need to incorporate a couple source files from Imagination Technology's PowerVR SDK.

Enough Xcode shenanigans, let's get back to writing real code. Before adding PVR support to the ResourceManager class, we need to make some enhancements to Interfaces.hpp. These changes are highlighted in bold in Example 5.17, “Adding PVRTC Support to Interfaces.hpp”.

enum TextureFormat {
    TextureFormatGray,
    TextureFormatGrayAlpha,
    TextureFormatRgb,
    TextureFormatRgba,
    TextureFormatPvrtcRgb2,
    TextureFormatPvrtcRgba2,
    TextureFormatPvrtcRgb4,
    TextureFormatPvrtcRgba4,
};

struct TextureDescription {
    TextureFormat Format;
    int BitsPerComponent;
    ivec2 Size;
    int MipCount;
};

// ...

struct IResourceManager {
    virtual string GetResourcePath() const = 0;
    virtual TextureDescription LoadPvrImage(const string& filename) = 0;
    virtual TextureDescription LoadPngImage(const string& filename) = 0;
    virtual void* GetImageData() = 0;
    virtual ivec2 GetImageSize() = 0;
    virtual void UnloadImage() = 0;
    virtual ~IResourceManager() {}
};

The implementation of LoadPvrImage is shown in Example 5.18, “Adding PVRTC Support to ResourceManager.mm” (you'll replace everything within the class definition except the GetResourcePath and LoadPngImage methods). It parses the header fields by simply casting the data pointer to a pointer-to-struct. The size of the struct isn't necessarily the size of the header, so the GetImageData method looks at the dwHeaderSize field to determine where the raw data starts.

...

#import "../PowerVR/PVRTTexture.h"

class ResourceManager : public IResourceManager {
public:

    // ...

    TextureDescription LoadPvrImage(const string& file)
    {
        NSString* basePath = [NSString stringWithUTF8String:file.c_str()];
        NSString* resourcePath = [[NSBundle mainBundle] resourcePath];
        NSString* fullPath = [resourcePath stringByAppendingPathComponent:basePath];
        
        m_imageData = [NSData dataWithContentsOfFile:fullPath];
        m_hasPvrHeader = true;
        PVR_Texture_Header* header = (PVR_Texture_Header*) [m_imageData bytes];
        bool hasAlpha = header->dwAlphaBitMask ? true : false;

        TextureDescription description;
        switch (header->dwpfFlags & PVRTEX_PIXELTYPE) {
            case OGL_PVRTC2:    
                description.Format = hasAlpha ? TextureFormatPvrtcRgba2 :
                                                TextureFormatPvrtcRgb2;
                break;
            case OGL_PVRTC4:
                description.Format = hasAlpha ? TextureFormatPvrtcRgba4 :
                                                TextureFormatPvrtcRgb4;
                break;
            default:
                assert(!"Unsupported PVR image.");
                break;
        }
        
        description.Size.x = header->dwWidth;
        description.Size.y = header->dwHeight;
        description.MipCount = header->dwMipMapCount;
        return description;
    }
    void* GetImageData()
    {
        if (!m_hasPvrHeader)
            return (void*) [m_imageData bytes];
        
        PVR_Texture_Header* header = (PVR_Texture_Header*) [m_imageData bytes];
        char* data = (char*) [m_imageData bytes];
        unsigned int headerSize = header->dwHeaderSize;
        return data + headerSize;
    }
    void UnloadImage()
    {
        m_imageData = 0;
    }
private:
    NSData* m_imageData;
    bool m_hasPvrHeader;
    ivec2 m_imageSize;
};

Note that we changed the type of m_imageData from CFDataRef to NSData*. Since we create the NSData object using auto-release semantics, there's no need to call a release function in the UnloadImage() method.

Because of this change, we'll also need to make one change to LoadPngImage. Find this line:

m_imageData = CGDataProviderCopyData(CGImageGetDataProvider(cgImage));

and replace it with:

CFDataRef dataRef = CGDataProviderCopyData(CGImageGetDataProvider(cgImage));
m_imageData = [NSData dataWithData:(NSData*) dataRef];

You should now be able to build and run, although your application is still using the PNG file.

Example 5.19, “RenderingEngine::SetPvrTexture()” adds a new method to the rendering engine for creating a compressed texture object. This code will work under both ES 1.1 and ES 2.0.

private:
    void SetPvrTexture(const string& name) const;
    // ...

void RenderingEngine::SetPvrTexture(const string& filename) const
{
    TextureDescription description = 
      m_resourceManager->LoadPvrImage(filename);
    unsigned char* data = 
      (unsigned char*) m_resourceManager->GetImageData();
    int width = description.Size.x;
    int height = description.Size.y;
    
    int bitsPerPixel;
    GLenum format;
    switch (description.Format) {
        case TextureFormatPvrtcRgba2:
            bitsPerPixel = 2;
            format = GL_COMPRESSED_RGBA_PVRTC_2BPPV1_IMG;
            break;
        case TextureFormatPvrtcRgb2:
            bitsPerPixel = 2;
            format = GL_COMPRESSED_RGB_PVRTC_2BPPV1_IMG;
            break;
        case TextureFormatPvrtcRgba4:
            bitsPerPixel = 4;
            format = GL_COMPRESSED_RGBA_PVRTC_4BPPV1_IMG;
            break;
        case TextureFormatPvrtcRgb4:
            bitsPerPixel = 4;
            format = GL_COMPRESSED_RGB_PVRTC_4BPPV1_IMG;
            break;
    }
    
    for (int level = 0; width > 0 && height > 0; ++level) {
        GLsizei size = std::max(32, width * height * bitsPerPixel / 8);
        glCompressedTexImage2D(GL_TEXTURE_2D, level, format, width, 
                               height, 0, size, data);
        data += size;
        width >>= 1; height >>= 1;
    }
    
    m_resourceManager->UnloadImage();
}

You can now replace this:

SetPngTexture("Grid16.png");

With this:

SetPvrTexture("Grid16.pvr");

Since the PVR file contains multiple mipmap levels, you'll also need to remove any code you added for mipmap auto-generation (glGenerateMipmap under ES 2.0, glTexParameter with GL_GENERATE_MIPMAP under ES 1.1).

After re-building your project, your app will now be using the compressed texture.

Of particular interest in Example 5.19, “RenderingEngine::SetPvrTexture()” is the section that loops over each mipmap level. Rather than calling glTexImage2D, it uses glCompressedTexImage2D to upload the data. Here's its formal declaration:

void glCompressedTexImage2D(GLenum target, GLint level, GLenum format,
                            GLsizei width, GLsizei height, GLint border,
                            GLsizei byteCount, const GLvoid* data);

The low-precision uncompressed formats (565, 5551, and 4444) are often overlooked. Unlike block compression, they do not cause speckle artifacts in the image. While they work poorly with images that have smooth color gradients, they're quite good at preserving detail in photographs and keeping clean lines in simple vector art.

At the time of this writing, the iPhone SDK does not contain any tools for encoding images to these formats, but the free PowerVR SDK from Imagination Technologies includes a tool called PVRTexTool just for this purpose. Download the SDK as directed in the section called “Texture Compression with PVRTC”. Extract the tarball archive if you haven't already.

After opening up the tarball, execute the application in Utilities/PVRTexTool/PVRTexToolGUI/MacOS.

Open your source image in the GUI, and select Edit→Encode. After you choose a format (try RGB 565), you can save the output image to a PVR file. Save it as Grid16-PVRTool.pvr and add it to Xcode as described in 5. Next, go into both renderers, and find:

SetPvrTexture("Grid16.pvr");

And replace it with:

SetPvrTexture("Grid16-PVRTool.pvr");

You may have noticed that PVRTexTool has many of the same capabilities as the texturetool program presented in the previous section, and much more. It can encode images to a plethora of formats, generate mipmap levels, and even dump out C header files that contain raw image data. This tool also has a command line variant to allow integration into a script or an Xcode build.

Let's go ahead and flesh out some of the image-loading code to support the uncompressed low-precision formats. New lines in ResourceManager.mm are shown in bold in Example 5.20, “New Texture Formats in ResourceManager.mm”.

TextureDescription LoadPvrImage(const string& file)
{
    // ...

    TextureDescription description;
    switch (header->dwpfFlags & PVRTEX_PIXELTYPE) {
        case OGL_RGB_565:
            description.Format = TextureFormat565;
            break;
        case OGL_RGBA_5551:
            description.Format = TextureFormat5551;
            break;
        case OGL_RGBA_4444:
            description.Format = TextureFormatRgba;
            description.BitsPerComponent = 4;
            break;
        case OGL_PVRTC2:    
            description.Format = hasAlpha ? TextureFormatPvrtcRgba2 :
                                            TextureFormatPvrtcRgb2;
            break;
        case OGL_PVRTC4:
            description.Format = hasAlpha ? TextureFormatPvrtcRgba4 :
                                            TextureFormatPvrtcRgb4;
            break;
    }

    // ...    
}

Next we need to add some new code to the SetPvrTexture method in the rendering engine class, seen in Example 5.21, “New Texture Formats in the Rendering Engines”. This code works for both ES 1.1 and 2.0.

void RenderingEngine::SetPvrTexture(const string& filename) const
{

    // ...
    
    int bitsPerPixel;
    GLenum format;
    bool compressed = false;
    switch (description.Format) {
        case TextureFormatPvrtcRgba2:
        case TextureFormatPvrtcRgb2:
        case TextureFormatPvrtcRgba4:
        case TextureFormatPvrtcRgb4:
            compressed = true;
            break;
    }
    
    if (!compressed) {
        GLenum type;
        switch (description.Format) {
            case TextureFormatRgba:
                assert(description.BitsPerComponent == 4);
                format = GL_RGBA;
                type = GL_UNSIGNED_SHORT_4_4_4_4;
                bitsPerPixel = 16;
                break;
            case TextureFormat565:
                format = GL_RGB;
                type = GL_UNSIGNED_SHORT_5_6_5;
                bitsPerPixel = 16;
                break;
            case TextureFormat5551:
                format = GL_RGBA;
                type = GL_UNSIGNED_SHORT_5_5_5_1;
                bitsPerPixel = 16;
                break;
        }
        for (int level = 0; width > 0 && height > 0; ++level) {
            GLsizei size = width * height * bitsPerPixel / 8;
            glTexImage2D(GL_TEXTURE_2D, level, format, width, 
                         height, 0, format, type, data);
            data += size;
            width >>= 1; height >>= 1;
        }
    
        m_resourceManager->UnloadImage();
        return;
    }
}

Next, we need to make a change to Interfaces.hpp:

enum TextureFormat {
    TextureFormatGray,
    TextureFormatGrayAlpha,
    TextureFormatRgb,
    TextureFormatRgba,
    TextureFormatPvrtcRgb2,
    TextureFormatPvrtcRgba2,
    TextureFormatPvrtcRgb4,
    TextureFormatPvrtcRgba4,
    TextureFormat565,
    TextureFormat5551,
};

You can use Quartz to draw 2D paths into an OpenGL texture, resize the source image, convert from one format to another, and even generate text. We'll cover some of these techniques in Chapter 7, Sprites and Text; for now let's go over a few simple ways to generate textures.

One way of loading textures into OpenGL is creating a Quartz surface using whatever format you'd like, then drawing the source image to it, as seen in Example 5.22, “Texture Loading with CGContextDrawImage”.

TextureDescription LoadImage(const string& file)
{
    NSString* basePath = [NSString stringWithUTF8String:file.c_str()];
    NSString* resourcePath = [[NSBundle mainBundle] resourcePath];
    NSString* fullPath = 
      [resourcePath stringByAppendingPathComponent:basePath];
    UIImage* uiImage = [UIImage imageWithContentsOfFile:fullPath];
            
    TextureDescription description;
    description.Size.x = CGImageGetWidth(uiImage.CGImage);
    description.Size.y = CGImageGetHeight(uiImage.CGImage);
    description.BitsPerComponent = 8;
    description.Format = TextureFormatRgba;
    description.MipCount = 1;
    m_hasPvrHeader = false;

    int bpp = description.BitsPerComponent / 2;
    int byteCount = description.Size.x * description.Size.y * bpp;
    unsigned char* data = (unsigned char*) calloc(byteCount, 1);
    
    CGColorSpaceRef colorSpace = CGColorSpaceCreateDeviceRGB();
    CGBitmapInfo bitmapInfo = 
      kCGImageAlphaPremultipliedLast | kCGBitmapByteOrder32Big;
    CGContextRef context = CGBitmapContextCreate(data,
        description.Size.x,
        description.Size.y,
        description.BitsPerComponent,
        bpp * description.Size.x,
        colorSpace,
        bitmapInfo);
    CGColorSpaceRelease(colorSpace);
    CGRect rect = CGRectMake(0, 0, description.Size.x, description.Size.y);
    CGContextDrawImage(context, rect, uiImage.CGImage);
    CGContextRelease(context);
    
    m_imageData = [NSData dataWithBytesNoCopy:data 
                                       length:byteCount 
                                 freeWhenDone:YES];
    return description;
}

If you want to try out the Quartz-loading code in the sample app, perform the following steps:

One advantage of loading images with Quartz is that you can have it do some transformations before uploading the image to OpenGL. For example, say you want to flip the image vertically. You could do so by simply adding the following two lines immediately before the line that calls CGContextDrawImage:

CGContextTranslateCTM(context, 0, description.Size.y);
CGContextScaleCTM(context, 1, -1);

Another neat thing you can do with Quartz is generate new images from scratch in real time. This can shrink your application, making it faster to download. This is particularly important if you're trying to trim down to less than 10 MB, the maximum size that Apple allows for downloading over the 3G network. Of course, you can only do this for textures that contain simple vector-based images, as opposed to truly artistic content.

For example, you could use Quartz to generate a 256x256 texture that contains a blue filled-in circle, as in Example 5.23, “ResourceManager::GenerateCircle()”. The code for creating the surface should look familiar; lines of interest are shown in boldface.

TextureDescription GenerateCircle()
{
    TextureDescription description;
    description.Size = ivec2(256, 256);
    description.BitsPerComponent = 8;
    description.Format = TextureFormatRgba;

    int bpp = description.BitsPerComponent / 2;
    int byteCount = description.Size.x * description.Size.y * bpp;
    unsigned char* data = (unsigned char*) calloc(byteCount, 1);
    
    CGColorSpaceRef colorSpace = CGColorSpaceCreateDeviceRGB();
    CGBitmapInfo bitmapInfo = kCGImageAlphaPremultipliedLast | kCGBitmapByteOrder32Big;
    CGContextRef context = CGBitmapContextCreate(data,
                                                 description.Size.x,
                                                 description.Size.y,
                                                 description.BitsPerComponent,
                                                 bpp * description.Size.x,
                                                 colorSpace,
                                                 bitmapInfo);
    CGColorSpaceRelease(colorSpace);
            
    CGRect rect = CGRectMake(5, 5, 246, 246);
    CGContextSetRGBFillColor(context, 0, 0, 1, 1);
    CGContextFillEllipseInRect(context, rect);

    CGContextRelease(context);
    
    m_imageData = [NSData dataWithBytesNoCopy:data length:byteCount freeWhenDone:YES];
    return description;
}

If you want to try out the circle-generation code in the sample app, perform the following steps:

Quartz is a rich 2D graphics API and could have a book all to itself, so I can't cover it here; check out Apple's online documentation for more information.

Some of the biggest gotchas in texturing are the various constraints imposed on their size. Strictly speaking, OpenGL ES 1.1 stipulates that all textures must have dimensions that are powers of two, and OpenGL ES 2.0 has no such restriction. In the graphics community, textures that have a power-of-two width and height are commonly known as POT textures; non power-of-two textures are NPOT.

For better or worse, the iPhone platform diverges from the OpenGL core specifications here. The POT constraint in ES 1.1 doesn't always apply, nor does the NPOT feature in ES 2.0.

Newer iPhone models support an extension to ES 1.1 that opens up the POT restriction, but only under a certain set of conditions. It's called GL_APPLE_texture_2D_limited_npot, and it basically states the following:

As hairy as this seems, it covers quite a few situations, including the common case of displaying a background texture with the same dimensions as the screen (320x480). Since it requires no minification, it doesn't need mipmapping, so you can create a texture object that fits "just right".

Not all iPhones support the aforementioned extension to ES 1.1; the only sure-fire way to find out is by programmatically checking for the extension string, which can be done like this:

const char* extensions = (char*) glGetString(GL_EXTENSIONS);
bool npot = strstr(extensions, "GL_APPLE_texture_2D_limited_npot") != 0;

void PrettyPrintExtensions()
{
    std::string extensions = (const char*) glGetString(GL_EXTENSIONS);
    char* extensionStart = &extensions[0];
    char** extension = &extensionStart;
    std::cout << "Supported OpenGL ES Extensions:" << std::endl;
    while (*extension)
        std::cout << '\t' << strsep(extension, " ") << std::endl;
    std::cout << std::endl;
}

If your 320x480 texture needs to be mipmapped (or if you're supporting older iPhones) then you can simply use a 512x512 texture and adjust your texture coordinates to address a 320x480 subregion. One quick way of doing this is with a texture matrix:

glMatrixMode(GL_TEXTURE);
glLoadIdentity();
glScalef(320.0f / 512.0f, 480.0f / 512.0f, 1.0f);

Unfortunately, the portions of the image that lie outside the 320x480 subregion are wasted. If this causes you to grimace, keep in mind that you can add "mini-textures" to those unused regions. Doing so makes the texture into a texture atlas, which we'll discuss further in Chapter 7, Sprites and Text.

If you don't want to use a 512x512 texture, then it's possible to create five POT textures and carefully puzzle them together to fit the screen, as seen in Figure 5.7, “Slicing the iPhone Screen into Pot Textures”. This is a hassle though, and I don't recommend it unless you have a strong penchant for masochism.

Figure 5.7. Slicing the iPhone Screen into Pot Textures

By the way, according to the official OpenGL ES 2.0 specification, NPOT textures are actually allowed in any situation! Apple has made a minor transgression here by imposing the aforementioned limitations.

Keep in mind that even when the POT restriction applies, your texture can still be non-square (e.g., 512x256), unless it uses a compressed format.

Think these are a lot of rules to juggle? Well it's not over yet! Textures also have a maximum allowable size. At the time of this writing, the first two iPhone generations have a maximum size of 1024x1024, and third generation devices have a maximum size of 2048x2048. Again, the only way to be sure is querying its capabilities at run time, like so:

GLint maxSize;
glGetIntegerv(GL_MAX_TEXTURE_SIZE, &maxSize);

Don't groan, but there's yet another gotcha I want to mention regarding texture dimensions. By default, OpenGL expects each row of uncompressed texture data to be aligned on a four-byte boundary. This isn't a concern if your texture is GL_RGBA with UNSIGNED_BYTE; in this case, the data is always properly aligned. However, if your format has a texel size less than four bytes, you should take care to ensure each row is padded out to the proper alignment. Alternatively you can turn off OpenGL's alignment restriction like this:

glPixelStorei(GL_UNPACK_ALIGNMENT, 1);

Also be aware that the PNG decoder in Quartz may or may not internally align the image data; this can be a concern if you load images using the CGDataProviderCopyData method presented in Example 5.15, “Update to ResourceManager.mm”. It's more robust (but less performant) to load in images by drawing to a Quartz surface, which we'll go over in the next section.

Before moving on, I'll forewarn you of yet another thing to watch out for: the iPhone simulator doesn't necessarily impose the same restrictions on texture size that a physical device would. Many developers throw up their hands and simply stick to power-of-two dimensions only; I'll show you how to make this easier in the next section.

struct TextureDescription {
    TextureFormat Format;
    int BitsPerComponent;
    ivec2 Size;
    int MipCount;
    ivec2 OriginalSize;
};

TextureDescription LoadImagePot(const string& file)
{
    NSString* basePath = [NSString stringWithUTF8String:file.c_str()];
    NSString* resourcePath = [[NSBundle mainBundle] resourcePath];
    NSString* fullPath = 
      [resourcePath stringByAppendingPathComponent:basePath];
    UIImage* uiImage = [UIImage imageWithContentsOfFile:fullPath];

    TextureDescription description;
    description.OriginalSize.x = CGImageGetWidth(uiImage.CGImage);
    description.OriginalSize.y = CGImageGetHeight(uiImage.CGImage);
    description.Size.x = NextPot(description.OriginalSize.x);
    description.Size.y = NextPot(description.OriginalSize.y);
    description.BitsPerComponent = 8;
    description.Format = TextureFormatRgba;

    int bpp = description.BitsPerComponent / 2;
    int byteCount = description.Size.x * description.Size.y * bpp;
    unsigned char* data = (unsigned char*) calloc(byteCount, 1);

    CGColorSpaceRef colorSpace = CGColorSpaceCreateDeviceRGB();
    CGBitmapInfo bitmapInfo = 
      kCGImageAlphaPremultipliedLast | kCGBitmapByteOrder32Big;
    CGContextRef context = CGBitmapContextCreate(data,
        description.Size.x,
        description.Size.y,
        description.BitsPerComponent,
        bpp * description.Size.x,
        colorSpace,
        bitmapInfo);
    CGColorSpaceRelease(colorSpace);
    CGRect rect = CGRectMake(0, 0, description.Size.x, description.Size.y);
    CGContextDrawImage(context, rect, uiImage.CGImage);
    CGContextRelease(context);
    
    m_imageData = [NSData dataWithBytesNoCopy:data length:byteCount freeWhenDone:YES];
    return description;
}

unsigned int NextPot(unsigned int n)
{
    n--;
    n |= n >> 1; n |= n >> 2;
    n |= n >> 4; n |= n >> 8;
    n |= n >> 16;
    n++;
    return n;
}

For the grand finale sample of this chapter, let's create an app called CameraTexture which allows the user to snap a photo and wrap it around an ellipsoid (a squashed sphere). The embarrassingly simple user interface consists of a single button for taking a new photo, as seen in Figure 5.8, “CameraTexture Sample”. We'll also add some animation by periodically spinning the ellipsoid along the X axis.

Figure 5.8. CameraTexture Sample

Unlike much of the sample code in this book, the interesting parts here will actually be in Objective C rather than C++. The application logic is simple enough that we can dispense with the IApplicationEngine interface.

Using Model Viewer as the baseline, start by removing all the ApplicationEngine related code as follows:

The code won't build until we fill it out a bit more. Replace the IRenderingEngine interface in Interfaces.hpp with Example 5.26, “CameraTexture's IRenderingEngine Interface”, and move the TextureFormat and TextureDescription type definitions to the top of the file.

struct IRenderingEngine {
    virtual void Initialize() = 0;
    virtual void Render(float zScale, float theta, bool waiting) const = 0;
    virtual void LoadCameraTexture(const TextureDescription&, void* data) = 0;
    virtual ~IRenderingEngine() {}
};

We'll go over the implementation of these methods later. Let's jump back to the Objective C since that's where the interesting stuff is. For starters, we need to modify the GLView class declaration by adopting a couple new protocols and adding a few data fields; see Example 5.27, “CameraTexture's GLView.h”. New code is shown in bold.

#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#import <OpenGLES/EAGL.h>
#import "Interfaces.hpp"

@interface GLView : UIView <UIImagePickerControllerDelegate,UINavigationControllerDelegate> {
@private
    IRenderingEngine* m_renderingEngine;
    IResourceManager* m_resourceManager;
    EAGLContext* m_context;
    UIViewController* m_viewController;bool m_paused;float m_zScale;float m_xRotation;
}

- (void) drawView: (CADisplayLink*) displayLink;

@end

Next, open GLView.mm and rewrite the drawView method as in Example 5.28, “CameraTexture's drawView method”. The code that computes the time step is the same as previous examples; perhaps more interesting are the mathematical shenanigans used to oscillate between two types of useless and silly animation: "spinning" and "pulsing".

- (void) drawView: (CADisplayLink*) displayLink
{
    if (m_paused)
        return;
    
    if (displayLink != nil) {
        float t = displayLink.timestamp / 3;
        int integer = (int) t;
        float fraction = t - integer;
        if (integer % 2) {
            m_xRotation = 360 * fraction;
            m_zScale = 0.5;
        } else {
            m_xRotation = 0;
            m_zScale = 0.5 + sin(fraction * 6 * M_PI) * 0.3;
        }
    }
    
    m_renderingEngine->Render(m_zScale, m_xRotation, false);
    [m_context presentRenderbuffer:GL_RENDERBUFFER];
}

While we're still in GLView.mm, let's go ahead and write the touch handler. Because of the embarrassingly simple UI, we only need to handle a single touch event: touchesEnded, as seen in Example 5.29, “CameraTexture's touchesEnded method”. Note that the first thing it does is check if the touch location lies within the bounds of the button's rectangle; if not, it returns early.

- (void) touchesEnded: (NSSet*) touches withEvent: (UIEvent*) event
{
    UITouch* touch = [touches anyObject];
    CGPoint location  = [touch locationInView: self];
    
    // Return early if touched outside the button's area.
    if (location.y < 395 || location.y > 450 || 
        location.x < 75 || location.x > 245)
        return;

    // Instance the image picker and set up its configuration.
    UIImagePickerController* imagePicker = 
      [[UIImagePickerController alloc] init];
    imagePicker.delegate = self;
    imagePicker.navigationBarHidden = YES;
    imagePicker.toolbarHidden = YES;

    // Enable camera mode if supported, otherwise fall back to the default.
    UIImagePickerControllerSourceType source = 
      UIImagePickerControllerSourceTypeCamera;
    if ([UIImagePickerController isSourceTypeAvailable:source])
        imagePicker.sourceType = source;  

    // Instance the view controller if it doesn't already exist.
    if (m_viewController == 0) {
        m_viewController = [[UIViewController alloc] init];
        m_viewController.view = self;
    }
    
    // Turn off the OpenGL rendering cycle and present the image picker.
    m_paused = true;
    [m_viewController presentModalViewController:imagePicker animated:NO];
}

Perhaps the most interesting piece in Example 5.29, “CameraTexture's touchesEnded method” is the code that checks if the camera is supported; if so, it sets the camera as the picker's source type:

UIImagePickerControllerSourceType source =
  UIImagePickerControllerSourceTypeCamera;
if ([UIImagePickerController isSourceTypeAvailable:source])
    imagePicker.sourceType = source;  

I recommend following this pattern even if you know a priori that your application will only run on devices with cameras. The fallback path provides a convenient testing platform on the iPhone simulator; by default, the image picker simply opens a file picker with image thumbnails.

Next we'll add a couple new methods to GLView.mm for implementing the UIImagePickerControllerDelegate protocol, as seen in Example 5.30, “imagePickerControllerDidCancel and didFinishPickingMediaWithInfo”. Depending on the megapixel resolution of your camera, the captured image can be quite large, much larger than what we need for an OpenGL texture. So, the first thing we do is scale the image down to 256x256. Since this destroys the aspect ratio, we'll store the original image's dimensions in the TextureDescription structure just in case. A more detailed explanation of the code follows the listing.

- (void) imagePickerControllerDidCancel:(UIImagePickerController*) picker
{
    [m_viewController dismissModalViewControllerAnimated:NO];
    m_paused = false;
    [picker release];
}

- (void) imagePickerController:(UIImagePickerController*) picker 
         didFinishPickingMediaWithInfo:(NSDictionary*) info
{
    UIImage* image = 
      [info objectForKey:UIImagePickerControllerOriginalImage];
    
    float theta = 0;
    switch (image.imageOrientation) {
        case UIImageOrientationDown: theta =  M_PI; break;
        case UIImageOrientationLeft: theta = M_PI / 2; break;
        case UIImageOrientationRight: theta = -M_PI / 2; break;
    }

    int bpp = 4;
    ivec2 size(256, 256);
    int byteCount = size.x * size.y * bpp;
    unsigned char* data = (unsigned char*) calloc(byteCount, 1);
    
    CGColorSpaceRef colorSpace = CGColorSpaceCreateDeviceRGB();
    CGBitmapInfo bitmapInfo = 
      kCGImageAlphaPremultipliedLast | kCGBitmapByteOrder32Big;
    CGContextRef context = CGBitmapContextCreate(data,
                                                 size.x,
                                                 size.y,
                                                 8,
                                                 bpp * size.x,
                                                 colorSpace,
                                                 bitmapInfo);
    CGColorSpaceRelease(colorSpace);
    CGRect rect = CGRectMake(0, 0, size.x, size.y);
    CGContextTranslateCTM(context, size.x / 2, size.y / 2);
    CGContextRotateCTM(context, theta);
    CGContextTranslateCTM(context, -size.x / 2, -size.y / 2);
    CGContextDrawImage(context, rect, image.CGImage);
    
    TextureDescription description;
    description.Size = size;
    description.OriginalSize.x = CGImageGetWidth(image.CGImage);
    description.OriginalSize.y = CGImageGetHeight(image.CGImage);
    description.Format = TextureFormatRgba;
    description.BitsPerComponent = 8;
    
    m_renderingEngine->LoadCameraTexture(description, data);
    m_renderingEngine->Render(m_zScale, m_xRotation, true);
    [m_context presentRenderbuffer:GL_RENDERBUFFER];
    
    CGContextRelease(context);
    free(data);
    
    [m_viewController dismissModalViewControllerAnimated:NO];
    m_paused = false;
    [picker release];
}

@end

#include <OpenGLES/ES1/gl.h>
#include <OpenGLES/ES1/glext.h>
#include <iostream>
#include "Interfaces.hpp"
#include "Matrix.hpp"
#include "ParametricEquations.hpp"

using namespace std;

struct Drawable {
    GLuint VertexBuffer;
    GLuint IndexBuffer;
    int IndexCount;
};

namespace ES1 {

class RenderingEngine : public IRenderingEngine {
public:
    RenderingEngine(IResourceManager* resourceManager);
    void Initialize();
    void Render(float zScale, float theta, bool waiting) const;
    void LoadCameraTexture(const TextureDescription& description, 
                           void* data);
private:
    GLuint CreateTexture(const string& file);
    Drawable CreateDrawable(const ParametricSurface& surface);
    void RenderDrawable(const Drawable& drawable) const;
    void UploadImage(const TextureDescription& description, 
                     void* data = 0);
    Drawable m_sphere;
    Drawable m_button;
    GLuint m_colorRenderbuffer;
    GLuint m_depthRenderbuffer;
    GLuint m_cameraTexture;
    GLuint m_waitTexture;
    GLuint m_actionTexture;
    IResourceManager* m_resourceManager;
};
    
IRenderingEngine* CreateRenderingEngine(IResourceManager* resourceManager)
{
    return new RenderingEngine(resourceManager);
}

RenderingEngine::RenderingEngine(IResourceManager* resourceManager)
{
    m_resourceManager = resourceManager;
    glGenRenderbuffersOES(1, &m_colorRenderbuffer);
    glBindRenderbufferOES(GL_RENDERBUFFER_OES, m_colorRenderbuffer);
}

void RenderingEngine::Initialize()
{
    // Create vertex buffer objects.
    m_sphere = CreateDrawable(Sphere(2.5));
    m_button = CreateDrawable(Quad(4, 1));
    
    // Load up some textures.
    m_cameraTexture = CreateTexture("Tarsier.png");
    m_waitTexture = CreateTexture("PleaseWait.png");
    m_actionTexture = CreateTexture("TakePicture.png");

    // Extract width and height from the color buffer.
    int width, height;
    glGetRenderbufferParameterivOES(GL_RENDERBUFFER_OES,
                                    GL_RENDERBUFFER_WIDTH_OES, &width);
    glGetRenderbufferParameterivOES(GL_RENDERBUFFER_OES,
                                    GL_RENDERBUFFER_HEIGHT_OES, &height);
    glViewport(0, 0, width, height);

    // Create a depth buffer that has the same size as the color buffer.
    glGenRenderbuffersOES(1, &m_depthRenderbuffer);
    glBindRenderbufferOES(GL_RENDERBUFFER_OES, m_depthRenderbuffer);
    glRenderbufferStorageOES(GL_RENDERBUFFER_OES, 
                             GL_DEPTH_COMPONENT16_OES, 
                             width, height);
        
    // Create the framebuffer object.
    GLuint framebuffer;
    glGenFramebuffersOES(1, &framebuffer);
    glBindFramebufferOES(GL_FRAMEBUFFER_OES, framebuffer);
    glFramebufferRenderbufferOES(GL_FRAMEBUFFER_OES, 
                                 GL_COLOR_ATTACHMENT0_OES,
                                 GL_RENDERBUFFER_OES, 
                                 m_colorRenderbuffer);
    glFramebufferRenderbufferOES(GL_FRAMEBUFFER_OES, 
                                 GL_DEPTH_ATTACHMENT_OES,
                                 GL_RENDERBUFFER_OES, 
                                 m_depthRenderbuffer);
    glBindRenderbufferOES(GL_RENDERBUFFER_OES, m_colorRenderbuffer);
    
    // Set up various GL state.
    glEnableClientState(GL_VERTEX_ARRAY);
    glEnableClientState(GL_NORMAL_ARRAY);
    glEnableClientState(GL_TEXTURE_COORD_ARRAY);
    glEnable(GL_LIGHT0);
    glEnable(GL_TEXTURE_2D);
    glEnable(GL_DEPTH_TEST);

    // Set up the material properties.
    vec4 diffuse(1, 1, 1, 1);
    glMaterialfv(GL_FRONT_AND_BACK, GL_DIFFUSE, diffuse.Pointer());
    
    // Set the light position.
    glMatrixMode(GL_MODELVIEW);
    glLoadIdentity();
    vec4 lightPosition(0.25, 0.25, 1, 0);
    glLightfv(GL_LIGHT0, GL_POSITION, lightPosition.Pointer());
    
    // Set the model-view transform.
    mat4 modelview = mat4::Translate(0, 0, -8);
    glLoadMatrixf(modelview.Pointer());
    
    // Set the projection transform.
    float h = 4.0f * height / width;
    mat4 projection = mat4::Frustum(-2, 2, -h / 2, h / 2, 5, 10);
    glMatrixMode(GL_PROJECTION);
    glLoadMatrixf(projection.Pointer());
    glMatrixMode(GL_MODELVIEW);
}

} // end namespace ES1

void RenderingEngine::Render(float zScale, float theta, bool waiting) const
{
    glClearColor(0.5f, 0.5f, 0.5f, 1);
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
    glPushMatrix();
    
    // Draw the button.
    glTranslatef(0, -4, 0);
    glBindTexture(GL_TEXTURE_2D, waiting ? m_waitTexture : m_actionTexture);
    RenderDrawable(m_button);
    
    // Draw the sphere.
    glBindTexture(GL_TEXTURE_2D, m_cameraTexture);
    glTranslatef(0, 4.75, 0);
    glRotatef(theta, 1, 0, 0);
    glScalef(1, 1, zScale);
    glEnable(GL_LIGHTING);
    RenderDrawable(m_sphere);
    glDisable(GL_LIGHTING);

    glPopMatrix();
}

void RenderingEngine::LoadCameraTexture(const TextureDescription& 
                                        desc, void* data)
{
    glBindTexture(GL_TEXTURE_2D, m_cameraTexture);
    UploadImage(desc, data);
}

GLuint RenderingEngine::CreateTexture(const string& file)
{
    GLuint name;
    glGenTextures(1, &name);
    glBindTexture(GL_TEXTURE_2D, name);
    glTexParameteri(GL_TEXTURE_2D, 
                    GL_TEXTURE_MIN_FILTER, 
                    GL_LINEAR_MIPMAP_LINEAR);
    glTexParameteri(GL_TEXTURE_2D, 
                    GL_TEXTURE_MAG_FILTER, 
                    GL_LINEAR);
    glTexParameteri(GL_TEXTURE_2D, GL_GENERATE_MIPMAP, GL_TRUE);
    UploadImage(m_resourceManager->LoadImagePot(file));
    return name;
}

Drawable RenderingEngine::CreateDrawable(const ParametricSurface& surface)
{
    // Create the VBO for the vertices.
    vector<float> vertices;
    unsigned char vertexFlags = VertexFlagsNormals | VertexFlagsTexCoords;
    surface.GenerateVertices(vertices, vertexFlags);
    GLuint vertexBuffer;
    glGenBuffers(1, &vertexBuffer);
    glBindBuffer(GL_ARRAY_BUFFER, vertexBuffer);
    glBufferData(GL_ARRAY_BUFFER,
                 vertices.size() * sizeof(vertices[0]),
                 &vertices[0],
                 GL_STATIC_DRAW);
    
    // Create a new VBO for the indices if needed.
    int indexCount = surface.GetTriangleIndexCount();
    GLuint indexBuffer;
    vector<GLushort> indices(indexCount);
    surface.GenerateTriangleIndices(indices);
    glGenBuffers(1, &indexBuffer);
    glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, indexBuffer);
    glBufferData(GL_ELEMENT_ARRAY_BUFFER,
                 indexCount * sizeof(GLushort),
                 &indices[0],
                 GL_STATIC_DRAW);
    
    // Fill in a descriptive struct and return it.
    Drawable drawable;
    drawable.IndexBuffer = indexBuffer;
    drawable.VertexBuffer = vertexBuffer;
    drawable.IndexCount = indexCount;
    return drawable;
}

void RenderingEngine::RenderDrawable(const Drawable& drawable) const
{
    int stride = sizeof(vec3) + sizeof(vec3) + sizeof(vec2);
    const GLvoid* normalOffset = (const GLvoid*) sizeof(vec3);
    const GLvoid* texCoordOffset = (const GLvoid*) (2 * sizeof(vec3));
    glBindBuffer(GL_ARRAY_BUFFER, drawable.VertexBuffer);
    glVertexPointer(3, GL_FLOAT, stride, 0);
    glNormalPointer(GL_FLOAT, stride, normalOffset);
    glTexCoordPointer(2, GL_FLOAT, stride, texCoordOffset);
    glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, drawable.IndexBuffer);
    glDrawElements(GL_TRIANGLES, drawable.IndexCount, 
                   GL_UNSIGNED_SHORT, 0);
}

void RenderingEngine::UploadImage(const TextureDescription& description, 
                                  void* data)
{
    GLenum format;
    switch (description.Format) {
        case TextureFormatRgb:  format = GL_RGB;  break;
        case TextureFormatRgba: format = GL_RGBA; break;
    }
    
    GLenum type = GL_UNSIGNED_BYTE;
    ivec2 size = description.Size;
    
    if (data == 0) {
        data = m_resourceManager->GetImageData();
        glTexImage2D(GL_TEXTURE_2D, 0, format, size.x, size.y, 
                     0, format, type, data);
        m_resourceManager->UnloadImage();
    } else {
        glTexImage2D(GL_TEXTURE_2D, 0, format, size.x, size.y, 
                     0, format, type, data);
    }
}

In this chapter we went over the basics of texturing, and we presented several methods of loading them into an iPhone application:

We also presented a couple ways of generating new textures at run time:

Texturing is a deep subject, and we actually left quite a lot out of this chapter. New techniques relating to texturing will be covered in Chapter 8, Advanced Lighting and Texturing.