Featured games (81)
games approved by the League of Dukes
Games in Showcase (498)
Games in Android Showcase (117)
games submitted by our members
Games in WIP (563)
games currently in development
News: Read the Java Gaming Resources, or peek at the official Java tutorials
    Home     Help   Search   Login   Register   
Pages: [1] 2
  ignore  |  Print  
  JSR-231 1.0.0 released!  (Read 35306 times)
0 Members and 1 Guest are viewing this topic.
Offline Ken Russell

JGO Coder

Java games rock!

« Posted 2005-10-20 00:13:58 »

JSR-231 (Java Bindings for OpenGL) is finally in the Early Draft Review stage! This is the first official publicly visible draft of the forthcoming JSR-231 APIs. You can download the specification here:

The spec is basically the javadoc target of the JSR-231 branch of the JOGL workspace. The only packages covered by the spec are and The others are "utility" packages not guaranteed to be shipped by any particular implementor of the JSR-231 APIs.

The specification is fairly minimal, primarily covering the cross-platform exposure of the GLContext and GLDrawable abstractions. The current JOGL callback model, which is similar to GLUT's, is also supported through the GLAutoDrawable API. All of the concrete OpenGL widgets and drawables shipped with the JSR-231 implementation (GLCanvas, GLJPanel, and GLPbuffer) implement the GLAutoDrawable interface. If desired, end users can use the GLDrawable and GLContext APIs directly to either grab the underlying OpenGL context from one of the existing widgets, or can easily create their own OpenGL widgets supporting different, non-callback rendering models like game loops.

All of the APIs have been implemented and tested on all of JOGL's supported platforms. There are some known issues on certain kinds of machines like Mac PowerBook laptops, but by and large the new code base is more robust than the current JOGL 1.1.1 release. Exciting new functionality like the Java2D/JOGL bridge, previously mentioned on this forum, is built in to the new implementation. There are some new demos in the jogl-demos workspace which show off the new functionality and performance enhancements.

While most JOGL applications will require very few changes to work under the new APIs, some application changes will definitely be necessary, and there are many cosmetic and some semantic changes to the APIs. We will try to provide a definitive list of the differences between the current JOGL APIs and the new JSR-231 APIs soon. A few key points:
  • All non-core APIs like the Animator have been moved into the com.sun.opengl.utils package. We aim to populate this package with utilities like texture loaders, screen grabbers, etc. Help from the community would be greatly appreciated.
  • APIs which accept a void* argument on the C side now accept java.nio.Buffer on the Java side rather than overloadings for each primitive array type. Some APIs like glVertexPointer require that this Buffer be direct; others, like glTexImage2D, do not. If the buffer must be direct, this is specified in the API. JOGL applications which used to call these APIs by passing in primitive arrays can be converted to the new API by using <Type>Buffer.wrap(). This change was done to reduce the explosion of overloadings for various APIs.
  • APIs which accept a strongly-typed C primitive pointer argument like int* are expanded to two overloadings, one taking an IntBuffer and optionally one taking an int[]. If the API requires a persistent pointer, only the IntBuffer variant will be generated, and the passed buffer must be direct. If not, both overloadings will be generated, and the IntBuffer may be direct or not.
  • The positions of passed Buffers are now significant; the pointer passed down to C is the address of the current element in the Buffer rather than the beginning of the Buffer. This decision was informed by the LWJGL project so as to avoid needing to create slices of Buffers. Please provide feedback on this stylistic change.
  • Access to the GLU library has changed. Rather than being attached to the GLDrawable, a GLU object can now be instantiated at any point in the program, and the GL object does not need to be passed to all of the methods. The GLU routines which use OpenGL require only that an OpenGL context is current at the point where they are called. The GLUT library has been refactored similarly.
  • All of the OpenGL extensions which were folded into 1.1, 1.2, and 1.3 have been excluded during the glue code generation process. This eliminates some pretty useless extensions like glVertexPointerEXT and on the whole seems like the right thing to do. It does imply that these extensions will not be callable if the host's OpenGL implementation is not at least OpenGL 1.3 compliant; however, an OpenGL 1.3 implementation is not required in order to run applications using only OpenGL 1.1 or 1.2 APIs.
  • Vertex Buffer Object and Pixel Buffer Object support has been changed. APIs affected by these extensions now have two overloadings generated, one for use when the extension is enabled (accepting a Java long in place of a C pointer like void*) and one for when it is disabled (accepting a Buffer in place of a C pointer). Checks are performed at run-time to ensure that arbitrary pointers can not be constructed by end users and passed in to the OpenGL implementation.
Nightly builds and new Java Web Start binaries are coming on line and should be available within a day or two. We will post updates to this forum when they are available. The JSR-231 branch of the JOGL tree will also soon be merged on to the main trunk, at which point all JOGL development going forward will be on the new APIs.

The Early Draft Review period is scheduled to last for roughly a month, followed by the public review period. Compared to the length of time the JSR has been underway, we realize that this is a relatively short period of time in which changes to the specification can be made. Please provide your feedback on the new APIs and spread the word to others that the specification is in the review phase.

We are looking forward to a speedy review process and getting the final APIs in the hands of developers and end users. Thanks in advance for your help.
Offline rexguo

Junior Member

Real-Time Java

« Reply #1 - Posted 2005-10-20 05:59:37 »

This is really good news! I'm looking forward to testing
out the binaries on a branch of my app made specifically
for this.

.rex - Technologist + Designer
Offline Matzon

JGO Knight

Medals: 19
Projects: 1

I'm gonna wring your pants!

« Reply #2 - Posted 2005-10-20 06:22:44 »

Great, so basically to be conformant, one must "just" implement the*/glu.* packages?
Some comments this far:

