javax.media.opengl
Class GLContext

java.lang.Object
  javax.media.opengl.GLContext

public abstract class GLContext
extends Object

Abstraction for an OpenGL rendering context. In order to perform OpenGL rendering, a context must be "made current" on the current thread. OpenGL rendering semantics specify that only one context may be current on the current thread at any given time, and also that a given context may be current on only one thread at any given time. Because components can be added to and removed from the component hierarchy at any time, it is possible that the underlying OpenGL context may need to be destroyed and recreated multiple times over the lifetime of a given component. This process is handled by the implementation, and the GLContext abstraction provides a stable object which clients can use to refer to a given context.

Field Summary

static int	CONTEXT_CURRENT Indicates that the context was made current during the last call to makeCurrent.
static int	CONTEXT_CURRENT_NEW Indicates that a newly-created context was made current during the last call to makeCurrent.
static int	CONTEXT_NOT_CURRENT Indicates that the context was not made current during the last call to makeCurrent.
static int	CTX_OPTION_DEBUG ARB_create_context related: flag debug
static boolean	DEBUG_GL Reflects property jogl.debug.DebugGL.
static int[][]	GL_VERSIONS
static boolean	TRACE_GL Reflects property jogl.debug.TraceGL.

Method Summary

abstract void	addGLDebugListener(GLDebugListener listener) Add GLDebugListener.
StringBuffer	append(StringBuffer sb)
Object	attachObject(int name, Object obj) Sets the attached user object for the given name to this GLContext.
Object	attachObject(String name, Object obj) Sets the attached user object for the given name to this GLContext.
boolean	bindSwapBarrier(int group, int barrier)
abstract void	copy(GLContext source, int mask) Copies selected groups of OpenGL state variables from the supplied source context into this one.
static boolean	decrementGLVersion(int[] major, int[] minor)
abstract void	destroy() Destroys this OpenGL context and frees its associated resources.
Object	detachObject(int name)
Object	detachObject(String name)
abstract void	enableGLDebugMessage(boolean enable) Enables or disables the GLDebugOutput feature of extension GL_ARB_debug_output or GL_AMD_debug_output, if available.
Object	getAttachedObject(int name) Returns the attached user object for the given name to this GLContext.
Object	getAttachedObject(String name) Returns the attached user object for the given name to this GLContext.
static String	getAvailableGLVersionAsString(AbstractGraphicsDevice device, int major, int profile)
abstract int	getContextCreationFlags()
static GLContext	getCurrent() Returns this thread current context.
static GL	getCurrentGL() Returns the GL object bound to this thread current context.
abstract GL	getGL() Returns the GL pipeline object for this GLContext.
abstract String	getGLDebugMessageExtension()
abstract GLDrawable	getGLDrawable() Returns the GLDrawable to which this context may be used to draw.
abstract String	getGLExtensionsString() Returns a non-null (but possibly empty) string containing the space-separated list of available extensions.
abstract GLDrawable	getGLReadDrawable() Returns the read GLDrawable this context uses for read framebuffer operations.
String	getGLVersion() Returns a valid OpenGL version string, ie
static String	getGLVersion(int major, int minor, int ctp, String gl_version)
int	getGLVersionMajor()
int	getGLVersionMinor()
long	getHandle() Returns the native GL context handle
static int	getMaxMajor()
static int	getMaxMinor(int major)
abstract String	getPlatformExtensionsString() Returns a non-null (but possibly empty) string containing the space-separated list of available platform-dependent (e.g., WGL, GLX) extensions.
int	getSwapGroup()
int	getSwapInterval()
abstract void	glDebugMessageControl(int source, int type, int severity, int count, int[] ids, int ids_offset, boolean enabled) Generic entry for GL2GL3.glDebugMessageControlARB(int, int, int, int, int[], int, boolean) and GL2GL3.glDebugMessageEnableAMD(int, int, int, int[], int, boolean) of the GLDebugOutput feature.
abstract void	glDebugMessageControl(int source, int type, int severity, int count, IntBuffer ids, boolean enabled) Generic entry for GL2GL3.glDebugMessageControlARB(int, int, int, int, IntBuffer, boolean) and GL2GL3.glDebugMessageEnableAMD(int, int, int, IntBuffer, boolean) of the GLDebugOutput feature.
abstract void	glDebugMessageInsert(int source, int type, int id, int severity, String buf) Generic entry for GL2GL3.glDebugMessageInsertARB(int, int, int, int, int, String) and GL2GL3.glDebugMessageInsertAMD(int, int, int, int, String) of the GLDebugOutput feature.
boolean	hasGLSL()
boolean	isCreated() Indicates whether the underlying OpenGL context has been created.
boolean	isCreatedWithARBMethod()
boolean	isCurrent()
boolean	isGL2()
static boolean	isGL2Available(AbstractGraphicsDevice device)
boolean	isGL2ES1()
boolean	isGL2ES2()
boolean	isGL2GL3()
boolean	isGL3()
static boolean	isGL3Available(AbstractGraphicsDevice device)
boolean	isGL3bc()
static boolean	isGL3bcAvailable(AbstractGraphicsDevice device)
boolean	isGL4()
static boolean	isGL4Available(AbstractGraphicsDevice device)
boolean	isGL4bc()
static boolean	isGL4bcAvailable(AbstractGraphicsDevice device)
boolean	isGLCompatibilityProfile()
boolean	isGLCoreProfile()
abstract boolean	isGLDebugMessageEnabled()
abstract boolean	isGLDebugSynchronous()
boolean	isGLES()
boolean	isGLES1()
static boolean	isGLES1Available(AbstractGraphicsDevice device)
boolean	isGLES2()
static boolean	isGLES2Available(AbstractGraphicsDevice device)
boolean	isGLES2Compatible()
boolean	isGLForwardCompatible()
abstract boolean	isGLReadDrawableAvailable() Return availability of GL read drawable.
static boolean	isGLVersionAvailable(AbstractGraphicsDevice device, int major, int profile)
abstract boolean	isSynchronized() Returns true if 'makeCurrent' will exhibit synchronized behavior.
static boolean	isValidGLVersion(int major, int minor)
boolean	joinSwapGroup(int group)
abstract int	makeCurrent() Makes this GLContext current on the calling thread.
boolean	queryMaxSwapGroups(int[] maxGroups, int maxGroups_offset, int[] maxBarriers, int maxBarriers_offset)
abstract void	release() Releases control of this GLContext from the current thread.
abstract void	removeGLDebugListener(GLDebugListener listener) Remove GLDebugListener.
abstract void	setContextCreationFlags(int flags)
abstract GL	setGL(GL gl) Sets the GL pipeline object for this GLContext.
abstract void	setGLDebugSynchronous(boolean synchronous) Enables or disables the synchronous debug behavior via glEnable/glDisable(GL_DEBUG_OUTPUT_SYNCHRONOUS_ARB), if extension is #GL_ARB_debug_output.
abstract void	setGLReadDrawable(GLDrawable read) Set the read GLDrawable for read framebuffer operations. The caller should query if this feature is supported via isGLReadDrawableAvailable().
void	setSwapInterval(int interval)
abstract void	setSynchronized(boolean isSynchronized) Determines whether 'makeCurrent' will exhibit synchronized behavior.
String	toString() Classname, GL, GLDrawable
void	validateCurrent()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEBUG_GL

