3.8 `glcanvas` -- UI Control for Displaying OpenGL ES Graphics

Availability: S60.

The glcanvas module provides a UI control, GLCanvas, for displaying OpenGL ES graphics. GLCanvas component is similar to the appuifw Canvas component that supports Symbian OS -level drawing.

Internally GLCanvas uses EGL for displaying the OpenGL ES graphics. EGL, as OpenGL ES, is a standard API defined by the Khronos Group (www.khronos.org). Specifically, GLCanvas uses an EGL window surface, which supports double-buffered rendering. It is possible to affect selection of the EGL config that is used to create the window surface; for details, see the documentation of the GLCanvas constructor.

GLCanvas instances also hold the OpenGL ES context object, which together with the surface, are needed for rendering. When one wants to render with a specific OpenGL ES context to a specific surface, they need to be made current. This also applies to GLCanvas, which has the makeCurrent method for this purpose. Generally, calling makeCurrent has to be done only if multiple GLCanvas objects are used in the same program, as each GLCanvas object is automatically made current when it is created and it remains current until it is destroyed or makeCurrent of some other GLCanvas object is called.

class GLCanvas( redraw_callback, [event_callback=None, resize_callback=None, attributes=None])

Constructs a new GLCanvas object that can be used as a UI control for displaying OpenGL ES graphics. Parameters redraw_callback, event_callback, and resize_callback have the same meaning as with appuifw module Canvas. Using redraw_callback to specify the OpenGL ES drawing is preferred as it will be automatically called by drawNow method.

Parameter attributes can be used to specify attributes used in EGL config selection. It must be a Python dictionary where keys are EGL attribute names (which are defined in the glcanvas module) and values are integers defining the desired attribute values. Unless specified in attributes, EGL_BUFFER_SIZE is set to value based on the display mode of the window owned by the underlying CCoeControl object and EGL_DEPTH_SIZE is set to 16. Attributes specified in attributes are given to eglChooseConfig. Refer to the EGL specification for a detailed list of config attributes and explanation of how the selection of EGL configs works.

The new GLCanvas object will be made current when the constructor returns so makeCurrent does not have to be called before starting to use OpenGL ES calls.

bind( key_code, c [, ((x1, y1), (x2, y2))]): Sets a callback to be called when a specific key is pressed or pointer event occurs. Parameter key_code should be one of the standard Symbian key codes defined in key_codes. Parameter c must be a callable object. The optional two co-ordinate tuple corresponds to the top left and bottom right points of the rectangle to be monitored for pointer events. This argument is ignored for Key events.
For different bind scenarios refer Canvas's bind method.

drawNow( ): Calls the redraw callback (if set) and then calls eglSwapBuffers to render and display the OpenGL ES graphics.

makeCurrent( ): Makes this GLCanvas object current, meaning that it will be used to display the results of the subsequent OpenGL ES calls. In EGL terms this means that the EGL context and surface held by this object will be passed to eglMakeCurrent. Using makeCurrent makes it possible to use several GLCanvas objects in a single application: the receiver of the OpenGL ES calls can be switched with makeCurrent easily.

See About this document... for information on suggesting changes.

3.8 glcanvas -- UI Control for Displaying OpenGL ES Graphics

3.8 `glcanvas` -- UI Control for Displaying OpenGL ES Graphics