An abstraction for an OpenGL rendering target. More...

Inheritance diagram for com.jogamp.opengl.GLDrawable:

Collaboration diagram for com.jogamp.opengl.GLDrawable:

Public Member Functions
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...

Detailed Description

An abstraction for an OpenGL rendering target.

A GLDrawable's primary functionality is to create OpenGL contexts which can be used to perform rendering. A GLDrawable does not automatically create an OpenGL context, but all implementations of GLAutoDrawable do so upon creation.

Definition at line 51 of file GLDrawable.java.

Member Function Documentation

◆ createContext()

GLContext com.jogamp.opengl.GLDrawable.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.

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, com.jogamp.opengl.swt.GLCanvas, and com.jogamp.opengl.GLAutoDrawable.

Here is the caller graph for this function:

◆ getChosenGLCapabilities()

GLCapabilitiesImmutable com.jogamp.opengl.GLDrawable.getChosenGLCapabilities ( )

Fetches the GLCapabilitiesImmutable corresponding to the chosen OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.

This query only returns the chosen capabilities if isRealized().

On some platforms, the pixel format is not directly associated with the drawable; a best attempt is made to return a reasonable value in this case.

This object shall be directly associated to the attached NativeSurface's AbstractGraphicsConfiguration, and if changes are necessary, they should reflect those as well.

Returns: The immutable queried instance.

See also: getRequestedGLCapabilities()

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, and com.jogamp.opengl.swt.GLCanvas.

◆ getFactory()

GLDrawableFactory com.jogamp.opengl.GLDrawable.getFactory ( )

Return the GLDrawableFactory being used to create this instance.

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, com.jogamp.opengl.GLAutoDrawableDelegate, com.jogamp.opengl.swt.GLCanvas, and com.jogamp.newt.opengl.GLWindow.

Here is the caller graph for this function:

◆ getGLProfile()

GLProfile com.jogamp.opengl.GLDrawable.getGLProfile ( )

Fetches the GLProfile for this drawable.

Returns the GLProfile object, no copy.

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, and com.jogamp.opengl.swt.GLCanvas.

Here is the caller graph for this function:

◆ getHandle()

long com.jogamp.opengl.GLDrawable.getHandle ( )

Returns the GL drawable handle, guaranteed to be valid after realization and while it's surface is being locked.

It is usually identical to the underlying windowing toolkit surface's handle or an intermediate layer to suite GL, e.g. an EGL surface.

On EGL it is represented by the EGLSurface.
On X11/GLX it is represented by either the Window XID, GLXPixmap, or GLXPbuffer.
On Windows it is represented by the HDC, which may change with each NativeSurface#lockSurface().

See also: setRealized(boolean); NativeSurface::lockSurface(); NativeSurface::unlockSurface()

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, and com.jogamp.opengl.swt.GLCanvas.

Here is the caller graph for this function:

◆ getNativeSurface()

NativeSurface com.jogamp.opengl.GLDrawable.getNativeSurface ( )

Returns the associated NativeSurface of this NativeSurfaceHolder.

Returns the underlying NativeSurface which native handle represents this OpenGL drawable's native resource.

See also: getHandle()

Implements com.jogamp.nativewindow.NativeSurfaceHolder.

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, and com.jogamp.opengl.swt.GLCanvas.

Here is the caller graph for this function:

◆ getRequestedGLCapabilities()

GLCapabilitiesImmutable com.jogamp.opengl.GLDrawable.getRequestedGLCapabilities ( )

Fetches the GLCapabilitiesImmutable corresponding to the user requested OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.

If realized, the chosen capabilities reflect the actual selected OpenGL capabilities.

Returns: The immutable queried instance.

See also: getChosenGLCapabilities()

Since: 2.2

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, and com.jogamp.opengl.swt.GLCanvas.

Here is the caller graph for this function:

◆ getSurfaceHeight()

int com.jogamp.opengl.GLDrawable.getSurfaceHeight ( )

Returns the height of this GLDrawable's surface client area in pixel units.

See also: NativeSurface::getSurfaceHeight()

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, com.jogamp.opengl.swt.GLCanvas, and com.jogamp.newt.opengl.GLWindow.

◆ getSurfaceWidth()

int com.jogamp.opengl.GLDrawable.getSurfaceWidth ( )

Returns the width of this GLDrawable's surface client area in pixel units.