* As this is an implementation that everybody can implement, references to JOGL should go
* The Threading class is a bit... awkward - and very much JOGL specific.
* The specs dont mention anything about threading behaviour
* The JSR doesn't solve the fullscreen issues
* No mentions of what must, should, may be implemented to be conformant
* Adding utility into com.sun seems like a bad way, since it's not guarenteed to exist. If there are some std utilities then it should be in*

I'll look into it more when I have some time

Games published by our own members! Check 'em out!
Legends of Yore - The Casual Retro Roguelike
Offline rexguo

Junior Member

Real-Time Java

« Reply #3 - Posted 2005-10-20 06:35:08 »

Hi Ken,

Below is my initial feedback from a quick look
at the API spec:

  Didn't specify behaviour if parameter is null, or
  can be null.

  Specification can easily be tightened to
  say that it will do nothing if called on
  a GLAutoDrawable, instead of undefined results.

  Must release() be called before destroy()?
  What happens if release() is called after destroy()?

  createExternalGLContext() is a little misleading:
  it seems to imply a new GLContext is being created.
  getExistingGLContext(), wrapExternalGLContext() or
  createGLContextFromExisting() sounds more intuitive.
  The fact that this function accesses an existing
  context should be reflected in the method name.

.rex - Technologist + Designer
Offline pepijnve

Junior Member

Java games rock!

« Reply #4 - Posted 2005-10-20 09:11:22 »

The jsr seems to be very much tied to the current reference implementation. As an example, the documentation for GLCanvas contains quite a few implementation details (addNotify, removeNotify, update, ...) which might only be relevant for the reference implementation. GLDrawable#setRealized seems to fall under this category too (haven't checked how this is used in practice yet).
IMO if the spec wants to mandate that there should be at least a heavyweight and a lightweight GLDrawable implementation, the javadoc should reflect only that. (i.e. abstract class GLCanvas extends Canvas implements GLDrawable). Or does this cause problems when actually using the api?
Also, is there a way for a non AWT binding (read lwjgl Smiley) to implement the jsr or does the jsr only cover AWT based bindings? The GLDrawableFactory seems to limit this.

Since BufferUtils won't be part of the spec, it might be useful to mention byte ordering in the javax part somewhere. It should say that this is either implementation dependent or that Buffers are assumed to have ByteOrder.nativeOrder() as order.
Offline Markus_Persson

JGO Wizard

Medals: 15
Projects: 19

Mojang Specifications

« Reply #5 - Posted 2005-10-20 12:39:43 »

This is kinda minor, but I noticed there's no public default GLCanvas constructor.
It would be really nice to have one as a convenience for small test apps.

public GLCanvas()
    this(new GLCapabilities(), new DefaultGLCapabilitesChooser(), null, GraphicsEnvironment.getDefaultScreenDevice());

Play Minecraft!
Offline zingbat

Senior Member

Java games rock!

« Reply #6 - Posted 2005-10-24 00:08:35 »

All non-core APIs like the Animator have been moved into the com.sun.opengl.utils package. We aim to populate this package with utilities like texture loaders, screen grabbers, etc. Help from the community would be greatly appreciated.

I may possibly try to contribute with a Blender importer/exporter for a simple ascii scene format similar to obj for models:

m triangle
v  1.0 0.0 0.0
v 0.0 1.0 0.0
v 0.0 0.0 0.0
vn 0.0 0.0 1.0
f  1/1 2/1 3/1

And something like this for scenes:

ob x
m triangle
p 0 0 0
r 0 0 0 0
s 1 1 1
prop type emitter
prop set torchfire

Don't even need to mess with something like antlr for this. A binary encoder can also be done.

Offline campbell

Junior Member

Java games rock!

« Reply #7 - Posted 2005-10-24 20:53:14 »

I have a couple nits that I've noticed in trying to port some code to use the new JSR-231 codebase:

- GLJPanel.paintComponent() should be protected, not public.

- Regarding GLJPanel.shouldPreserveColorBufferIfTranslucent()... Ideally GLJPanel would clear the color buffer conditionally for the user, but I guess that can't be done due to the whole GLEventListener architecture.  So my only remaining complaint is about the name.  As it's written now, it sounds like you're asking whether the GLJPanel should preserve the color buffer, but it's really the application's responsibility.  How about one of the following names instead:
    - GLJPanel.isColorBufferClearRequiredWhenNonOpaque()
    - GLJPanel.isColorBufferInitializedExternally()

I realize those names aren't great, but I'm having trouble coming up with something better.  There must be something better than the way the method name is currently worded though Smiley

- Also from the GLJPanel docs:
"This class can not be  instantiated directly; use GLDrawableFactory to construct  them."

Does this mean that one is not allowed to subclass a GLJPanel?  I've been working on creating a simplified version of GLJPanel (a subclass of GLJPanel) that makes it easier for Swing/Java2D developers to jump into the world of JOGL.  This line from the docs makes it sound like I'm doing something bad/unallowed.  If GLJPanel (and GLCanvas) cannot be instantiated directly, perhaps they should be marked final (although I'm not suggesting this should be the case)?

- From GLCanvas docs:
"Overridden from Canvas to prevent Java2D's clearing of the  canvas from interfering with the OpenGL rendering."

To clarify, it's not Java2D that is clearing the canvas; it's AWT that triggers this.  Also, there are a few other places (like in the GLJPanel docs) that mention Java2D.  This might be accurate for Swing/AWT components where Java2D is involved in the painting process, but what about a LWJGL or SWT implementation where that might not be the case?  I just want to make sure the JSR-231 spec is not being overly restrictive here (and that it is not mentioning implementation details in the spec).

8: Undefined index: online
File: /home/jgo/public_html/Themes/default/Display.template.php (main sub template - eval?)
Line: 151