First we let IwGx know what color (or indeed colors) and image we want applied to our polygon. We do this by specifying the material we want to use, which is an instance of the CIwMaterial class that groups together this information. To set the material we want to use, we must provide IwGx with a pointer to the relevant CIwMaterial instance using the following function call:

IwGxSetMaterial(pMaterial);

If we are drawing a polygon with no image applied to it, then the very minimum information the material will need to provide is the color we want to use.

A material actually contains four different colors that, if you are at all familiar with 3D graphics rendering, you will probably recognize. They are the ambient, diffuse, emissive, and specular colors. For 2D rendering purposes, it is only the ambient color that we are concerned with. We'll look into the others when we move on to 3D rendering in Chapter 4, 3D Graphics Rendering.

The material also specifies the texture we want to apply. A texture specifies a bitmapped image that we want to apply to our polygon, and is represented in Marmalade by the CIwTexture class.

The CIwTexture class is actually a wrapper for the CIwImage class that actually stores the pixel information for an image. CIwTexture adds functionality to control how the image is actually rendered, with support for enabling and disabling features such as bilinear filtering and mipmapping.

Materials also provide control over other polygon rendering features, such as whether the polygon is rendered flat or gouraud shaded, and how it should be blended with the current screen contents when it is drawn.

Materials can either be created in code or they can be instanced by the resource manager. The following sections illustrate this.

CIwMaterial* lpRedMaterial = new CIwMaterial;
lpRedMaterial->SetColAmbient(255, 0, 0, 128);
lpRedMaterial->SetAlphaMode(CIwMaterial::ALPHA_BLEND);

CIwMaterial
{
  name      "red"
  colAmbient  { 255 0 0 128 }
  alphaMode    BLEND
}

CIwMaterial
{
  name      "grid"
  colAmbient  { 128 128 128 128 }
  texture0    "grid.png"
  alphaMode    ADD
  shadeMode    FLAT
  filtering    false
}

In order to display a polygon on screen, we need to specify a list of screen coordinates that define the corner points. Since we are only rendering in 2D at the moment, each coordinate is specified as a CIwSVec2 instance, which is a vector class defined in another Marmalade API called IwGeom. Any list of data items used when rendering polygons, be it vertices, colors, or whatever, is often referred to as a stream, so a list of vertices is called a vertex stream.

While we can specify this API to be part of our project by adding iwgeom to the subprojects section of the MKB file and calling IwGeomInit and IwGeomTerminate, there isn't actually a need to, since IwGx relies on this API itself.

The CIwSVec2 class defines a two-component vector using signed 16-bit integers, so it is perfect for specifying screen coordinates.

The default screen coordinate system in IwGx places the origin at the top-left corner of the screen, with the x component increasing horizontally to the right and the y component increasing vertically downwards. It is possible to change the position of the origin, however, by passing a CIwSVec2 instance containing the desired position of the origin to the function IwGxSetScreenSpaceOrg.

The following diagram illustrates how we could specify the coordinates for a triangle on a standard iPhone resolution screen (320 x 480 pixels). The top left of the screen is the origin and has a coordinate position of (0,0), while the bottom-right corner has a position of (320,480).

To render this triangle all we have to do is fill in an array of CIwSVec2 with the coordinates and submit them to IwGx, as follows:

CIwSVec2* v = new CIwSVec2[3];
v[0].x = 160;    v[0].y = 120;
v[1].x = 20;     v[1].y = 360;
v[2].x = 300;    v[2].y = 360;
IwGxSetVertStreamScreenSpace(v, 3);

The function call, IwGxSetVertStreamScreenSpace, allows us to specify a list of screen space (that is, pixel) coordinates we want to use for rendering, but we must also explicitly state how many vertices we are submitting. In the case of our triangle, this is three.

It is also possible to specify our coordinates using sub-pixel positioning with the function call IwGxSetVertStreamScreenSpaceSubPixel. It may be getting a bit on the long side to type, but using sub-pixel positioning does provide the advantage of smoother movement on screen, as we are no longer limited to only moving things around the screen in terms of whole pixels.

Using sub-pixel coordinates can also improve the quality of the final rendered image, as slow moving objects won't appear to jump between pixel positions if we are rendering using bilinear filtering.

IwGx only supports eight sub-pixel positions per pixel; so to convert our coordinates to use sub-pixel positioning, all we need to do is multiply the screen coordinates by eight or use the bitwise shift operator to shift left by three places.

If we want to draw a polygon using flat shading, so that every pixel rendered is the same color, we can just set the ambient color of our material and our work is done.

However, if we want to render a polygon using gouraud shading, we need to specify a color to be used at each vertex. This can't be done with a material, so we need to override the material's color information by providing our own color stream.

We do this by creating an array of CIwColour objects, which is Marmalade's chosen method of representing a color. This class has four public member variables of type uint8 (an unsigned byte) called r, g, b, and a, which (probably not surprisingly) represent the red, green, blue, and alpha values of a color.

CIwColour also provide several methods to make setting and manipulating colors easier.

Returning to the triangle defined in the earlier diagram, if we wanted to color the top of it red, the bottom-right corner green, and the bottom-left corner blue, we can use the following code:

CIwColour* c = new CIwColour[3];
c[0].Set(255, 0, 0, 255);
c[1].Set(0 255, 0, 255);
c[2].Set(0, 0, 255, 255);
IwGxSetColStream(c);