public static final boolean DEBUG_GL

Reflects property jogl.debug.DebugGL. If true, the debug pipeline is enabled at context creation.

TRACE_GL

public static final boolean TRACE_GL

Reflects property jogl.debug.TraceGL. If true, the trace pipeline is enabled at context creation.

CONTEXT_NOT_CURRENT

public static final int CONTEXT_NOT_CURRENT

Indicates that the context was not made current during the last call to makeCurrent.

See Also:

Constant Field Values

CONTEXT_CURRENT

public static final int CONTEXT_CURRENT

Indicates that the context was made current during the last call to makeCurrent.

See Also:

Constant Field Values

CONTEXT_CURRENT_NEW

public static final int CONTEXT_CURRENT_NEW

Indicates that a newly-created context was made current during the last call to makeCurrent.

See Also:

Constant Field Values

CTX_OPTION_DEBUG

public static final int CTX_OPTION_DEBUG

ARB_create_context related: flag debug

See Also:

Constant Field Values

GL_VERSIONS

public static final int[][] GL_VERSIONS

Method Detail

getGLDrawable

public abstract GLDrawable getGLDrawable()

Returns the GLDrawable to which this context may be used to draw.

isGLReadDrawableAvailable

public abstract boolean isGLReadDrawableAvailable()

Return availability of GL read drawable.

