1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
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>
|
