com.openinventor.inventor.devices

Class SoGLContext

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.devices.SoDeviceContext

com.openinventor.inventor.devices.SoGLContext

All Implemented Interfaces:

SafeDisposable

public class SoGLContext
extends SoDeviceContext

OpenGL context management class. This class provides functions to manage OpenGL device contexts.

Starting with Open Inventor 8.5, the application can control sharing of OpenGL contexts (previously this was done internally for rendering contexts). When OpenGL contexts are shared it means that display lists, texture objects, buffer objects, etc created in any context in that share group can be used by any other context in that group. This saves time and memory when rendering into multiple windows, buffers, etc.

In a typical Open Inventor application an OpenGL device context is created automatically by the viewer class and is managed automatically by the viewer for rendering and other operations involving the GPU. However this context is only made current when the viewer is actively using it, for example to render the scene graph. (Prior to Open Inventor 8.5, the viewer made its OpenGL context "current" and this context remained current even when the viewer was not actively rendering the scene graph. This was convenient in some cases, but could conflict with application strategies for managing OpenGL contexts.)

Do not assume that any OpenGL context is current. If you need a current OpenGL context, for example to create an SoGLBufferObject, bind() and unbind() an SoGLContext object.

If your application uses an Open Inventor viewer, the viewer's rendering context can be made current using the viewer's bindNormalContext() method and released using the viewer's unbindNormalContext() method. This context can also be queried using the viewer's getNormalSoContext() method.

If you do not have (or do not have access to) a viewer, you can create a context by creating an SoGLContext object. In almost all cases, calling the constructor with a true value will create a context that is in a share group with the rendering context. In other words, resources such as textures and buffer objects are shared between these contexts and can be used in any of the contexts in the share group. For example:

 SoGLContext glContext = new SoGLContext( true );
 glContext.bind();
     SoGLBufferObject gpuBuffer = new SoGLBufferObject( SoGLBufferObject.Usages.STATIC_DRAW );
     gpuBuffer.setTarget( SoGLBufferObject.BufferObjectTargets.ARRAY_BUFFER );
 glContext.unbind();

If the OpenGL context is created and managed by the application or a third- party library, the application should create an SoGLContext object to wrap the actual current context, then bind() and unbind() this object around the Open Inventor render call. Note that this method will return null if there is no current OpenGL context. Also note that the SoGLContext object should be told not to manage (specifically not to delete) the OpenGL context since its lifespan is managed by other software. For example:

 if (context != null)
     context.setNoGLContextDelete(); // Context is managed by someone else
 else
     context = new SoGLContext( true );
 context.bind();
     . . .
 context.unbind();

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SoGLContext.SharedGroupPolicies Sharing Policy.

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Inventor.ConstructorCommand

Field Summary

Fields

Modifier and Type	Field and Description
static int	AGGRESSIVE Deprecated. Use SoGLContext.SharedGroupPolicies.AGGRESSIVE instead.
static int	CONSERVATIVE Deprecated. Use SoGLContext.SharedGroupPolicies.CONSERVATIVE instead.
static int	DISABLED Deprecated. Use SoGLContext.SharedGroupPolicies.DISABLED instead.

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

Constructor and Description
SoGLContext(boolean shared) Constructor which creates an SoGLContext based on the attributes of the current context.
SoGLContext(SoGLContext context, boolean shared) Constructor which creates an SoGLContext based on the attributes of the specified context.

Method Summary

Modifier and Type	Method and Description
void	applySharedGroupPolicy() Deprecated. As of Open Inventor 9630 See documentation for more details
void	assertContext() Assert this context and the current active context are the same.
static SoGLContext	getContextFromId(int id) Returns the context corresponding to an internal id.
static SoGLContext	getContextFromSharedId(int sharedIdGroup) Returns the first context that belongs to the specified sharedIdGroup.
SbGPUCapabilities	getContextGraphicsCapabilities() Retrieve graphics capabilities from this context.
static SoGLContext	getCurrent() Calls getCurrent((boolean)false).
static SoGLContext	getCurrent(boolean checkGLState) Returns the current active OpenGL context (if any).
SoGLFormat	getFormat() Returns the SoGLFormat associated to the SoGLContext.
static SbGPUCapabilities	getGraphicsCapabilities() Retrieve graphics capabilities from the current bound context, if any.
int	getId() Returns the internal id for this context.
static SoGLContext.SharedGroupPolicies	getSharedGroupPolicy() Returns the current sharedGroupPolicy.
void	invalidate() Set this context as invalid so it won't be used anymore.
boolean	isSharedWith(SoGLContext context) Returns true if the specified context and this context are shared.
boolean	isValid() Returns true if this context is valid.
boolean	isValidForCurrent() Returns true if the context is the current active context or if it is shared with the current active context.
void	setNoGLContextDelete() Prevent deletion of the native OpenGL context by SoGLContext.
boolean	swapBuffers() Swaps the buffers with the value stored in the SoGLFormat, which is set to the main plane by default.
boolean	swapBuffers(int plane) Deprecated. As of Open Inventor 9610 See documentation for more details
boolean	tryBind() Try to bind the OpenGL context to the current thread.

Methods inherited from class com.openinventor.inventor.devices.SoDeviceContext

bind, dispose, getSharedGroup, getSharedId, isCompatible, isCurrent, isDisposable, isSharable, isSharedWith, setSharable, setSharedGroup, setSharedWith, unbind

