Top Fields Constructors Methods
jogamp.opengl

public abstract Class GLDrawableImpl

extends Object
implements GLDrawable
Class Inheritance
All Implemented Interfaces
com.jogamp.opengl.GLDrawable, com.jogamp.nativewindow.NativeSurfaceHolder
Known Direct Subclasses
jogamp.opengl.GLFBODrawableImpl, jogamp.opengl.egl.EGLDrawable, jogamp.opengl.macosx.cgl.MacOSXCGLDrawable, jogamp.opengl.windows.wgl.WindowsWGLDrawable, jogamp.opengl.x11.glx.X11GLXDrawable
Imports
com.jogamp.nativewindow.AbstractGraphicsDevice, .NativeSurface, .ProxySurface, com.jogamp.opengl.GL, .GLCapabilitiesImmutable, .GLContext, .GLDrawable, .GLDrawableFactory, .GLException, .GLProfile, com.jogamp.common.ExceptionUtils

Field Summary

Modifier and TypeField and Description
protected static final boolean
DEBUG

protected final GLDrawableFactory
factory

protected volatile boolean
realized

protected final GLCapabilitiesImmutable
requestedCapabilities

protected final NativeSurface
surface

Constructor Summary

AccessConstructor and Description
protected
GLDrawableImpl(final GLDrawableFactory factory, final NativeSurface comp, final boolean realized)

protected
GLDrawableImpl(final GLDrawableFactory factory, final NativeSurface comp, final GLCapabilitiesImmutable requestedCapabilities, final boolean realized)

Method Summary

Modifier and TypeMethod and Description
protected void
associateContext(final GLContext
the just bounded or unbounded context
ctx, final boolean
if true create an association, otherwise remove it
bound)

Callback for special implementations, allowing

  • to associate bound context to this drawable (bound == true) or to remove such association (bound == false).
  • to trigger GLContext/GLDrawable related lifecycle: construct, destroy.
protected void
contextMadeCurrent(final GLContext glc, final boolean current)

Callback for special implementations, allowing GLContext to trigger GL related lifecycle: makeCurrent, release.

protected void
createHandle()

called with locked surface @ setRealized(true) or @ lockSurface(..) when surface changed

Must be paired w/ destroyHandle().

protected void
destroyHandle()

called with locked surface @ setRealized(false) or @ lockSurface(..) when surface changed

Must be paired w/ createHandle().

public final GLCapabilitiesImmutable
getChosenGLCapabilities()

Implements com.jogamp.opengl.GLDrawable.getChosenGLCapabilities.

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

Callback for special implementations, allowing GLContext to fetch a custom default render framebuffer.

protected int
getDefaultReadBuffer(final GL gl, final boolean hasDedicatedDrawableRead)

Callback for special implementations, allowing GLContext to fetch a custom default read buffer of current framebuffer.

protected int
getDefaultReadFramebuffer()

Callback for special implementations, allowing GLContext to fetch a custom default read framebuffer.

public final GLDrawableFactory
getFactory()

Implements com.jogamp.opengl.GLDrawable.getFactory.

Return the GLDrawableFactory being used to create this instance.
public final GLDrawableFactoryImpl
getFactoryImpl()

public final GLProfile
getGLProfile()

Implements com.jogamp.opengl.GLDrawable.getGLProfile.

Fetches the GLProfile for this drawable.
public long
getHandle()

Implements com.jogamp.opengl.GLDrawable.getHandle.

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

Implements com.jogamp.opengl.GLDrawable.getNativeSurface.

Returns the associated NativeSurface of this NativeSurfaceHolder.
public final GLCapabilitiesImmutable
getRequestedGLCapabilities()

Implements com.jogamp.opengl.GLDrawable.getRequestedGLCapabilities.

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

Implements com.jogamp.opengl.GLDrawable.getSurfaceHeight.

Returns the height of this GLDrawable's surface client area in pixel units.
public int
getSurfaceWidth()

Implements com.jogamp.opengl.GLDrawable.getSurfaceWidth.

Returns the width of this GLDrawable's surface client area in pixel units.
protected static String
getThreadName()

public boolean
isGLOriented()

Implements com.jogamp.opengl.GLDrawable.isGLOriented.