Note that IwGxSetColStream does not require us to specify the number of colors in our stream. This is because IwGx expects to find the same number of colors as there are vertices. If we do not want to specify a color stream, we can just pass NULL into the IwGxSetColStream function and the selected material's colors will be used instead.

When rendering a polygon with a texture, we need to somehow indicate how that texture should be mapped to the polygon. We do this by specifying a UV stream that allows us to state which part of the texture should appear at each vertex. The part of the texture required for each rendered pixel can then be worked out by the rendering engine by interpolating the UV values across the surface of the polygon.

In IwGx, UV coordinates are specified using floating point numbers. An individual UV value is often written as (u, v) and is represented in IwGx using the CIwFVec2 class, which is a floating point equivalent of CIwSVec2 that we came across earlier. The x component of the vector represents u, and the y component represents v.

UV values are mapped to a texture so that (0.0, 0.0) is the top left of the image and (1.0, 1.0) is the bottom-right corner. We can repeatedly tile a texture up to a maximum of eight times across our polygon by using values larger than one.

By mapping UV values in this way, we make them independent of the actual size of the texture image. If we change the size of the image for any reason, it won't mess up rendering as our UV values do not need to change.

As with vertex streams, all we have to do to specify a set of UV values is allocate an array of CIwSVec2, populate the array, and submit it to IwGx. We don't need to specify the number of UV values we are submitting, as IwGx expects to see the same number of UVs as there are vertices. Here is some sample code that we might want to use to apply a texture to a triangle:

CIwSVec2* uv = new CIwSVec2[3];
uv[0].x = IW_GEOM_ONE / 2;    uv[0].y = 0;
uv[1].x = 0;                  uv[1].y = IW_GEOM_ONE;
uv[2].x = IW_GEOM_ONE;        uv[2].y = IW_GEOM_ONE;
IwGxSetUVStream(uv, 0);

The second parameter of IwGxSetUVStream indicates which texture the UV values apply to. If the material we are using only has a single texture, we can just leave this parameter out entirely as it will default to 0, but if the material does have a second texture, we need to supply a UV stream to be used with it by changing the second parameter of IwGxSetUVStream to 1. This UV stream could be the same as the stream for the first texture or it could be a completely different set of UV values.

If our material does not have a texture applied to it, there is no need to set the UV stream to NULL as it will be ignored completely.

We've now seen how to set just about all the information we need to specify how we want our polygon to appear, so we can finally instruct IwGx to draw it. To do so, we need to let IwGx know how our various input streams should be interpreted by using the following function call:

IwGxDrawPrims(polygon_type, indices, num_indices);

The polygon_type parameter indicates whether we are drawing triangles, quads, lines, sprites, or n-polys, while the indices parameter is an array of uint16 values showing the order in which the elements of our input streams should be accessed. This is called an index stream. The num_indices parameter is just a count of how many elements are in the indices array.

The following diagram shows the types of polygons supported by IwGx. Note that it is possible to draw more than one polygon at a time by providing longer streams of data. This is something we should try to do as much as possible, since it prevents the GPU from idling while it is waiting to be supplied with new polygon information.

The numbers labeling the vertices in the diagram correspond to the elements of the index stream. When rendering, the indices array is traversed in the order shown for each polygon type, and the values it contains indicate which element of the various input streams should be used to render each vertex.

To draw the triangle we've been building up to, we can use the following code snippet:

uint16* indices = new uint16[3];
indices[0] = 0;  indices[1] = 1;  indices[2] = 2;
IwGxDrawPrims(IW_GX_TRI_STRIP, indices, 3);

We could simplify this a little more as the index stream isn't actually necessary in this instance since our input streams are accessed one element at a time in the order they occur in the stream, so we can just specify NULL for the indices parameter like this:

IwGxDrawPrims(IW_GX_TRI_STRIP, NULL, 3);

When creating the index stream there is one other point to bear in mind, which is the order in which we supply our vertices. Because IwGx can also be used to render 3D polygons on screen, it supports back face culling, which prevents any polygon that is facing away from the viewer from being rendered.

How is a polygon classified as facing toward or away from the viewer? If we label each vertex of a polygon with an incrementing number, starting with zero for the first vertex and following around the edges of the polygon from vertex to vertex, then a polygon is facing the viewer if its vertices form an anti-clockwise pattern when rendered on screen and considered in ascending numerical order. The order the vertices are supplied in is called the winding order, and the following diagram shows this more clearly:

Putting the vertices in the correct order is not the only way to solve this problem, but it is worth getting in the habit of ordering the vertices in this way for when we progress to rendering 3D polygons. We can disable or reverse the back face culling operation on a per material basis by calling the CIwMaterial::SetCullMode method with one of the following enumeration values: CULL_FRONT, CULL_BACK, or CULL_NONE. The default is CULL_BACK.

Our polygon information has now been submitted for rendering; but we won't see it appear on screen just yet.

The final step in making something appear on screen is to flush all the drawing requests to the screen, and then display the final image.

IwGx automatically provides us with a double-buffered display setup. All this means is we do all our rendering to an off-screen buffer and then switch to displaying this buffer when all the drawing is complete. If we did not do this, we would likely see an incomplete, flickering screen display as our graphics could be displayed in an incomplete state if we drew straight to the visible display.

To complete the cycle of drawing, all we have to do is add the following two lines of code:

IwGxFlush();
IwGxSwapBuffers();

That's it! We've drawn our first polygon!