Khronos API Implementers' Guidelines

Edited by

Mark Callow

HI Corporation

Copyright © 2007 The Khronos Group Inc.

This document is protected by copyright laws and contains material proprietary to the Khronos Group, Inc. It or any components may not be reproduced, republished, distributed, transmitted, displayed, broadcast or otherwise exploited in any manner without the express prior written permission of Khronos Group. The receipt or possession of this document does not convey any rights to reproduce, disclose, or distribute its contents, or to manufacture, use, or sell anything that it may describe, in whole or in part.

Khronos Group grants express permission to any current Promoter, Contributor or Adopter member of Khronos to copy and redistribute UNMODIFIED versions of this document in any fashion, provided that NO CHARGE is made for the document and the latest available update of the document is used whenever possible. Such distributed document may be re-formatted AS LONG AS the contents of the document are not changed in any way. The document may be incorporated into a product that is sold as long as such product includes significant independent work developed by the seller. A link to the current version of this document on the Khronos Group web-site should be included whenever possible with document distributions.

Khronos Group makes no, and expressly disclaims any, representations or warranties, express or implied, regarding this document, including, without limitation, any implied warranties of merchantability or fitness for a particular purpose or non-infringement of any intellectual property. Khronos Group makes no, and expressly disclaims any, warranties, express or implied, regarding the correctness, accuracy, completeness, timeliness, and reliability of the document. Under no circumstances will the Khronos Group, or any of its Promoters, Contributors or Members or their respective partners, officers, directors, employees, agents or representatives be liable for any damages, whether direct, indirect, special or consequential damages for lost revenues, lost profits, or otherwise, arising from or in connection with these materials.

Khronos™ is a trademark of The Khronos Group Inc. OpenGL® is a registered trademark, and OpenGL ES™is a trademark, of Silicon Graphics, Inc.

Revision History
Revision 0.9.02006-12-08 19:15:11 -0800msc
First docbook version
Revision 0.91.02006-12-12 17:26:03 -0800msc
Public review version: amended copyright notice; changed OpenKODE and GLES utility library names.

Abstract

Guidelines to be followed by implementers of Khronos Group APIs

Table of Contents

Introduction
General Guidelines
Vendor Controlled Platforms (e.g. BREW, SymbianOS)
Uncontrolled Platforms (e.g. GNU/Linux, Windows, Windows CE)
Acknowledgements
Glossary

List of Tables

1. Header File Names and Locations
2. Recommended Library Names

Introduction

This document provides guidelines for implementers of OpenGL ES, OpenVG and other API standards specified by the Khronos Group. The aim of these hints is to provide commonality between implementations to ease the logistical problems faced by developers using multiple different implementations of an API.

One of the primary goals is to allow an application binary to run on top of multiple different OpenGL ES / OpenVG / EGL implementations on the same platform.

Implementers are strongly urged to comply with these guidelines.

General Guidelines

Vendor Controlled Platforms (e.g. BREW, SymbianOS)

Implementers should follow the linkage specifications established by the platform vendor .

  • Use the header files, (e.g., for OpenGL ES, gl.h & egl.h) provided by the platform vendor.

  • Use the function names specified in those header files.

  • Implement all API entry points in the same way as in the vendor-provided ABI. That is, functions should be functions, in-line functions should be in-line functions and macros should be macros.

  • Use the platform specified library names.

Vendors of controlled platforms are strongly urged to follow the recommendations given below for Uncontrolled Platforms when adding a Khronos Group API to their platform.

Uncontrolled Platforms (e.g. GNU/Linux, Windows, Windows CE)

When providing implementations for platforms where the vendor does not provide standard linkage specifications, implementers are urged to follow the following recommendations.

Header Files

General

  • Use the Khronos provided header files (e.g., for OpenGL ES, gl.h & egl.h). If changes are unavoidable, consider contributing your changes back to Khronos by updating the standard header files in the Khronos Subversion tree.

  • If you make your own header files and the platform is Windows, make sure they 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 MFC have their own GetDC(void) methods.

EGL

  • Package the EGL header files egl.h and eglplatform.h in the folder EGL.

  • eglplatform.h contains platform dependent items and 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.

  • Include eglplatform.h in egl.h thus: #include <EGL/eglplatform.h> . Do not use #include <eglplatform.h> because app. makefiles will then need 2 different -I<path> options to find both include files.

  • Do not include gl.h in egl.h .

OpenGL ES 1.x

  • Package the OpenGL ES header files gl.h and glplatform.h in the folder GLES .

  • glplatform.h contains platform dependent items and may need to be modified by the implementer. Implementers are encouraged to provide their additions for newly supported platforms to the Khronos Group for inclusion in the Adopters' distribution.

  • 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.

