com.hermetica.magician
Class GLContext

java.lang.Object
  |
  +--com.hermetica.magician.GLContext

public class GLContext

extends java.lang.Object

This class encapsulates an OpenGL rendering context. This object is associated with a drawing surface, beit and X Widget or Win32 HDC which funnels all OpenGL calls onto that surface. Each rendering context has a set of ``capabilities'' associated with it which are used to select the most apt device context to render onto. After the context successfully acquires a device to render to, the capabilities may not be changed.

Version:

$Revision: 1.2 $

Author:

Alligator Descartes <descarte@hermetica.com>

See Also:

GLComponent, GLCapabilities

Field Summary

static java.lang.String

VERSION Version information

Constructor Summary

GLContext()
Default context constructor.

GLContext(boolean mode)
Context constructor with the locking trace level specified.

GLContext(GLCapabilities capabilities)
Context constructor using a previously prepared set of capabilities.

GLContext(GLCapabilities capabilities, boolean mode)
Context constructor with the locking trace level specified as well as a non-default set of context capabilities.

Method Summary

boolean	createContext(GLDrawable component) Checks to see whether or not a context is created
void	destroy() Destroys the context and frees any resources associated with it.
void	destroyContext() Deprecated. This method has been deprecated in favour of ``destroy()''. It will be removed as of beta 4 or a final release of Magician
GLCapabilities	getCapabilities() Returns the GLCapabilities object associated with this context
GLComponent	getComponent() Returns the GLComponent associated with this context
static GLContext	getCurrentContext() Returns the current GLContext in OpenGL, if one exists
static boolean	getTraceStatus() Returns the current tracing status
boolean	isInitialized() Returns the current initialization status of the context
static void	lock() Locks the OpenGL context for exclusive use.
void	makeCurrent() Makes this context the current one within the OpenGL state machine
void	setCapabilities(GLCapabilities capability) Sets the capabilities of this context to a brand-new object.
protected void	setComponent(GLDrawable component) Sets the GLComponent associated with this context
static void	setTraceStatus(boolean mode) Sets the tracing level of the context lock.
void	swapBuffers() Swaps the buffers of a context, if double-buffering is used
void	swapBuffers(GLDrawable drawable) Swaps the buffer ( typically offscreen ) onto the given drawable
static void	unlock() Releases the OpenGL context for use elsewhere.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERSION

public static final java.lang.String VERSION

Version information

Constructor Detail

GLContext

public GLContext()

Default context constructor. This has a default set of capabilities that is probably unsuitable for all visuals!

See Also:

GLCapabilities

GLContext

public GLContext(GLCapabilities capabilities)

Context constructor using a previously prepared set of capabilities. The capability object being used is actually cloned not pointed to. This means that the same capability can be used to initialize multiple rendering contexts, instead of being indirectly locked after the first rendering context creation succeeds.

See Also:

GLCapabilities

GLContext

public GLContext(boolean mode)

Context constructor with the locking trace level specified. This constructor uses a default set of capabilities that should be configured to suit your target visual capabilities.

Parameters:

mode - Lock tracing mode.

GLContext

public GLContext(GLCapabilities capabilities,
                 boolean mode)

Context constructor with the locking trace level specified as well as a non-default set of context capabilities.

Parameters:

capabilities - The configured capabilities for this context

mode - The context lock tracing level

Method Detail

isInitialized

public boolean isInitialized()

Returns the current initialization status of the context

setTraceStatus

public static void setTraceStatus(boolean mode)

Sets the tracing level of the context lock.

getTraceStatus

public static boolean getTraceStatus()

Returns the current tracing status

getCurrentContext

public static GLContext getCurrentContext()

Returns the current GLContext in OpenGL, if one exists

setComponent

protected void setComponent(GLDrawable component)

Sets the GLComponent associated with this context

getComponent

public GLComponent getComponent()

Returns the GLComponent associated with this context

createContext

public boolean createContext(GLDrawable component)

Checks to see whether or not a context is created

destroyContext

public void destroyContext()
                    throws GLContextException

Deprecated. This method has been deprecated in favour of ``destroy()''. It will be removed as of beta 4 or a final release of Magician

Destroys the context and frees any resources associated with it

Parameters:

component - A GLComponent associated with this context

Throws:

GLContextException - GL context exception

See Also:

destroy()

destroy

public void destroy()
             throws GLContextException

Destroys the context and frees any resources associated with it. This method replaces ``destroyContext()''

Parameters:

component - A GLComponent associated with this context

Throws:

GLContextException - GL context exception

See Also:

destroyContext()

lock

public static final void lock()

Locks the OpenGL context for exclusive use. This is generally done internally, but in some cases developers may wish to enforce synchronization.

unlock

public static final void unlock()

Releases the OpenGL context for use elsewhere. This essentially unlocks the mutex on this object. This is a potentially destructive operation unless you can guarantee no other OpenGL activity is occurring within your program when you make this call, eg, you are simply initializing the frustrum or somesuch. If you unlock the mutex during heavy multi-threaded OpenGL activity, there is a possibility that critical sections of code will not be respected and context cross-over may occur.

makeCurrent

public void makeCurrent()
                 throws GLContextException

Makes this context the current one within the OpenGL state machine

swapBuffers

public void swapBuffers()
                 throws GLContextException

Swaps the buffers of a context, if double-buffering is used

swapBuffers

public void swapBuffers(GLDrawable drawable)

Swaps the buffer ( typically offscreen ) onto the given drawable

getCapabilities

public GLCapabilities getCapabilities()

Returns the GLCapabilities object associated with this context

See Also:

GLCapabilities

setCapabilities

public void setCapabilities(GLCapabilities capability)

Sets the capabilities of this context to a brand-new object. This is not actually possible if the capabilities object already associated with this context is locked, ie, the context is already created.

See Also:

GLCapabilities