Open Inventor Release 2024.1.0
 
Loading...
Searching...
No Matches
SoGLContext Class Reference

VSG extension OpenGL context management class. More...

#include <Inventor/devices/SoGLContext.h>

+ Inheritance diagram for SoGLContext:

Public Types

enum  SharedGroupPolicy {
  DISABLED ,
  CONSERVATIVE ,
  AGGRESSIVE
}
 Sharing Policy. More...
 
typedef SbGlContextHelper::Display SharedGroupDescription
 Returns an SoGLContext that matches the specified SharedGroupDescription.
 

Public Member Functions

 SoGLContext (bool shared)
 Constructor which creates an SoGLContext based on the attributes of the current context.
 
 SoGLContext (SbGlContextHelper::Display dpy, SbGlContextHelper::VisualInfo vis, SbGlContextHelper::Drawable drawable, SbGlContextHelper::GLContext ctx)
 Constructor which creates an SoGLContext based on the specifed parameters.
 
 SoGLContext (const SoGLFormat &format, SbGlContextHelper::GLContext ctx, SbGlContextHelper::Drawable drawable=0)
 Constructor which creates a SoGLContext based on the specified parameters.
 
 SoGLContext (const SoGLFormat &format, SbGlContextHelper::Drawable drawable=0)
 Constructor which creates a SoGLContext based on the specifed format.
 
 SoGLContext (SbGlContextHelper::Display dpy, SbGlContextHelper::VisualInfo vis, SbGlContextHelper::Drawable drawable, bool shared=true)
 Constructor which creates a SoGLContext based on the specified parameters.
 
 SoGLContext (SoGLContext *context, bool shared)
 Constructor which creates an SoGLContext based on the attributes of the specified context.
 
 SoGLContext (SoGLContext *context, const SoGLFormat &format, SbGlContextHelper::Drawable drawable=0)
 Constructor which creates a SoGLContext shared with a specific context, but attached to the display specified in the SoGLFormat.
 
virtual void bind ()
 Bind the OpenGL context to the current thread.
 
virtual bool tryBind ()
 Try to bind the OpenGL context to the current thread.
 
virtual void unbind ()
 Unbind the OpenGL context from the current thread.
 
bool isSharedWith (const SoDeviceContext *context) const
 Returns true if the specified context and this context are shared.
 
virtual bool isValid () const
 Returns true if this context is valid.
 
void invalidate ()
 Set this context as invalid so it won't be used anymore.
 
int getId () const
 Returns the internal id for this context.
 
virtual bool isCompatible (SoDeviceContext *context) const
 Returns true if the specified context and this one are compatible.
 
virtual bool isCurrent () const
 Returns true if this context is valid and currently active.
 
const SbGlContextHelper::GLContextgetGLContext () const
 Returns the OpenGL rendering context of this SoGLContext.
 
const SbGlContextHelper::DisplaygetDisplay () const
 Returns the Display of this SoGLContext.
 
const SbGlContextHelper::VisualInfogetVisualInfo () const
 Returns the VisualInfo of this SoGLContext.
 
const SoGLFormatgetFormat () const
 Returns the SoGLFormat associated to the SoGLContext.
 
bool isValidForCurrent () const
 Returns true if the context is the current active context or if it is shared with the current active context.
 
void assertContext () const
 Assert this context and the current active context are the same.
 
bool swapBuffers ()
 Swaps the buffers with the value stored in the SoGLFormat, which is set to the main plane by default.
 
SbStringList getSupportedExtensions ()
 Returns an SbString containing the supported extensions for this context.
 
void setNoGLContextDelete ()
 Prevent deletion of the native OpenGL context by SoGLContext.
 
const SbGPUCapabilitiesgetContextGraphicsCapabilities ()
 Retrieve graphics capabilities from this context.
 
- Public Member Functions inherited from SoDeviceContext
 SoDeviceContext ()
 Default constructor.
 
void setSharable (bool sharable)
 Sets the sharable property.
 
bool isSharable () const
 Returns the sharable status of this context.
 
