EGL Functions with Symbian-Specific Behavior

This topic describes the EGL functions that are defined as having platform-specific behavior and explains their expected behavior on the Symbian platform.

The functions that have Symbian-specific behavior are:

eglQueryString()

const char *eglQueryString(
                  EGLDisplay dpy,
                  EGLint name)

When name is EGL_EXTENSIONS, the function returns the list of extensions supported by the implementation. The platform-specific strings are as follows:

String Description

EGL_SYMBIAN_COMPOSITION

Indicates that the ScreenPlay variant is in use.

EGL_KHR_reusable_sync

Indicates that the EGL reusable sync extension is supported.
EGL_NOK_resource_profiling

Indicates that the EGL resource profiling extension is supported.
EGL_NOK_resource_profiling2

Indicates that the EGL resource profiling2 extension is supported.

Example 

if ( NULL == strstr(eglQueryString(display, EGL_EXTENSIONS), "EGL_SYMBIAN_COMPOSITION") ) 
    {
    RDebug::Printf("ScreenPlay not in use.");
    error = KErrNotSupported;
    }

eglCreatePixmapSurface()

EGLSurface eglCreatePixmapSurface(
                  EGLDisplay dpy,
                  EGLConfig config,
                  EGLNativePixmapType pixmap,
                  const EGLint *attrib_list)

EGLNativePixmapType is a CFbsBitmap* . See Symbian-Specific Behavior for more information.

You must choose <config> using the attribute EGL_MATCH_NATIVE_PIXMAP when calling eglChooseConfig() in order to ensure compatibility with the Symbian pixmap.

Preconditions

  • <pixmap> has been initialized.

  • The EGL_VG_ALPHA_FORMAT attribute must be set to EGL_VG_ALPHA_FORMAT_PRE if the following conditions are all true:

    • The pixel format of <pixmap> specifies premultiplied alpha—such as EColor16MAP.

    • The EGL_RENDERABLE_TYPE of <config> includes EGL_OPENVG_BIT.

Error conditions

Error Description

EGL_NO_SURFACE

Returned if any of the preconditions are violated.

EGL_BAD_NATIVE_PIXMAP

Error generated when <pixmap> is not initialized.

EGL_BAD_MATCH

Error generated when any of the following occur:

  • The attributes of <pixmap> do not correspond to those of <config>.

  • <config> does not support rendering to pixmaps (the EGL_SURFACE_TYPE attribute does not contain the EGL_PIXMAP_BIT).

  • The EGL_VG_ALPHA_FORMAT attribute is not set to EGL_VG_ALPHA_FORMAT_PRE for the cases described in the preconditions section above.

eglChooseConfig()

EGLBoolean eglChooseConfig(
                  EGLDisplay dpy,
                  const EGLint *attrib_list,
                  EGLConfig *configs,
                  EGLint config_size,
                  EGLint *num_config)

The EGLNativePixmapType value corresponding to the EGL_MATCH_NATIVE_PIXMAP attribute is CFbsBitmap*. See Symbian-Specific Behavior for more information.

The configuration attribute EGL_SWAP_BEHAVIOR_PRESERVED_BIT is set by default on window surfaces. This bit is not relevant to pixmap and pbuffer surfaces because they are single-buffered.

Postconditions

The following apply to the EGLNativePixmapType value only.

  • The EGL_SURFACE_TYPE of each matching config contains EGL_VG_ALPHA_FORMAT_PRE_BIT if the following conditions are all true:

    • The pixel format of the pixmap specifies premultiplied alpha—such as EColor16MAP.

    • The EGL_RENDERABLE_TYPE of the config includes EGL_OPENVG_BIT.

Note: The EGL_RENDERABLE_TYPE can be used as an input to eglChooseConfig() to further filter the set of configs returned.

eglSurfaceAttrib()

EGLBoolean eglSurfaceAttrib(
                  EGLDisplay dpy,
                  EGLSurface surface, 
                  EGLint attribute,
                  EGLint value);

If the attribute is EGL_SWAP_BEHAVIOR, the value can be one of the following:.

  • EGL_BUFFER_DESTROYED: Indicates that posting a surface with eglSwapBuffers() changes or destroys the back buffer content.

  • EGL_BUFFER_PRESERVED: Indicates that posting a surface with eglSwapBuffers() preserves the back buffer content.

The preserve buffer feature is relevant only to window surfaces. It is not relevant to pbuffer or pixmap surfaces because they are single-buffered. Therefore setting the swap behavior to preserve buffer is not allowed for these surface types, as shown in the following table.

Table 1. Configuration behaviors
Configuration Mask Default EGL_SWAP_BEHAVIOR Set Destroyed Allowed? Set Preserved Allowed?
EGL_SWAP_BEHAVIOR_PRESERVED_BIT|EGL_WINDOW_BIT Destroyed Yes Yes
EGL_WINDOW_BIT Destroyed Yes Yes
EGL_PIXMAP_BIT Preserved Yes No
EGL_PBUFFER_BIT Preserved Yes No

Error conditions

This applies to attempting to set the EGL_SWAP_BEHAVIOR attribute to EGL_BUFFER_PRESERVED. If the surface configuration does not match EGL_SWAP_BEHAVIOR_PRESERVED_BIT, this function returns EGL_FALSE and generates an error of EGL_BAD_MATCH.

Parent topic: EGL Interface Component

Related concepts

© Nokia 2010.