Returns:

true if a GL read drawable is supported with your driver, otherwise false.

setGLReadDrawable

public abstract void setGLReadDrawable(GLDrawable read)

Set the read GLDrawable for read framebuffer operations.
The caller should query if this feature is supported via isGLReadDrawableAvailable().

Parameters:

read - the read GLDrawable for read framebuffer operations. If null is passed, the default write drawable will be set.

Throws:

GLException - in case a read drawable is not supported and the given drawable is not null and not equal to the internal write drawable.

See Also:

isGLReadDrawableAvailable(), getGLReadDrawable()

getGLReadDrawable

public abstract GLDrawable getGLReadDrawable()

Returns the read GLDrawable this context uses for read framebuffer operations.

See Also:

isGLReadDrawableAvailable(), setGLReadDrawable(javax.media.opengl.GLDrawable)

makeCurrent

public abstract int makeCurrent()
                         throws GLException

Makes this GLContext current on the calling thread. There are two return values that indicate success and one that indicates failure. A return value of CONTEXT_CURRENT_NEW indicates that that context has been made current, and that this is the first time this context has been made current, or that the state of the underlying context or drawable may have changed since the last time this context was made current. In this case, the application may wish to initialize the state. A return value of CONTEXT_CURRENT indicates that the context has been made currrent, with its previous state restored. If the context could not be made current (for example, because the underlying drawable has not ben realized on the display) , a value of CONTEXT_NOT_CURRENT is returned. If the context is in use by another thread at the time of the call, then if isSynchronized() is true the call will block. If isSynchronized() is false, an exception will be thrown and the context will remain current on the other thread.

Returns:

CONTEXT_CURRENT if the context was successfully made current

Throws:

GLException - if synchronization is disabled and the context is current on another thread, or because the context could not be created or made current due to non-recoverable, window system-specific errors.

release

public abstract void release()
                      throws GLException

Releases control of this GLContext from the current thread.

Throws:

GLException - if the context had not previously been made current on the current thread

copy

public abstract void copy(GLContext source,
                          int mask)
                   throws GLException

Copies selected groups of OpenGL state variables from the supplied source context into this one. The mask parameter indicates which groups of state variables are to be copied. mask contains the bitwise OR of the same symbolic names that are passed to the GL command glPushAttrib. The single symbolic constant GL_ALL_ATTRIB_BITS can be used to copy the maximum possible portion of rendering state.

Not all values for GL state can be copied. For example, pixel pack and unpack state, render mode state, and select and feedback state are not copied. The state that can be copied is exactly the state that is manipulated by the GL command glPushAttrib.

On most platforms, this context may not be current to any thread, including the calling thread, when this method is called. Some platforms have additional requirements such as whether this context or the source context must occasionally be made current in order for the results of the copy to be seen; these requirements are beyond the scope of this specification.

Parameters:

source - the source OpenGL context from which to copy state

mask - a mask of symbolic names indicating which groups of state to copy

Throws:

GLException - if an OpenGL-related error occurred

getCurrentGL

public static GL getCurrentGL()
                       throws GLException

