JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
com.jogamp.opengl.GLAutoDrawableDelegate Class Reference

Fully functional GLAutoDrawable implementation utilizing already created GLDrawable and GLContext instances. More...

Inheritance diagram for com.jogamp.opengl.GLAutoDrawableDelegate:
Collaboration diagram for com.jogamp.opengl.GLAutoDrawableDelegate:

Public Member Functions

 GLAutoDrawableDelegate (final GLDrawable drawable, final GLContext context, final Object upstreamWidget, final boolean ownDevice, final RecursiveLock lock)
 
final void windowRepaintOp ()
 Default implementation to handle repaint events from the windowing system. More...
 
final void windowResizedOp (final int newWidth, final int newHeight)
 Handling resize events from the windowing system. More...
 
final void windowDestroyNotifyOp ()
 Implementation to handle destroy notifications from the windowing system. More...
 
final RecursiveLock getUpstreamLock ()
 Returns the recursive lock object of the upstream widget to synchronize multithreaded access on top of NativeSurface#lockSurface(). More...
 
final Object getUpstreamWidget ()
 Method may return the upstream UI toolkit object holding this GLAutoDrawable instance, if exist. More...
 
final void setUpstreamWidget (final Object newUpstreamWidget)
 Set the upstream UI toolkit object. More...
 
final void destroy ()
 Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext.If a window is attached to it's implementation, it shall be closed. Causes disposing of all OpenGL resources by calling dispose(..) for all registered GLEventListeners. Called automatically by the window system toolkit upon receiving a destroy notification. This routine may be called manually. More...
 
void display ()
 
final GLDrawableFactory getFactory ()
 Return the GLDrawableFactory being used to create this instance. More...
 
final void swapBuffers () throws GLException
 Swaps the front and back buffers of this drawable. More...
 
String toString ()
 
- Public Member Functions inherited from com.jogamp.opengl.GLAutoDrawable
GLDrawable getDelegatedDrawable ()
 If the implementation uses delegation, return the delegated GLDrawable instance, otherwise return this instance. More...
 
GLContext getContext ()
 Returns the context associated with this drawable. More...
 
GLContext setContext (GLContext newCtx, boolean destroyPrevCtx)
 Associate the new context, newtCtx, to this auto-drawable. More...
 
void addGLEventListener (GLEventListener listener)
 Adds the given listener to the end of this drawable queue. More...
 
void addGLEventListener (int index, GLEventListener listener) throws IndexOutOfBoundsException
 Adds the given listener at the given index of this drawable queue. More...
 
int getGLEventListenerCount ()
 Returns the number of GLEventListener of this drawable queue. More...
 
boolean areAllGLEventListenerInitialized ()
 Returns true if all added GLEventListener are initialized, otherwise false. More...
 
GLEventListener getGLEventListener (int index) throws IndexOutOfBoundsException
 Returns the GLEventListener at the given index of this drawable queue. More...
 
boolean getGLEventListenerInitState (GLEventListener listener)
 Retrieves whether the given listener is initialized or not. More...
 
void setGLEventListenerInitState (GLEventListener listener, boolean initialized)
 Sets the given listener's initialized state. More...
 
GLEventListener disposeGLEventListener (GLEventListener listener, boolean remove)
 Disposes the given listener via dispose(..) if it has been initialized and added to this queue. More...
 
GLEventListener removeGLEventListener (GLEventListener listener)
 Removes the given listener from this drawable queue. More...
 
abstract void setAnimator (GLAnimatorControl animatorControl) throws GLException
 Registers the usage of an animator, an com.jogamp.opengl.GLAnimatorControl implementation. More...
 
GLAnimatorControl getAnimator ()
 
Thread setExclusiveContextThread (Thread t) throws GLException
 Dedicates this instance's GLContext to the given thread. More...
 
Thread getExclusiveContextThread ()
 
