EGL -Porting Guide

diff -r 4816d766a08a -r f345bda72bc4 Symbian3/PDK/Source/GUID-DC3A8785-3ED3-5696-A5ED-AB66588A5C14.dita --- a/Symbian3/PDK/Source/GUID-DC3A8785-3ED3-5696-A5ED-AB66588A5C14.dita Tue Mar 30 11:42:04 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-DC3A8785-3ED3-5696-A5ED-AB66588A5C14.dita Tue Mar 30 11:56:28 2010 +0100 @@ -1,273 +1,273 @@ - - - - - -EGL -Porting GuideThis is a guide for implementers of EGL working with the Symbian -platform. -

Target audience: Device creators.

Required functionality

The -implementation DLL must implement:

All of the standard functions declared in the EGL -Interface component.
The EGL Reusable -Sync Extension if OpenWF Composition is in use.
The EGL Resource -Profiling Extension which can be used to retrieve GPU -resource utilization information.

Any implementation-specific functions can be included in the DLL or -placed into a separate DLL.

Symbian implementations must use the following -native type interpretations for compatibility. Window and pixmap types are -actually defined as void* to avoid compilation problems for -C programs. However, the native types specified must be used, because pointers -are cast to these types within the implementation.

- - - -OpenGL ES type -Native type -Defined type - - - - -EGLNativeDisplayType -int -int - - -EGLNativeWindowType -RWindow * -void* - - - -EGLNativePixmapType -CFbsBitmap * -void* - - - -

For information about implementing window surfaces and pixmaps, -see:

Window -Surface Implementation
Pixmap -Implementation

Warning

Implementations of the EGL APIs must not -open a session (RFbsSession) with the Font -and Bitmap Server because this can lead to a deadlock caused by the -Font and Bitmap Server's dependence on EGL. Therefore within the implementation -of the EGL APIs:

Do not call RWsSession::Connect() to -create a session to the Window Server because this automatically creates an RFbsSession.
Do not call any of the -Font and Bitmap Server APIs except on a CFbsBitmap object -that has been passed into the function as an argument.

Library file

The -EGL implementation must not deliver the libEGL.lib file, -because it is provided by the EGL -Interface component. To prevent a LIB file being automatically generated, -place the NOEXPORTLIBRARY directive in the MMP project file -that builds the implementation DLL.

The LIB file delivered by the EGL Interface component has -only EGL standard functions and no implementation-specific functions. This -is to ensure that client programs do not link to implementation-specific functions -and so are portable across EGL implementations.

EGL version -variability point

The EGL -Interface component provides header files for EGL 1.2, 1.3 and 1.4. -The EGL 1.4 headers are used by default. However, there is a variability point -that can be used to change the header version. This allows a staged migration -from one version to the next.

The variability point consists of adding -one of the following #define identifiers to the eglheaders.mmh file:

SYMBIAN_EGLHEADERS_API_VERSION_1_4
SYMBIAN_EGLHEADERS_API_VERSION_1_3
SYMBIAN_EGLHEADERS_API_VERSION_1_2

The eglheaders.mmh file is #included in -the EGL Interface component's bld.inf and egllib.mmp files.

Ordinal reservation

Symbian -has adopted an ordinal reservation scheme for EGL in order to maximize extensibility -while minimizing compatibility problems. The scheme is shown in the following -table.

- - - -Ordinals -Description -Owner - - - - -

Reserved for use by implementations.

EGL implementer

- - -

2…249

Reserved for the EGL Interface component to use for the standard -functions that are defined in the EGL specification. In order to avoid future -binary compatibility issues, do not use these in your implementation.

Symbian

- - -

250…499

Reserved for use by implementations.

EGL implementer

- - - -

The following diagram illustrates a typical ordinal usage scenario.

- Typical EGL ordinal usage scenario - -

Note the following:

The DEF file for the -EGL Interface uses ordinal position entry points 2-249.
The TARGETTYPE keyword -is set to IMPLIB in the EGL Interfaces's MMP file to indicate -that only a LIB file is to be generated.
The DEF file for the -EGL implementation uses the full range of ordinal position entry points.
The NOEXPORT keyword -is used in the implementation's MMP file to suppress the generation of a LIB -file.
The TARGETTYPE keyword -is set to DLL in the implementation's MMP file to indicate -that it is a DLL project.

