diff options
Diffstat (limited to 'make/spec-overview.html')
| -rw-r--r-- | make/spec-overview.html | 370 |
1 files changed, 0 insertions, 370 deletions
diff --git a/make/spec-overview.html b/make/spec-overview.html deleted file mode 100644 index 1e52669ed..000000000 --- a/make/spec-overview.html +++ /dev/null @@ -1,370 +0,0 @@ -<!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 3D graphics library, OpenGL(R).<br> - <br> - -<h3>Package Structure</h3> - The packages defined by this specification include:<br> - -<ul> - <li> - <p>The javax.media.opengl package<br> - <br> - This package contains Java bindings for all core OpenGL methods through -version 2.0, inclusive, as well as most OpenGL extensions defined at the -time of this specification. Early OpenGL extensions whose functionality -was incorporated into core OpenGL by version 1.3, inclusive, are specifically -excluded.</p> - </li> - <li>The javax.media.opengl.glu package</li> - <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.<br> - <br> - -</ul> - -<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<br> - </li> - -</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>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 1.3, then the extension was dropped from the Java bindings.</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 1.3, inclusive, are not included in the bindings, it should -be noted that OpenGL version 1.3 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. -However, in general, it is reasonable to expect at least OpenGL 1.3 to be -installed on the runtime system and an implementor of the API is free to require -the presence of at least OpenGL 1.3 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> -<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>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://oss.sgi.com/projects/ogl-sample/registry/index.html"> http://oss.sgi.com/projects/ogl-sample/registry/index.html</a></blockquote> - -<pre></pre> - -<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 -</ul> - <br> - <br> - <br> -</body> -</html> |