diff options
Diffstat (limited to 'make/spec-overview.html')
| -rw-r--r-- | make/spec-overview.html | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/make/spec-overview.html b/make/spec-overview.html new file mode 100644 index 000000000..ec295b1d6 --- /dev/null +++ b/make/spec-overview.html @@ -0,0 +1,229 @@ +<!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 OpenGL GLU 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> +<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>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> +<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> +<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> +</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> +</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> +<pre>Early Draft Review, October/November 2005<br><br>Public Review, December/January 2005 <br></pre> +<br> +</body> +</html> |