Why does JOGL use Instances of GLContext / GL* instead of exposing a Static API?

"Why does JOGL use Instances of GLContext and GL*
instead of Static and Stateless Access?"

I have received this question over and over again,
hence I thought it might be a good thing to
elaborate here.

The usual questionnaire goes:
[1] Isn't static invocation faster?
[2] Isn't it more like OpenGL to have it static?
[3] It's quite a burden to pass the GL object, isn't it?

Well, the overall answer is simply: IT IS JUST PLAIN WRONG!
- ..  to have a static implementation, read bottom remark!
- Hint OpenGL's implementation is not static.

(This will end in the Wiki .. after a while,
hopefully reflecting discussions here.)

+++

We are all about exposing a correct API,
reflecting the real implementation model / design.

[A.1] OpenGL is a state machine.
OpenGL associates locks and memory references
and those OpenGL rendering states.

In JOGL, we do track certain states,
required for a functional binding.

- GLBufferStorage and its private tracker is used
  to manage memory mapped and use-create storage.
  <http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLBufferStorage.html>

- Seamless FBO handling requires us to track
  currently used FBO buffer, see:
  <http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLBase.html#getDefaultDrawFramebuffer%28%29>

  This allows us to pipe even onscreen rendering
  using FBO as required for certain machines (OSX/CALayer w/ AWT).
  However, this can be utilized by user applications,
  since tracking of the FBO is for free.

- Sharing GLContext
  <http://jogamp.org/deployment/jogamp-next/javadoc/jogl/javadoc/com/jogamp/opengl/GLSharedContextSetter.html>
  To allow seamless and stable context sharing,
  we are required to track its actual state
  to know when we are able to create the shared 'slave' context.

- Last but not least, GLContext performs proper locking.
  User can query states and try locking,
  as well as associate data to TLS.

[A.2] OpenGL has many variations, read: Profiles
You can have different OpenGL context,
e.g. GL 3.3, GL 4.5, ES 3.1 .. and so on.
See <http://jogamp.org/jogl/doc/Overview-OpenGL-Evolution-And-JOGL.html>

In JOGL you can actually use desktop GL [1.x - 4.5]
besides GL-ES [1.0 - 3.1] in the same application!

[A.3] OpenGL may expose different function tables
OpenGL may even expose different
function pointer, using different function tables
depending on the OpenGL profile and what-not.

OpenGL may be implemented by different native
libraries (libGL, libGLES, ..).

Here it is required to bind the exposed
OpenGL functions _dynamically_ to their respective
function table used in JOGL.
JOGL caches there function tables
using certain compatibility criterias, e.g.
  - Display connection (X11 networking)!
  - OpenGL profile

See [A.2] as well.

+++

Bottom Remark: But but but ...

A static API can accommodate the above
by using thread-local-storage (TLS).

However, this would require to map all the static
API entries to proper state-full objects.
  - OpenGL actually maps static -> TLS objects

  - JOGL however, exposes the plain state-full API.
    <http://jogamp.org/jogl/doc/uml/html/>
   
  - Know that TLS access is not as fast
    as passing an object!
    (Even though TLS is not slow at all)    

Since we like to expose and map reality,
the JOGL API is as is!

+++

Cheers, Sven

This: "In JOGL, we do track certain states" is enough motivation to do it the JOGL-way. Even if OpenGL was stateless (which it isn't) JOGL can still be stateful and should use the Java/OO-way of keeping state, i.e. instance a class.
Using TLS to simulate OO in an OO-language is just silly

jmaasing wrote

This: "In JOGL, we do track certain states" is enough motivation to do it the JOGL-way.

I also forgot to mention, that tracking these states allows us not to query the
native OpenGL context via glGet*. The latter most certainly cause a pipeline flush/sync
and slow down rendering, see Bug 1066 <https://jogamp.org/bugzilla/show_bug.cgi?id=1066>.

Tracking itself is cheap, occurring on the Java side simply setting a variable
or using O(1) maps for more advanced stuff (memory objects).