Internal functions

The -LIB file that the EGL Interface component produces is used to access the public -methods of libEGL.dll. However, the DLL also has private -methods. Sometimes internal access to these private methods is required—for -example, by the implementation of an EGL client rendering API, such as OpenVG.

When -access to the private methods is required, it is recommended that the EGL -implementation provides a separate private LIB file containing the internal -API calls. This private LIB file works in a similar way to the public one -in that it does not create a DLL. Appropriate clients can then link to the -private LIB file when required. Applications should use the public LIB file -to access the public methods of the EGL DLL.

This mechanism ensures -that normal clients never see the internal API calls and avoids tight coupling -with a specific implementation.

- EGL implementation's private LIB file - -

Note the following:

The DEF file for the -private interface uses ordinal position entry points 1 and 250-499.
The TARGETTYPE keyword -is set to IMPLIB in the private interface's MMP file to indicate -that only a LIB file is to be generated.
The LINKAS keyword -is used in the private interface's MMP file to indicate that it is to work -with libEGL.dll.

Extension functions

If -an EGL implementation provides an extension to EGL, clients must use the standard -EGL function eglGetProcAddress() to access that functionality. -This mechanism allows client programs to access the extension function without -the need to expose the function through the DEF file.

UIDs

The -Symbian platform libraries are given unique identifiers when they are built. -The following UIDs have been allocated for EGL implementations:

- - - -Library - UID2 -UID3 - - - - -EGL -0x1000008d -0x10281AB8 - - - -

The UIDs are provided in egluids.hrh, which -is provided in the EGL -Interface component.

Platform security

From -Symbian OS v9.0 onwards, platform security must be considered. Essentially -this requires adding the following lines to the MMP file: -

CAPABILITY All –Tcb -VENDORID <your vendor id in hex>

ROM building

Building -a ROM image for a target platform involves using IBY files. There is a generic -IBY file called egl.iby for the EGL implementation. This -must not be replaced. However, you can create an implementation-specific IBY -file. This should have a unique name with the format egl_adaptation.iby, -where adaptation is replaced by the vendor's name. For -example:

// EGL_VENDOR.IBY - -#ifndef __EGL_VENDOR_IBY__ -#define __EGL_VENDOR_IBY__ - -REM EGL Vendor implementation - -file=ABI_DIR/BUILD_DIR/libegl_vendor.dll /sys/bin/libEGL.dll - -#endif

This IBY file must be exported by the bld.inf file -to the /epoc32/rom/include/ folder.

You can include -this implementation-specific IBY file in a device ROM configuration file by -adding the following line to a top-level OBY file like this:

#define EGL_DRV <egl_vendor.iby>

This -is the preferred method. However, an alternative is to specify the IBY on -the BUILDROM command line like this:

BUILDROM ... –DEGL_DRV="^<"EGL_vendor.iby"^>" ...

Notice that the ^ character is used as an escape character for the < -and > characters.

See Selection -of Adaptations for more information.

Project files

Here -is an example MMP file:

#include "/epoc32/include/platform/egl/egluids.hrh" // For UIDs - -// These statements are always required: -target libEGL.dll // Destination filename -targettype dll // Binary build type -uid KUidSharedDllUidValue KUidEGLDllUidValue // File UIDs -capability All –Tcb // Platform Security requirement -vendorid <Your vendor ID in hex> -NOEXPORTLIBRARY // Suppress generation of LIB/DSO file -DEFFILE libegl13.def - -// These statements are examples and may vary: -userinclude ../include // Local include files -systeminclude /epoc32/include // Symbian include files - -sourcepath ../egl // Relative path to source files - -source context.cpp // Source files -source display.cpp -source egl.cpp -source surface.cpp - -library euser.lib // For the user library. -library fbscli.lib // For CFbsBitmap, etc. -library bitgdi.lib // For CFbsBitmapDevice, CFbsBitGc, etc. -library ws32.lib // For RWindow, Direct Screen Access, etc.

Example bld.inf

A bld.inf file -is also required:

