diff options
Diffstat (limited to 'make/doc')
| -rw-r--r-- | make/doc/jogl/spec-overview.html | 509 |
1 files changed, 509 insertions, 0 deletions
diff --git a/make/doc/jogl/spec-overview.html b/make/doc/jogl/spec-overview.html new file mode 100644 index 000000000..11074e601 --- /dev/null +++ b/make/doc/jogl/spec-overview.html @@ -0,0 +1,509 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + <title>JSR 231 Draft Public Review Specification</title> +</head> + <body> + +<h2>JSR 231 Specification Overview</h2> + +<h3>Preface</h3> + 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 >= 5 and y >= 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> + 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> + +<h3>Dependencies</h3> + This binding has dependencies to the following:<br><br> + <ul> + <li> Either of the following Java implementations:<br> + <ul> + <li> <a href="http://java.sun.com/j2se/1.4.2/docs/api/">Java SE 1.4 or later</a> </li><br> + <li> <a href="http://java.sun.com/javame/technology/cdc/">Java ME CDC 1.1.2 (JSR 218)</a> and + <a href="http://java.sun.com/products/foundation/">Foundation Profile 1.1.2 (JSR 219)</a><br> + and either of the following <i>java.nio</i> implementations:<br> + <ul> + <li> <a href="http://java.sun.com/javame/reference/apis/jsr239/java/nio/package-summary.html"> JSR239 <i>java.nio</i> subset</a> </li> + <li> <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/package-summary.html"> Java 1.4 <i>java.nio</i> implementation</a> </li> + </ul><br> + </ul> + <li> {@linkplain javax.media.nativewindow NativeWindow Protocol} <br> + <br> + The <i>NativeWindow Protocol</i> is included in Sun's sample implementation </li><br> + </ul> + <br> + +<h3>Package Structure</h3> + The packages defined by this specification include:<br> + +<ul> + <li>The <b>javax.media.opengl</b> package<br><br> + This package contains all Java bindings for all OpenGL profiles.<br> + The main OpenGL profile interfaces are:<br><br> + <ul> + <li> {@link javax.media.opengl.GL2 javax.media.opengl.GL2} interface<br> + <br> + This interface contains all core desktop OpenGL methods through +version 3.0, inclusive, as well as most of it's extensions defined at the +time of this specification. Early OpenGL extensions whose functionality +was incorporated into core OpenGL by version 2.0, inclusive, are specifically +excluded.<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, as well as most of it's extensions defined at the +time of this specification. <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> + <br> + This interface contains all core embedded OpenGL methods of ES 1.x, with x >= 0, +inclusive, as well as most of it's extensions defined at the +time of this specification. <br> + Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></li><br> + + <li> {@link javax.media.opengl.GLES2 javax.media.opengl.GLES2} interface<br> + <br> + This interface contains all core embedded OpenGL methods of ES 2.x, with x >= 0, +inclusive, as well as most of it's extensions defined at the +time of this specification. <br> + Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></li><br> + </ul> + Additionally the packages contains interfaces where the main profiles intersect each other. + These interfaces purposes is to provide common subsets of profiles to be used + on both, the desktop and the embedded device. These are:<br><br> + <ul> + <li> {@link javax.media.opengl.GLBase javax.media.opengl.GLBase} interface<br> + <br> + Common interface containing the profile type identification and conversion methods.<br> + Used to query which specialized profile class an instance of this object actually is and + offering a protocol to convert it to these types.</li><br> + + <li> {@link javax.media.opengl.GL javax.media.opengl.GL} interface<br> + <br> + Common interface containing the subset of all profiles, GL3, GL2, GLES1 and GLES2.<br> + This interface reflects common data types, texture and framebuffer functionality.</li><br> + + <li> {@link javax.media.opengl.GL2ES1 javax.media.opengl.GL2ES1} interface<br> + <br> + Interface containing the common subset of GL2 and GLES1.<br> + This interface reflects only the fixed functionality of OpenGL</li><br> + + <li> {@link javax.media.opengl.GL2ES2 javax.media.opengl.GL2ES2} interface<br> + <br> + Interface containing the common subset of GL3, GL2 and GLES2.<br> + This interface reflects only the programmable shader functionality of OpenGL</li><br> + </ul> + </li><br> + + <li>The <b>javax.media.opengl.glu</b> package<br> + <br> + This package contains bindings for the OpenGL Graphics System Utility (GLU) +Library version 1.3, inclusive, with the exception of the GLU NURBS routines +which are not exposed.</li><br> +</ul> +<br> + +<h3>API Binding Conventions</h3> + The Java language bindings to the pre-existing C APIs in these packages +have been created using a consistent set of rules. Vendor-defined extensions +should make use of the same rules in order to provide a consistent developer +experience.<br> + <br> + The rules for creating the Java language binding are described in the following +sections. These rules should be followed as closely as possible for all future +APIs that share the javax.media.opengl namespace.<br> + +<h4>Function Naming</h4> + Functions are named in the same way as in the C binding. That is, an OpenGL +API function glClear is bound to Java method GL.glClear. Although it would +be possible to drop the gl prefix (since it is redundant with the interface +name GL), the resulting code was deemed to look too foreign to experienced +OpenGL developers. For the same reason, we have also carried over all type +suffixes like 3f and 3fv from methods such as glColor3f and glColor3fv, respectively.<br> + <br> + Extension suffixes, such as EXT, ARB, and vendor-specific suffixes, are +retained so as to match C conventions.<br> + +<h4>Mapping of Constants</h4> + Constants are named in the same way as in the C binding. For instance, +the OpenGL constant GL_RGB is bound to Java constant GL.GL_RGB.<br> + +<h4>Mapping of Primitive Types</h4> + All 8-bit integral types become byte, all 16-bit integral types become +short, and all 32-bit integral types become int. All 32-bit floating-point +types become float and all 64-bit floating-point types become double.<br> + <br> + Integer return values that can only be GL_TRUE or GL_FALSE are mapped to +boolean.<br> + +<h4>Mapping of Pointer Arguments</h4> + OpenGL functions that take pointer arguments fall into several categories:<br> + +<ul> + <li>Functions that take an untyped pointer argument for immediate use</li> + <li>Functions that take a typed pointer argument for immediate use</li> + <li>Functions that take an untyped pointer argument for deferred use</li> + <li>Functions that take a typed pointer argument for deferred use</li> + <br> +</ul> + Functions that take an untyped (void*) pointer argument for immediate use +are given a single binding that takes a New I/O (NIO) Buffer object. The Buffer +may be of any type allowable by the function (and compatible with the other +arguments to the function) and may be direct or indirect. An example of +an OpenGL API in this category is glTexImage2D.<br> + <br> + Functions that take a typed pointer (e.g., GLfloat *) argument for immediate +use are given two bindings. The first takes a Java primitive array with a +type that matches the C pointer type (i.e., GLfloat* maps to float[]). The +second takes a typed Buffer object (i.e., GLfloat* maps to FloatBuffer). +An example of an OpenGL API in this category is glColor3fv.<br> + <br> + Functions that take an untyped (void*) pointer argument for deferred use +are given a single binding that takes a Buffer object. The Buffer may be of +any type allowable by the function (and compatible with the other arguments +to the function), but must be direct. That is, it may not have been created +from a Java primitive array using the wrap method. The functions that fall +into this category generally have names ending with the suffix "pointer." +An example of an OpenGL API in this category is glVertexPointer. Because these +functions do not consume the data located at the given pointer immediately, +but only at some unspecified later time, it is not possible to use a Java +primitive array whose memory location may change.<br> + <br> + Functions that take a typed (e.g., GLfloat*) pointer argument for deferred +use are given a single binding that takes a typed Buffer object (i.e., GLfloat* +maps to FloatBuffer). The Buffer must be direct. That is, it may not have +been created from a Java primitive array using the wrap method. An example +of an OpenGL API in this category is glFeedbackBuffer.<br> + <br> + Methods that read or write a specific number of values from an array or +Buffer argument do not read or write any subsequent elements of the array +or Buffer.<br> + <br> + An outgoing C char* pointer, if representing a null-terminated, read-only +C string, maps to a Java String. An outgoing C char** pointer, if similarly +representing an array of read-only C strings, maps to a Java String[] (array +of String objects). All other char* pointers, including those representing +mutable C strings as used in some Get methods, are mapped to byte[] and ByteBuffer. + <br> + +<h4>Index Parameter for Arrays</h4> + Each C method argument that is mapped to a primitive array in Java is actually +mapped to two separate parameters: the appropriate primitive array type in +Java and an integer offset parameter. The value of the integer offset is +the index which the method will start reading from within the array. Earlier +indices will be ignored. This mapping provides more congruity with existing +Java APIs and allows reuse of a single array across multiple Java method calls +by changing the index in much the same way that C pointers permit for C arrays.<br> + +<h4>Reduction of Method Explosions</h4> + Since there are two ways to expand a given C method pointer parameter, +it would be possible for C methods with multiple pointer arguments to expand +to many Java methods if one was to consider every possible combination of +mappings (the C method would expand to the number of pointer parameters to +the power of 2). In order to avoid an API explosion, we restrict a given +Java method to like kind mappings only. In other words, a given C method +with N typed pointer parameters for immediate use, where N >= 1, will map +to exactly two Java methods: One with all primitive arrays and one with all +Buffer types.<br> + <br> + Also, methods that accept multiple Buffer arguments require all direct +or all non-direct Buffers. Direct and non-direct buffers should never be +mixed within an API call by an application.<br> + +<h4>Byte ordering of Buffers</h4> + When allocating a New I/O Buffer (in particular, a direct ByteBuffer) to +be passed to the APIs in these packages, it is essential to set the <em>byte +ordering</em> of the newly-allocated ByteBuffer to the <em>native</em> byte +ordering of the platform: e.g. <code>ByteBuffer.allocateDirect(...).order(ByteOrder.nativeOrder());</code>. +The byte order of the ByteBuffer indicates how multi-byte values such as +int and float are stored in the Buffer either using methods like putInt and +putFloat or views such as IntBuffer or FloatBuffer. The Java bindings perform +no conversion or byte swapping on the outgoing data to OpenGL, and the native +OpenGL implementation expects data in the host CPU's byte order, so it is +essential to always match the byte order of the underlying platform when +filling Buffers with data. <br> + +<h4>Auto-slicing of Buffers</h4> + When a Buffer object is passed to an OpenGL function binding, the actual +pointer argument that is passed down to the OpenGL C implementation is equal +to the starting pointer of the Buffer data, plus an offset given by the Buffer.position() +function, multiplied by the data type size in bytes (1 for a ByteBuffer, 2 +for a ShortBuffer, 4 for a IntBuffer or FloatBuffer, and 8 for DoubleBuffer). + The array offset given by Buffer<type>.arrayOffset() is also added +in the offset for wrapped arrays.<br> + <br> + This feature is known as "auto-slicing," as it mimics the effect of calling +slice() on the Buffer object without the overhead of explicit object creation.<br> + +<h4>Errors and Exceptions</h4> + For performance reasons, OpenGL functions do not return error values directly. +Instead, applications must query for errors using functions such as glGetError. +This behavior is largely preserved in the Java language bindings, as described +below.<br> + <br> + In the interest of efficiency, the Java API does not generally throw exceptions. + However, running an application with the DebugGL composable pipeline, which +is part of the API, will force an exception to be thrown at the point of failure.<br> + <br> + Many errors are defined by OpenGL merely to set the error code, rather +than throwing an exception. For example, passing a bad enumerated parameter +value may result in the error flag being set to GL.GL_INVALID_VALUE. Attempting +to check for such errors in the binding layer would require either replicating +the error-checking logic of the underlying engine, or querying the error state +after every function. This would greatly impact performance by inhibiting +the ability of the hardware to pipeline work.<br> + +<h4>Security</h4> + Exception behavior is defined in cases that could otherwise lead to illegal +memory accesses in the underlying OpenGL engine. Implementations should take +necessary steps to prevent the GL from accessing or overwriting memory except +for properly allocated Buffers and array method arguments.<br> + <br> + An implementation should take care to validate arguments correctly before +invoking native methods that could potentially access memory illegally. In +particular, methods that validate the contents of an array (such as a list +of GL attributes) or a Buffer should take precautions against exploits in +which a separate thread attempts to alter the contents of the argument during +the time interval following validation but preceding passage of the argument +to the underlying native engine.<br> + +<h3><a name="SHARING">Sharing of Server-Side OpenGL Objects between GLContexts</a></h3> + +Sharing of server-side OpenGL objects such as textures and display +lists among OpenGL contexts is supported in this specification. +However, the specification does not guarantee that a request to share +objects between two contexts will succeed. Certain OpenGL +implementations restrict sharing in certain ways. Applications should +assume that sharing is a request more than an assertion. +Implementations of this specification should, but are not required to, +provide timely notification of a failure of a request to share objects +between two GLContexts, perhaps in the form of a GLException. The +situation in which sharing is most likely to work on all platforms is +between two GLContexts associated with the same GLDrawable. + +<h3>Criteria Used for Inclusion of APIs into the Java Bindings</h3> + +<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 2.0, inclusive, have been included.</li> + <li>If the functionality of the OpenGL extension was subsumed into core +OpenGL by version 2.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>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 +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 +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 +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, +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> + +</ul> + +<h4>OpenGL GLU API Inclusion Criteria</h4> + Bindings for all core GLU APIs have been included with the exception of +the GLU NURBS APIs. These APIs may be included in a future maintenance +release of the Java bindings.<br> + +<h3>OpenGL Extensions</h3> + +<h4>Creating New Extensions</h4> + While the Java APIs for OpenGL extensions are unconditionally exposed, the +underlying functions may not be present. A program can query whether a potentially +unavailable function is actually available at runtime by using the method +GL.isFunctionAvailable.<br> + <br> + Bindings for OpenGL extensions not covered in this specification may be +supplied by individual vendors or groups. Such bindings may be considered +for inclusion in a future version of the JSR. In order to avoid fragmentation, +vendors creating extension bindings should expose new extensions using the +method GL.getExtension. This method is intended to provide a mechanism for +vendors who wish to provide access to new OpenGL extensions without changing +the public API of the core package. <br> + <br> + Names for added extension methods and extension-defined constants and Java +bindings for C parameters should follow the guidelines set forth in this specfication.<br> + +<h4>Accessing Platform-Specific Extensions</h4> + Platform-specific extensions such as those that begin with WGL, GLX, CGL, +etc. are not included in the API. Each implementation can choose to +export all, some, or none of these APIs via the GL.getPlatformGLExtensions +API which returns an Object whose underlying data type is specific to a given +implementation.<br> + +<br> + Therefore, any usage of these APIs is both platform and implementation specific.<br> + +<h3>OpenGL Version on Runtime System</h3> + Even though OpenGL extensions whose functionality was included into core +OpenGL by version 2.0, inclusive, are not included in the bindings, it should +be noted that OpenGL version 2.0 is not an absolute requirement on the runtime +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 +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> + +<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 +at runtime via the java.lang.Package API. At least the following information +is included in the Reference Implementation jar file manifest: Specification +Title, Specification Vendor, Specification Version, Implementation Vendor, +and Implementation Version.<br> +<a name="maintenanceupdates"/> +<h3>Future Maintenance Updates</h3> + New core APIs found in future versions of OpenGL, as well as new OpenGL +extensions, are expected to be added to the bindings and included into the +javax.media.opengl namespace via future maintenance updates to the API.<br> + +<h3>Related Links</h3> + +<ul> + <li> JSR 231 JCP Web Page</li> + +</ul> + +<blockquote><a href="http://www.jcp.org/en/jsr/detail?id=231"> http://www.jcp.org/en/jsr/detail?id=231</a></blockquote> + +<ul> + <li>OpenCL Specification</li> + +</ul> + +<blockquote><a + href="http://www.khronos.org/registry/cl/"> +http://www.khronos.org/registry/cl/</a></blockquote> + +<ul> + <li>OpenGL 3.1 Specification</li> + +</ul> + +<blockquote><a + href="http://www.opengl.org/registry/doc/glspec31.20090324.pdf"> +http://www.opengl.org/registry/doc/glspec31.20090324.pdf</a></blockquote> + +<ul> + <li>OpenGL 2.1 Specification</li> + +</ul> + +<blockquote><a + href="http://www.opengl.org/registry/doc/glspec21.20061201.pdf"> +http://www.opengl.org/registry/doc/glspec21.20061201.pdf</a></blockquote> + +<ul> + <li>OpenGL 2.0 Specification</li> + +</ul> + +<blockquote><a + href="http://www.opengl.org/documentation/specs/version2.0/glspec20.pdf"> +http://www.opengl.org/documentation/specs/version2.0/glspec20.pdf</a></blockquote> + +<ul> + <li> OpenGL Extension Registry</li> + +</ul> + +<blockquote><a + href="http://www.opengl.org/registry/"> http://www.opengl.org/registry/</a></blockquote> + +<pre></pre> + +<ul> + <li>OpenGL ES 2.x Specification </li> + +</ul> + +<blockquote><a + href="http://www.khronos.org/registry/gles/specs/2.0/es_full_spec_2.0.24.pdf"> +http://www.khronos.org/registry/gles/specs/2.0/es_full_spec_2.0.24.pdf</a></blockquote> + +<ul> + <li>OpenGL ES 1.x Specification </li> + +</ul> + +<blockquote><a + href="http://www.khronos.org/registry/gles/specs/1.1/es_full_spec_1.1.12.pdf"> +http://www.khronos.org/registry/gles/specs/1.1/es_full_spec_1.1.12.pdf</a></blockquote> + +<ul> + <li>OpenGL ES Registry</li> + +</ul> + +<blockquote><a + href="http://www.khronos.org/registry/gles/"> +http://www.khronos.org/registry/gles/</a></blockquote> + +<ul> + <li>OpenGL Utility Library: GLU 1.3 Specificiation</li> + +</ul> + +<blockquote><a + href="http://www.opengl.org/documentation/specs/glu/glu1_3.pdf"> http://www.opengl.org/documentation/specs/glu/glu1_3.pdf</a></blockquote> + +<ul> + <li>OpenGL ARB Web site</li> + +</ul> + +<blockquote><a href="http://www.opengl.org/about/arb/index.html"> http://www.opengl.org/about/arb/index.html</a></blockquote> + +<h3><br> + </h3> + +<h3>Revision History<br> + </h3> + +<ul> +<li> Early Draft Review, October/November 2005 +<li> Public Review, December/January 2005 +<li> Proposed Final Draft Review, February/March 2006 +<li> 1.0.0 Final Release, September 2006 +<li> 1.1.0 Maintenance Release, April 2007 +<li> 1.2.0 Maintenance Release, June 2009 +</ul> + <br> + <br> + <br> +</body> +</html> |