Methods inherited from class com.openinventor.inventor.Inventor

getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object

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

Field Detail

DISABLED

@Deprecated
public static final int DISABLED

Deprecated. Use SoGLContext.SharedGroupPolicies.DISABLED instead.

CONSERVATIVE

@Deprecated
public static final int CONSERVATIVE

Deprecated. Use SoGLContext.SharedGroupPolicies.CONSERVATIVE instead.

AGGRESSIVE

@Deprecated
public static final int AGGRESSIVE

Deprecated. Use SoGLContext.SharedGroupPolicies.AGGRESSIVE instead.

Constructor Detail

SoGLContext

public SoGLContext(boolean shared)

Constructor which creates an SoGLContext based on the attributes of the current context.
If the current context is NULL, the function tries to create a context on a temporary window. If this doesn't work, the resulting SoGLContext will not be valid!

Parameters:

shared - Indicates if we want to share the context. If true, context is shared with current context, depending on the currently defined SharedGroupPolicy. If false, context is explicitly not shared.

SoGLContext

public SoGLContext(SoGLContext context,
                   boolean shared)

Constructor which creates an SoGLContext based on the attributes of the specified context. If shared is true then the created OpenGL context will be shared with the given context, depending on the current SharedGroupPolicy.

Method Detail

getCurrent

public static SoGLContext getCurrent()

Calls getCurrent((boolean)false).

applySharedGroupPolicy

@Deprecated
public void applySharedGroupPolicy()

Deprecated. As of Open Inventor 9630 See documentation for more details

Force the context to be shared following the current SharedPolicy. Deprecated since Open Inventor 9630
Please use new SoGLContext(SoGLContext.findSharedContext()) instead.

isSharedWith

public boolean isSharedWith(SoGLContext context)

Returns true if the specified context and this context are shared.

Returns:

true if the two contexts are shared.

tryBind

public boolean tryBind()

Try to bind the OpenGL context to the current thread.
Returns false if already bound, else calls bind() and returns true.

setNoGLContextDelete

public void setNoGLContextDelete()

Prevent deletion of the native OpenGL context by SoGLContext.

Note: Can be useful when the OpenGL context is created and managed by the application or a third-party library such as wxWidgets.

getContextGraphicsCapabilities

public SbGPUCapabilities getContextGraphicsCapabilities()

Retrieve graphics capabilities from this context. Make sure that this context is valid, otherwise capabilities will be wrong.

getCurrent

public static SoGLContext getCurrent(boolean checkGLState)

Returns the current active OpenGL context (if any). By default this method returns the current active OpenGL context from the Open Inventor state. However it can also be used to get the actual current context from OpenGL, by passing true for the checkGLState parameter. In a typical Open Inventor application this is not necessary. It may be useful if Open Inventor should render using an OpenGL context created by the application or a third-party library.

Parameters:

checkGLState - If this parameter is true, the getCurrent() function checks if the actual OpenGL context is the same as the one Open Inventor thinks is current. If the actual OpenGL context is different, for example because Open Inventor does not have a current context, then a new SoGLContext object is created with the actual OpenGL context. This check is expensive if called many times.

Returns:

The current OpenGL context (or NULL if there isn't one).

getSharedGroupPolicy

public static SoGLContext.SharedGroupPolicies getSharedGroupPolicy()

Returns the current sharedGroupPolicy.

isValidForCurrent

public boolean isValidForCurrent()

Returns true if the context is the current active context or if it is shared with the current active context.

getFormat

public SoGLFormat getFormat()

Returns the SoGLFormat associated to the SoGLContext.

Returns:

the SoGLFormat.

assertContext

public void assertContext()

Assert this context and the current active context are the same.

getGraphicsCapabilities

public static SbGPUCapabilities getGraphicsCapabilities()

Retrieve graphics capabilities from the current bound context, if any. A tempory context is created with default values if no context is bound.

swapBuffers

@Deprecated
public boolean swapBuffers(int plane)

Deprecated. As of Open Inventor 9610 See documentation for more details

Swaps the buffers for the desired plane. -1 Uses the value stored in the SoGLFormat, which is set to the main plane by default. 0 If there is an overlay context and we want to swap the main plane 1 If there is an overlay context and we want to swap the overlay planeDeprecated since Open Inventor 9610
Overlay feature is legacy, and no longer makes sense with current hardware. Use swapBuffers() method without arguments instead.

getId

public int getId()

Returns the internal id for this context. The internal id is unique, it's not possible to get two contexts with the same id.

Returns:

The internal id of the context.

invalidate

public void invalidate()

Set this context as invalid so it won't be used anymore. This is mainly useful when the SoGLContext has been created from an OpenGL context managed by the application or a third-party library (e.g.: Qt, JOGL...).

isValid

public boolean isValid()

Returns true if this context is valid.

Returns:

true if the context is valid.

swapBuffers

public boolean swapBuffers()

Swaps the buffers with the value stored in the SoGLFormat, which is set to the main plane by default.

getContextFromSharedId

public static SoGLContext getContextFromSharedId(int sharedIdGroup)

Returns the first context that belongs to the specified sharedIdGroup.

Parameters:

sharedIdGroup - The internal sharedIdGroup used to search for the context.

Returns:

The first context that belongs to the specified sharedIdGroup.

getContextFromId

public static SoGLContext getContextFromId(int id)

Returns the context corresponding to an internal id.

Parameters:

id - The internal id used to search for the context.

Returns:

The context which has the specified id.