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.0 | 2006-12-08 19:15:11 -0800 | msc |
| First docbook version | ||
| Revision 0.91.0 | 2006-12-12 17:26:03 -0800 | msc |
| 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
List of Tables
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. -
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. -
When providing implementations for platforms where the vendor - does not provide standard linkage specifications, implementers - are urged to follow the following recommendations.
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.
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
- .
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.
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.
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.
-
Package the OpenVG header files
- openvg.h
- and, when provided,
- vgu.h
- in the folder
- VG
- .
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. -
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. -
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. -
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.
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.
-
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 - |
- The low-level interface between a compiled application program and the - operating system or its libraries. -
- The source-code level interface between an application program - and the operating system or its libraries. -
- A company or person who implements a Khronos API. -
- A set of C++ utility classes provided by Microsoft Corporation. -
- 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. -