Returns the GL object bound to this thread current context. If no context is current, throw an GLException

Returns:

the current context's GL object on this thread

Throws:

GLException - if no context is current

getCurrent

public static GLContext getCurrent()

Returns this thread current context. If no context is current, returns null.

Returns:

the context current on this thread, or null if no context is current.

isCurrent

public final boolean isCurrent()

Returns:

true if this GLContext is current on this thread

validateCurrent

public final void validateCurrent()
                           throws GLException

Throws:

GLException - if this GLContext is not current on this thread

destroy

public abstract void destroy()

Destroys this OpenGL context and frees its associated resources. The context should have been released before this method is called.

isSynchronized

public abstract boolean isSynchronized()

Returns true if 'makeCurrent' will exhibit synchronized behavior.

setSynchronized

public abstract void setSynchronized(boolean isSynchronized)

Determines whether 'makeCurrent' will exhibit synchronized behavior.

getGL

public abstract GL getGL()

Returns the GL pipeline object for this GLContext.

Returns:

the aggregated GL instance, or null if this context was not yet made current.

setGL

public abstract GL setGL(GL gl)

Sets the GL pipeline object for this GLContext.

Returns:

the set GL pipeline or null if not successful

getHandle

public final long getHandle()

Returns the native GL context handle

isCreated

public final boolean isCreated()

Indicates whether the underlying OpenGL context has been created.

getAttachedObject

public final Object getAttachedObject(int name)

Returns the attached user object for the given name to this GLContext.

getAttachedObject

public final Object getAttachedObject(String name)

Returns the attached user object for the given name to this GLContext.

attachObject

public final Object attachObject(int name,
                                 Object obj)

Sets the attached user object for the given name to this GLContext. Returns the previously set object or null.

detachObject

public final Object detachObject(int name)

attachObject

public final Object attachObject(String name,
                                 Object obj)

Sets the attached user object for the given name to this GLContext. Returns the previously set object or null.

detachObject

public final Object detachObject(String name)

toString

public String toString()

Classname, GL, GLDrawable

Overrides:

toString in class Object

append

public final StringBuffer append(StringBuffer sb)

getPlatformExtensionsString

public abstract String getPlatformExtensionsString()

Returns a non-null (but possibly empty) string containing the space-separated list of available platform-dependent (e.g., WGL, GLX) extensions. Can only be called while this context is current.

getGLExtensionsString

public abstract String getGLExtensionsString()

Returns a non-null (but possibly empty) string containing the space-separated list of available extensions. Can only be called while this context is current. This is equivalent to glGetString(GL_EXTENSIONS)

getGLVersionMajor

public final int getGLVersionMajor()

getGLVersionMinor

public final int getGLVersionMinor()

isGLCompatibilityProfile

public final boolean isGLCompatibilityProfile()

isGLCoreProfile

public final boolean isGLCoreProfile()

isGLForwardCompatible

public final boolean isGLForwardCompatible()

isCreatedWithARBMethod

public final boolean isCreatedWithARBMethod()

getContextCreationFlags

public abstract int getContextCreationFlags()

Returns:

Additional context creation flags, supported: CTX_OPTION_DEBUG.

setContextCreationFlags

public abstract void setContextCreationFlags(int flags)

Parameters:

flags - Additional context creation flags, supported: CTX_OPTION_DEBUG. Unsupported flags are masked out. Only affects this context state if not created yet via makeCurrent().

See Also:

enableGLDebugMessage(boolean), GLAutoDrawable.setContextCreationFlags(int)

getGLVersion

public final String getGLVersion()

Returns a valid OpenGL version string, ie

     major.minor ([option]?[options,]*) - gl-version
 

• options
  • old refers to the non ARB_create_context created context
  • new refers to the ARB_create_context created context
  • compatible profile
  • core profile
  • forward compatible
  • any refers to the non forward compatible context
  • ES refers to the GLES context variant