virtual int getSharedId () const
 Returns an id common to all compatible/shared contexts.
 
SoDeviceContextSharedGroupgetSharedGroup () const
 Returns the current shared group.
 
bool setSharedGroup (SoDeviceContextSharedGroup *sharedGroup)
 Explicitly change the sharedGroup.
 
- Public Member Functions inherited from SoRefCounter
void ref () const
 Adds a reference to an instance.
 
void unref () const
 Removes a reference from an instance.
 
void unrefNoDelete () const
 unrefNoDelete() should be called when it is desired to decrement the reference count, but not delete the instance if this brings the reference count to zero.
 
int getRefCount () const
 Returns current reference count.
 
void lock () const
 lock this instance.
 
void unlock () const
 unlock this instance.
 

Static Public Member Functions

static SoGLContextgetCurrent (bool checkGLState=false)
 Returns the current active OpenGL context (if any).
 
static SoGLContextfindGLContext (SbGlContextHelper::GLContext)
 Returns the first SoGLContext associated with the specified OpenGL context.
 
static SoGLContextfindSharedContext (SharedGroupDescription)
 
static SoGLContextgetContextFromId (int id)
 Returns the context corresponding to an internal id.
 
static SoGLContextgetContextFromSharedId (int sharedIdGroup)
 Returns the first context that belongs to the specified sharedIdGroup.
 
static SharedGroupPolicy getSharedGroupPolicy ()
 Returns the current sharedGroupPolicy.
 
static const SbGPUCapabilitiesgetGraphicsCapabilities ()
 Retrieve graphics capabilities from the current bound context, if any.
 

Detailed Description

VSG extension 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 SoGpuBufferObject, 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:

SoRef<SoGLContext> glContext = new SoGLContext(true);
glContext->bind();
glContext->unbind();
<a href="IconLegend.html"><img src="extTGS.gif" alt="VSG extension" border="0"></a> OpenGL context m...
<a href="IconLegend.html"><img src="extTGS.gif" alt="VSG extension" border="0"></a> GPU buffer objec...
@ STATIC
The application will set the data once.
@ SHARED
The application will be writing data to the buffer, but will not read it.
Smart pointer for any class inheriting SoRefCounter.
Definition SoRef.h:90

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();
virtual void bind()
Bind the OpenGL context to the current thread.
static SoGLContext * getCurrent(bool checkGLState=false)
Returns the current active OpenGL context (if any).
void setNoGLContextDelete()
Prevent deletion of the native OpenGL context by SoGLContext.

Reference counting:

Definition at line 184 of file SoGLContext.h.

Member Typedef Documentation

◆ SharedGroupDescription

Returns an SoGLContext that matches the specified SharedGroupDescription.

On Windows, SharedGroupDescription is a PixelFormat id.
On Unix, SharedGroupDescription is a display pointer.

Definition at line 404 of file SoGLContext.h.

Member Enumeration Documentation

◆ SharedGroupPolicy

Sharing Policy.


User can change sharing policy by defining the OIV_SHARE_LISTS environment variable.

Enumerator
DISABLED 

Disables context sharing (same behavior as v2.6 and older)

CONSERVATIVE 

Conservative sharing (not available on Unix)
Only add context to a share group containing contexts with the constraint (ex: same pixel format for SoGLContext objects).

This mode matchs the official behavior of the wglShareLists() function. (Please refer to Microsoft documentation for more details.)

AGGRESSIVE 

Aggressive sharing (default)
Tries to share contexts, independent of their sharing constraint.

When sharing succeeds, shared contexts are part of the same sharedGroup, else, a new sharedGroup is created.

Definition at line 192 of file SoGLContext.h.

Constructor & Destructor Documentation

◆ SoGLContext() [1/7]

