make/doc/jogl/spec-overview.html


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
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565

<!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 OpenGL(R) 3D graphics library profiles:
<ul>
    <li> Desktop OpenGL 1.0 - 3.0 </li>
    <li> Desktop OpenGL 3.x, with x >= 1, forward compatible, core profile - and compatibility profile </li>
    <li> Embedded OpenGL ES 1.x, with x >= 0 </li>
    <li> Embedded OpenGL ES 2.x, with x >= 0 </li>
</ul><br>
  See <a href="#GLAPIInclusionCriteria">Inclusion Criteria</a> explaining the OpenGL profile seperation.<br>
  See <a href="#GLRuntimeVersion">OpenGL Runtime Requirements</a>.<br>
  <p>
  A sample implementation is available as
  <a href="http://jogl.jogamp.org">JOGL, a JogAmp module</a>.</p>
 
  Other API bindings are available as JogAmp modules:
  <ul>
    <li>OpenCL(R) <a href="http://jocl.jogamp.org">as JOCL</a></li>
    <li>OpenAL(R) <a href="http://joal.jogamp.org">as JOAL</a></li>
  </ul>
   
<h3>Dependencies</h3>
  This binding has dependencies to the following:<br><br>
  <ul>
    <li> Either of the following Java implementations:<br/>
    <ul>
        <li> <a href="http://java.sun.com/j2se/1.5.0/docs/api/">Java SE 1.5 or later</a> </li>
        <li> A mobile JavaVM with language 1.5 support, ie:
            <ul>
                <li> <a href="http://developer.android.com/reference/packages.html">Dalvik API Level 7</a> </li>
                <li> <a href="http://jamvm.sourceforge.net/">JamVM</a> </li>
            </ul>
            with
            <ul>
                <li> <a href="http://java.sun.com/products/foundation/">Foundation Profile 1.1.2 (JSR 219)</a> </li>
                <li> <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/package-summary.html"> Java 1.4 <i>java.nio</i> implementation</a> </li>
            </ul></li>
    </ul></li>
    <li> {@linkplain javax.media.nativewindow NativeWindow Protocol} <br>
    <br>
    The <i>NativeWindow Protocol</i> is included in JogAmp's sample implementation </li>
  </ul>
  <br>

<h3>OpenGL Profile Model</h3>
  OpenGL today is not just a single set of functionality, it offers many profiles for different
  purposes, e.g. ES1 and ES2 for mobile, etc.<br>
  JOGL reflects these profiles <a href="http://jogamp.org/jogl/doc/bouml/html/">with an OO abstraction model</a>,
  specifying interfaces encapsulating common subsets.<br> 
   
<h3>Package Structure</h3>
  The packages defined by this specification include:<br>
   
<ul>
  <li>The <b>javax.media.opengl</b> package<br><br>
    This package contains all Java bindings for all OpenGL profiles.<br>
    See <a href="#GLAPIInclusionCriteria">Inclusion Criteria</a> explaining the OpenGL profile seperation.<br>
    See <a href="#GLRuntimeVersion">OpenGL Runtime Requirements</a>.<br>
    The main OpenGL profile interfaces are:<br><br>
    <ul> 
        <li> {@link javax.media.opengl.GL2 javax.media.opengl.GL2} interface<br>
        <br>
        This interface contains all core desktop OpenGL methods through
version 3.0, inclusive, as well as most of it's extensions defined at the
time of this specification.  OpenGL extensions whose functionality
was incorporated into core OpenGL until version 3.1, inclusive, are subsumed into the core namespace.<br> 
        Note: OpenGL 3.0 is the last completly subsumed version in the specification. 
        You need to use a {@link javax.media.opengl.GL3} OpenGL 3.1+ context to benefit
        from new functionality and versions.<br>
        Note: Intersecting OpenGL 3.1 subsumed extensions are subsumed in GL2 as well, to offer the best common GL2GL3 intersection.<br>
        See <a href="#GL2InclusionCriteria">GL2 Inclusion Criteria</a>.<br>
        See <a href="#GL2RuntimeVersion">GL2 Runtime Requirements</a>.<br>
        Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></li>

        <li> {@link javax.media.opengl.GL3 javax.media.opengl.GL3} interface<br>
        <br>
        This interface contains all core, forward compatible, OpenGL methods starting from 3.1,