• gl-version the GL_VERSION string

e.g.:

row 2, cell 1	row 2, cell 2

	ES2	2.0 (ES, any, new) - 2.0 ES Profile
ATI	GL2	3.0 (compatibility profile, any, new) - 3.2.9704 Compatibility Profile Context
ATI	GL3	3.3 (core profile, any, new) - 1.4 (3.2.9704 Compatibility Profile Context)
ATI	GL3bc	3.3 (compatibility profile, any, new) - 1.4 (3.2.9704 Compatibility Profile Context)
NV	GL2	3.0 (compatibility profile, any, new) - 3.0.0 NVIDIA 195.36.07.03
NV	GL3	3.3 (core profile, any, new) - 3.3.0 NVIDIA 195.36.07.03
NV	GL3bc	3.3 (compatibility profile, any, new) - 3.3.0 NVIDIA 195.36.07.03

isGL4bc

public final boolean isGL4bc()

isGL4

public final boolean isGL4()

isGL3bc

public final boolean isGL3bc()

isGL3

public final boolean isGL3()

isGL2

public final boolean isGL2()

isGL2GL3

public final boolean isGL2GL3()

isGLES1

public final boolean isGLES1()

isGLES2

public final boolean isGLES2()

isGLES

public final boolean isGLES()

isGL2ES1

public final boolean isGL2ES1()

isGL2ES2

public final boolean isGL2ES2()

isGLES2Compatible

public final boolean isGLES2Compatible()

Returns:

true if this context is an ES2 context or implements the extension GL_ARB_ES2_compatibility, otherwise false

hasGLSL

public final boolean hasGLSL()

setSwapInterval

public final void setSwapInterval(int interval)

getSwapInterval

public int getSwapInterval()

queryMaxSwapGroups

public final boolean queryMaxSwapGroups(int[] maxGroups,
                                        int maxGroups_offset,
                                        int[] maxBarriers,
                                        int maxBarriers_offset)

joinSwapGroup

public final boolean joinSwapGroup(int group)

getSwapGroup

public int getSwapGroup()

bindSwapBarrier

public final boolean bindSwapBarrier(int group,
                                     int barrier)

getGLDebugMessageExtension

public abstract String getGLDebugMessageExtension()

Returns:

The extension implementing the GLDebugOutput feature, either GL_ARB_debug_output or GL_AMD_debug_output. If unavailable or called before initialized via makeCurrent(), null is returned.

isGLDebugSynchronous

public abstract boolean isGLDebugSynchronous()

Returns:

the current synchronous debug behavior via

See Also:

#setSynchronous(boolean)

setGLDebugSynchronous

public abstract void setGLDebugSynchronous(boolean synchronous)

Enables or disables the synchronous debug behavior via glEnable/glDisable(GL_DEBUG_OUTPUT_SYNCHRONOUS_ARB), if extension is #GL_ARB_debug_output. There is no equivalent for #GL_AMD_debug_output.

The default is true, ie GL2GL3.GL_DEBUG_OUTPUT_SYNCHRONOUS_ARB.

isGLDebugMessageEnabled

public abstract boolean isGLDebugMessageEnabled()

Returns:

true if the GLDebugOutput feature is enabled or not.

enableGLDebugMessage

public abstract void enableGLDebugMessage(boolean enable)
                                   throws GLException

Enables or disables the GLDebugOutput feature of extension GL_ARB_debug_output or GL_AMD_debug_output, if available.

To enable the GLDebugOutput feature enableGLDebugMessage(true) or setContextCreationFlags(CTX_OPTION_DEBUG) shall be called before context creation via makeCurrent()!

In case GLAutoDrawable are being used, glAutoDrawable.setContextCreationFlags(CTX_OPTION_DEBUG) shall be issued before context creation via makeCurrent()!

After context creation, the GLDebugOutput feature may be enabled or disabled at any time using this method.

Parameters:

enable - If true enables, otherwise disables the GLDebugOutput feature.

