MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

OpenGL ES 2.0 interface with gaming features. More...

Inherits QObject.

Collaboration diagram for QGameOpenGLES2:
Collaboration graph
[legend]

List of all members.

Classes

class   RenderConfig
  Render configuration. Do not construct this yourself, but use API to query for available render configurations. More...
class   ScreenConfig
  Screen configuration. Do not construct this yourself, but use API to query for available screen configurations. More...

Public Types

enum   ColorFormat { ECOLOR_FORMAT_RGB565, ECOLOR_FORMAT_RGBA8888 }
 

Color format (16-bit vs. 32-bit). Note: currently on Maemo/MeeGo select 16, on Symbian^3 select 32-bit.

More...
enum   AntiAliasingQuality { EANTI_ALIASING_NONE, EANTI_ALIASING_BEST }
 

Anti-aliasing selection on / off. Depending on GFX HW architecture, enabling AA may reduce performance AND may increase graphics memory usage (less available for actual GL content). Especially on current Symbian^3 devices this might a problem due to smallish graphics memory.

More...
enum   DepthBufferSize { EDEPTH_NONE, EDEPTH_MINIMUM_16BITS, EDEPTH_MINIMUM_24BITS }
 

Depth buffer size selection. Using higher depth buffer resolution may increase graphics memory usage.

More...
enum   StencilBufferSize { ESTENCIL_NONE, ESTENCIL_8BITS }
 

Stencil buffer size selection. Enabling stencil may increase graphics memory usage.

More...
enum   ScalingPerformance { EPERFORMANCE_NORMAL, EPERFORMANCE_SLOWER }
 

Indicator of scaling performance.

More...

Public Member Functions

virtual int  RenderConfigurationCount ()=0
  Get amount of supported render configurations. Note that the ACTUAL render configuration (EGL) may have LARGER buffer depths than the configuration returned here. These configurations are "minimum" configs.
virtual void  RenderConfiguration (int aRenderConfigIndex, QGameOpenGLES2::RenderConfig &aConfiguration)=0
  Get a render configuration by index.
virtual int  ScreenConfigurationCount ()=0
  Get amount of supported screen configurations.
virtual void  ScreenConfiguration (int aScreenConfigIndex, QGameOpenGLES2::ScreenConfig &aConfiguration)=0
  Get a screen configuration by index.
virtual void  Initialize (int aRenderConfigIndex, int aScreenConfigIndex, QGameOpenGLESWrapMode aWrapMode=QGAMEOPENGLES_WRAP_MODE)=0
  Initialize OpenGL ES for rendering with selected render index and screen configuration (resolution). Surface and context are created automatically.
virtual void  Reconfigure (int aScreenConfigIndex)=0
  Reconfigure OpenGL ES to new screen configuration. GL context stays intact with reconfigure. Surface configuration / scaling configuration (underneath) may change. Since the surface may get deleted and re-created, the contents on the screen are undefined until something has been rendered and swapped.
virtual void  SwapBuffers ()=0
  Copy contents of the back buffer to the screen.
virtual void  SwapInterval (int aSwapInterval)=0
  Sets swap interval. Note that this API is a HINT. There is no readback or knowledge of whether this change actually is supported by OS / Device. E.g., Maemo / MeeGo devices do not support this setting, but Symbian^3 devices do support this.
virtual void *  ExtensionFunction (char *aFunctionName)=0
  Get extension function pointer by extension name. Using extensions are not supported "cross-OS" by this API (e.g., some extension that may work on MeeGo device may not work on Linux desktop for example).
virtual bool  IsExtensionSupported (char *aExtensionName)=0
  Query if the extension is supported or not.
virtual void  RegisterAssert (void(*aAssertFunction)(char *))=0
  Register a debugging assert. When wrapper detects a GL error situation, it will call function registered via this API (depending on GL debugging definitions). Typically the function registered here is a function with minimum functionality and breakpoint set to the code. See the main description for more in-depth info.
virtual void  MapTouchCoordinate (QPoint &aPoint)=0
  Map a touch coordinate coming from Qt to a coordinate that matches the pixel coordinate system of the render surface. Use this if you are not using native screen resolution AND you want your coordinates to lie within the 'emulated' surface resolution.
virtual QWidget GetWidget ()=0
  Get the underlying QWidget used by this API. The widget should ONLY be used for setting up event processing (touch events, Symbian events).
virtual void  Sleep ()=0
  Manually prepare the QGameOpenGLES2 to enter sleep state.
virtual void  Resume ()=0
  Resume from a sleep state.
virtual void  SetActiveMode (bool aEnable)=0
  Set game to non-active or non-active state.
virtual void  Release ()=0
  This destroys the object and all resources owned by the API.

Static Public Member Functions

static QGameOpenGLES2 Create (QApplication *aApplication, QObject *parent=0)

Protected Member Functions

virtual  ~QGameOpenGLES2 ()

Detailed Description

OpenGL ES 2.0 interface with gaming features.


Member Enumeration Documentation

