Marmalade Blog

Floating your boat – Marmalade’s newly-optimised graphics pipeline


In Marmalade 6.1, we’ve overhauled our entire graphics pipeline, including the IwGx, IwGraphics and IwAnim modules. We’ve removed all of the “software pipeline” code – including the software renderer, the software transform path, and the software lighting path. What remains is a new streamlined pipeline, entirely optimised for devices with hardware graphics acceleration.

Step back in time

Let’s step back a little. When we first designed the Marmalade graphics pipeline several years ago, there were many devices that had no (or very limited) hardware graphics acceleration. We created a flexible graphics pipeline that could independently switch the transform, lighting and rasterisation stages between our own software implementation, and any OpenGL ES drivers on the device. For example, if the pipeline had been configured to use software lighting, we would do all the vertex lighting calculations within Marmalade, without creating any OpenGL ES lights, and then pass the pre-calculated colour stream to the OpenGL ES drivers. This allowed us to support devices with no OpenGL ES drivers, or with OpenGL ES drivers that would slow to a crawl if too many lighting or transform calculations were pushed through them.

Furthermore, we many of the devices we were targeting had no hardware floating-point support. Any use of C “float” types in the app code would be compiled to a lengthy series of fixed-point instructions, adding up to a big performance hit.

Back to the future

Fast-forward to 2012. Nearly every device targeted by mobile app developers now has good hardware graphics acceleration, and hardware floating-point support. So the time was right to optimise Marmalade’s pipeline for this new reality.

Now, the historic switchable Marmalade pipeline was pretty complex, and was entirely based on fixed-point maths. Extending this to add full support for floating-point types, whilst keeping the fixed-point path at the same time, would have been very difficult and lead to a gnarly codebase. Therefore we took the decision to carve out the legacy pipeline into a separate set of libraries. These are still available for us by developers with existing fixed-point graphics code, and are stored in the “/modules/legacy” folder. Just add “define IW_USE_LEGACY_MODULES” to your MKB project file in order to link against these libraries. By default, Marmalade projects will instead link to the new floating-point libraries.

So what’s in Marmalade’s graphics 2.0?

The new graphics pipeline links to OpenGL ES 2.0 by default, as nearly every target device now supports this API. If your app code makes calls directly to the OpenGL ES 1.x APIs, you will need to add these lines to your app.icf file:


We’ve done a lot of work to ensure that OpenGL ES 2.0 also performs really well on desktop Windows/Mac, across all sorts of graphics cards. If you’ve previously had the pain of struggling with ATI cards, then your problems will hopefully be solved!

As mentioned, the new graphics pipeline now supports floating-point types for 3D vertices, normals, and UVs. Colours remain in 8888 format, and 2D vertices remain in screenspace coordinates. The transform pipeline supports 3x4 floating-point matrices.

With the legacy fixed-point types, it could be quite tricky getting the scale of models right, and if they were too small detail would get lost. Larger models required being manually cut up into smaller models. There were also problems with UV coordinates, which were restricted to the range (-8, 8). Animation also had problems, not being as smooth as it could be. All these problems are addressed by converting to floating-point, which gives us a much greater range of values to work within.

We think you’ll like the new streamlined and improved graphics pipeline. Please go onto the forums and tell us about your experiences!