Throws:

GLException - if this context is not current or GLDebugOutput registration failed (enable)

See Also:

setContextCreationFlags(int), addGLDebugListener(GLDebugListener), GLAutoDrawable.setContextCreationFlags(int)

addGLDebugListener

public abstract void addGLDebugListener(GLDebugListener listener)

Add GLDebugListener.

Parameters:

listener - GLDebugListener handling s

See Also:

enableGLDebugMessage(boolean), removeGLDebugListener(GLDebugListener)

removeGLDebugListener

public abstract void removeGLDebugListener(GLDebugListener listener)

Remove GLDebugListener.

Parameters:

listener - GLDebugListener handling s

See Also:

enableGLDebugMessage(boolean), addGLDebugListener(GLDebugListener)

glDebugMessageControl

public abstract void glDebugMessageControl(int source,
                                           int type,
                                           int severity,
                                           int count,
                                           IntBuffer ids,
                                           boolean enabled)

Generic entry for GL2GL3.glDebugMessageControlARB(int, int, int, int, IntBuffer, boolean) and GL2GL3.glDebugMessageEnableAMD(int, int, int, IntBuffer, boolean) of the GLDebugOutput feature.

See Also:

enableGLDebugMessage(boolean)

glDebugMessageControl

public abstract void glDebugMessageControl(int source,
                                           int type,
                                           int severity,
                                           int count,
                                           int[] ids,
                                           int ids_offset,
                                           boolean enabled)

Generic entry for GL2GL3.glDebugMessageControlARB(int, int, int, int, int[], int, boolean) and GL2GL3.glDebugMessageEnableAMD(int, int, int, int[], int, boolean) of the GLDebugOutput feature.

See Also:

enableGLDebugMessage(boolean)

glDebugMessageInsert

public abstract void glDebugMessageInsert(int source,
                                          int type,
                                          int id,
                                          int severity,
                                          String buf)

Generic entry for GL2GL3.glDebugMessageInsertARB(int, int, int, int, int, String) and GL2GL3.glDebugMessageInsertAMD(int, int, int, int, String) of the GLDebugOutput feature.

See Also:

enableGLDebugMessage(boolean)

getMaxMajor

public static final int getMaxMajor()

getMaxMinor

public static final int getMaxMinor(int major)

isValidGLVersion

public static final boolean isValidGLVersion(int major,
                                             int minor)

decrementGLVersion

public static final boolean decrementGLVersion(int[] major,
                                               int[] minor)

isGLVersionAvailable

public static boolean isGLVersionAvailable(AbstractGraphicsDevice device,
                                           int major,
                                           int profile)

Parameters:

major - Key Value either 1, 2, 3 or 4

profile - Key Value either CTX_PROFILE_COMPAT, CTX_PROFILE_CORE or CTX_PROFILE_ES

isGLES1Available

public static boolean isGLES1Available(AbstractGraphicsDevice device)

isGLES2Available

public static boolean isGLES2Available(AbstractGraphicsDevice device)

isGL4bcAvailable

public static boolean isGL4bcAvailable(AbstractGraphicsDevice device)

isGL4Available

public static boolean isGL4Available(AbstractGraphicsDevice device)

isGL3bcAvailable

public static boolean isGL3bcAvailable(AbstractGraphicsDevice device)

isGL3Available

public static boolean isGL3Available(AbstractGraphicsDevice device)

isGL2Available

public static boolean isGL2Available(AbstractGraphicsDevice device)

getAvailableGLVersionAsString

public static String getAvailableGLVersionAsString(AbstractGraphicsDevice device,
                                                   int major,
                                                   int profile)

Parameters:

major - Key Value either 1, 2, 3 or 4

profile - Key Value either CTX_PROFILE_COMPAT, CTX_PROFILE_CORE or CTX_PROFILE_ES

getGLVersion

public static String getGLVersion(int major,
                                  int minor,
                                  int ctp,
                                  String gl_version)