See also: NativeSurface::getSurfaceWidth()

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, com.jogamp.opengl.swt.GLCanvas, and com.jogamp.newt.opengl.GLWindow.

◆ isGLOriented()

boolean com.jogamp.opengl.GLDrawable.isGLOriented ( )

Returns true if the drawable is rendered in OpenGL's coordinate system, origin at bottom left.

Otherwise returns false, i.e. origin at top left.

Default impl. is true, i.e. OpenGL coordinate system.

Currently only MS-Windows bitmap offscreen drawable uses a non OpenGL orientation and hence returns false.
This removes the need of a vertical flip when used in AWT or Windows applications.

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, and com.jogamp.opengl.swt.GLCanvas.

Here is the caller graph for this function:

◆ isRealized()

boolean com.jogamp.opengl.GLDrawable.isRealized ( )

Returns true if this drawable is realized, otherwise false.

A drawable can be realized and unrealized via setRealized(boolean).

See also: setRealized(boolean)

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, and com.jogamp.opengl.swt.GLCanvas.

Here is the caller graph for this function:

◆ setRealized()

void com.jogamp.opengl.GLDrawable.setRealized ( boolean realized )

Indicates to GLDrawable implementations whether the underlying surface has been created and can be drawn into.

If realized, the drawable handle may become valid while it's surface is being locked.

End users do not need to call this method; it is not necessary to call setRealized on a GLAutoDrawable as these perform the appropriate calls on their underlying GLDrawables internally.

Developers implementing new OpenGL components for various window toolkits need to call this method against GLDrawables obtained from the GLDrawableFactory via the GLDrawableFactory#createGLDrawable(NativeSurface) method. It must typically be called with an argument of true when the component associated with the GLDrawable is realized and with an argument of false just before the component is unrealized. For the AWT, this means calling setRealized(true) in the addNotify method and with an argument of false in the removeNotify method.

GLDrawable implementations should handle multiple cycles of setRealized(true) / setRealized(false) calls. Most, if not all, Java window toolkits have a persistent object associated with a given component, regardless of whether that component is currently realized. The GLDrawable object associated with a particular component is intended to be similarly persistent. A GLDrawable is intended to be created for a given component when it is constructed and live as long as that component. setRealized allows the GLDrawable to re-initialize and destroy any associated resources as the component becomes realized and unrealized, respectively.

With an argument of true, the minimum implementation shall call NativeSurface's lockSurface() and if successful:

Update the GLCapabilities, which are associated with the attached NativeSurface's AbstractGraphicsConfiguration.
Release the lock with NativeSurface's unlockSurface().

This is important since NativeSurface's lockSurface() ensures resolving the window/surface handles, and the drawable's GLCapabilities might have changed.

Calling this method has no other effects. For example, if removeNotify is called on a Canvas implementation for which a GLDrawable has been created, it is also necessary to destroy all OpenGL contexts associated with that GLDrawable. This is not done automatically by the implementation.

See also: isRealized(); getHandle(); NativeSurface::lockSurface()

Implemented in com.jogamp.opengl.swt.GLCanvas, com.jogamp.opengl.awt.GLCanvas, and com.jogamp.opengl.awt.GLJPanel.

Here is the caller graph for this function:

◆ swapBuffers()

void com.jogamp.opengl.GLDrawable.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.

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, com.jogamp.opengl.GLAutoDrawableDelegate, com.jogamp.opengl.swt.GLCanvas, and com.jogamp.newt.opengl.GLWindow.

Here is the caller graph for this function:

◆ toString()

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

Implemented in com.jogamp.opengl.awt.GLCanvas, com.jogamp.opengl.awt.GLJPanel, com.jogamp.opengl.GLAutoDrawableDelegate, com.jogamp.opengl.swt.GLCanvas, and com.jogamp.newt.opengl.GLWindow.

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

src/jogl/classes/com/jogamp/opengl/GLDrawable.java

Public Member Functions

Detailed Description

Member Function Documentation

◆ createContext()

◆ getChosenGLCapabilities()

◆ getFactory()

◆ getGLProfile()

◆ getHandle()

◆ getNativeSurface()

◆ getRequestedGLCapabilities()

◆ getSurfaceHeight()

◆ getSurfaceWidth()

◆ isGLOriented()

◆ isRealized()

◆ setRealized()

◆ swapBuffers()

◆ toString()