boolean invoke (boolean wait, GLRunnable glRunnable) throws IllegalStateException
 Enqueues a one-shot GLRunnable, which will be executed within the next display() call after all registered GLEventListeners display(GLAutoDrawable) methods have been called. More...
 
boolean invoke (boolean wait, List< GLRunnable > glRunnables) throws IllegalStateException
 Extends invoke(boolean, GLRunnable) functionality allowing to inject a list of GLRunnables. More...
 
void flushGLRunnables ()
 Flushes all enqueued GLRunnable of this GLAutoDrawable including notifying waiting executor. More...
 
void destroy ()
 Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext. More...
 
void display ()
 
void setAutoSwapBufferMode (boolean enable)
 Enables or disables automatic buffer swapping for this drawable. More...
 
boolean getAutoSwapBufferMode ()
 Indicates whether automatic buffer swapping is enabled for this drawable. More...
 
void setContextCreationFlags (int flags)
 
int getContextCreationFlags ()
 
GLContext createContext (GLContext shareWith)
 Creates a new context for drawing to this drawable that will optionally share buffer objects, textures and other server-side OpenGL objects with the specified GLContext.The GLContext share need not be associated with this GLDrawable and may be null if sharing of display lists and other objects is not desired. See the note in the overview documentation context sharing as well as GLSharedContextSetter. More...
 
GL getGL ()
 Returns the GL pipeline object this GLAutoDrawable uses. More...
 
GL setGL (GL gl)
 Sets the GL pipeline object this GLAutoDrawable uses. More...
 
Object getUpstreamWidget ()
 Method may return the upstream UI toolkit object holding this GLAutoDrawable instance, if exist. More...
 
RecursiveLock getUpstreamLock ()
 Returns the recursive lock object of the upstream widget to synchronize multithreaded access on top of NativeSurface#lockSurface(). More...
 
boolean isThreadGLCapable ()
 Indicates whether the current thread is capable of performing OpenGL-related work. More...
 
- Public Member Functions inherited from com.jogamp.opengl.GLDrawable
GLContext createContext (GLContext shareWith)
 Creates a new context for drawing to this drawable that will optionally share buffer objects, textures and other server-side OpenGL objects with the specified GLContext. More...
 
void setRealized (boolean realized)
 Indicates to GLDrawable implementations whether the underlying surface has been created and can be drawn into. More...
 
boolean isRealized ()
 Returns true if this drawable is realized, otherwise false. More...
 
int getSurfaceWidth ()
 Returns the width of this GLDrawable's surface client area in pixel units. More...
 
int getSurfaceHeight ()
 Returns the height of this GLDrawable's surface client area in pixel units. More...
 
boolean isGLOriented ()
 Returns true if the drawable is rendered in OpenGL's coordinate system, origin at bottom left. More...
 
void swapBuffers () throws GLException
 Swaps the front and back buffers of this drawable. More...
 
GLCapabilitiesImmutable getChosenGLCapabilities ()
 Fetches the GLCapabilitiesImmutable corresponding to the chosen OpenGL capabilities (pixel format / visual / GLProfile) for this drawable. More...
 
GLCapabilitiesImmutable getRequestedGLCapabilities ()
 Fetches the GLCapabilitiesImmutable corresponding to the user requested OpenGL capabilities (pixel format / visual / GLProfile) for this drawable. More...
 
GLProfile getGLProfile ()
 Fetches the GLProfile for this drawable. More...
 
NativeSurface getNativeSurface ()
 Returns the associated NativeSurface of this NativeSurfaceHolder. More...
 
long getHandle ()
 Returns the GL drawable handle, guaranteed to be valid after realization and while it's surface is being locked. More...
 
GLDrawableFactory getFactory ()
 Return the GLDrawableFactory being used to create this instance. More...
 
String toString ()
 
NativeSurface getNativeSurface ()
 Returns the associated NativeSurface of this NativeSurfaceHolder. More...
 

Protected Member Functions

void destroyImplInLock ()
 

Additional Inherited Members

