OpenVG Porting Guide

Required functionality

The implementation DLL must implement all of the standard functions declared in the OpenVG Interface component and optionally any implementation-specific functions. Alternatively, implementation-specific functions can be placed into a separate DLL.

The reserved ordinal entry points are only for use by Symbian in order to avoid future binary compatibility issues. Therefore you must not use them for implementation-specific functions.

The header files are provided for both OpenVG 1.0 and OpenVG 1.1. Stub openvg.h and vgu.h files redirect to the OpenVG 1.0 headers by default. However a variability point can be used to expose the OpenVG 1.1 headers. See OpenVG Version Variability Point for information.

LIB files

• The OpenVG specification specifies that the VGU implementation is not guaranteed to be available at runtime. However, Symbian recommends that the VGU library is provided on all smartphones that support OpenVG. Providing the VGU library means that the size of application binaries can be reduced whilst maintaining broad compatibility.

• The OpenVG implementation must not deliver the LIB files, because they are provided by the OpenVG Interface component. To prevent LIB files being automatically generated, place the NOEXPORTLIBRARY directive in the MMP project file that builds the implementation DLL.

• The LIB file provides exports all of the OpenVG 1.0 and OpenVG 1.1 functions. See OpenVG Version Variability Point for information about controlling which version is exposed.

• The libOpenVG.lib file includes only OpenVG standard functions and no implementation-specific functions. This means that client programs do not link to functions that are specific to a particular OpenVG implementation and therefore allows client program portability to other OpenVG implementations.

Extension functions

If an OpenVG implementation provides an extension to OpenVG, clients must use the standard EGL function eglGetProcAddress to access such functionality. This mechanism allows client programs to access the extension function regardless of which ordinal position has been chosen by the OpenVG vendor.

Internal functions

Sometimes internal access to the OpenVG implementation is required—for example, in a bench marking or regression test for the OpenVG implementation. To avoid tight coupling with a specific implementation in these circumstances, Symbian recommends that the OpenVG implementation provides a separate vendor-specific LIB file containing the internal API calls. Then appropriate clients can link to the internal LIB file when required. This mechanism ensures that normal clients never see the internal API calls.

UIDs

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

ROM building

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

// OPENVG_VENDOR.IBY
     
#ifndef __OPENVG_VENDOR_IBY__
#define __OPENVG_VENDOR_IBY__
    
REM OpenVG implementation
    
file=ABI_DIR/BUILD_DIR/libOpenVG.dll   sys/bin/libOpenVG.dll
file=ABI_DIR/BUILD_DIR/libOpenVGU.dll  sys/bin/libOpenVGU.dll
    
#endif

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

You include the implementation-specific IBY file in a device ROM configuration file by defining the OPENVG_DRV macro in a top-level OBY file or in the buildrom command. For example, in a top-level OBY file, declare the following:

#define OPENVG_DRV <openvg_vendor.iby>

See Selection of Adaptations for more information.

Example project (MMP) file

The MMP file brings the details described above together. For example:

#include "/epoc32/include/platform/vg/openvguids.hrh"                // For UIDs
    
// These statements are always required:
target          libOpenVG.dll                               // Destination filename
targettype      dll                                         // Binary build type
uid             KUidSharedDllUidValue KUidOpenVGDllUidValue // File UIDs
capability      All –Tcb
vendorid        <your vendor id in hex>
noexportlibrary
DEFFILE         libegl13U.def
    
// These statements are examples and may vary:
userinclude     ../include                                  // Local include files
systeminclude   /epoc32/include                             // General Symbian include files
    
sourcepath      ../openvg                                   // Relative path to source files
    
source          context.cpp                                 // Source files
source          image.cpp
source          path.cpp
    
library         euser.lib             
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 file

The bld.inf file specifies the exports and the MMP files. For example:

PRJ_PLATFORMS
DEFAULT    
    
PRJ_EXPORTS
openvg_vendor.iby  /epoc32/rom/include/openvg_vendor.iby
    
PRJ_MMPFILES
./openvg.mmp