JSR 231 Draft Public Review Specification

From 903f1fae57c30df5c1e07a1c51996042faa707fb Mon Sep 17 00:00:00 2001 From: gfxadmin Date: Fri, 11 Nov 2005 02:28:11 +0000 Subject: Submitted by: Travis Add first draft of Specification Overview section to the javadoc build on main javadoc Overview page. This will be evolving as we continue to make specification changes. Modified Files: make/build.xml Added Files: make/spec-overview.html git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/trunk@438 232f8b59-042b-4e1e-8c03-345bb8c30851 --- make/build.xml | 7 +- make/spec-overview.html | 229 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 235 insertions(+), 1 deletion(-) create mode 100644 make/spec-overview.html diff --git a/make/build.xml b/make/build.xml index 5a4fea720..9ffdba22e 100644 --- a/make/build.xml +++ b/make/build.xml @@ -236,7 +236,8 @@ - + + @@ -930,6 +931,7 @@ @@ -941,6 +943,7 @@ @@ -953,6 +956,7 @@ @@ -964,6 +968,7 @@ 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 @@ + + + + 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).
+
+

Package Structure

+The packages defined by this specification include:
+

+
The javax.media.opengl package
+
+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.
+
The javax.media.opengl.glu package

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

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

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

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

Mapping of Pointer Arguments

+OpenGL functions that take pointer arguments fall into several +categories:
+

Functions that take an untyped pointer argument for immediate use
Functions that take a typed pointer argument for immediate use
Functions that take an untyped pointer argument for deferred use
Functions that take a typed pointer argument for deferred use
+

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

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

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

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

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

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

+

Revision History
+

Early Draft Review, October/November 2005

Public Review, December/January 2005

+
+ + -- cgit v1.2.3