Now that we are familiar with resource management, we can get on to the more interesting task of showing a picture on the display.
Marmalade spoils us by providing several different ways in which we can draw graphics on the screen. The following sections provide an overview of the different options available to us.
The lowest level of display access is the
s3eSurface API. This provides access to the display by using a memory pointer that you can then use to directly read or alter pixels.
You can discover the width and height of the display in pixels and also the pitch, which is the number of bytes that you need to skip through memory to get to the next row of the display image.
The pitch is affected by the pixel format of the display (16-, 24-, or 32-bit displays are all possible) and often extra padding bytes are also added to allow each row to begin on a word-aligned memory address, which can improve display memory access times.
In practice this API is very rarely used, partly because it provides no support for drawing bitmapped images or lines, but mostly because it is incredibly slow on many modern devices due to the display being drawn by a Graphics Processing Unit (GPU), which may place restrictions on how and when this memory can be accessed by the CPU.
We will not be using this API anywhere in this book, but if you wish to use it there is nothing you have to add to your project as it is always available in any Marmalade project.
As mentioned above, most mobile devices available today contain a GPU that is used to speed up drawing operations and free the CPU for other tasks, such as updating the current state of a game. The standard API that has been adopted across most mobile platforms is OpenGL ES.
The OpenGL ES API is a derivative of the OpenGL API, which has been used on many desktop systems for many years. OpenGL ES was conceived as a cut-down version of OpenGL designed for embedded systems (hence the ES part of the name!).
There are two main versions of the OpenGL ES. The 1.x standard is intended for devices that have fixed, function rendering pipelines, which means that while control is provided in how a 3D point is transformed to 2D coordinates, and how a polygon and its associated textures (if any) are rasterized to the screen, you are completely limited to the options provided by the hardware.
The 2.x standard of OpenGL ES is intended for GPU hardware where the act of both transforming 3D points and rasterizing the resultant polygons can be programmed by way of shaders. A shader is a short program that can be applied very quickly to either transform 3D points (a vertex shader) or work out the required color of a rendered pixel (a pixel or fragment shader).
In most cases a device supporting OpenGL ES 2.x will also support OpenGL ES 1.x, but the two cannot be mixed. When initializing OpenGL, you request one or the other of these interfaces to be created as the OpenGL context. The context is really nothing more than a big structure which stores all the information that OpenGL needs in order to operate, such as the current frame buffer, pixel blending mode, and available shaders.
So what exactly is the IwGL API? Put simply, it is a wrapper for OpenGL ES that allows us to make normal OpenGL ES function calls directly, but it also provides some other very useful functionality:
- IwGL simplifies the process of initializing OpenGL ES to a single function call—
IwGLInit. This function call will initialize the frame buffer and set up the OpenGL context so that it is ready and raring to go, with settings that should be optimal for the type of hardware available. Fine control over initialization is also provided to allow display and depth buffer formats to be chosen using settings made in the application's ICF file. - It provides context state caching functions, such as keeping a copy of all textures currently uploaded to OpenGL ES. In the event of your application being suspended (for example, by an incoming call) all its textures and other resources could be lost, and normally it would be your responsibility to reload everything you need. IwGL automatically takes care of all this for us.
- Any OpenGL ES extension functions (extra functionality that a particular GPU may provide over and above the required base level of OpenGL ES) become mapped to functions that can be called directly and will not cause an error if that function is not actually supported. Normally you would need to specifically check if an extension exists before trying to call it.
- It also provides a Virtual Resolution system that makes it easy to take existing code that was hardcoded to a particular resolution or screen orientation and make it run at a different resolution or orientation by resizing or rotating the rendered image.
IwGL is an invaluable part of the Marmalade SDK when you are porting existing code written using OpenGL ES, as it allows you to take advantage of Marmalade's ability to deploy to multiple platforms without having to completely recode the entire project.
However, we won't be using IwGL in this book either. While there is nothing to stop us from using this API to develop a new project, it does mean we are limited to targeting only devices that feature GPUs (or support a software emulated version of OpenGL), and we still need to take care of things like loading textures ourselves.
You can use the IwGL API in your own project by adding iwgl to the subprojects section of the MKB file.
Given that this is a chapter about 2D graphics rendering, the Iw2D API must surely be the way to go, right?
Well, yes and no. It certainly has a lot going for it, like the following:
- It provides us with the ability to render flat shaded primitives such as lines, arcs, rectangles, and polygons, either as outlines or filled shapes.
- It allows us to easily load bitmapped images and render them on screen and also apply scaling or rotational transforms to those images.
- It makes it easy for us to draw text on screen that looks substantially better than the default debug font we've currently seen.
- It provides certain optimizations that allow us to speed up rendering. For example, it can batch together several requests to draw a particular image into a single call, which can yield good performance increases on many devices.
However, as you've probably already inferred from the tone of this section, we won't be using Iw2D in this book either.
If you are only interested in rendering 2D graphics, Iw2D may well be perfectly adequate for your needs, but if you ever want to make the jump to 3D graphics you will eventually find that the Iw2D API just doesn't do everything you need, such as rendering textured polygons of any shape, not just rectangular.
Since we will be tackling 3D graphics later in this very book, it makes sense for us to begin our journey into rendering with Marmalade by using 3D graphics itself.
If you want to use this API in your own project, just add iw2d to the subprojects section of the MKB file.
Finally we come to the API that we will be using in this book; in fact we have already used a very small part of it in the creation of our "Hello World" project. Ladies and gentlemen, I give you the IwGx API!
This API is extremely flexible and boasts the following functionalities:
- It supports both hardware and software rendering pipelines, so your code can potentially run unaltered on modern hardware featuring a GPU yet still fall back to a software-based renderer for older or less capable hardware. You can even mix the two pipelines, so you could use the GPU for rasterization but still use the CPU for transform and lighting operations.
- It takes care of the nitty-gritty for us, such as initializing the display and texture management, in a similar way to the IwGL API.
- It allows us to use features such as texture mapping and flat or gouraud shading on arbitrary polygons.
- It provides some debugging functionality, such as simple text rendering (as in our "Hello World" project) and rendering shapes like rectangles and circles.
- It makes targeting OpenGL ES 2.x devices much easier, as it provides the necessary shader programs to emulate the fixed function pipeline of Open GL ES 1.x while still allowing us to provide our own custom shaders when we want to.
By using IwGx for rendering 2D graphics from the start, we will find it a whole lot easier to move on to drawing 3D polygons later, as the techniques involved are incredibly similar.
Note
With Version 6.1 of Marmalade, the IwGx API underwent a little modernization and standardized using floating point values for specifying polygon information. Prior to this version, some information (for example, texture UV values) was specified in fixed point integer formats. There was also a software-based rendering engine for targeting old devices with no GPU hardware. If you have existing code that still needs the old fixed point way of doing things, you can revert back by adding define IW_USE_LEGACY_MODULES to the project MKB file.
It should come as no surprise by now that we can use IwGx in our project simply by adding iwgx to the subprojects section of the MKB file.