javax.media.opengl
Interface GLDrawable

All Known Subinterfaces:

AWTGLAutoDrawable, GLAutoDrawable, GLPbuffer

All Known Implementing Classes:

GLCanvas, GLJPanel

public interface GLDrawable

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.

Method Summary

GLContext	createContext(GLContext shareWith) Creates a new context for drawing to this drawable that will optionally share display lists and other server-side OpenGL objects with the specified GLContext.
GLCapabilitiesImmutable	getChosenGLCapabilities() Fetches the GLCapabilitiesImmutable corresponding to the chosen OpenGL capabilities (pixel format / visual / GLProfile) for this drawable. 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.
GLDrawableFactory	getFactory()
GLProfile	getGLProfile() Fetches the GLProfile for this drawable.
long	getHandle() This is the GL/Windowing drawable handle. It is usually the NativeSurface.getSurfaceHandle(), ie the native surface handle of the underlying windowing toolkit. However, on X11/GLX this reflects a GLXDrawable, which represents a GLXWindow, GLXPixmap, or GLXPbuffer. On EGL, this represents the EGLSurface.
int	getHeight() Returns the current height of this GLDrawable.
NativeSurface	getNativeSurface()
int	getWidth() Returns the current width of this GLDrawable.
boolean	isRealized()
void	setRealized(boolean realized) Indicates to on-screen GLDrawable implementations whether the underlying window has been created and can be drawn into.
void	swapBuffers() Swaps the front and back buffers of this drawable.
String	toString()

Method Detail

createContext

GLContext createContext(GLContext shareWith)

Creates a new context for drawing to this drawable that will optionally share display lists 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 on context sharing.

setRealized

void setRealized(boolean realized)

Indicates to on-screen GLDrawable implementations whether the underlying window has been created and can be drawn into. End users do not need to call this method; it is not necessary to call setRealized on a GLCanvas, a GLJPanel, or a GLPbuffer, 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.getGLDrawable() 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 successfull:

• 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.

isRealized

boolean isRealized()

Returns:

true if this drawable is realized, otherwise false

getWidth

int getWidth()

Returns the current width of this GLDrawable.

getHeight

int getHeight()

Returns the current height of this GLDrawable.

swapBuffers

void 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.

Throws:

GLException

getChosenGLCapabilities

GLCapabilitiesImmutable getChosenGLCapabilities()

Fetches the GLCapabilitiesImmutable corresponding to the chosen OpenGL capabilities (pixel format / visual / GLProfile) for this drawable.
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:

A copy of the queried object.

getGLProfile

GLProfile getGLProfile()

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

getNativeSurface

NativeSurface getNativeSurface()

getHandle

long getHandle()

This is the GL/Windowing drawable handle.
It is usually the NativeSurface.getSurfaceHandle(), ie the native surface handle of the underlying windowing toolkit.
However, on X11/GLX this reflects a GLXDrawable, which represents a GLXWindow, GLXPixmap, or GLXPbuffer.
On EGL, this represents the EGLSurface.

getFactory

GLDrawableFactory getFactory()

toString

String toString()

Overrides:

toString in class Object