PRJ_PLATFORMS -DEFAULT - -PRJ_EXPORTS -egl_vendor.iby /epoc32/rom/include/egl_vendor.iby - -PRJ_MMPFILES -./egl.mmp

-Window Surface -Implementation -Pixmap Implementation - -EGL Interface -Component -EGL Collection -Overview -http://www.khronos.org/egl/ - + + + + + +EGL +Porting GuideThis is a guide for implementers of EGL working with the Symbian +platform. +

Target audience: Device creators.

Required functionality

The +implementation DLL must implement:

All of the standard functions declared in the EGL +Interface component.
The EGL Reusable +Sync Extension if OpenWF Composition is in use.
The EGL Resource +Profiling Extension which can be used to retrieve GPU +resource utilization information.

Any implementation-specific functions can be included in the DLL or +placed into a separate DLL.

Symbian implementations must use the following +native type interpretations for compatibility. Window and pixmap types are +actually defined as void* to avoid compilation problems for +C programs. However, the native types specified must be used, because pointers +are cast to these types within the implementation.

+ + + +OpenGL ES type +Native type +Defined type + + + + +EGLNativeDisplayType +int +int + + +EGLNativeWindowType +RWindow * +void* + + + +EGLNativePixmapType +CFbsBitmap * +void* + + + +

For information about implementing window surfaces and pixmaps, +see:

Window +Surface Implementation
Pixmap +Implementation

Warning

Implementations of the EGL APIs must not +open a session (RFbsSession) with the Font +and Bitmap Server because this can lead to a deadlock caused by the +Font and Bitmap Server's dependence on EGL. Therefore within the implementation +of the EGL APIs:

Do not call RWsSession::Connect() to +create a session to the Window Server because this automatically creates an RFbsSession.
Do not call any of the +Font and Bitmap Server APIs except on a CFbsBitmap object +that has been passed into the function as an argument.

Library file

The +EGL implementation must not deliver the libEGL.lib file, +because it is provided by the EGL +Interface component. To prevent a LIB file being automatically generated, +place the NOEXPORTLIBRARY directive in the MMP project file +that builds the implementation DLL.

The LIB file delivered by the EGL Interface component has +only EGL standard functions and no implementation-specific functions. This +is to ensure that client programs do not link to implementation-specific functions +and so are portable across EGL implementations.

EGL version +variability point

The EGL +Interface component provides header files for EGL 1.2, 1.3 and 1.4. +The EGL 1.4 headers are used by default. However, there is a variability point +that can be used to change the header version. This allows a staged migration +from one version to the next.

The variability point consists of adding +one of the following #define identifiers to the eglheaders.mmh file:

SYMBIAN_EGLHEADERS_API_VERSION_1_4
SYMBIAN_EGLHEADERS_API_VERSION_1_3
SYMBIAN_EGLHEADERS_API_VERSION_1_2

The eglheaders.mmh file is #included in +the EGL Interface component's bld.inf and egllib.mmp files.

Ordinal reservation

Symbian +has adopted an ordinal reservation scheme for EGL in order to maximize extensibility +while minimizing compatibility problems. The scheme is shown in the following +table.

+ + + +Ordinals +Description +Owner + + + + +

Reserved for use by implementations.

EGL implementer

+ + +

2…249

Reserved for the EGL Interface component to use for the standard +functions that are defined in the EGL specification. In order to avoid future +binary compatibility issues, do not use these in your implementation.

Symbian

+ + +

250…499

Reserved for use by implementations.

EGL implementer

+ + + +

The following diagram illustrates a typical ordinal usage scenario.

+ Typical EGL ordinal usage scenario + +

Note the following:

The DEF file for the +EGL Interface uses ordinal position entry points 2-249.
The TARGETTYPE keyword +is set to IMPLIB in the EGL Interfaces's MMP file to indicate +that only a LIB file is to be generated.
The DEF file for the +EGL implementation uses the full range of ordinal position entry points.
The NOEXPORT keyword +is used in the implementation's MMP file to suppress the generation of a LIB +file.
The TARGETTYPE keyword +is set to DLL in the implementation's MMP file to indicate +that it is a DLL project.

Internal functions

The +LIB file that the EGL Interface component produces is used to access the public +methods of libEGL.dll. However, the DLL also has private +methods. Sometimes internal access to these private methods is required—for +example, by the implementation of an EGL client rendering API, such as OpenVG.