Returns true if the drawable is rendered in OpenGL's coordinate system, origin at bottom left.
public final boolean
isRealized()

Implements com.jogamp.opengl.GLDrawable.isRealized.

Returns true if this drawable is realized, otherwise true.
public final int
lockSurface()

Locks the underlying windowing toolkit's surface.

public final void
setRealized(final boolean realizedArg)

Implements com.jogamp.opengl.GLDrawable.setRealized.

Indicates to GLDrawable implementations whether the underlying surface has been created and can be drawn into.
protected abstract void
setRealizedImpl()

Platform specific realization of drawable

public final void
swapBuffers()

Implements com.jogamp.opengl.GLDrawable.swapBuffers.

Swaps the front and back buffers of this drawable.
protected abstract void
swapBuffersImpl(boolean
indicates whether double buffering is enabled, see above.
doubleBuffered)

Platform and implementation depending surface swap.

public static final String
toHexString(final long hex)

public String
toString()

Overrides java.lang.Object.toString.

Implements com.jogamp.opengl.GLDrawable.toString.

Returns a string representation of the object.
public final void
unlockSurface()

Unlocks the underlying windowing toolkit surface, which may render the drawable handle invalid.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

DEBUGback to summary
protected static final boolean DEBUG
factoryback to summary
protected final GLDrawableFactory factory
realizedback to summary
protected volatile boolean realized
requestedCapabilitiesback to summary
protected final GLCapabilitiesImmutable requestedCapabilities
surfaceback to summary
protected final NativeSurface surface

Constructor Detail

GLDrawableImplback to summary
protected GLDrawableImpl(final GLDrawableFactory factory, final NativeSurface comp, final boolean realized)
GLDrawableImplback to summary
protected GLDrawableImpl(final GLDrawableFactory factory, final NativeSurface comp, final GLCapabilitiesImmutable requestedCapabilities, final boolean realized)

Method Detail

associateContextback to summary
protected void associateContext(final GLContext ctx, final boolean bound)

Callback for special implementations, allowing

  • to associate bound context to this drawable (bound == true) or to remove such association (bound == false).
  • to trigger GLContext/GLDrawable related lifecycle: construct, destroy.

If bound is true, the context is current and being newly associated w/ this drawable.

If bound is false, the context is still current and will be unbound (released and destroyed, or simply disassociated).

Being called by GLContextImpl#associateDrawable(boolean).

Parameters
ctx:GLContext

the just bounded or unbounded context

bound:boolean

if true create an association, otherwise remove it

contextMadeCurrentback to summary
protected void contextMadeCurrent(final GLContext glc, final boolean current)

Callback for special implementations, allowing GLContext to trigger GL related lifecycle: makeCurrent, release.

If current is true, the context has just been made current.

If current is false, the context is still current and will be release after this method returns.

Being called by GLContextImpl#contextMadeCurrent(boolean).

See Also
associateContext(GLContext, boolean)
createHandleback to summary
protected void createHandle()

called with locked surface @ setRealized(true) or @ lockSurface(..) when surface changed

Must be paired w/ destroyHandle().

destroyHandleback to summary
protected void destroyHandle()

called with locked surface @ setRealized(false) or @ lockSurface(..) when surface changed

Must be paired w/ createHandle().

getChosenGLCapabilitiesback to summary
public final GLCapabilitiesImmutable getChosenGLCapabilities()

Implements com.jogamp.opengl.GLDrawable.getChosenGLCapabilities.

Doc from 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:GLCapabilitiesImmutable

The immutable queried instance.

Annotations
@Override
getDefaultDrawFramebufferback to summary
protected int getDefaultDrawFramebuffer()

Callback for special implementations, allowing GLContext to fetch a custom default render framebuffer. Defaults to zero.

getDefaultReadBufferback to summary
protected int getDefaultReadBuffer(final GL gl, final boolean hasDedicatedDrawableRead)

Callback for special implementations, allowing GLContext to fetch a custom default read buffer of current framebuffer.

getDefaultReadFramebufferback to summary
protected int getDefaultReadFramebuffer()

Callback for special implementations, allowing GLContext to fetch a custom default read framebuffer. Defaults to zero.

getFactoryback to summary
public final GLDrawableFactory getFactory()

Implements com.jogamp.opengl.GLDrawable.getFactory.

Doc from com.jogamp.opengl.GLDrawable.getFactory.

Return the GLDrawableFactory being used to create this instance.

Annotations
@Override
getFactoryImplback to summary
public final GLDrawableFactoryImpl getFactoryImpl()
getGLProfileback to summary
public final GLProfile getGLProfile()

Implements com.jogamp.opengl.GLDrawable.getGLProfile.

Doc from com.jogamp.opengl.GLDrawable.getGLProfile.

Fetches the GLProfile for this drawable. Returns the GLProfile object, no copy.

Annotations
@Override
getHandleback to summary
public long getHandle()

Implements com.jogamp.opengl.GLDrawable.getHandle.

Doc from 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().

Annotations
@Override
getNativeSurfaceback to summary
public NativeSurface getNativeSurface()

Implements com.jogamp.opengl.GLDrawable.getNativeSurface.

Doc from 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.

Annotations
@Override
getRequestedGLCapabilitiesback to summary
public final GLCapabilitiesImmutable getRequestedGLCapabilities()

Implements com.jogamp.opengl.GLDrawable.getRequestedGLCapabilities.

Doc from 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:GLCapabilitiesImmutable

The immutable queried instance.

Annotations
@Override
getSurfaceHeightback to summary
public int getSurfaceHeight()

Implements com.jogamp.opengl.GLDrawable.getSurfaceHeight.

Doc from com.jogamp.opengl.GLDrawable.getSurfaceHeight.

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

Annotations
@Override
getSurfaceWidthback to summary
public int getSurfaceWidth()

Implements com.jogamp.opengl.GLDrawable.getSurfaceWidth.

Doc from com.jogamp.opengl.GLDrawable.getSurfaceWidth.

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

Annotations
@Override
getThreadNameback to summary
protected static String getThreadName()
isGLOrientedback to summary
public boolean isGLOriented()

Implements com.jogamp.opengl.GLDrawable.isGLOriented.

Doc from 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.

Annotations
@Override
isRealizedback to summary
public final boolean isRealized()

Implements com.jogamp.opengl.GLDrawable.isRealized.

Doc from com.jogamp.opengl.GLDrawable.isRealized.

Returns true if this drawable is realized, otherwise true.

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

Annotations
@Override
lockSurfaceback to summary
public final int lockSurface() throws GLException

Locks the underlying windowing toolkit's surface.

If drawable is realized, the drawable handle is valid after successfully locking it's surface until being unlocked.

In case the surface has changed as indicated by it's lock result NativeSurface#LOCK_SURFACE_CHANGED, the implementation is required to update this information as needed within it's implementation.

See Also
NativeSurface#lockSurface(), getHandle()
setRealizedback to summary
public final void setRealized(final boolean realizedArg)

Implements com.jogamp.opengl.GLDrawable.setRealized.

Doc from com.jogamp.opengl.GLDrawable.setRealized.

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:


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.

Annotations
@Override
setRealizedImplback to summary
protected abstract void setRealizedImpl()

Platform specific realization of drawable

swapBuffersback to summary
public final void swapBuffers() throws GLException

Implements com.jogamp.opengl.GLDrawable.swapBuffers.

Doc from com.jogamp.opengl.GLDrawable.swapBuffers.

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.

Annotations
@Override
swapBuffersImplback to summary
protected abstract void swapBuffersImpl(boolean doubleBuffered)

Platform and implementation depending surface swap.

The surface is locked.

If doubleBuffered is true, an actual platform dependent surface swap shall be executed.

If doubleBuffered is false, GL#glFlush() has been called already and the implementation may execute implementation specific code.

Parameters
doubleBuffered:boolean

indicates whether double buffering is enabled, see above.

toHexStringback to summary
public static final String toHexString(final long hex)
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Implements com.jogamp.opengl.GLDrawable.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object

Annotations
@Override
unlockSurfaceback to summary
public final void unlockSurface()

Unlocks the underlying windowing toolkit surface, which may render the drawable handle invalid.

See Also
NativeSurface#unlockSurface(), getHandle()