From 63bcc3767fecf6ce5471c86e89233a08f80ecb04 Mon Sep 17 00:00:00 2001 From: gfxadmin Date: Fri, 18 Nov 2005 20:59:10 +0000 Subject: Issue number: Obtained from: Submitted by: Travis Reviewed by: Modified Files: spec-overview.html I added several more sections to the Specification overview document including: * Criteria Used for Inclusion of APIs into the Java Bindings * OpenGL Extensions * OpenGL Version on Runtime System * Future Maintenance Updates git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@454 232f8b59-042b-4e1e-8c03-345bb8c30851 --- make/spec-overview.html | 455 ++++++++++++++++++++++++++++-------------------- 1 file changed, 271 insertions(+), 184 deletions(-) (limited to 'make') diff --git a/make/spec-overview.html b/make/spec-overview.html index ec295b1d6..e8e631f6a 100644 --- a/make/spec-overview.html +++ b/make/spec-overview.html @@ -3,227 +3,314 @@ JSR 231 Draft Public Review Specification - + +

JSR 231 Specification Overview

+

Preface

-This specification, an optional set of packages, describes the Java(TM) -bindings to the native 3D graphics library, OpenGL(R).
-
+ This specification, an optional set of packages, describes the Java(TM) bindings +to the native 3D graphics library, OpenGL(R).
+
+

Package Structure

-The packages defined by this specification include:
+ The packages defined by this specification include:
+ +

API Binding Conventions

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

Function Naming

-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.
-
-Extension suffixes, such as EXT, ARB, and vendor-specific suffixes, are -retained so as to match C conventions.
+ 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.
+
+ Extension suffixes, such as EXT, ARB, and vendor-specific suffixes, are retained +so as to match C conventions.
+

Mapping of Constants

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

Mapping of Primitive Types

-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.
-
-Integer return values that can only be GL_TRUE or GL_FALSE are mapped -to boolean.
+ 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.
+
+ Integer return values that can only be GL_TRUE or GL_FALSE are mapped to +boolean.
+

Mapping of Pointer Arguments

-OpenGL functions that take pointer arguments fall into several -categories:
+ OpenGL functions that take pointer arguments fall into several categories:
+ -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.
-
-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.
-
-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.
-
-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.
-
-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.
+ 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.
+
+ 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.
+
+ 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.
+
+ 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.
+
+ 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.
+

Index Parameter for Arrays

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

Reduction of Method Explosions

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

Auto-slicing of Buffers

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

Errors and Exceptions

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

Security

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

Criteria Used for Inclusion of APIs into the Java Bindings

+ +

OpenGL API Inclusion Criteria

+ OpenGL functions and OpenGL extensions have been included in the Java bindings +according the following rules:
+ + +

OpenGL GLU API Inclusion Criteria

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

OpenGL Extensions

+

Creating New Extensions

-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.
+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.
+
+ 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.
+
+ Names for added extension methods and extension-defined constants and Java +bindings for C parameters should follow the guidelines set forth in this +specfication.
+

Accessing Platform-Specific Extensions

+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.
+                                                                                                                                  
-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.
-
-Names for added extension methods and extension-defined constants and -Java bindings for C parameters should follow the guidelines set forth -in this specfication.
+Therefore, any usage of these APIs is both platform and implementation specific.
+

OpenGL Version on Runtime System

+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.
+                                                                                                                                  
+In future revisions of the API, this minimum standard may be raised.
+

Future Maintenance Updates

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

Related Links

+ +
http://www.jcp.org/en/jsr/detail?id=231
+ - -
http://www.opengl.org/documentation/specs/version2.0/glspec20.pdf
- + +
+http://www.opengl.org/documentation/specs/version2.0/glspec20.pdf
+ -
http://oss.sgi.com/projects/ogl-sample/registry/index.html
- + +
http://oss.sgi.com/projects/ogl-sample/registry/index.html
+ 

+ 
 
-
 http://www.opengl.org/documentation/specs/glu/glu1_3.pdf

+ 
+
 http://www.opengl.org/documentation/specs/glu/glu1_3.pdf

+ 
 
+ 
 
 http://www.opengl.org/about/arb/index.html

+ 
 


-

+ 
+ 
 
Revision History

-

+ 
+ 
 
Early Draft Review, October/November 2005

Public Review, December/January 2005 

-

+ 

+ 

 
 
-- 
cgit v1.2.3