inclusive, as well as most of it's extensions defined at the time of this specification. <br>
        Note: OpenGL 3.0 forward compatible, non deprecated functionality is included in the 
        3.1 specification, hence the {@link javax.media.opengl.GL2GL3} implemented interface.<br>
        Note: OpenGL 3.1 forward compatible no more includes fixed point functionality.<br>
        See <a href="#GL3InclusionCriteria">GL3 Inclusion Criteria</a>.<br>
        See <a href="#GL3RuntimeVersion">GL3 Runtime Requirements</a>.<br>
        Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></li>

        <li> {@link javax.media.opengl.GL3bc javax.media.opengl.GL3bc} interface<br>
        <br>
        This interface contains the OpenGL 3.x compatibility profile,<br>
        ie includes all methods as defined in {@link javax.media.opengl.GL2} and {@link javax.media.opengl.GL3}.<br>
        Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></li>

        <li> {@link javax.media.opengl.GLES1 javax.media.opengl.GLES1} interface<br>
        <br>
        This interface contains all core embedded OpenGL methods of ES 1.x, with x >= 0,
inclusive, as well as most of it's extensions defined at the
time of this specification. <br>
        Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></li>

        <li> {@link javax.media.opengl.GLES2 javax.media.opengl.GLES2} interface<br>
        <br>
        This interface contains all core embedded OpenGL methods of ES 2.x, with x >= 0,
inclusive, as well as most of it's extensions defined at the
time of this specification. <br>
        Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></li>
    </ul>
    Additionally the packages contains interfaces where the main profiles intersect each other.
    These interfaces purposes is to provide common subsets of profiles to be used
    on both, the desktop and the embedded device. These are:<br><br>
    <ul> 
        <li> {@link javax.media.opengl.GLBase javax.media.opengl.GLBase} interface<br>
        <br>
        Common interface containing the profile type identification and conversion methods.<br>
        Used to query which specialized profile class an instance of this object actually is and 
        offering a protocol to convert it to these types.</li>

        <li> {@link javax.media.opengl.GL javax.media.opengl.GL} interface<br>
        <br>
        Common interface containing the subset of all profiles, GL3bc, GL3, GL2, GLES1 and GLES2.<br>
        This interface reflects common data types, texture and framebuffer functionality.</li>

        <li> {@link javax.media.opengl.GL2ES1 javax.media.opengl.GL2ES1} interface<br>
        <br>
        Interface containing the common subset of GL2 and GLES1.<br>
        This interface reflects only the fixed functionality of OpenGL</li>

        <li> {@link javax.media.opengl.GL2ES2 javax.media.opengl.GL2ES2} interface<br>
        <br>
        Interface containing the common subset of GL3, GL2 and GLES2.<br>
        This interface reflects only the programmable shader functionality of desktop and embedded OpenGL</li>

        <li> {@link javax.media.opengl.GL2GL3 javax.media.opengl.GL2GL3} interface<br>
        <br>
        Interface containing the common subset of core GL3 (OpenGL 3.1+) and GL2 (OpenGL 3.0),
        also known as the OpenGL 3.0 forward compatible, non deprecated subset.<br>
        This interface reflects only the programmable shader functionality of desktop OpenGL</li>
    </ul>
  </li>

  <li>The <b>javax.media.opengl.glu</b> package<br>
    <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.</li>
</ul>
<br>
   
<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</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 &gt;= 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&lt;type&gt;.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>
   
<a name="GLAPIInclusionCriteria"/>
<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> <a name="GL3InclusionCriteria"/> {@link javax.media.opengl.GL3 javax.media.opengl.GL3} interface
   <ul>
       <li>All functions in core, forward compatible, OpenGL 3.1 - 3.2, inclusive, have been included,
           as described in the header files <code>GL3/gl3.h</code>.</li>
       <li>Reason for starting a new profile beginning with 3.1 are:
           <ul>
            <li> OpenGL 3.1 requires a new native context, incompatible with prior versions.</li>
            <li> OpenGL 3.1 forward compatible profile drops fixed functionality.</li>
           </ul></li>
       <li>Forward compatibility, aka core, ie a context without <code>GL_ARB_compatibility</code>, is chosen because:
           <ul>