When +access to the private methods is required, it is recommended that the EGL +implementation provides a separate private LIB file containing the internal +API calls. This private LIB file works in a similar way to the public one +in that it does not create a DLL. Appropriate clients can then link to the +private LIB file when required. Applications should use the public LIB file +to access the public methods of the EGL DLL.

This mechanism ensures +that normal clients never see the internal API calls and avoids tight coupling +with a specific implementation.

+ EGL implementation's private LIB file + +

Note the following:

The DEF file for the +private interface uses ordinal position entry points 1 and 250-499.
The TARGETTYPE keyword +is set to IMPLIB in the private interface's MMP file to indicate +that only a LIB file is to be generated.
The LINKAS keyword +is used in the private interface's MMP file to indicate that it is to work +with libEGL.dll.

Extension functions

If +an EGL implementation provides an extension to EGL, clients must use the standard +EGL function eglGetProcAddress() to access that functionality. +This mechanism allows client programs to access the extension function without +the need to expose the function through the DEF file.

UIDs

The +Symbian platform libraries are given unique identifiers when they are built. +The following UIDs have been allocated for EGL implementations:

+ + + +Library + UID2 +UID3 + + + + +EGL +0x1000008d +0x10281AB8 + + + +

The UIDs are provided in egluids.hrh, which +is provided in the EGL +Interface component.

Platform security

From +Symbian OS v9.0 onwards, platform security must be considered. Essentially +this requires adding the following lines to the MMP file: +

CAPABILITY All –Tcb +VENDORID <your vendor id in hex>

ROM building

Building +a ROM image for a target platform involves using IBY files. There is a generic +IBY file called egl.iby for the EGL implementation. This +must not be replaced. However, you can create an implementation-specific IBY +file. This should have a unique name with the format egl_adaptation.iby, +where adaptation is replaced by the vendor's name. For +example:

// EGL_VENDOR.IBY + +#ifndef __EGL_VENDOR_IBY__ +#define __EGL_VENDOR_IBY__ + +REM EGL Vendor implementation + +file=ABI_DIR/BUILD_DIR/libegl_vendor.dll /sys/bin/libEGL.dll + +#endif

This IBY file must be exported by the bld.inf file +to the /epoc32/rom/include/ folder.

You can include +this implementation-specific IBY file in a device ROM configuration file by +adding the following line to a top-level OBY file like this:

#define EGL_DRV <egl_vendor.iby>

This +is the preferred method. However, an alternative is to specify the IBY on +the BUILDROM command line like this:

BUILDROM ... –DEGL_DRV="^<"EGL_vendor.iby"^>" ...

Notice that the ^ character is used as an escape character for the < +and > characters.

See Selection +of Adaptations for more information.

Project files

Here +is an example MMP file:

#include "/epoc32/include/platform/egl/egluids.hrh" // For UIDs + +// These statements are always required: +target libEGL.dll // Destination filename +targettype dll // Binary build type +uid KUidSharedDllUidValue KUidEGLDllUidValue // File UIDs +capability All –Tcb // Platform Security requirement +vendorid <Your vendor ID in hex> +NOEXPORTLIBRARY // Suppress generation of LIB/DSO file +DEFFILE libegl13.def + +// These statements are examples and may vary: +userinclude ../include // Local include files +systeminclude /epoc32/include // Symbian include files + +sourcepath ../egl // Relative path to source files + +source context.cpp // Source files +source display.cpp +source egl.cpp +source surface.cpp + +library euser.lib // For the user library. +library fbscli.lib // For CFbsBitmap, etc. +library bitgdi.lib // For CFbsBitmapDevice, CFbsBitGc, etc. +library ws32.lib // For RWindow, Direct Screen Access, etc.

Example bld.inf

A bld.inf file +is also required:

PRJ_PLATFORMS +DEFAULT + +PRJ_EXPORTS +egl_vendor.iby /epoc32/rom/include/egl_vendor.iby + +PRJ_MMPFILES +./egl.mmp

+Window Surface +Implementation +Pixmap Implementation + +EGL Interface +Component +EGL Collection +Overview +http://www.khronos.org/egl/ +

\ No newline at end of file