Nokia N97 SDK
Example Applications Guide

OpenC OpenGL ES Example

1. About this Example
2. Prerequisites
3. Design and Implementation


1. About this Example

The OpenC OpenGL ES example demonstrates how to create a simple interactive OpenC 3D application, on Symbian OS. The program described here displays a rotating cube, that can be moved using the up and down keys. The application can be exited by pressing the right soft key. This application can be easily adapted to make much more interesting 3D applications, using OpenGL ES, in the OpenC environment.
cube.gif


2. Prerequisites

To build and run this example you need to have the S60 SDK installed and working correctly on your computer. You also need a basic understanding on how to build S60 applications. This example also requires familiarity with OpenGL ES, the C++ programming language, and access to the Symbian OS documentation.


3. Design and Implementation

3.1 Capabilities

No capabilities are needed for running the executable.

3.2 ScalableUI

The program is designed to work with all screen modes. The program supports changing the screen layout while the program is running.

3.3 Static structure

The application comprises of the following classes:

All the above classes are derived from CBase, which has a number of useful features, namely:

3.4 Launch sequence and event handling

This section explains the operations performed during application launch and the steps for handling events.

  1. Once the application is launched, the operating system loads the application executable and the main method is called.
  2. The EGL Initialization is done for the default display.
  3. A new Active Scheduler is installed, to ensure that the Active Objects installed by the CCoeEnv are not run.
  4. The CGameController object is intialized.
    The Game Controller takes care of
  5. The CGame object is initialized. The CGame object takes care of rendering using opengl es apis and responding to key events.
  6. The Game loop is started by calling the CGameController::StartGameL() function.
  7. Any key related or focus related events are received by the CWsEventReceiver Active Object and passed on to the CGameController object.
  8. After the CGame::RenderFrame() API returns EFalse, the game is exited. This happens when the Right Soft Key is pressed.
  9. After the Game's exit, Cleanup is performed on the Game & Game Controller Objects. This inturn ensures that the egl surfaces and contexts that were created are destroyed.
  10. Finally, eglTerminate performs the final cleanup and the application exits.

The following sections describe the above steps in more detail.

3.4.1 Initializing the Application

The initialization of the application involves initializing the egl display, using calls to eglGetDisplay and eglInitialize. After eglInitialize is successful, the currently installed Active Scheduler is deleted and a new Active Scheduler is installed. This is done to prevent any unnecessary active objects from running. The following sections cover the creation of the Game Controller and Game objects, in detail.

3.4.2 Creating the Game Controller object

The Game Controller (CGameController) creation involves the following steps:

The CGameController::CreateNativeWindowL() is responsible for creating the RWindow object and making it visible.

NOTE: The address of the created RWindow is passed as the window handle to eglCreateWindowSurface.

3.4.3 Creating the Game object

The CGame object is solely responsible for rendering the rotating cube, using opengl es apis. On creation, the CGame object initializes the opengl es state by initializing the view frustum, shading model and the vertex/color arrays.

3.4.4 The Game loop

The Game loop performs the following steps:

The CGame::RenderFrame() API make sure that the frames are rendered at 25 frames per second.

The game loop is exited once CGame::RenderFrame() returns EFalse.

The processing of background tasks is explained in more detail in the next section.

3.4.5 Processing Background tasks

The CWsEventReceiver Active object waits for the Windows Server events. Whenever, a windows server event is pending, the CWsEventReciever Active object should get a chance to run. This is ensured by calling the CGameController::ProcessBackgroundTasks() function. This function has a blocking mode as well as a non-blocking mode, based on the parameter passed in. In the blocking mode, the function blocks till an asynchronous event occurs and then gives the Active Scheduler a chance to run on all the pending events. In the non-blocking mode, it runs the Active Scheduler only if there are any pending asynchronous events.

3.4.6 Handling Key Events

The key events (press / release) from the Windows Server are captured by the CWsEventReceiver Active Object. The active object then forwards this to the CGameController object, which in turn forwards it to the CGame object. The CGame object moves the rotating cube based on the up / down keys and quits if the Right Soft Key is pressed.

3.4.6 Handling Key Events

The focus events (gain / lost) from the Windows Server are captured by the CWsEventReceiver Active Object. The active object then forwards this to the CGameController object. If the focus is lost, the Game Controller ensures that the ProcessBackgroundTasks() is called in the blocking mode, until the focus is gained. This is to ensure that no unnecessary processing is done when the window does not have focus.

3.4.8 Cleanup

Once the CGame::RenderFrame API returns EFalse, the cleanup on the application is performed. This mainly involves cleaning up the CGame and CGameController objects. The destructor of the CGameController object ensures that the egl related resources are cleaned up. Finally, the eglTerminate() API ensures the final cleanup of egl resources.

© Nokia 2009

Back to top