Khronos API Implementers Guide

Implementers are strongly encouraged to use the standard header files (egl.h, gl.h, kd.h, etc.) provided by Khronos for each specification. Links are provided in Table 1, “Header File Names and Locations”. Portable and non-portable definitions are separated into <api>.h and <api>platform.h files. The intention is that implementers do not need to change the former and they are strongly discouraged from doing so. Consider contributing any header file changes back to Khronos by updating the files in the Khronos Subversion tree so that others may benefit from your expertise.

If you make your own header files use the names given in Table 1, “Header File Names and Locations”.

If the platform is Windows, make sure your header files are suitable for use with MFC. For example #define EGL_DEFAULT_DISPLAY GetDC(0) is broken for MFC. You need to use ::GetDC(0) because several Microsoft Foundation Classes have their own GetDC(void) methods.

When including one header in another, include the parent directory name. For example when including eglplatform.h in egl.h use #include <EGL/eglplatform.h>. Do not use #include <eglplatform.h> because application makefiles will then need 2 different -I<path> options to find both include files.

Functions and enumerants for implementer extensions should be declared and defined in an implementer's own header file. Follow the extension writing and naming rules given in How to Create Khronos API Extensions . Use enumerant values obtained from the Khronos Extension Registry, as explained in OpenGL Enumerant Allocation Policies .

Function declarations and constant definitions for EGL are divided into 2 header files: egl.h declares and defines all the core functions and constants; eglext.h declares and defines functions and constants for all Khronos approved extensions and can be used even if the implementation doesn't provide a particular extension.

Platform dependent and non-portable items are in eglplatform.h, which needs to be modified by the implementer. In particular the eglNativeDisplayType, eglNativeWindowType, and eglNativePixmapType typedefs must be defined as appropriate for the platform (typically, they will be typedef'ed to corresponding types in the native window system). Developer documentation should mention the correspondence so that developers know what parameters to pass to eglCreateWindowSurface, eglCreatePixmapSurface, and eglCopyBuffers. Documentation should also describe the format of the display_id parameter to eglGetDisplay, since this is a platform-specific identifier.

Package these and any header files for implementer extensions in the folder EGL.

Do not include gl.h in egl.h .

As with EGL, the function declarations and constant definitions for OpenGL ES 1.x are divided into 2 header files: gl.h and glext.h.

Platform dependent and non-portable declarations are in glplatform.h. This file may need to be modified by the implementer.

Package these and any header files for implementer extensions in the folder GLES.

For compatibility with GLES 1.0 implementations, include in GLES a special egl.h containing the following:

#include <EGL/egl.h>
#include <GLES/gl.h>

This is because many early OpenGL ES 1.0 implementations included gl.h in egl.h so many existing applications only include egl.h .

The name glu.h is reserved for future use by the Khronos Group.

The organization of the header files for OpenGL ES 2.x mirrors that for OpenGL ES 1.x. except that the files are called gl2.h, gl2ext.h & gl2platform.h to keep them distinct from the GLES 1.x header files and enable both versions to coexist on a platform.

Package these and any header files for implementer extensions in the folder GLES2.

The name glu2.h is reserved for future use by the Khronos Group.

Function declarations and constant definitions for OpenKODE are in kd.h; platform dependent and non-portable declarations are in kdplatform.h.

As noted earlier, implementers are strongly encouraged to use the Khronos provided header files. Implementers, who are creating their own kd.h or need to modify kdplatform.h, are encouraged to code them such that they include as few as possible of the platform's include files, and to avoid declaring C and POSIX standard functions. This will ease the creation of portable OpenKODE applications, and help stop non-portable code being added accidentally.

Each OpenKODE extension is defined in its own header file. Khronos provided header files for each ratified extension are available in the Extension Headers subsection of the OpenKODE registry.

Package all these OpenKODE header files in the folder KD.

Package the OpenVG header files openvg.h and, when provided, vgu.h in the folder VG .

To find the include files, use appropriate compiler options in the makefiles for your sample programs; e.g. -I (gcc, linux) or /I (Visual C++).

Given the different IDEs & compilers people use, especially on Windows, it is not possible to recommend a system location to place these include files. Where obvious choices exist Khronos recommends implementers take advantage of them.

In particular, GNU/Linux implementations should follow the Filesystem Hierarchy Standard for location of headers and libraries.

OpenGL ES, EGL, OpenVG and OpenKODE entry points should be packaged in separate libraries.

However to provide backward compatibility for existing applications, two OpenGL ES 1.1 libraries should be provided: one with and one without the EGL entry points.

Note: There are extant implementations of the dual OpenGL ES libraries demonstrating this is possible on Symbian, GNU/Linux, Win32 and WinCE.

For OpenGL ES 2.x, only a library without EGL entry points is needed.

The extensions .lib & .dll are allowed to vary by platform. On GNU/Linux for example they should be .a and .so to match that platform's conventions.