diff options
| author | Sven Gothel <[email protected]> | 2009-08-02 06:40:46 -0700 |
|---|---|---|
| committer | Sven Gothel <[email protected]> | 2009-08-02 06:40:46 -0700 |
| commit | 19e49d093adf2c13587d5cc016438f9caed1576a (patch) | |
| tree | c124af06e2e29e7ea2ebade4a09840d2382970ad | |
| parent | 363fe8afc173ec9bf7fda4f863ddd14cd5ceabb5 (diff) | |
Fix Spec Documentation; GL version, inclusion criteria and requirements
| -rw-r--r-- | make/doc/jogl/spec-overview.html | 105 |
1 files changed, 74 insertions, 31 deletions
diff --git a/make/doc/jogl/spec-overview.html b/make/doc/jogl/spec-overview.html index 89b4ac7c8..37f0caa00 100644 --- a/make/doc/jogl/spec-overview.html +++ b/make/doc/jogl/spec-overview.html @@ -11,11 +11,14 @@ This specification, an optional set of packages, describes the Java(TM) bindings to the native OpenGL(R) 3D graphics library profiles: <ul> - <li> Desktop OpenGL 1.x, 2.y and 3.0, with x >= 3 and y >= 0 </li> + <li> Desktop OpenGL 1.0 - 3.0 </li> <li> Desktop OpenGL 3.x, with x >= 1 </li> <li> Embedded OpenGL ES 1.x, with x >= 0 </li> <li> Embedded OpenGL ES 2.x, with x >= 0 </li> </ul><br> + See <a href="#GLAPIInclusionCriteria">Inclusion Criteria</a> explaining the OpenGL profile seperation.<br> + See <a href="#GLRuntimeVersion">OpenGL Runtime Requirements</a>.<br> + <br> A binding to the native OpenCL(R) library is not yet specified, but intended to be included in a <a href="#maintenanceupdates">maintenance update</a>. <br> @@ -46,8 +49,22 @@ bindings to the native OpenGL(R) 3D graphics library profiles: <ul> <li>The <b>javax.media.opengl</b> package<br><br> This package contains all Java bindings for all OpenGL profiles.<br> + See <a href="#GLAPIInclusionCriteria">Inclusion Criteria</a> explaining the OpenGL profile seperation.<br> + See <a href="#GLRuntimeVersion">OpenGL Runtime Requirements</a>.<br> The main OpenGL profile interfaces are:<br><br> <ul> + <li> {@link javax.media.opengl.GL3 javax.media.opengl.GL3} interface<br> + <br> + This interface contains all core desktop OpenGL methods starting from 3.1, +inclusive - forward compatible only, as well as most of it's extensions defined at the +time of this specification. <br> + Note: OpenGL 3.0 forward compatible, non deprecated functionality is included in the + 3.1 specification, hence the {@link javax.media.opengl.GL2GL3} implemented interface.<br> + Note: OpenGL 3.1 forward compatible no more includes fixed point functionality.<br> + See <a href="#GL3InclusionCriteria">GL3 Inclusion Criteria</a>.<br> + See <a href="#GL3RuntimeVersion">GL3 Runtime Requirements</a>.<br> + Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></li><br> + <li> {@link javax.media.opengl.GL2 javax.media.opengl.GL2} interface<br> <br> This interface contains all core desktop OpenGL methods through @@ -58,16 +75,8 @@ excluded.<br> Note: OpenGL 3.0 is the last subsumed version in the specification. You need to use a {@link javax.media.opengl.GL3} OpenGL 3.1+ context to benefit from new functionality and versions.<br> - Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></li><br> - - <li> {@link javax.media.opengl.GL3 javax.media.opengl.GL3} interface<br> - <br> - This interface contains all core desktop OpenGL methods starting from 3.1, -inclusive - forward compatible only, as well as most of it's extensions defined at the -time of this specification. <br> - Note: OpenGL 3.0 forward compatible, non deprecated functionality is included in the - 3.1 specification, hence the {@link javax.media.opengl.GL2GL3} implemented interface.<br> - Note: OpenGL 3.1 forward compatible no more includes fixed point functionality.<br> + See <a href="#GL2InclusionCriteria">GL2 Inclusion Criteria</a>.<br> + See <a href="#GL2RuntimeVersion">GL2 Runtime Requirements</a>.<br> Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></li><br> <li> {@link javax.media.opengl.GLES1 javax.media.opengl.GLES1} interface<br> @@ -305,29 +314,55 @@ between two GLContexts associated with the same GLDrawable. <h3>Criteria Used for Inclusion of APIs into the Java Bindings</h3> +<a name="GLAPIInclusionCriteria"/> <h4>OpenGL API Inclusion Criteria</h4> OpenGL functions and OpenGL extensions have been included in the Java bindings according the following rules: <br> <ul> - <li> - <li>All functions in core OpenGL 3.0, inclusive, have been included.</li> - <li>If the functionality of the OpenGL extension was subsumed into core -OpenGL by version 3.0, then the extension was dropped from the Java bindings. - However, if the core function name is not available in the native OpenGL implementation, - the extension named equivalent is used instead, e.g. <i>GL_ARB_framebuffer_object</i>. - In general the native method name will be looked up as follows - <ul> - <li> Try the interface name</li> - <li> Try the extension name: ARB, EXT, ..</li> - </ul> </li> - <li>Functions that deal with explicit pointer values in such a way that + <a name="GL3InclusionCriteria"/> + <li> {@link javax.media.opengl.GL3 javax.media.opengl.GL3} interface + <ul> + <li>All functions in core OpenGL 3.1 - forward compatible, inclusive, have been included, + as described in the header files <code>GL3/gl3.h</code>.</li> + <li>Reason for starting a new profile beginning with 3.1 are: + <ul> + <li> OpenGL 3.1 requires a new native context, incompatible with prior versions.</li> + <li> OpenGL 3.1 forward compatible profile drops fixed functionality.</li> + </ul></li> + <li>Forward compatibility, dropping fixed functionality, is choosen because: + <ul> + <li> It shares a commont subset with ES2.x</li> + <li> It is not guaranteed to be provided by all vendors.</li> + <li> It is not guaranteed to be provided in future versions.</li> + </ul></li> + </ul></li> + <a name="GL2InclusionCriteria"/> + <li> {@link javax.media.opengl.GL2 javax.media.opengl.GL2} interface + <ul> + <li>All functions in core OpenGL 3.0, inclusive, have been included.</li> + <li>Reason for making the <em>cut</em> at OpenGL 3.0 are: + <ul> + <li>Availability of 3.0 with the same native context.</li> + <li>Availability of 3.0 via extensions.</li> + </ul></li> + <li>If the functionality of the OpenGL extension was subsumed into core + OpenGL by version 3.0, then the extension was dropped from the Java bindings. + However, if the core function name is not available in the native OpenGL implementation, + the extension named equivalent is used instead, e.g. <i>GL_ARB_framebuffer_object</i>.</li> + <li>In general the native method name will be looked up as follows + <ul> + <li> Try the interface name</li> + <li> Try the extension name: ARB, EXT, ..</li> + </ul></li> + </ul></li> + <li>Functions that deal with explicit pointer values in such a way that they cannot be properly implemented in Java have been excluded. This includes retrieval methods with a C void ** in the OpenGL signature like glGetBufferPointerv, glGetPointerv, glGetVertexAttribPointerv, as well as functions that require persistent pointer to pointer storage across function calls like vertex array lists.</li> - <li>If the extension is registered in the official OpenGL extension registry + <li>If the extension is registered in the official OpenGL extension registry but the specification was never completed or was discontinued (as indicated in the specification and/or lack of inclusion in SGI's official OpenGL header files), then the extension was not included. Using these criteria, ARB @@ -335,15 +370,14 @@ extensions through number 42 (GL_ARB_pixel_buffer_object), inclusive, and non-ARB extensions through number 311 (GL_REMEDY_string_marker), inclusive, have been included in the Java bindings according to the numbering scheme found in the official OpenGL extension registry.</li> - <li>Some bindings to several vendor-specific extensions have been included + <li>Some bindings to several vendor-specific extensions have been included that are not found in the OpenGL extension registry. These extensions were deemed popular enough and/or were specifically requested by users.</li> - <li>Platform-specific extensions, such as those that begin with WGL, GLX, + <li>Platform-specific extensions, such as those that begin with WGL, GLX, CGL, etc., have been excluded from the public API. See the section "Accessing platform-specific extensions" for more information about accessing these functions on certain implementations.<br> - </li> - + </li> </ul> <h4>OpenGL GLU API Inclusion Criteria</h4> @@ -380,7 +414,14 @@ implementation.<br> <br> Therefore, any usage of these APIs is both platform and implementation specific.<br> +<a name="GLRuntimeVersion"/> <h3>OpenGL Version on Runtime System</h3> +<a name="GL3RuntimeVersion"/> +<h4> {@link javax.media.opengl.GL3 GL3} Desktop Requirements</h4> +An OpenGL ≥ 3.1 version is required to instantiate a GL3 context. +<br> +<a name="GL2RuntimeVersion"/> +<h4> {@link javax.media.opengl.GL2 GL2} Desktop Requirements</h4> Even though OpenGL extensions whose functionality was included into core OpenGL by version 3.0, inclusive, are not included in the bindings, it should be noted that OpenGL version 3.0 is not an absolute requirement on the runtime @@ -388,13 +429,15 @@ system. This is because a user could query whether any particular function is available before calling certain core APIs that might not be present. Also, if the core function name is not available in the native OpenGL implementation, the extension named equivalent is used instead, e.g. <i>GL_ARB_framebuffer_object</i>. -However, in general, it is reasonable to expect at least OpenGL 2.0 to be +However, in general, it is reasonable to expect at least OpenGL 1.5 to be installed on the runtime system and an implementor of the API is free to require -the presence of at least OpenGL 2.0 on the target system.<br> +the presence of at least OpenGL 1.5 on the target system.<br> +<b>The JOGL reference implementation require at least OpenGL version 1.1</b>, +due to it's dynamical function binding starting with OpenGL 1.2. <br> In future revisions of the API, this minimum standard may be raised.<br> - + <h3>Runtime Version Information</h3> Any Java Bindings for OpenGL implementation should include version information in its jar manifest file. This information can then easily be accessed |