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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>JOGL Specification Overview</title>
</head>
<body>
<h2>JOGL 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> OpenGL [ 1.0 .. 4.5 ], compatibility- and core profiles</li>
<li> OpenGL ES [ 1.0 .. 3.1 ]</li>
<li> EGL [ 1.0 .. 1.5 ]</li>
</ul>
<p><a href="#GLAPIInclusionCriteria">Inclusion Criteria</a> explains the OpenGL profile separation.</p>
<p>See <a href="#GLRuntimeVersion">OpenGL Runtime Requirements</a>.</p>
<p>
An 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:
<ul>
<li> <a href="http://docs.oracle.com/javase/6/docs/api/">Java SE 1.6 or later</a> </li>
<li> A mobile JavaVM with language 1.6 support, ie:
<ul>
<li> <a href="http://developer.android.com/reference/packages.html">Android API Level 9 (Version 2.3)</a> </li>
<li> <a href="http://jamvm.sourceforge.net/">JamVM</a> </li>
</ul>
with
<ul>
<li> <a href="http://docs.oracle.com/javase/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 com.jogamp.nativewindow NativeWindow Protocol}
<p>The <i>NativeWindow Protocol</i> is included in JogAmp's implementation</p></li>
</ul>
<br>
<h3>OpenGL Profile Model</h3>
OpenGL today is not just a single set of functions, it offers many profiles for different
purposes, e.g. ES1, ES2 and ES3 for mobile, GL [ 3.1 .. 4.5 ] core for a programmable shader application, etc.
<p>JOGL reflects these profiles <a href="http://jogamp.org/jogl/doc/uml/html/">with an OO abstraction model</a>,
specifying interfaces encapsulating common subsets.</p>
<h3>Package Structure</h3>
The packages defined by this specification include:<br>
<ul>
<li>The <b>com.jogamp.opengl</b> package<br>
<p>This package contains all Java bindings for all OpenGL profiles.</p>
<p>See <a href="#GLAPIInclusionCriteria">Inclusion Criteria</a> explaining the OpenGL profile seperation.</p>
<p>See <a href="#GLRuntimeVersion">OpenGL Runtime Requirements</a>.</p>
<p>The main OpenGL profile interfaces are:</p>
<ul>
<li> {@link com.jogamp.opengl.GL2 com.jogamp.opengl.GL2} interface
<p>This interface contains all OpenGL [ 1.0 .. 3.0 ] methods,
as well as most of it's extensions defined at the time of this specification.</p>
<p>OpenGL extensions whose functionality was incorporated into core OpenGL ≤ 3.0,
are subsumed into the core namespace.</p>
<p>See <a href="#GL2InclusionCriteria">GL2 Inclusion Criteria</a>.</p>
<p>See <a href="#GL2RuntimeVersion">GL2 Runtime Requirements</a>.</p>
<p>Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></p>
</li>
<li> {@link com.jogamp.opengl.GL3 com.jogamp.opengl.GL3} interface
<p>This interface contains all OpenGL [ 3.1 .. 3.3 ] <i>core</i> methods,
as well as most of it's extensions defined at the time of this specification.</p>
<p>Note: OpenGL [ 3.1 .. 3.3 ] core profile does not includes fixed point functionality.</p>
<p>See <a href="#GL3InclusionCriteria">GL3 Inclusion Criteria</a>.</p>
<p>See <a href="#GL3RuntimeVersion">GL3 Runtime Requirements</a>.</p>
<p>Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></p>
</li>
<li> {@link com.jogamp.opengl.GL3bc com.jogamp.opengl.GL3bc} interface
<p>This interface contains all OpenGL [ 3.1 .. 3.3 ] <i>compatibility</i> methods,
as well as most of it's extensions defined at the time of this specification.</p>
<p>Note: OpenGL [ 3.1 .. 3.3 ] compatibility profile does includes fixed point functionality.</p>
<p>Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></p>
</li>
<li> {@link com.jogamp.opengl.GL4 com.jogamp.opengl.GL4} interface
<p>This interface contains all OpenGL [ 4.0 .. 4.5 ] <i>core</i> methods,
as well as most of it's extensions defined at the time of this specification.</p>
<p>Note: OpenGL [ 4.0 .. 4.5 ] core profile does not includes fixed point functionality.</p>
<p>Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></p>
</li>
<li> {@link com.jogamp.opengl.GL4bc com.jogamp.opengl.GL4bc} interface
<p>This interface contains all OpenGL [ 4.0 .. 4.5 ] <i>compatibility</i> profile,
as well as most of it's extensions defined at the time of this specification.</p>
<p>Note: OpenGL [ 4.0 .. 4.5 ] compatibility profile does includes fixed point functionality.</p>
<p>Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></p>
</li>
<li> {@link com.jogamp.opengl.GLES1 com.jogamp.opengl.GLES1} interface
<p>This interface contains all OpenGL ES [ 1.0 .. 1.1 ] methods,
as well as most of it's extensions defined at the time of this specification.</p>
<p>Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></p>
</li>
<li> {@link com.jogamp.opengl.GLES2 com.jogamp.opengl.GLES2} interface
<p>This interface contains all OpenGL ES 2.0 methods,
as well as most of it's extensions defined at the time of this specification.</p>
<p>Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></p>
</li>
<li> {@link com.jogamp.opengl.GLES3 com.jogamp.opengl.GLES3} interface
<p>This interface contains all OpenGL ES [ 3.0 .. 3.1 ] methods,
as well as most of it's extensions defined at the time of this specification.</p>
<p>Future extensions will be added with a <a href="#maintenanceupdates">maintenance update</a></p>
</li>
</ul>
<p>Additionally the packages contains interfaces resembling intersecting <i>common profiles</i>.
These <i>common profiles</i> may be utilize for cross profile code supposed to either run
on desktop and mobile devices, or across GL profiles themselves:</p>
<ul>
<li> {@link com.jogamp.opengl.GLBase com.jogamp.opengl.GLBase} interface
<p>Common interface containing the profile type identification and conversion methods.</p>
<p>Used to query which specialized profile class an instance of this object actually is and
offering a protocol to convert it to these types.</p></li>
<li> {@link com.jogamp.opengl.GL com.jogamp.opengl.GL} interface
<p>Common interface containing the subset of all profiles, GL4bc, GL4, GL3bc, GL3, GL2, GLES1, GLES2 and GLES3.</p>
<p>This interface reflects common data types, texture and framebuffer functionality.</p></li>
<li> {@link com.jogamp.opengl.GL2ES1 com.jogamp.opengl.GL2ES1} interface
<p>Interface containing the common subset of GL2 and GLES1.</p>
<p>This interface reflects the fixed functionality of OpenGL, without the immediate mode API.</p></li>
<li> {@link com.jogamp.opengl.GL2ES2 com.jogamp.opengl.GL2ES2} interface
<p>Interface containing the common subset of GL2 and GLES2. Interface is almost GLES2 complete.</p>
<p>This interface reflects the programmable shader functionality of desktop and embedded OpenGL up until GLES2.</p></li>
<li> {@link com.jogamp.opengl.GL3ES3 com.jogamp.opengl.GL3ES3} interface
<p>Interface containing the common subset of core GL3 and GLES3. Interface is almost GLES3 complete, lacking <code>GL_ARB_ES3_compatibility</code> extension.</p>
<p>This interface reflects the programmable shader functionality of desktop and embedded OpenGL up until GLES3.</p></li>
<li> {@link com.jogamp.opengl.GL4ES3 com.jogamp.opengl.GL4ES3} interface
<p>Interface containing the common subset of core GL4 and GLES3. Interface is GLES3 complete w/o vendor extensions.</p>
<p>This interface reflects the programmable shader functionality of desktop and embedded OpenGL up until GLES3.</p></li>
<li> {@link com.jogamp.opengl.GL2GL3 com.jogamp.opengl.GL2GL3} interface
<p>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.</p>
<p>This interface reflects only the programmable shader functionality of desktop OpenGL</p></li>
</ul>
</li>
<li>The <b>com.jogamp.opengl.glu</b> package
<p>
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.</p></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.
<p>
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 com.jogamp.opengl namespace.</p>
<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.
<p>
Extension suffixes, such as EXT, ARB, and vendor-specific suffixes, are
retained so as to match C conventions.</p>
<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.
<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.
<p>
Integer return values that can only be GL_TRUE or GL_FALSE are mapped to
boolean.</p>
<h4>Mapping of Pointer Arguments</h4>
<p>OpenGL functions that take pointer arguments fall into several categories:</p>
<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.
<p>
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.</p>
<p>
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.</p>
<p>
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.</p>
<p>
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.</p>
<p>
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.
</p>
<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.
<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.
<p>
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.</p>
<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.
<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.
<p>
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.</p>
<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.
<p>
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.</p>
<p>
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.</p>
<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.
<p>
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.</p>
<h3><a name="SHARING">Sharing of Server-Side OpenGL Objects between GLContexts</a></h3>
Sharing of server-side OpenGL objects such as buffer objects, e.g. VBOs,
and textures among OpenGL contexts is supported in this specification.
<p>
See {@link com.jogamp.opengl.GLSharedContextSetter GLSharedContextSetter} interface
for details.
</p>
<h3>Criteria Used for Inclusion of APIs into the Java Bindings</h3>
<h4><a name="GLAPIInclusionCriteria">OpenGL API Inclusion Criteria</a></h4>
<p>OpenGL functions and OpenGL extensions have been included in the Java bindings
according the following rules: </p>
<ul>
<li><a name="GL3InclusionCriteria">{@link com.jogamp.opengl.GL3 com.jogamp.opengl.GL3} interface</a>
<ul>
<li>All functions in core, forward compatible, OpenGL [ 3.1 - 3.3 ], inclusive, have been included,
as described in the header files <code>GL/glcorearb.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 core 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>
<li> It shares a common subset with ES2.x</li>
<li> It is not guaranteed to be provided by all vendors.</li>
<li> It is not guaranteed to be provided in future versions.</li>
<li> OpenGL 3.2 core profile is compatible with OpenGL 3.1 forward compatible spec.</li>
<li> OpenGL 3.2 Spec Appendix E.1: It is not possible to implement both core and compatibility profiles in a single GL context, ..</li>
</ul></li>
</ul></li>
<li><a name="GL2InclusionCriteria"> {@link com.jogamp.opengl.GL2 com.jogamp.opengl.GL2} interface</a>
<ul>
<li>All functions in core OpenGL 3.0, inclusive, have been included.</li>
<li>Reason for making the <em>cut</em> at OpenGL 3.0 are:
<ul>
<li>Availability of 3.0 with the same native context.</li>
<li>Availability of 3.0 via extensions.</li>
</ul></li>
<li>If the functionality of the OpenGL extension was subsumed into core
OpenGL by version 3.0, then the extension was dropped from the Java bindings.
However, if the core function name is not available in the native OpenGL implementation,
the extension named equivalent is used instead, e.g. <i>GL_ARB_framebuffer_object</i>.</li>
<li>In general the native method name will be looked up as follows
<ul>
<li> Try the interface name</li>
<li> Try the extension name: ARB, EXT, ..</li>
</ul></li>
</ul></li>
<li>Functions that deal with explicit pointer values in such a way that
they cannot be properly implemented in Java have been excluded. This
includes retrieval methods with a C void ** in the OpenGL signature like glGetBufferPointerv,
glGetPointerv, glGetVertexAttribPointerv, as well as functions that require
persistent pointer to pointer storage across function calls like vertex array
lists.</li>
<li>If the extension is registered in the official OpenGL extension registry
but the specification was never completed or was discontinued (as indicated
in the specification and/or lack of inclusion in SGI's official OpenGL header
files), then the extension was not included. Using these criteria, ARB
extensions through number 42 (GL_ARB_pixel_buffer_object), inclusive, and
non-ARB extensions through number 311 (GL_REMEDY_string_marker), inclusive,
have been included in the Java bindings according to the numbering scheme
found in the official OpenGL extension registry.</li>
<li>Some bindings to several vendor-specific extensions have been included
that are not found in the OpenGL extension registry. These extensions
were deemed popular enough and/or were specifically requested by users.</li>
<li>Platform-specific extensions, such as those that begin with WGL, GLX,
CGL, etc., have been excluded from the public API. See the section "Accessing
platform-specific extensions" for more information about accessing these
functions on certain implementations.
</li>
</ul>
<h4>OpenGL GLU API Inclusion Criteria</h4>
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.
<h3>OpenGL Extensions</h3>
<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.
<p>
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 this specification. 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.</p>
<p>
Names for added extension methods and extension-defined constants and Java
bindings for C parameters should follow the guidelines set forth in this specification.</p>
<h4>Accessing Platform-Specific Extensions</h4>
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.
<p>
Therefore, any usage of these APIs is both platform and implementation specific.</p>
<h3><a name="GLRuntimeVersion">OpenGL Version on Runtime System</a></h3>
<h4><a name="GL4RuntimeVersion">{@link com.jogamp.opengl.GL4 GL4} Desktop Requirements</a></h4>
An OpenGL ≥ 4.0 version is required to instantiate a GL4 context.
<h4><a name="GL3RuntimeVersion">{@link com.jogamp.opengl.GL3 GL3} Desktop Requirements</a></h4>
An OpenGL ≥ 3.1 version is required to instantiate a GL3 context.
<h4><a name="GL2RuntimeVersion">{@link com.jogamp.opengl.GL2 GL2} Desktop Requirements</a></h4>
Even though OpenGL extensions whose functionality was included into core
OpenGL by version 3.0, inclusive, are not included in the bindings, it should
be noted that OpenGL version 3.0 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.
Also, if the core function name is not available in the native OpenGL implementation,
the extension named equivalent is used instead, e.g. <i>GL_ARB_framebuffer_object</i>.
However, in general, it is reasonable to expect at least OpenGL 1.5 to be
installed on the runtime system and an implementor of the API is free to require
the presence of at least OpenGL 1.5 on the target system.
<p><b>The JOGL reference implementation require at least OpenGL version 1.1</b>,
due to it's dynamical function binding starting with OpenGL 1.2.</p>
<p>In future revisions of the API, this minimum standard may be raised.</p>
<h4><a name="GLES3RuntimeVersion">{@link com.jogamp.opengl.GLES3 GLES3} Requirements</a></h4>
An OpenGL ES ≥ 3.0 version is required to instantiate an ES3 context.
<h4><a name="GLES2RuntimeVersion">{@link com.jogamp.opengl.GLES2 GLES2} Requirements</a></h4>
An OpenGL ES ≥ 2.0 version is required to instantiate an ES2 context.
<h4><a name="GLES1RuntimeVersion">{@link com.jogamp.opengl.GLES1 GLES1} Requirements</a></h4>
An OpenGL ES [ 1.0 .. 1.1 ] version is required to instantiate an ES1 context.
<h3><a name="RuntimeVersionInformation">Runtime Version Information</a></h3>
Any Java Bindings for OpenGL implementation should include version information
in its jar manifest file. This information can then easily be accessed
at runtime via the java.lang.Package API. At least the following information
is included in the Reference Implementation jar file manifest: Specification
Title, Specification Vendor, Specification Version, Implementation Vendor,
and Implementation Version.
<p>
JOGL provides {@link com.jogamp.opengl.JoglVersion} implementing {@link com.jogamp.common.util.JogampVersion},
which provides users access to the specification and implementation version,
the build date and source code repository branch name and it's latest commit identifier.
</p>
<h3><a name="maintenanceupdates">Future Maintenance Updates</a></h3>
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
com.jogamp.opengl namespace via future maintenance updates to the API.
<h3>Related Links</h3>
<ul>
<li><a href="http://www.khronos.org/registry/"><b>Khronos Registry</b></a>
<ul>
<li><a href="http://www.khronos.org/opengles/sdk/docs/man31/">ES 3.1 Ref Pages</a></li>
<li><a href="http://www.khronos.org/registry/gles/specs/3.1/es_spec_3.1.withchanges.pdf">ES 3.1 Spec</a></li>
<li><a href="http://www.khronos.org/registry/gles/specs/3.1/GLSL_ES_Specification_3.10.withchanges.pdf">GLSL ES 3.10 Spec</a></li>
<li><a href="http://www.khronos.org/files/opengles3-quick-reference-card.pdf">ES 3.0 Ref Card</a></li>
</ul></li>
<li><a href="http://www.opengl.org/registry/"><b>OpenGL Registry</b></a>
<ul>
<li><a href="http://www.opengl.org/sdk/docs/man4/">GL 4 Ref Pages </a></li>
<li><a href="http://www.opengl.org/sdk/docs/manglsl/">GLSL Ref Pages </a></li>
<li><a href="http://www.opengl.org/registry/doc/glspec45.core.withchanges.pdf">GL 4.5 Core Spec</a></li>
<li><a href="http://www.opengl.org/registry/doc/glspec45.compatibility.withchanges.pdf">GL 4.5 Compat. Spec</a></li>
<li><a href="http://www.opengl.org/registry/doc/GLSLangSpec.4.50.diff.pdf">GLSL 4.50 spec</a></li>
<li><a href="http://www.opengl.org/sdk/docs/reference_card/opengl45-reference-card.pdf">GL 4.5 Ref Card</a></li>
</ul></li>
</ul>
<h3>Revision History</h3>
<ul>
<li> Early Draft Review, October/November 2005</li>
<li> Public Review, December/January 2005</li>
<li> Proposed Final Draft Review, February/March 2006</li>
<li> 1.0.0 Final Release, September 2006</li>
<li> 1.1.0 Maintenance Release, April 2007</li>
<li> 2.0.0 Maintenance Release, July 2009</li>
<li> 2.0.1 Java Dependency Update to 1.5, February 2011</li>
<li> 2.0.2 Major Release, July 18th 2013</li>
<li> 2.3.0 Major Release, March 11th 2015</li>
</ul>
</body>
</html>
|
