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

Collaboration diagram for QGameOpenGLES2:

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

enum QGameOpenGLES2::AntiAliasingQuality

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.

enum QGameOpenGLES2::ColorFormat

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

enum QGameOpenGLES2::DepthBufferSize

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

enum QGameOpenGLES2::ScalingPerformance

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.

enum QGameOpenGLES2::StencilBufferSize

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.

QGameOpenGLES2 Class Reference

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation