Interface GLDrawable
-
- All Superinterfaces:
NativeSurfaceHolder
- All Known Subinterfaces:
AWTGLAutoDrawable,GLAutoDrawable,GLFBODrawable,GLFBODrawable.Resizeable,GLOffscreenAutoDrawable,GLOffscreenAutoDrawable.FBO,GLSharedContextSetter
- All Known Implementing Classes:
jogamp.opengl.GLAutoDrawableBase,GLAutoDrawableDelegate,GLCanvas,GLCanvas,GLJPanel,GLWindow
public interface GLDrawable extends NativeSurfaceHolder
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 ofGLAutoDrawabledo so upon creation.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description GLContextcreateContext(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.GLCapabilitiesImmutablegetChosenGLCapabilities()Fetches theGLCapabilitiesImmutablecorresponding to the chosen OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.GLDrawableFactorygetFactory()Return theGLDrawableFactorybeing used to create this instance.GLProfilegetGLProfile()Fetches theGLProfilefor this drawable.longgetHandle()Returns the GL drawable handle, guaranteed to be valid afterrealizationand while it'ssurfaceis beinglocked.NativeSurfacegetNativeSurface()Returns the associatedNativeSurfaceof thisNativeSurfaceHolder.GLCapabilitiesImmutablegetRequestedGLCapabilities()Fetches theGLCapabilitiesImmutablecorresponding to the user requested OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.intgetSurfaceHeight()Returns the height of thisGLDrawable'ssurfaceclient area in pixel units.intgetSurfaceWidth()Returns the width of thisGLDrawable'ssurfaceclient area in pixel units.booleanisGLOriented()Returnstrueif the drawable is rendered in OpenGL's coordinate system, origin at bottom left.booleanisRealized()Returnstrueif this drawable is realized, otherwisefalse.voidsetRealized(boolean realized)Indicates to GLDrawable implementations whether the underlyingsurfacehas been created and can be drawn into.voidswapBuffers()Swaps the front and back buffers of this drawable.StringtoString()
-
-
-
Method Detail
-
createContext
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
shareneed 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 asGLSharedContextSetter.
-
setRealized
void setRealized(boolean realized)
Indicates to GLDrawable implementations whether the underlyingsurfacehas been created and can be drawn into.If realized, the
drawable handlemay become valid while it'ssurfaceis beinglocked.End users do not need to call this method; it is not necessary to call
setRealizedon aGLAutoDrawableas 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 oftruewhen the component associated with the GLDrawable is realized and with an argument offalsejust before the component is unrealized. For the AWT, this means callingsetRealized(true)in theaddNotifymethod and with an argument offalsein theremoveNotifymethod.GLDrawableimplementations should handle multiple cycles ofsetRealized(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. TheGLDrawableobject associated with a particular component is intended to be similarly persistent. AGLDrawableis intended to be created for a given component when it is constructed and live as long as that component.setRealizedallows theGLDrawableto re-initialize and destroy any associated resources as the component becomes realized and unrealized, respectively.With an argument of
true, the minimum implementation shall callNativeSurface's lockSurface()and if successful:- Update the
GLCapabilities, which are associated with the attachedNativeSurface'sAbstractGraphicsConfiguration. - Release the lock with
NativeSurface's unlockSurface().
This is important sinceNativeSurface's lockSurface()ensures resolving the window/surface handles, and the drawable'sGLCapabilitiesmight have changed.Calling this method has no other effects. For example, if
removeNotifyis 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()
- Update the
-
isRealized
boolean isRealized()
Returnstrueif this drawable is realized, otherwisefalse.A drawable can be realized and unrealized via
setRealized(boolean).- See Also:
setRealized(boolean)
-
getSurfaceWidth
int getSurfaceWidth()
Returns the width of thisGLDrawable'ssurfaceclient area in pixel units.- See Also:
NativeSurface.getSurfaceWidth()
-
getSurfaceHeight
int getSurfaceHeight()
Returns the height of thisGLDrawable'ssurfaceclient area in pixel units.- See Also:
NativeSurface.getSurfaceHeight()
-
isGLOriented
boolean isGLOriented()
Returnstrueif the drawable is rendered in OpenGL's coordinate system, origin at bottom left. Otherwise returnsfalse, 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.
-
swapBuffers
void swapBuffers() throws GLExceptionSwaps the front and back buffers of this drawable. ForGLAutoDrawableimplementations, when automatic buffer swapping is enabled (as is the default), this method is called automatically and should not be called by the end user.- Throws:
GLException
-
getChosenGLCapabilities
GLCapabilitiesImmutable getChosenGLCapabilities()
Fetches theGLCapabilitiesImmutablecorresponding 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'sAbstractGraphicsConfiguration, and if changes are necessary, they should reflect those as well.- Returns:
- The immutable queried instance.
- See Also:
getRequestedGLCapabilities()
-
getRequestedGLCapabilities
GLCapabilitiesImmutable getRequestedGLCapabilities()
Fetches theGLCapabilitiesImmutablecorresponding to the user requested OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.If
realized,the chosen capabilitiesreflect the actual selected OpenGL capabilities.- Returns:
- The immutable queried instance.
- Since:
- 2.2
- See Also:
getChosenGLCapabilities()
-
getGLProfile
GLProfile getGLProfile()
Fetches theGLProfilefor this drawable. Returns the GLProfile object, no copy.
-
getNativeSurface
NativeSurface getNativeSurface()
Returns the associatedNativeSurfaceof thisNativeSurfaceHolder.Returns the underlying
NativeSurfacewhichnative handlerepresents this OpenGL drawable's native resource.- Specified by:
getNativeSurfacein interfaceNativeSurfaceHolder- See Also:
getHandle()
-
getHandle
long getHandle()
Returns the GL drawable handle, guaranteed to be valid afterrealizationand while it'ssurfaceis beinglocked.It is usually identical to the underlying windowing toolkit
surface'shandleor 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 eachNativeSurface.lockSurface().
-
getFactory
GLDrawableFactory getFactory()
Return theGLDrawableFactorybeing used to create this instance.
-
-