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
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<TITLE>Jogl - User's Guide</TITLE>
</HEAD>
<BODY>
<H1>Jogl - User's Guide</H1>
<P>
<UL>
<LI> Overview
<LI> Developing with JOGL
<UL>
<LI> Local installation for development
<LI> Java Web Start integration
<LI> Applet support
</UL>
<LI> Creating a GLDrawable
<LI> Writing a GLEventListener
<LI> Using the Composable Pipeline
<LI> Heavyweight and Lightweight Issues
<LI> Multithreading Issues
<LI> Pbuffers
<LI> GLU
<LI> More Resources
<LI> Platform notes
<UL>
<LI> All Platforms
<LI> Windows
<LI> Solaris, Linux (X11 platforms)
<LI> Macintosh OS X
</UL>
<LI> Version History
</UL>
<H2> Overview </H2>
<P>
Jogl is a Java programming language binding for the OpenGL 3D graphics
API. It supports integration with the Java platform's AWT and Swing
widget sets while providing a minimal and easy-to-use API that handles
many of the issues associated with building multithreaded OpenGL
applications. Jogl provides access to the latest OpenGL routines
(OpenGL 2.0 with vendor extensions) as well as platform-independent
access to hardware-accelerated offscreen rendering ("pbuffers"). Jogl
also provides some of the most popular features introduced by other
Java bindings for OpenGL like GL4Java, LWJGL and Magician, including a
composable pipeline model which can provide faster debugging for
Java-based OpenGL applications than the analogous C program.
</P>
<P>
Jogl was designed for the most recent version of the Java platform and
for this reason supports only J2SE 1.4 and later. It also only
supports truecolor (15 bits per pixel and higher) rendering; it does
not support color-indexed modes. Certain areas of the public APIs are
more restrictive than in other bindings; for example, the GLCanvas and
GLJPanel classes are final, unlike in GL4Java, and the GLContext class
is no longer exposed in the public API. These changes have been made
to keep the public API simple and because most of the programming
errors that have been seen with earlier Java/OpenGL interfaces, in
particular GL4Java, have been related to subclassing the OpenGL widget
classes and performing manual OpenGL context management. Several
complex and leading-edge OpenGL demonstrations have been successfully
ported from C/C++ to Jogl without needing direct access to any of
these APIs. However, all of these classes and concepts are accessible
at the Java programming language level in implementation packages, and
in fact the Jogl binding is itself written almost completely in the
Java programming language. There are roughly 150 lines of handwritten
C code in the entire Jogl source base (100 of which work around bugs
in older OpenGL drivers on Windows); the rest of the native code is
autogenerated during the build process by a new tool called GlueGen,
the source code of which is in the Jogl source tree. Documentation for
GlueGen is forthcoming.
</P>
<H2> Developing with JOGL </H2>
<H3> Local installation for development </H3>
<P>
The JOGL distribution for developers contains two parts: a
platform-independent JAR file containing the Java classes of the
library (jogl.jar) and a platform-dependent native library containing
the associated JNI code which calls OpenGL.
</P>
<P>
If you are developing a new application which uses JOGL, download both
jogl.jar and the appropriate native library jar file (for example,
jogl-natives-win32.jar). It is recommended to place both of these jar
files in the same directory. Modify your CLASSPATH environment
variable to include the full path to jogl.jar; for example,
".;C:\Some\Other\Package\foo.jar;C:\Users\myhome\jogl\jogl.jar". (If
you did not previously set the CLASSPATH environment variable, you may
want to make sure that ".", the current directory, is on your new
CLASSPATH.) Use the jar command which ships with the JDK to extract
the native library jar; e.g., "jar xvf jogl-natives-win32.jar". Modify
your PATH environment variable (Windows), LD_LIBRARY_PATH environment
variable (Solaris and Linux), or DYLD_LIBRARY_PATH environment
variable (Mac OS X) to contain the directory holding the new .dll, .so
or .jnilib files. At this point your Java installation should be able
to see the JOGL class files. Users of IDEs such as NetBeans and
Eclipse should consult the IDE's documentation to see how to add jar
files and native libraries to their current project.
</P>
<P>
Dropping the JOGL jar and native library into the extension directory
of the JRE is strongly discouraged. Doing so can cause conflicts with
third-party applications launched via Java Web Start, and causes
confusion later when upgrading the distribution.
</P>
<H3> Java Web Start integration </H3>
<P>
The recommended distribution vehicle for applications using JOGL is
Java Web Start. JOGL-based applications do not even need to be signed;
all that is necessary is to reference the JOGL extension JNLP file.
Because the JOGL jar files are signed, an unsigned application can
reference the signed JOGL library and continue to run inside the
sandbox.
</P>
<P>
To reference JOGL within your application's JNLP file, simply place
the following line in the <code><resources></code> section:
<PRE>
<extension name="jogl" href="http://download.java.net/media/jogl/builds/archive/jsr-231-webstart-current/jogl.jnlp" />
</PRE>
This JNLP file points to the current JSR-231 unofficial development
build; the JNLP file's location will change once the reference
implementation is complete. The APIs in this release differ
significantly from the 1.1.1 release of JOGL, which was the last
pre-JSR release of the JOGL project. It is strongly recommended that
applications transition to the new APIs, as the implementation is
generally more robust than the 1.1.1 release and provides new and
useful functionality. For reference, the stable JOGL 1.1.1 extension
JNLP file is
<PRE>
<extension name="jogl" href="https://jogl.dev.java.net/webstart/jogl-1-1.jnlp" />
</PRE>
</P>
<H3> Applet support </H3>
<P>
Lilian Chamontin, in conjunction with several other members of the
JOGL community, has contributed a JOGL applet installer. This
installer uses some clever tricks to allow deployment of unsigned
applets which use JOGL into existing web browsers and JREs as far back
as 1.4.2, which is the earliest version of Java supported by JOGL.
</P>
<P>
The JOGLAppletInstaller is distributed inside jogl.jar as a utility
class in com.sun.opengl.utils. It requires that the developer host a
local, signed copy of jogl.jar and all of the jogl-natives jars; the
certificates must be the same on all of these jars. Note that in the
release builds of JOGL all of these jars are signed by Sun
Microsystems, so the developer can deploy applets without needing any
certificates.
</P>
<P>
The JOGLAppletInstaller javadoc describes the basic steps for
deployment of an applet utilizing JOGL. Please refer to this
documentation for more information. A live example of deploying an
unsigned JOGL applet will be added to this documentation shortly once
the first signed build of the JOGLAppletInstaller has been shipped.
</P>
<H2> Creating a GLDrawable </H2>
<P>
Jogl provides two basic widgets into which OpenGL rendering can be
performed. The GLCanvas is a heavyweight AWT widget which supports
hardware acceleration and which is intended to be the primary widget
used by applications. The GLJPanel is a fully Swing-compatible
lightweight widget which supports hardware acceleration but which is
not as fast as the GLCanvas because it reads back the frame buffer in
order to draw it using Java2D. The GLJPanel is intended to provide
100% correct Swing integration in the circumstances where a GLCanvas
can not be used. See <a href =
"http://java.sun.com/products/jfc/tsc/articles/mixing/">this
article</a> on <a href = "http://java.sun.com/products/jfc/tsc/">The
Swing Connection</a> for more information about mixing lightweight and
heavyweight widgets. See also the section on "Heavyweight and
Lightweight Issues" below.
</P>
<P>
Both the GLCanvas and GLJPanel implement a common interface called
GLDrawable so applications can switch between them with minimal code
changes. The GLDrawable interface provides
<UL>
<LI> access to the GL and GLU objects for calling OpenGL routines
<LI> the mechanism for registering GLEventListeners for performing
OpenGL rendering
<LI> a <CODE>display()</CODE> method for forcing OpenGL rendering to
be performed
<LI> exclusion methods (<CODE>setRenderingThread()</CODE>,
<CODE>setNoAutoRedrawMode()</CODE>) for controlling the
multithreading behavior of the widget
<LI> AWT- and Swing-independent abstractions for getting and setting
the size of the widget and adding and removing event listeners
<LI> a platform-independent mechanism for creating
hardware-accelerated offscreen surfaces (pbuffers) for performing
advanced rendering techniques
</UL>
</P>
<P>
GLCanvas and GLJPanel instances are created using the factory methods
in GLDrawableFactory. These factory methods allow the user to request
a certain set of OpenGL parameters in the form of a GLCapabilities
object, to customize the format selection algorithm by specifying a
GLCapabilitiesChooser, to share textures and display lists with other
GLDrawables, and to specify the display device on which the GLDrawable
will be created.
</P>
<P>
A GLCapabilities object specifies the OpenGL parameters for a
newly-created widget, such as the color, alpha,, z-buffer and
accumulation buffer bit depths and whether the widget is
double-buffered. The default capabilities are loosely specified but
provide for truecolor RGB, a reasonably large depth buffer,
double-buffered, with no alpha, stencil, or accumulation buffers.
</P>
<P>
An application can override the default pixel format selection
algorithm by providing a GLCapabilitiesChooser to the
GLDrawableFactory. The chooseCapabilities method will be called with
all of the available pixel formats as an array of GLCapabilities
objects, as well as the index indicating the window system's
recommended choice; it should return an integer index into this
array. The DefaultGLCapabilitiesChooser uses the window system's
recommendation when it is available, and otherwise attempts to use a
platform-independent selection algorithm.
</P>
<P>
The GLJPanel can be made non-opaque according to Swing's rendering
model, so it can act as an overlay to other Swing or Java2D drawing.
In order to enable this, set up your GLCapabilities object with a
non-zero alpha depth (a common value is 8 bits) and call
setOpaque(false) on the GLJPanel once it has been created. Java2D
rendering underneath it will then show through areas where OpenGL has
produced an alpha value less than 1.0. See the JGears and JRefract
demos for examples of how to use this functionality.
</P>
<H2> Writing a GLEventListener </H2>
<P>
Applications implement the GLEventListener interface to perform OpenGL
drawing. When the methods of the GLEventListener are called, the
underlying OpenGL context associated with the drawable is already
current. The listener fetches the GL object out of the GLDrawable and
begins to perform rendering.
</P>
<P>
The <CODE>init()</CODE> method is called when a new OpenGL context is
created for the given GLDrawable. Any display lists or textures used
during the application's normal rendering loop can be safely
initialized in <CODE>init()</CODE>. It is important to note that
because the underlying AWT window may be destroyed and recreated while
using the same GLCanvas and GLEventListener, the GLEventListener's
<CODE>init()</CODE> method may be called more than once during the
lifetime of the application. The init() method should therefore be
kept as short as possible and only contain the OpenGL initialization
required for the <CODE>display()</CODE> method to run properly. It is
the responsibility of the application to keep track of how its various
OpenGL contexts share display lists, textures and other OpenGL objects
so they can be either be reinitialized or so that reinitialization can
be skipped when the <CODE>init()</CODE> callback is called.
</P>
<P>
The <CODE>display()</CODE> method is called to perform per-frame
rendering. The <CODE>reshape()</CODE> method is called when the
drawable has been resized; the default implementation automatically
resizes the OpenGL viewport so often it is not necessary to do any
work in this method. The <CODE>displayChanged()</CODE> method is
designed to allow applications to support on-the-fly screen mode
switching, but support for this is not yet implemented so the body of
this method should remain empty.
</P>
<P>
It is strongly recommended that applications always refetch the GL and
GLU objects out of the GLDrawable upon each call to the
<CODE>init()</CODE>, <CODE>display()</CODE> and <CODE>reshape()</CODE>
methods and pass the GL object down on the stack to any drawing
routines, as opposed to storing the GL in a field and referencing it
from there. The reason is that multithreading issues inherent to the
AWT toolkit make it difficult to reason about which threads certain
operations are occurring on, and if the GL object is stored in a field
it is unfortunately too easy to accidentally make OpenGL calls from a
thread that does not have a current context. This will usually cause
the application to crash. For more information please see the section
on multithreading.
</P>
<H2> Using the Composable Pipeline </H2>
<P>
Jogl supports the "composable pipeline" paradigm introduced by the
Magician Java binding for OpenGL. The DebugGL pipeline calls
<CODE>glGetError</CODE> after each OpenGL call, reporting any errors
found. It can greatly speed up development time because of its
fine-grained error checking as opposed to the manual error checking
usually required in OpenGL programs written in C. The TraceGL prints
logging information upon each OpenGL call and is helpful when an
application crash makes it difficult to see where the error occurred.
</P>
<P>
To use these pipelines, call <CODE>GLDrawable.setGL</CODE> at the
beginning of the <CODE>init</CODE> method in your GLEventListener. For
example,
<PRE>
class MyListener implements GLEventListener {
public void init(GLDrawable drawable) {
drawable.setGL(new DebugGL(drawable.getGL()));
// ...
}
// ...
}
</PRE>
</P>
<H2> Heavyweight and Lightweight Issues </H2>
<P>
As mentioned above, JOGL supplies both a heavyweight (GLCanvas) and a
lightweight (GLJPanel) widget to be able to provide the fastest
possible performance for applications which need it as well as 100%
correct Swing integration, again for applications which need it. The
GLCanvas provides much higher performance than the GLJPanel in nearly
all situations and can be used in almost every kind of application
except those using JInternalFrames. Please see the Swing Connection
article mentioned above for details on mixing heavyweight and
lightweight widgets. A couple of common pitfalls are described here.
</P>
<P>
When using JPopupMenus or Swing tool tips in conjunction with the
GLCanvas, it is necessary to disable the use of lightweight widgets
for the popups. See the methods
<CODE>ToolTipManager.setLightWeightPopupEnabled</CODE>,
<CODE>JPopupMenu.setLightWeightPopupEnabled</CODE>, and
<CODE>JPopupMenu.setDefaultLightWeightPopupEnabled</CODE>.
</P>
<P>
There are occasionally problems with certain LayoutManagers and
component configurations where if a GLCanvas is placed in the middle
of a set of lightweight widgets then it may only grow and never
shrink. These issues are documented somewhat in <a href =
"https://jogl.dev.java.net/issues/show_bug.cgi?id=135">JOGL Issue
135</a> and most recently in the thread <a
href="http://192.18.37.44/forums/index.php?topic=8699.0">"Resize
behaviour"</a> in the JOGL forum. The root cause is behavior of the
Canvas, and in particular its ComponentPeer. The implementation of
getPreferredSize() calls getMinimumSize() and getMinimumSize() turns
around and calls Component.getSize(). This effectively means that the
Canvas will report its preferred size as being as large as the
component has ever been. For some layout managers this doesn't seem to
matter, but for others like the BoxLayout it does. See the test case
attached to Issue 135 for an example. Replacing the GLCanvas with an
ordinary Canvas yields the same behavior.
</P>
<P>
One suggestion was to override getPreferredSize() so that if a
preferred size has not been set by the user, to default to (0,
0). This works fine for some test cases but breaks all of the other
JOGL demos because they use a different LayoutManager. There appear to
be a lot of interactions between heavyweight vs. lightweight widgets
and layout managers. One experiment which was done was to override
setSize() in GLCanvas to update the preferred size. This works down
to the size specified by the user; if the window is resized any
smeller the same problem appears. If reshape() (the base routine of
setSize(), setBounds(), etc.) is changed to do the same thing, the
demo breaks in the same way it originally did. Therefore this solution
is fragile because it isn't clear which of these methods are used
internally by the AWT and for what purposes.
</P>
<P>
There are two possible solutions, both application-specific. The best
and most portable appears to be to put the GLCanvas into a JPanel and
set the JPanel's preferred size to (0, 0). The JPanel will cause this
constraint to be enforced on its contained GLCanvas. The other
workaround is to call <CODE>setPreferredSize(new Dimension(0,
0))</CODE> on a newly-created GLCanvas; this method is new in 1.5.
</P>
<P>
Another issue that occasionally arises on Windows is flickering during
live resizing of a GLCanvas. This is caused by the AWT's repainting
the background of the Canvas and can not be overridden on a per-Canvas
basis, for example when subclassing Canvas into GLCanvas. The
repainting of the background of Canvases on Windows can be disabled by
specifying the system property
<CODE>-Dsun.awt.noerasebackground=true</CODE>. Whether to specify this
flag depends on the application and should not be done universally,
but instead on a case-by-case basis. Some more detail is in the thread
<a href="http://192.18.37.44/forums/index.php?topic=8770.0">"TIP: JOGL
+ Swing flicker"</a> in the JOGL forum.
</P>
<H2> Multithreading Issues </H2>
<P>
Jogl was designed to interoperate with the AWT, an inherently
multithreaded GUI toolkit. OpenGL, in contrast, was originally
designed in single-threaded C programming environments. For this
reason Jogl provides a framework in which it is possible to write
correct multithreaded OpenGL applications using the GLEventListener
paradigm.
</P>
<P>
If an application written using Jogl interacts in any way with the
mouse or keyboard, the AWT is processing these events and the
multithreaded aspects of the program must be considered.
</P>
<P>
OpenGL applications usually behave in one of two ways: either they
repaint only on demand, for example when mouse input comes in, or they
repaint continually, regardless of whether user input is coming in. In
the repaint-on-demand model, the application can merely call
<CODE>GLDrawable.display()</CODE> manually at the end of the mouse or
keyboard listener to cause repainting to be done. Alternatively if the
application knows the concrete type of the GLDrawable it can call
repaint() to have the painting scheduled for a later time.
</P>
<P>
In the continuous repaint model, the application typically has a main
loop which is calling <CODE>GLDrawable.display()</CODE> repeatedly, or
is using the Animator class, which does this internally. In both of
these cases the OpenGL rendering will be done on this thread rather
than the internal AWT event queue thread which dispatches mouse and
keyboard events.
</P>
<P>
Both of these models (repaint-on-demand and repaint continually) still
require the user to think about which thread keyboard and mouse events
are coming in on, and which thread is performing the OpenGL rendering.
OpenGL rendering <B>may not</B> occur directly inside the mouse or
keyboard handlers, because the OpenGL context for the drawable is not
current at this point (hence the warning about storing a GL object in
a field, where it can be fetched and accidentally used by another
thread). However, a mouse or keyboard listener may invoke
<CODE>GLDrawable.display()</CODE>.
</P>
<P>
It is generally recommended that applications perform as little work
as possible inside their mouse and keyboard handlers to keep the GUI
responsive. However, since OpenGL commands can not be run from
directly within the mouse or keyboard event listener, the best
practice is to store off state when the listener is entered and
retrieve this state during the next call to
<CODE>GLEventListener.display()</CODE>.
</P>
<P>
Furthermore, it is recommended that if there are long computational
sequences in the GLEventListener's <CODE>display</CODE> method which
reference variables which may be being simultaneously modified by the
AWT thread (mouse and keyboard listeners) that copies of these
variables be made upon entry to <CODE>display</CODE> and these copies
be referenced throughout display() and the methods it calls. This will
prevent the values from changing while the OpenGL rendering is being
performed. Errors of this kind show up in many ways, including certain
kinds of flickering of the rendered image as certain pieces of objects
are rendered in one place and other pieces are rendered elsewhere in
the scene. Restructuring the display() method as described has solved
all instances of this kind of error that have been seen with Jogl to
date.
</P>
<P>
Prior to Jogl 1.1 b10, the Jogl library attempted to give applications
strict control over which thread or threads performed OpenGL
rendering. The <CODE>setRenderingThread()</CODE>,
<CODE>setNoAutoRedrawMode()</CODE> and <CODE>display()</CODE> APIs
were originally designed to allow the application to create its own
animation thread and avoid OpenGL context switching on platforms that
supported it. Unfortunately, serious stability issues caused by
multithreading bugs in either vendors' OpenGL drivers or in the Java
platform implementation have arisen on three of Jogl's major supported
platforms: Windows, Linux and Mac OS X. In order to address these
bugs, the threading model in Jogl 1.1 b10 and later has changed.
</P>
<P>
All GLEventListener callbacks and other internal OpenGL context
management are now performed on one thread. (In the current
implementation, this thread is the AWT event queue thread, which is a
thread internal to the implementation of the AWT and which is always
present when the AWT is being used. Future versions of Jogl may change
the thread on which the OpenGL work is performed.) When the
<CODE>GLDrawable.display()</CODE> method is called from user code, it
now performs the work synchronously on the AWT event queue thread,
even if the calling thread is a different thread. The
<CODE>setRenderingThread()</CODE> optimization is now a no-op. The
<CODE>setNoAutoRedraw()</CODE> API still works as previously
advertised, though now that all work is done on the AWT event queue
thread it no longer needs to be used in most cases. (It was previously
useful for working around certain kinds of OpenGL driver bugs.)
</P>
<P>
Most applications will not see a change in behavior from this change
in the Jogl implementation. Applications which use thread-local
storage or complex multithreading and synchronization may see a change
in their control flow requiring code changes. While it is strongly
recommended to change such applications to work under the new
threading model, the old threading model can be used by specifying the
system property <CODE>-Djogl.1thread=auto</CODE> or
<CODE>-Djogl.1thread=false</CODE>. The "auto" setting is equivalent to
the behavior in 1.1 b09 and before, where on ATI cards the
single-threaded mode would be used. The "false' setting is equivalent
to disabling the single-threaded mode. "true" is now the default
setting.
</P>
<H2> Pbuffers </H2>
<P>
Jogl exposes hardware-accelerated offscreen rendering (pbuffers) with
a minimal and platform-agnostic API. Several recent demos have been
successfully ported from C/C++ to Java using Jogl's pbuffer APIs.
However, the pbuffer support in Jogl remains one of the more
experimental aspects of the package and the APIs may need to change in
the future.
</P>
<P>
To create a pbuffer, create a GLCanvas and (assuming it reports that
it can create an offscreen drawable) make a pbuffer using the
<CODE>createOffscreenDrawable</CODE> API. Because of the multithreaded
nature of the AWT, the pbuffer is actually created lazily. However,
even if multiple pbuffers are created, and the order in which they are
rendered is significant, handling the lazy instantiation can be
straightforward: the display(GLDrawable) method of one pbuffer's
GLEventListener can directly call another pbuffer's display() method.
See the source code for the Jogl demonstrations such as the
ProceduralTexturePhysics demo and the HDR demo for examples of this
usage.
</P>
<P>
Additionally, pbuffers are only created when the parent GLCanvas's
display(), init(), or reshape() methods are called; in other words, it
may be necessary to manually "prime" the GLCanvas by calling display()
on it until it creates all of its requested pbuffers. Again, please
see the demonstrations for concrete examples of this. We hope that it
may be possible to hide many of these details in the future.
</P>
<P>
A pbuffer is used by calling its display() method. Rendering, as
always, occurs while the pbuffer's OpenGL context is current. There
are render-to-texture options that can be specified in the
GLCapabilities for the pbuffer which can make it easier to operate
upon the resulting pixels. These APIs are however highly experimental
and not yet implemented on all platforms.
</P>
<H2> GLU </H2>
<P>
Jogl contains support for the GLU (OpenGL Utility Library) version
1.3. Jogl originally supported GLU by wrapping the C version of the
APIs, but over time, and thanks to the contributions of several
individuals, it now uses a pure-Java version of SGI's GLU library. The
pure Java port is enabled by default, and addresses stability issues
on certain Linux distributions as well as the lack of native GLU 1.3
support on the Windows platform. In case of problems with the Java
port, the C version of the GLU library may be used by specifying the
system property <CODE>-Djogl.glu.nojava</CODE> on the command
line. All of the same functionality is exposed with both the Java and
C versions of the GLU library; currently NURBS support is the only
missing feature on both sides. If you run into problems with the Java
port of the GLU library please file a bug using the Issue Tracker on
the Jogl home page.
</P>
<H2> More Resources </H2>
<P>
The <A HREF="http://192.18.37.44/forums/index.php?board=25.0">JOGL
forum</A> on <A HREF="http://javagaming.org/">javagaming.org</A> is
the best place to ask questions about the library. Many users, as well
as the Jogl developers, read this forum frequently, and the archived
threads contain a lot of useful information (which still needs to be
distilled into documentation).
</P>
<P>
The <A HREF="http://jogl-demos.dev.java.net/">JOGL demos</A> provide
several examples of usage of the library.
</P>
<P>
Pepijn Van Eeckhoudt has done <A
HREF="http://pepijn.fab4.be/nehe/">JOGL ports of many of the the NeHe
demos</A>. These are small examples of various pieces of OpenGL
functionality. See also the <A HREF="http://nehe.gamedev.net/">NeHe
web site</A>.
</P>
<P>
Pepijn also did a <A
HREF="http://www.glexcess.com/files/glexcess.jar">JOGL port</a> of
Paolo Martella's <A HREF="http://www.glexcess.com/">GLExcess</A>
demo. To see the news update about this port, go to the main GLExcess
site and scroll down.
</P>
<P>
Gregory Pierce's <A
HREF="http://192.18.37.44/forums/index.php?topic=1474.0">introduction
to JOGL</a> is a useful tutorial on starting to use the JOGL library.
</P>
<P>
For release information about the JOGL library, please see the <A
HREF="http://192.18.37.44/forums/index.php?topic=1596.0">JOGL Release
Information</A> thread on the JOGL forum on javagaming.org.
</P>
<P>
Please post on the JOGL forum if you have a resource you'd like to add
to this documentation.
</P>
<H2> Platform Notes </H2>
<H3> All Platforms </H3>
<P>
The following issues, among others, are outstanding on all platforms:
</P>
<UL>
<LI> A few remaining stability issues, mostly on older graphics cards.
</UL>
<H3> Windows </H3>
<P>
For correct operation, it is necessary to specify the system property
<CODE>-Dsun.java2d.noddraw=true</CODE> when running JOGL applications
on Windows; this system property disables the use of DirectDraw by
Java2D. There are driver-level incompatibilities between DirectDraw
and OpenGL which manifest themselves as application crashes, poor
performance, bad flickering, and other artifacts. This poor behavior
may exhibit itself when OpenGL and DirectDraw are simply used in the
same application, not even just in the same window, so disabling
Java2D's DirectDraw pipeline and forcing it to use its GDI pipeline is
the only way to work around these issues. Java Web Start applications
may set this system property by adding the following line to the
<CODE><resources></CODE> section of the JNLP file: <PRE>
<property name="sun.java2d.noddraw" value="true"/> </PRE>
</P>
<P>
JOGL currently does not interoperate well with the OpenGL pipeline for
Java2D available in JDK 5.0 and later. We will address this in a
future JOGL release and plan to have better interoperability by the
time JDK 6.0 is shipped.
</P>
<P>
There is a serious memory leak in ATI's OpenGL drivers which is
exhibited on Windows XP on Mobility Radeon 9700 hardware. It's
possible it will be present on other hardware as well though it was
not reproducible at the time of this writing on desktop Radeon
hardware or older ATI mobile chips. The bug is documented in <A
HREF="https://jogl.dev.java.net/issues/show_bug.cgi?id=166">JOGL Issue
166</A> and a bug has been filed with ATI. You can confirm the
presence of the bug either with the test case in that bug report or by
simply running the Gears demo; if the process size grows over time in
the Task Manager, the memory leak is present on your hardware. For the
time being, you can work around this memory leak by specifying the
system property <CODE>-Djogl.GLContext.nofree</CODE> on the command
line when launching your JOGL applications. There is no good
general-purpose workaround for this bug which behaves well on all
hardware.
</P>
<H3> Solaris, Linux (X11 platforms) </H3>
<P>
No outstanding issues at this time.
</P>
<H3> Mac OS X </H3>
<P>
There are some problems with visual artifacts and stability problems
with some of the Jogl demos on Mac OS X. It appears that at least some
of these problems are due to bugs in Apple's OpenGL support. Bugs have
been filed about these problems and it is hoped they will be addressed
in the near future.
</P>
<P>
The Mac OS X port of Jogl, in particular the GL interface and its
implementation, can be used either with the provided GLCanvas widget
or with the Cocoa NSOpenGLView. In order to use it with Cocoa the
following steps should be taken:
<UL>
<LI> Instantiate a
<CODE>net.java.games.jogl.impl.macosx.MacOSXDummyGLContext</CODE> using the
public constructor taking no arguments.
<LI> Upon the first render of your application, or whenever the
available OpenGL routines might have changed (because a window moved
from one screen to another) call the publicly-accessible method
<CODE>MacOSXDummyGLContext.resetGLFunctionAvailability()</CODE>.
<LI> Fetch the GL instance out of the context using getGL() as usual.
Only use the GL instance when the OpenGL context from the NSOpenGLView
is current.
</UL>
<B>NOTE:</B> the Cocoa interoperability has not yet been retested
since the GLCanvas was implemented. Please report any problems found
with using Jogl with an NSOpenGLView.
</P>
<P>
The following issues remain with the Mac OS X port:
<UL>
<LI> Due to the mechanism by which the Cocoa graphics system selects
OpenGL pixel formats, the GLCapabilitiesChooser mechanism can not be
implemented on Mac OS X as on other platforms. Currently the
underlying Cocoa pixel format selection is used on an
NSOpenGLPixelFormat derived from the settings in the GLCapabilities,
and the GLCapabilitiesChooser is ignored.
</UL>
</P>
<H2> Version History </H2>
<P>
JOGL's version history can be found online in the <a
href="http://192.18.37.44/forums/index.php?topic=1596.0">"JOGL Release
Information"</a> thread in the JOGL forum. Comments about the 1.1
release train are in the thread <a
href="http://192.18.37.44/forums/index.php?topic=4217.0">"JOGL 1.1
released"</a>.
</BODY>
</HTML>
|
