diff -r 000000000000 -r 5d03bc08d59c opengles/openglesinterface/documentation/implementers_guide.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/opengles/openglesinterface/documentation/implementers_guide.html Tue Feb 02 01:47:50 2010 +0200 @@ -0,0 +1,403 @@ +Khronos API Implementers' Guidelines

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