OpenGLContext.context
Abstract base class for all rendering contexts
OpenGL operates with the idea of a current context
in which OpenGL calls will operate. This is something
a little bit more than a "window", as it includes
a number of (optional) off-screen buffers, and
a great deal of state which is manipulated by the
various OpenGL functions. (OpenGL is basically a huge
state machine).
The Context in OpenGLContext is your basic interface
to the context, and simple operation of OpenGLContext
(such as that you'll see in most of the test scripts)
can focus almost entirely on the Context object and
its various customization points.
If you wish to use the scene graph facilities of
OpenGLContext, look particularly at the abstract
function getSceneGraph, which can be overridden to
provide a particular scenegraph object to the renderer.
SceneGraph objects provide their own light, background,
and render-traversal mechanisms, which allow you to
largely ignore the Context objects.
The bulk of the actual rendering work is done by the
Visitor and RenderVisitor classes (or their shadow-
enabled equivalents from shadow.passes), and it is
these classes which define the rendering callbacks
which are available from the Context class.
Functions
getCurrentContext(
)
Get the currently-rendering context
This function allows code running during the render cycle
to determine the current context. As a general rule, the
context is available as rendermode.context from the render
mode/pass which is passed to the rendering functions as an
argument.
Note: this function is deprecated, use the passed rendering
mode/pass's context attribute instead.
Classes
Abstract base class on which all Rendering Contexts are based
The Context object represents a single rendering context
for use by the application. This base class provides only
the most rudimentary of application support, but sub-classes
provide such things as navigation, and/or event handling.
Attributes:
- sg
- OpenGLContext.basenodes.sceneGraph; the root of the node-rendering tree. If not NULL, is used to control most aspects of the rendering process. See: getSceneGraph
- renderPasses
- callable object, normally an instance of OpenGLContext.passes.renderpass.PassSet which implements the rendering algorithm for the Context
- alreadyDrawn
- flag which is set/checked to determine whether the context needs to be redrawn, see: Context.triggerRedraw( ... ) Context.shouldRedraw( ... ) Context.suppressRedraw( ... ) for the API to use to interact with this attribute.
- viewportDimensions
- Storage for the current viewport dimensions, see: Context.Viewport( ... ) Context.getViewport( ... ) for the API used to interact with this attribute.
- drawPollTimeout
- default timeout for the drawPoll method
- currentContext
- class attribute pointing to the currently rendering Context instance. This allows code called during a Render-pass to access the Context object.
Note: wherever possible, use the passed render-pass's
"context" attribute, rather than this class attribute.
If that isn't possible, use the deprecated
getCurrentContext function in this module.
- allContexts
- list of weak references to all instantiated Context objects, mostly of use for code which wants to refresh all contexts when shared resources/states are updated
- drawing
- flag set to indicate that this Context is currently drawing, mostly used internally
- frameCounter
- node, normally a framecounter.FrameCounter instance which is used to track frame rates, must have an addFrame method as seen in framecounter.FrameCounter, See setupFrameRateCounter
- extensions
- extensionmanager.ExtensionManager instance with which to find and initialise extensions for this context. See setupExtensionManager
- cache
- vrml.cache.Cache instance used for optimising the rendering of scenegraphs. See setupCache
- redrawRequest
- threading Event for triggering a request
- scenegraphLock
- threading Lock for blocking rendering from re-entering during a rendering pass
- pickEvents
- dictionary mapping event type and key to event object where each event requires select-render-pass support
- contextDefinition
- node describing the options used to create this context, passed in as "definition" argument on init, see OpenGLContext.contextdefinition.ContextDefinition for details.
- coreProfile
- set if the contextDefinition specifies that this is a core-profile-only context, that is, it does not support compatibility (legacy) entry points.
__init__(
self
,
definition
= None
)
Establish the Context working environment
- definition
- an OpenGLContext.contextdefinition.ContextDefinition instance which controls the context features (size, bit-depth, etc). If null, then use self.contextDefinition if it exists, otherwise create a default ContextDefinition instance. Alternately, can be a dictionary of key:value pairs to set on the default ContextDefinition to specify required parameters.
Calls the following:
setupThreading,
setupExtensionManager,
initializeEventManagers,
setupCallbacks,
setupDefaultEventCallbacks,
setupCache,
setupFontProviders,
setupFrameRateCounter,
DoInit
addPickEvent(
self
,
event
)
Add event to list of events to be processed by selection-render-mode
This is a method of the Context, rather than the
rendering pass (which might seem more elegant given
that it is the rendering pass which deals with the
events being registered) because the requests to
render a pick event occur outside of the rendering
loop. As a result, there is (almost) never an
active context when the pick-event-request comes in.
ContextMainLoop(
cls
,
*
args
,
**
named
)
Mainloop for the context, each GUI sub-class must override this
DoEventCascade(
self
)
Customization point for generating non-GUI event cascades
This method should only be called after self.lockScenegraph
has been called. self.unlockScenegraph should then be called
Most Contexts will use the eventhandler mix-in's version of this
method. That provides support for the defered-execution of
functions/method during the event cascade.
DoInit(
self
)
Call the OnInit method at a time when the context is valid
This method provides a customization point where
contexts which do not completely initialize during
their __init__ method can arrange to have the OnInit
method processed after their initialization has
completed. The default implementation here simply
calls OnInit directly w/ appropriate setCurrent
and unsetCurrent calls and calls the glutInit()
function with an empty argument-list.
drawPoll(
self
,
timeout
= None
)
Wait timeout seconds for a redraw request
- timeout
- timeout in seconds, if None, use self.drawPollTimeout
returns 0 if timeout, 1 if true
getContextType(
cls
,
entrypoint
= None
,
type
= <class 'OpenGLContext.plugins.InteractiveContext'>
)
Load a single context type via entry-point resolution
returns a Context sub-class *or* None if there is no such
context defined/available, will have a ContextMainLoop method
for running the Context top-level loop.
getContextTypes(
cls
,
type
= <class 'OpenGLContext.plugins.InteractiveContext'>
)
Retrieve the set of defined context types
- type
- testing type key from setup.py for the registered modules
returns list of setuptools entry-point objects which can be passed to
getContextType( name ) to retrieve the actual context type.
getSceneGraph(
self
)
Get the scene graph for the context (or None)
You must return an instance of:
OpenGLContext.scenegraph.scenegraph.SceneGraph
Normally you would create that using either a loader
from OpenGLContext.loader:
from OpenGLContext.loader import vrml97
def OnInit( self ):
self.sg = vrml97.load( 'c:\somefile\world.wrl' )
or by using the classes in OpenGLContext.scenegraph.basenodes:
from OpenGLContext.scenegraph import basenodes
def OnInit( self ):
self.sg = basenodes.sceneGraph(
children =
basenodes.Transform(...)
,
)
to define the scenegraph in Python code.
getUserAppDataDirectory(
cls
)
Retrieve user-specific configuration directory
Default implementation gives a directory-name in the
user's (system-specific) "application data" directory
named
getViewPort(
self
)
Method to retrieve the current dimensions of the context
Return value is a width, height tuple. See Context.ViewPort
for setting of this value.
initializeEventManagers(
self
,
managerClasses
= ()
)
Customisation point for initialising event manager objects
See:
OpenGLContext.eventhandlermixin.EventHandlerMixin
lockScenegraph(
self
,
blocking
= 1
)
Lock scenegraph locks to prevent other update/rendering actions
Potentially this could be called from a thread other than the
GUI thread, allowing the other thread to update structures in
the scenegraph without mucking up any active rendering pass.
OnDraw(
self
,
force
= 1
,
*
arguments
)
Callback for the rendering/drawing mechanism
- force
- if true, force a redraw. If false, then only do a redraw if the event cascade has generated events.
return value is whether a visible change occured
This implementation does the following:
- calls self.lockScenegraph() o calls self.DoEventCascade()
- calls self.unlockScenegraph()
- calls self.setCurrent()
- calls self.renderPasses( self ) See: passes sub-package See: visitor.py, rendervisitor.py, renderpass.py, shadow/passes.py for examples of render-pass-sets which can be triggered. See: flat.py for standard second-generation renderer
The RenderPasses define the core of the rendering
mechanism. The default rendering passes will defer
most rendering options to the scenegraph returned by
self.getSceneGraph(). If that value is None (default)
then the pass will use the Context's callbacks.
You can define new RenderPasses to replace the
rendering algorithm, override the Context's various
callbacks to write raw OpenGL code, or work by
customizing the scene graph library.
* if there was a visible change (which is the return value
from the render-pass-set), calls self.SwapBuffers()
* calls self.unsetCurrent()
OnInit(
self
)
Customization point for scene set up and initial processing
You override this method to do housekeeping chores such as
loading images and generating textures, loading pre-established
geometry, spawning new threads, etc.
This method is called after the completion of the Context.__init__
method for the rendering context. GUI implementers:
Wherever possible, this should be the very last function
called in the initialization of the context to allow user
code to use all the functionality of the context.
OnSaveImage(
self
,
event
= None
,
template
= '%(script)s-screen-%(count)04i.png'
,
script
= None
,
date
= None
,
overwrite
= False
)
Save our current screen to disk (if possible)
Render(
self
,
mode
= None
)
Customization point for geometry rendering
This method is called by the default render passes to
render the geometry for the system. Wherever possible,
you should pay attention to the rendering modes to allow
for optimization of your geometry (for instance,
selection passes do not require lighting).
The default implementation merely ensures that matrix mode
is currently model view.
See: visitor.py, rendervisitor.py, renderpass.py,
shadow/passes.py for definitions of the properties of the
mode.
setDefaultTTFFont(
cls
,
name
,
type
= 'sans'
)
Set the current user's preference for a default font
setupCache(
self
)
Setup caching strutures for content
This includes the general compiled-geometry caches
and the texture cache
setupCallbacks(
self
)
Establishes GUI callbacks for asynchronous event GUI systems
Subclasses and applications will register events
here for those event types in which they are interested.
Most minor applications should use interactivecontext's
abstract callbacks (which translate the GUI library's
native events into a common event framework for all
interactivecontexts).
The default implementation does nothing.
setupDefaultEventCallbacks(
self
)
Setup common callbacks for the context
This will normally be done in the GUI-lib's sub-class of
context. You might override it to provide other default
callbacks, but you'll normally want to call the base-class
implementation somewhere in that overridden method.
setupFontProviders(
self
)
Load font providers for the context
See the OpenGLContext.scenegraph.text package for the
available font providers.
setupFrameRateCounter(
self
)
Setup structures for managing frame-rate
This sets self.frameCounter to an instance of
framecounter.FrameCounter, which is a simple node
used to track frame-rate metadata during rendering.
Updates to the framecounter are performed by OnDraw
iff there is a visible change processed.
Note:
If you override this method, you need to either use
an object which has the same API as a FrameCounter or
use None, anything else will cause failures in the
core rendering loop!
suppressRedraw(
self
)
Indicate to the context that there is no need to re-render
This method signals to the context that there are no updates
currently requiring redrawing of the context's contents.
See:
Context.shouldRedraw and Context.triggerRedraw
SwapBuffers(
self
)
Called by the rendering loop when the buffers should be swapped
Each GUI library needs to override this method with the appropriate
code for the library.
triggerPick(
self
)
Trigger a selection rendering pass
If the context is not currently drawing, the selection render will
occur immediately, otherwise it will occur the next time the
rendering loop reaches the selection stage.
triggerRedraw(
self
,
force
= 0
)
Indicate to the context that it should redraw when possible
If force is true, the rendering will begin immediately if the
context is not already drawing. Otherwise only the indicator flag
will be set.
class LockingError(
Exception
):