Anti-aliasing selection on / off. Depending on GFX HW architecture, enabling AA may reduce performance AND may increase graphics memory usage (less available for actual GL content). Especially on current Symbian^3 devices this might a problem due to smallish graphics memory.

Enumerator:
EANTI_ALIASING_NONE 

No anti aliasing.

EANTI_ALIASING_BEST 

'best' quality anti aliasing, what this setting actually means is hardware dependent. For the current generation hardware this effectively means MSAA for the current generation of hardware this effectively means MSAA with (multi sample, anti-aliasing_ with 4 samples per pixel.

Color format (16-bit vs. 32-bit). Note: currently on Maemo/MeeGo select 16, on Symbian^3 select 32-bit.

Enumerator:
ECOLOR_FORMAT_RGB565 

16 bit color format, where each 16 bit word in memory contains all color components for a single pixel

ECOLOR_FORMAT_RGBA8888 

32 bit color format, where each 32 bit work in memory contains all the color components for a single pixel

Depth buffer size selection. Using higher depth buffer resolution may increase graphics memory usage.

Enumerator:
EDEPTH_NONE 

No depth buffer.

EDEPTH_MINIMUM_16BITS 

At minimum a 16 bit depth buffer will be created, depending on the hardware this may map to something higher

EDEPTH_MINIMUM_24BITS 

At minimum a 24 bit depth buffer will be created, depending on the hardware this may map to something higher

Indicator of scaling performance.

Enumerator:
EPERFORMANCE_NORMAL 

Means that the scaling solution is 'native', or otherwise 'a good fit' performance wise. Usually this means that the resolution is either native or uses almost "zero cost" scaling solution such as display controller scaling HW.

EPERFORMANCE_SLOWER 

Means this scaling solution is less than ideal and there will be some kind of performance impact. Normally this is implemented as a render-to-texture solution.

Stencil buffer size selection. Enabling stencil may increase graphics memory usage.

Enumerator:
ESTENCIL_NONE 

No stencil.

ESTENCIL_8BITS 

8 bit sencil


Constructor & Destructor Documentation

virtual QGameOpenGLES2::~QGameOpenGLES2 (  )  [inline, protected, virtual]

Member Function Documentation

static QGameOpenGLES2* QGameOpenGLES2::Create ( QApplication aApplication,
QObject parent = 0  
) [static]
virtual void* QGameOpenGLES2::ExtensionFunction ( char *  aFunctionName  )  [pure virtual]

Get extension function pointer by extension name. Using extensions are not supported "cross-OS" by this API (e.g., some extension that may work on MeeGo device may not work on Linux desktop for example).

Parameters:
aFunctionName  - name of the extension function.
virtual QWidget* QGameOpenGLES2::GetWidget (  )  [pure virtual]

Get the underlying QWidget used by this API. The widget should ONLY be used for setting up event processing (touch events, Symbian events).

Example:

          // Install event filter. Touch etc. processing done in the event filter.
          MyEventFilter *filter = new MyEventFilter();
          mygles->GetWidget()->installEventFilter(filter);
virtual void QGameOpenGLES2::Initialize ( int  aRenderConfigIndex,
int  aScreenConfigIndex,
QGameOpenGLESWrapMode  aWrapMode = QGAMEOPENGLES_WRAP_MODE  
) [pure virtual]

Initialize OpenGL ES for rendering with selected render index and screen configuration (resolution). Surface and context are created automatically.

Parameters:
aRenderConfigIndex  - Index of render configuration to use. Must be between zero and value returned by ScreenConfigurationCount().
aScreenConfigIndex  - Index of screen configuration to use. Must be between zero and value returned by ScreenConfigurationCount().
aWrapMode  - Operation mode used by the wrapper. Developers should normally not touch this API, but just rely on what gets chosen by the preprocessor defines.
virtual bool QGameOpenGLES2::IsExtensionSupported ( char *  aExtensionName  )  [pure virtual]

Query if the extension is supported or not.

Parameters:
aExtensionName  - name of the extension function.
virtual void QGameOpenGLES2::MapTouchCoordinate ( QPoint aPoint  )  [pure virtual]

Map a touch coordinate coming from Qt to a coordinate that matches the pixel coordinate system of the render surface. Use this if you are not using native screen resolution AND you want your coordinates to lie within the 'emulated' surface resolution.

Parameters:
aPoint  - on call input coordinate to map, upon returning the mapped coordinate.
virtual void QGameOpenGLES2::Reconfigure ( int  aScreenConfigIndex  )  [pure virtual]

Reconfigure OpenGL ES to new screen configuration. GL context stays intact with reconfigure. Surface configuration / scaling configuration (underneath) may change. Since the surface may get deleted and re-created, the contents on the screen are undefined until something has been rendered and swapped.

Parameters:
aScreenConfigIndex  - Index of screen configuration to use. Must be between zero and value returned by ScreenConfigurationCount().
virtual void QGameOpenGLES2::RegisterAssert ( void(*)(char *)  aAssertFunction  )  [pure virtual]

Register a debugging assert. When wrapper detects a GL error situation, it will call function registered via this API (depending on GL debugging definitions). Typically the function registered here is a function with minimum functionality and breakpoint set to the code. See the main description for more in-depth info.

Example:

           void myglerrorassert()
           {
              volatile int i = 0;
              i++;                            // insert breakpoint here!!
           }
Parameters:
aAssertFunction  - function to call to in GL error situation.
virtual void QGameOpenGLES2::Release (  )  [pure virtual]

This destroys the object and all resources owned by the API.

virtual void QGameOpenGLES2::RenderConfiguration ( int  aRenderConfigIndex,
QGameOpenGLES2::RenderConfig aConfiguration  
) [pure virtual]

Get a render configuration by index.

Parameters:
aRenderConfigIndex  - Index of render configuration to get. Must be between zero and value returned by RenderConfigurationCount().
aConfiguration  - Reference to render configuration where the information will be copied to.
virtual int QGameOpenGLES2::RenderConfigurationCount (  )  [pure virtual]

Get amount of supported render configurations. Note that the ACTUAL render configuration (EGL) may have LARGER buffer depths than the configuration returned here. These configurations are "minimum" configs.

virtual void QGameOpenGLES2::Resume (  )  [pure virtual]

Resume from a sleep state.

See Sleep() for a description.

virtual void QGameOpenGLES2::ScreenConfiguration ( int  aScreenConfigIndex,
QGameOpenGLES2::ScreenConfig aConfiguration  
) [pure virtual]

Get a screen configuration by index.

Parameters:
aScreenConfigIndex  - Index of screen configuration to get. Must be between zero and value returned by ScreenConfigurationCount().
aConfiguration  - Reference to a screen configuration where the information will be copied to.
virtual int QGameOpenGLES2::ScreenConfigurationCount (  )  [pure virtual]

Get amount of supported screen configurations.

virtual void QGameOpenGLES2::SetActiveMode ( bool  aEnable  )  [pure virtual]

Set game to non-active or non-active state.

Some devices have support for things such as swiping the desktop into the view when you start a drag from the side of the display. This API can be used to switch between active and non-active states. In the active state, this API disables the desktop swiping mechanisms or similar (if device has them) to give best possible game play quality.

Game should set the state to non-active when the game is paused, or if it is a main menu or other "non-active" state.

Note: this will NOT disable the screen saver / blanker. That has to be done independently through the Qt APIs.

DEFAULT value is TRUE, that is unless this API is called, the active mode is ON.

virtual void QGameOpenGLES2::Sleep (  )  [pure virtual]

Manually prepare the QGameOpenGLES2 to enter sleep state.

This function calls OS dependent functionalities to prepare QGameOpenGLES2 to handle some cleanup/setup for rendering other UI's in the application context. Since QGameOpenGLES2 is owning OpenGL ES in the application thread, using other UI systems that talk to OpenGL ES / EGL (such as QML or QT UI's when the rendering system is 'opengl' instead of say, 'raster').