- Static Public Attributes inherited from com.jogamp.opengl.GLAutoDrawable
static final boolean SCREEN_CHANGE_ACTION_ENABLED = Debug.getBooleanProperty("jogl.screenchange.action", true)
 Flag reflecting whether the GLDrawable reconfiguration will be issued in case a screen device change occurred, e.g. More...
 

Detailed Description

Fully functional GLAutoDrawable implementation utilizing already created GLDrawable and GLContext instances.

Since no native windowing system events are being processed, it is recommended to handle at least the window events:

and setup a custom toolkit destruction issuing windowDestroyNotifyOp().

See example TestGLAutoDrawableDelegateNEWT.

OpenGL Context Sharing

To share a GLContext see the following note in the documentation overview: context sharing as well as GLSharedContextSetter.

Definition at line 73 of file GLAutoDrawableDelegate.java.

Constructor & Destructor Documentation

◆ GLAutoDrawableDelegate()

com.jogamp.opengl.GLAutoDrawableDelegate.GLAutoDrawableDelegate ( final GLDrawable  drawable,
final GLContext  context,
final Object  upstreamWidget,
final boolean  ownDevice,
final RecursiveLock  lock 
)

The GLContext can be assigned later manually via setContext(ctx) or it will be created lazily at the 1st display() method call.
Lazy GLContext creation will take a shared GLContext into account which has been set directly or via another GLAutoDrawable.

Parameters
drawablea valid GLDrawable, may not be realized yet.
contexta valid GLContext, may not have been made current (created) yet, may not be associated w/ drawable yet, may be null for lazy initialization at 1st display().
upstreamWidgetoptional UI element holding this instance, see getUpstreamWidget().
ownDevicepass true if AbstractGraphicsDevice#close() shall be issued, otherwise pass false. Closing the device is required in case the drawable is created w/ it's own new instance, e.g. offscreen drawables, and no further lifecycle handling is applied.
lockoptional custom RecursiveLock.

Definition at line 94 of file GLAutoDrawableDelegate.java.

Member Function Documentation

◆ destroy()

final void com.jogamp.opengl.GLAutoDrawableDelegate.destroy ( )

Destroys all resources associated with this GLAutoDrawable, inclusive the GLContext.If a window is attached to it's implementation, it shall be closed. Causes disposing of all OpenGL resources by calling dispose(..) for all registered GLEventListeners. Called automatically by the window system toolkit upon receiving a destroy notification. This routine may be called manually.

This implementation calls defaultDestroy().

User still needs to destroy the upstream window, which details are hidden from this aspect. This can be performed by overriding destroyImplInLock().

Implements com.jogamp.opengl.GLAutoDrawable.

Definition at line 179 of file GLAutoDrawableDelegate.java.

Here is the caller graph for this function:

◆ destroyImplInLock()

void com.jogamp.opengl.GLAutoDrawableDelegate.destroyImplInLock ( )
protected

Definition at line 184 of file GLAutoDrawableDelegate.java.

Here is the caller graph for this function:

◆ display()

void com.jogamp.opengl.GLAutoDrawableDelegate.display ( )

Causes OpenGL rendering to be performed for this GLAutoDrawable in the following order:

May be called periodically by a running com.jogamp.opengl.GLAnimatorControl implementation,
which must register itself with setAnimator(com.jogamp.opengl.GLAnimatorControl).

Called automatically by the window system toolkit upon receiving a repaint() request,
except an com.jogamp.opengl.GLAnimatorControl implementation com.jogamp.opengl.GLAnimatorControl#isAnimating().

This routine may also be called manually for better control over the rendering process. It is legal to call another GLAutoDrawable's display method from within the display(..) callback.

In case of a new generated OpenGL context, the implementation shall call init(..) for all registered GLEventListeners before making the actual display(..) calls, in case this has not been done yet.

See also
setAnimator(com.jogamp.opengl.GLAnimatorControl)

Implements com.jogamp.opengl.GLAutoDrawable.

Definition at line 189 of file GLAutoDrawableDelegate.java.