SoGLContext::SoGLContext ( bool  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
sharedIndicates 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() [2/7]

Constructor which creates an SoGLContext based on the specifed parameters.

On Microsoft Windows platforms the Display, VisualInfo and GLContext parameters cannot be NULL.
On Linux platforms the Display, Drawable, VisualInfo and GLContext parameters cannot be NULL.
On Mac platforms the Drawable, VisualInfo and GLContext parameters cannot be NULL.
Display is equal to zero for the first display, 1 for the second, ...

◆ SoGLContext() [3/7]

SoGLContext::SoGLContext ( const SoGLFormat format,
SbGlContextHelper::GLContext  ctx,
SbGlContextHelper::Drawable  drawable = 0 
)

Constructor which creates a SoGLContext based on the specified parameters.

The specified format must have been acticated before using it with this contructor. The GLContext paramater cannot be NULL as long as this constructor is not supposed to create an OpenGL context but use an existing one. If the constructor must create a context, you must use the constructor which takes only a SoGLFormat or the one which takes a SoGLContext and a SoGLFormat.

◆ SoGLContext() [4/7]

SoGLContext::SoGLContext ( const SoGLFormat format,
SbGlContextHelper::Drawable  drawable = 0 
)

Constructor which creates a SoGLContext based on the specifed format.


Note: Context will be shared with other contexts, depending on the currently defined SharedGroupPolicy

The specified format must have been activated before using it with this contructor.

◆ SoGLContext() [5/7]

SoGLContext::SoGLContext ( SbGlContextHelper::Display  dpy,
SbGlContextHelper::VisualInfo  vis,
SbGlContextHelper::Drawable  drawable,
bool  shared = true 
)

Constructor which creates a SoGLContext based on the specified parameters.


Note: Context will be shared with other contexts, depending on the currently defined SharedGroupPolicy.

On Microsoft Windows platforms the Display and VisualInfo parameters cannot be NULL.
On Linux platforms the Display, Drawable and VisualInfo parameters cannot be NULL.
On Mac platforms the Drawable and VisualInfo parameters cannot be NULL.
Display is equal to zero for the first display, 1 for the second, ...

Parameters
dpyThe display/device context.
visThe visual/pixel format descriptor for the rendering context.
drawableThe drawable (must be null under Windows).
sharedIndicates if we want to share the context. If TRUE, context is shared with one of the already created contexts, depending on the currently defined SharedGroupPolicy. If FALSE, context is explicitly not shared.

◆ SoGLContext() [6/7]

SoGLContext::SoGLContext ( SoGLContext context,
bool  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.

◆ SoGLContext() [7/7]

SoGLContext::SoGLContext ( SoGLContext context,
const SoGLFormat format,
SbGlContextHelper::Drawable  drawable = 0 
)

Constructor which creates a SoGLContext shared with a specific context, but attached to the display specified in the SoGLFormat.

Parameters
contextThe SoGLContext to be share with. Cannot be NULL.
formatThe format used for the drawable used by the new context.
drawableThe drawable on which the context is created. Use the one from the context parameter if NULL is provided.

Member Function Documentation

◆ assertContext()

void SoGLContext::assertContext ( ) const

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

◆ bind()

virtual void SoGLContext::bind ( )
virtual

Bind the OpenGL context to the current thread.

This call should be followed by a call to unbind() once the context is no longer used.

Implements SoDeviceContext.

◆ findGLContext()

static SoGLContext * SoGLContext::findGLContext ( SbGlContextHelper::GLContext  )
static

Returns the first SoGLContext associated with the specified OpenGL context.

Returns
The found SoGLContext or NULL if none found.

◆ findSharedContext()

static SoGLContext * SoGLContext::findSharedContext ( SharedGroupDescription  )
static

◆ getContextFromId()

static SoGLContext * SoGLContext::getContextFromId ( int  id)
static

Returns the context corresponding to an internal id.

Parameters
idThe internal id used to search for the context.
Returns
The context which has the specified id.

◆ getContextFromSharedId()

static SoGLContext * SoGLContext::getContextFromSharedId ( int  sharedIdGroup)
static

Returns the first context that belongs to the specified sharedIdGroup.

Parameters
sharedIdGroupThe internal sharedIdGroup used to search for the context.
Returns
The first context that belongs to the specified sharedIdGroup.

◆ getContextGraphicsCapabilities()

const SbGPUCapabilities & SoGLContext::getContextGraphicsCapabilities ( )

Retrieve graphics capabilities from this context.

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

◆ getCurrent()

static SoGLContext * SoGLContext::getCurrent ( bool  checkGLState = false)
static

Returns the current active OpenGL context (if any).

This method returns the current active OpenGL context from the Open Inventor state. However it can also get the actual current context from OpenGL. It may be useful if Open Inventor should render using an OpenGL context created by the application or a third-party library. In that case, Open Inventor will create a new SoGLContext using contextId returned by system getCurrentContext() method.

Parameters
checkGLStateThis param is no longer used.
Returns
The current OpenGL context (or NULL if there isn't one).

◆ getDisplay()

const SbGlContextHelper::Display & SoGLContext::getDisplay ( ) const

Returns the Display of this SoGLContext.

Returns
The Display.

◆ getFormat()

const SoGLFormat & SoGLContext::getFormat ( ) const

Returns the SoGLFormat associated to the SoGLContext.

Returns
the SoGLFormat.

◆ getGLContext()

const SbGlContextHelper::GLContext & SoGLContext::getGLContext ( ) const

Returns the OpenGL rendering context of this SoGLContext.

Returns
The OpenGL rendering context.

◆ getGraphicsCapabilities()

static const SbGPUCapabilities & SoGLContext::getGraphicsCapabilities ( )
static

Retrieve graphics capabilities from the current bound context, if any.

A tempory context is created with default values if no context is bound.

◆ getId()

int SoGLContext::getId ( ) const

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.

◆ getSharedGroupPolicy()

static SharedGroupPolicy SoGLContext::getSharedGroupPolicy ( )
static

Returns the current sharedGroupPolicy.

◆ getSupportedExtensions()

SbStringList SoGLContext::getSupportedExtensions ( )

Returns an SbString containing the supported extensions for this context.

Note: SbStringList is a list of pointers, not a list of objects, so the destructor for this class does not free the memory associated with the SbString objects. The application is responsible for deleting each object in the list.

◆ getVisualInfo()

const SbGlContextHelper::VisualInfo & SoGLContext::getVisualInfo ( ) const

Returns the VisualInfo of this SoGLContext.

Returns
The VisualInfo.

◆ invalidate()

void SoGLContext::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...).

◆ isCompatible()

virtual bool SoGLContext::isCompatible ( SoDeviceContext context) const
virtual

Returns true if the specified context and this one are compatible.

Compatible means that using a buffer from one of these contexts inside the other will not require copying the data. If two OpenGL contexts are compatible, they either have the same id or they are shared.

Parameters
contextThe context to compare with this one.
Returns
True if the specified context is compatible with this one.

Implements SoDeviceContext.

◆ isCurrent()

virtual bool SoGLContext::isCurrent ( ) const
virtual

Returns true if this context is valid and currently active.

If the current context is shared with this context then it returns true.

Implements SoDeviceContext.

◆ isSharedWith()

bool SoGLContext::isSharedWith ( const SoDeviceContext context) const
virtual

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

Returns
true if the two contexts are shared.

Reimplemented from SoDeviceContext.

◆ isValid()

virtual bool SoGLContext::isValid ( ) const
virtual

Returns true if this context is valid.

Returns
true if the context is valid.

Reimplemented from SoDeviceContext.

◆ isValidForCurrent()

bool SoGLContext::isValidForCurrent ( ) const

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

◆ setNoGLContextDelete()

void SoGLContext::setNoGLContextDelete ( )
inline

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

Definition at line 481 of file SoGLContext.h.

◆ swapBuffers()

bool SoGLContext::swapBuffers ( )

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

◆ tryBind()

virtual bool SoGLContext::tryBind ( )
virtual

Try to bind the OpenGL context to the current thread.


Returns false if already bound, else calls bind() and returns true.

◆ unbind()

virtual void SoGLContext::unbind ( )
virtual

Unbind the OpenGL context from the current thread.

Implements SoDeviceContext.


The documentation for this class was generated from the following file: