OpenGL_API_Divergence.md

# JOGL and OpenGL Divergence

## Overview

As described in mapping of OpenGL profiles to interfaces, JOGL is mostly API compatible with the OpenGL API while packaging functionality in OpenGL profiles.

However, there are certain aspects where JOGL diverges due to managed code aspects and the Java™ language.

### OpenGL Debugging

In 2009-2012 the Debug Output extensions AMD_debug_output and ARB_debug_output were created, subsumed to the core via KHR_debug.

They allow applications to enable and control low-level debugging using the OpenGL implementation.

These extensions have been subsumed in OpenGL 4.3 and in OpenGL ES 3.2.

In JOGL a user may attached a GLDebugListener to the GLContext via addGLDebugListener(..). The GLDebugListener receives the native GLDebugMessage if debugging is enabled.

To enable debugging, the GLContext must be created having CTX_OPTION_DEBUG set via `setContextCreationFlags(int)` on the GLContext or GLAutoDrawable. Alternatively, GLContext.enableGLDebugMessage(boolean may be used.

Test cases

- TestGLDebug00NEWT
- TestGLDebug01NEWT

### Retrieve Mapped Buffer’s Data

Since OpenGL 1.5, a mapped buffer object’s data can be retrieved via glGetBufferPointerv(..), i.e. the client’s memory pointer.

In JOGL, buffers are tracked via GLBufferStorage, covering the storage size, NIO client memory reference if mapped and usage flags. This ensures lifecycle alignment of the native NIO Java client memory with OpenGL buffer semantics.

To retrieve the bound buffer you may use getBoundBuffer(..) and getBufferStorage(..).

Tracker Implementation

- GLBufferObjectTracker
- GLBufferStateTracker

Test Cases

- TestMapBufferRead01NEWT
- TestMapBufferRead02NEWT

## References

- JogAmp Home
- JOGL Git Repo
- JOGL Home
- OpenGL Evolution & JOGL
- Mapping of OpenGL Profiles to Interfaces
  - OpenGL API Inclusion Criteria
  - UML Diagram
- How To Build