Here is the caller graph for this function:

◆ getFactory()

final GLDrawableFactory com.jogamp.opengl.GLAutoDrawableDelegate.getFactory ( )

Return the GLDrawableFactory being used to create this instance.

Implements com.jogamp.opengl.GLDrawable.

Definition at line 198 of file GLAutoDrawableDelegate.java.

Here is the call graph for this function:

◆ getUpstreamLock()

final RecursiveLock com.jogamp.opengl.GLAutoDrawableDelegate.getUpstreamLock ( )

Returns the recursive lock object of the upstream widget to synchronize multithreaded access on top of NativeSurface#lockSurface().

See GLAutoDrawable Locking.

Since
2.2

Implements com.jogamp.opengl.GLAutoDrawable.

Definition at line 153 of file GLAutoDrawableDelegate.java.

◆ getUpstreamWidget()

final Object com.jogamp.opengl.GLAutoDrawableDelegate.getUpstreamWidget ( )

Method may return the upstream UI toolkit object holding this GLAutoDrawable instance, if exist.

Currently known Java UI toolkits and it's known return types are:

Toolkit GLAutoDrawable Implementation ~ Return Type of getUpstreamWidget()</td
NEWT com.jogamp.newt.opengl.GLWindow has a com.jogamp.newt.Window</td
SWT com.jogamp.opengl.swt.GLCanvas is a org.eclipse.swt.widgets.Canvas</td
AWT com.jogamp.opengl.awt.GLCanvas is a java.awt.Canvas</td
AWT com.jogamp.opengl.awt.GLJPanel is a javax.swing.JPanel</td

However, the result may be other object types than the listed above due to new supported toolkits.

This method may also return null if no UI toolkit is being used, as common for offscreen rendering.

Implements com.jogamp.opengl.GLAutoDrawable.

Definition at line 156 of file GLAutoDrawableDelegate.java.

◆ setUpstreamWidget()

final void com.jogamp.opengl.GLAutoDrawableDelegate.setUpstreamWidget ( final Object  newUpstreamWidget)

Set the upstream UI toolkit object.

See also
getUpstreamWidget()

Definition at line 164 of file GLAutoDrawableDelegate.java.

◆ swapBuffers()

final void com.jogamp.opengl.GLAutoDrawableDelegate.swapBuffers ( ) throws GLException

Swaps the front and back buffers of this drawable.

For GLAutoDrawable implementations, when automatic buffer swapping is enabled (as is the default), this method is called automatically and should not be called by the end user.

Implements com.jogamp.opengl.GLDrawable.

Definition at line 203 of file GLAutoDrawableDelegate.java.

◆ toString()

String com.jogamp.opengl.GLAutoDrawableDelegate.toString ( )

Implements com.jogamp.opengl.GLDrawable.

Definition at line 208 of file GLAutoDrawableDelegate.java.

◆ windowDestroyNotifyOp()

final void com.jogamp.opengl.GLAutoDrawableDelegate.windowDestroyNotifyOp ( )

Implementation to handle destroy notifications from the windowing system.

If the NativeSurface does not implement WindowClosingProtocol or WindowClosingMode#DISPOSE_ON_CLOSE is enabled (default), a thread safe destruction is being induced.

Definition at line 141 of file GLAutoDrawableDelegate.java.

◆ windowRepaintOp()

final void com.jogamp.opengl.GLAutoDrawableDelegate.windowRepaintOp ( )

Default implementation to handle repaint events from the windowing system.

Definition at line 108 of file GLAutoDrawableDelegate.java.

◆ windowResizedOp()

final void com.jogamp.opengl.GLAutoDrawableDelegate.windowResizedOp ( final int  newWidth,
final int  newHeight 
)

Handling resize events from the windowing system.

Implementation:

All required locks are being claimed.

Parameters
newWidthnew width in pixel units
newWidthnew height in pixel units

Definition at line 128 of file GLAutoDrawableDelegate.java.


The documentation for this class was generated from the following file: