Porting a C/C++ OpenGL ES 2.0 iOS (iPhone) project "Match'em Poker" to Symbian^3

There are several ways a developer can choose from when facing this kind of a porting challenge. Porting is always possible, although it might mean rewriting the code completely. Luckily, in most cases it is easier. The porting of MatchemPoker aims to use existing assets as much as possible; examining how easily an iOS project can be ported to a Symbian^3 platform using all available means.

Program structure

The original MatchemPoker was designed with ease-of-porting in mind. It was written with the amount of pure C/C++ / OGLES 2.0 maximised, and platform-specific code isolated behind interfaces. The framework (engine) the game uses is called TileGame. It is designed for any "sprite"-based-games; puzzles, platformers, and so on, and consists of two parts: The game (ITileGame) and the engine (ITileRenderer). ITileGame is the interface for the actual game, and ITileRenderer is its 'runner'.

ITileEngine flow:

• Initialise framework. Window, OpenGL, etc.
• createTileGame
• prepare game
• run main loop
  • Listen to events and react to them (focus changed, screen touched, profile changed, and so on)
• release game
• delete game
• cleanup environment

Project

When we start the porting, the first thing required is a new Qt project. With MatchemPoker porting, the new project was created using Qt Creator's built-in wizard. It was known that the original game renders itself completely with OpenGL ES 2.0 which is not directly supported in a Qt application. As stated earlier, this was solved by using ​Qt !GameEnabler that provides native OpenGL ES 2.0. The next step was to get it working.

• Get QtGameEnabler's sources from the Nokia Developer project.
• Add the required files into the new project (All the files under QtGameEnabler's src folder).
• Tweak your PRO file a little bit.
  • All of the platforms to be built in a project using Qt GameEnabler require a OpenGL ES 2.0 library that can be linked against.
  • On Symbian^3 platforms, the libraries are already there, they just need to be added:

PRO file

symbian: {
	LIBS += -llibEGL -llibGLESv2
}

NOTE: The OpenGL libraries must be provided for each platform separately

If you want to build for Windows desktop for example, you must get some OpenGL ES 2.0 emulation libraries and use them to link against. ​Imgtec provides a good and easy-to-use solution for this. They are not open, but free. The downloading requires a registration and acceptance of a licence agreement.

When Qt GameEnabler is used, the application using it must implement at least a GE::GameWindow. So, this was the next step the porting project required. The Qt version of MatchemPoker has a QtTileGameEngine which is derived from GE::GameWindow and !ITileRenderer. This way we can implement GameEnabler's program-specific functionality and !ITileGame's functionality into a single class.

Once the project was building with Qt GameEnabler code inside, it was time to add all of the original MatchemPoker source files into the Qt project and start testing the compilation to get a list of errors to fix. Most of the files compiled without problems.

Before the game can actually run, the functionality of the !ITileRenderer must be implemented. This was codewise the most time consuming part with MatchemPoker. A new implementation of it (QtTileGameEngine) was created and implemented. OpenGL ES 2.0 rendering code was copied from the iOS version of the renderer. Some modifications/optimisations were done to the shaders and the rendering. For example, on Symbian^3 several triangle strips were very slow and they were replaced with fans.

Textures

In many cases, iOS textures are packed with the PowerVR - SDK's format (.PVR). These files cannot be used directly with Symbian^3 so the textures must be decoded to some open format. The easisest way of doing this is to get the free PowerVR SDK which provides the necessary tools for the task. Of course, it is better to use original unpacked formats to maximise the quality of graphics.

In MatchemPoker, this was the case. The iOS project had the original PNGs which were directly added into the new QRC file (textures.qrc) in the Qt project and used directly from there via Qt's resource system.

Icon

To have a high-quality icon on Symbian^3 devices, the image must be in SVG format. In iOS, PNG icons are normally used. Therefore the icon must be converted into an SVG that is readable by Symbian^3. An open-source (free) program, Inkscape, was used to create an SVG container which embedded the original PNG into itself. Steps:

• Launch Inkscape
• New document
• Set document's resolution (document properties) to 128x128
• Drag'n'drop the original PNG icon on the Inkscape document
• Select 'embed PNG' from the pop-up menu displayed
• Move and scale the PNG to match the SVG document's borders
• Save as Inkscape SVG
• Add 'ICON = savedsvg.svg' into the PRO file

Sounds

The original audio files were in WAV format, so no specific changes were required. The audio files were checked with a wave editor (Audacity) to make sure their properties were good for QtGameEnabler's audio playback (a good samplerate for QtGameEnabler's Audio is 22050Khz). A new Qt resource file (sounds.qrc) was created and added into the main project. All of the audio files were added into this QRC.

Audio playback

The iOS version uses its simple 'playSound' function for audio playback. Obviously this couldnt be used directly. Qt GameEnabler includes audio playback functionality which was deployed in the port. Sounds were added inside a QRC file and loaded into the memory at the beginning of the run. Qt GameEnabler's functionality was used to play the samples in ITileRenderer's effectNotify method.