OpenGL ES 2.x

  • The core header files for OpenGL ES 2.x are called gl2.h and gl2platform.h to keep them distinct from the GLES 1.x header files and enable application to use both versions.

  • The function declarations and constant definitions for OpenGL ES 2.x are divided into 2 header files: gl2.h declares and defines all the core functions and constants; gl2ext.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.

    Functions and constants for Implementer extensions should be declared and defined in an implementer's own header file using names and constant values obtained from the Khronos Group's Extension Registry.

  • Package all these header files in the folder GLES2.

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

OpenKODE

  • Package the OpenKODE header files kd.h and kdplatform.h in the folder KD.

  • Implementers are encouraged to code kd.h such that it includes 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.

OpenVG

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

Header File Summary

Table 1. Header File Names and Locations

API Location Header Files How to include Provider
EGL 1.x EGL egl.h #include <EGL/egl.h> Khronos
eglplatform.h [1] Included by egl.h Vendor or Implementer
OpenGL ES 1.x GLES gl.h #include <GLES/gl.h> Khronos
glplatform.h [2] Included by gl.h Vendor or Implementer
glu.h Reserved for future use
OpenGL ES 2.x GLES2 gl2.h #include <GLES2/gl2.h> Khronos
gl2platform.h Included by gl2.h Vendor or Implementer
gl2ext.h #include <GLES2/gl2ext.h> Khronos
glu2.h Reserved for future use
OpenKODE 1.x KD kd.h #include <KD/kd.h> Khronos
kdplatform.h Included by kd.h Vendor or Implementer
OpenVG 1.x VG openvg.h #include <VG/openvg.h> Khronos
vgu.h [3] #include <VG/vgu.h> Khronos

[1] Many early EGL implementations used egltypes.h instead of the now recommended eglplatform.h .

[2] glplatform.h does not exist in many early implementations of OpenGL ES 1.x. Platform dependent declarations were included directly in gl.h .

[3] Required, if the OpenVG utility library is provided.

Notes

  • 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.

Libraries

  • It is highly desirable to implement all API entry points as function calls. However in the OpenKODE core, macros or in-lines may be used instead of a function call provided the following rules are followed:

    • When calling a function, each argument must be evaluated exactly once (although the order of evaluation is undefined).

    • It must be possible to take the address of function.

  • Except in cases where macros are allowed, ensure the API function names exported by your lib & dll files match the function names specified by the Khronos standard for the API you are implementing.

Packaging

  • 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.

Naming

Khronos recommends the library names shown in the following table:

Table 2. Recommended Library Names

API/Entry Points Name
EGL libEGL.{lib,dll}
OpenGL ES 1.x with EGL (Common Profile) libGLES_CM.{lib,dll} [1] [2]
OpenGL ES 1.x with EGL (Lite Profile) libGLES_CL.{lib,dll} [1] [2]
OpenGL ES 1.x without EGL libGLESv1_C[LM].{lib,dll} [3]
OpenGL ES 2.x without EGL libGLESv2.{lib,dll}
  libGLUESv1.{lib,dll} [4]
  libGLUESv2.{lib,dll} [4]
OpenKODE libKD{lib,dll}
OpenVG libOpenVG{lib,dll}
OpenVG Utilities (when present) libOpenVGU.{lib,dll}

[1] These names are required for OpenGL ES 1.0 and the libraries must contain the EGL entry points as detailed in Chapter 8, Packaging, of the OpenGL ES 1.0 specification.

[2] These names are deprecated for OpenGL ES 1.1 and beyond and should only be used for a library that includes the EGL entry points in order to support legacy applications.

[3] The OpenGL ES 1.1 specification at revision 1.1.09 was updated to specify these alternate names for GLES libraries that do not contain the EGL entry points.

[4] These names are reserved for future use by the Khronos Group.

Notes

  • 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.

Acknowledgements

Thanks to all the members of the Khronos Group for their input and in particular to the following:

Petri Kero
Jon Leech
Robert Palmer
Jani Vaarala
Hans-Martin Will

Glossary

Application Binary Interface (ABI)

The low-level interface between a compiled application program and the operating system or its libraries.

Application Programming Interface (API)

The source-code level interface between an application program and the operating system or its libraries.

Implementer

A company or person who implements a Khronos API.

Microsoft Foundation Classes (MFC)

A set of C++ utility classes provided by Microsoft Corporation.

Platform Vendor (Vendor)

A company providing an operating system platform that includes an ABI specification for one or more Khronos APIs. E.g., Qualcomm (OpenGL ES on BREW) and Symbian (OpenGL ES on Symbian OS). A Vendor may also be an Implementer.