Note: this does NOT hide the underlying QWidget itself. This is to make the transitions from UI to UI nicer. If you need to hide, you can call QGameOpenGLES::GetWidget->hide();

Note: on Symbian^3, this also releases the graphics memory as much as possible. If SHADOWING is in use, texture memory, VBO's etc. are freed to give the other UI change to run (it can claim graphics memory). If you are not using SHADOWING, then it is your responsibility to release some graphics memory so that the other UI can run.

Note: depending on OS, you may be able to run the 'other UI' just fine, if you set the graphics system of Qt to "raster" ():

            // Note: this needs to be done, BEFORE QApplication is constructed!
            QApplication::setGraphicsSystem(QString("raster"));

Note: if you want to have some kind of UI showing on top of the QGameOpenGLES2 render view, then your only chance is to use the "raster" graphics system as the OpenGL ES usage is going to collide between Qt and QGameOpenGLES2.

When triggering other UI's (using API's that trigger UI's in application thread), correct sequence is:

    1) call QGameOpenGLES2::Sleep()
    2) start the other UI (say QML)
    3) stop ther other UI (call hide for the other widget)
    4) call QGameOpenGLES2::Resume()

If you call hide() for the QGameOpenGLES2 widget, you must also call show() before QGameOpenGLES2::Resume()

virtual void QGameOpenGLES2::SwapBuffers (  )  [pure virtual]

Copy contents of the back buffer to the screen.

virtual void QGameOpenGLES2::SwapInterval ( int  aSwapInterval  )  [pure virtual]

Sets swap interval. Note that this API is a HINT. There is no readback or knowledge of whether this change actually is supported by OS / Device. E.g., Maemo / MeeGo devices do not support this setting, but Symbian^3 devices do support this.

Parameters:
aSwapInterval  - swap interval value. 0 means that swaps are "unsynced", 1 means 1:1 swap to VSYNC ratio, 2 means 1:2 swap to VSYNC ratio etc.

Copyright (C) 2010-2011 Nokia Corporation
Nokia Proprietary
MeeGo 1.2 Harmattan API