Author: eilemann@gmail.com
State: Implemented in 0.3 beta
NodeFactory
Config
Node
Pipe
Window
Channel
Overview
The application developer overrides methods on Equalizer classes to plug in
the application's rendering code. The programming interface
overview describes the concept on a high level. This document lists all
currently implemented task methods, their typical use case and default
implementation. Some methods related to the task methods are described as
well. Task methods invoked by Equalizer start with a noun declaring the
context, followed by a verb for the action to implement,
e.g., Channel::frameInit. All other Equalizer methods start with
a verb, e.g., Channel::applyFrustum. The eqPly
example can be used as a reference.
NodeFactory
The NodeFactory is the place where the subclassed Equalizer
objects are created by the application. It consists of virtual methods to
instantiate new instances of all classes mentioned below. The methods in the
base class eq::NodeFactory instantiate base Equalizer
objects, allowing selective subclassing. The node factory is created by the
application and passed to eq::init.
Config
The config represents an Equalizer session and controls frame generation. It
is instantiated on the application node
by eq::Server::chooseConfig and on the render nodes
during eq::Config::init.
Config::init
This method is called directly by the application on the application node to
initialize the configuration. The application can override it to update
application-specific data before or after
calling eq::Config::init.
Config::exit
This method is called directly by the application on the application node to
exit a running configuration. The application can override it to update
application-specific data before or after
calling eq::Config::exit.
Config::startFrame
This method is called directly by the application on the application node to
request a new frame to be rendered. The application can override it to update
frame-specific data before or after
calling eq::Config::startFrame.
Config::finishFrame
This method is called directly by the application on the application node to
request a frame to be finished. The frame finished can be older than the last
frame started, depending on the config's latency. The application can override
it to update frame-specific data before or after
calling eq::Config::finishFrame.
Config::finishAllFrames
This method is called directly by the application on the application node to
finish all started frames. The application can override it to update
frame-specific data before or after
calling eq::Config::finishAllFrames.
Config::handleEvents
This method is called on the application node from
within Config::finishFrame to process all pending events. Its
purpose is to implement custom event handling, for example event-driven
execution. The default implementation does not block and calls
Config::handleEvent for each queued event. See also
Event Handling.
Config::handleEvent
This method is called by Config::handleEvents to process a single
event. Its purpose is to update the application's state depending on the
received event. The default implementation does nothing.
Node
The node represent a single machine in the cluster. It is instantiated on the
render clients during Config::init.
Node::configInit
This method is called during Config::init on the render
clients. Its purpose is to initialize node-specific application data. It is
called in the node's main thread. The default implementation does nothing. A
return value of false causes the config initialization to fail.
Node::configExit
This method is called during Config::exit on the render
clients. Its purpose is to de-initialize node-specific application data. It is
called in the node's main thread. The default implementation does nothing. A
return value of false causes the config exit to fail.
Node::frameStart
This method is the first method called for a given frame on the node. Its
purpose is to update all frame-specific per-node data, and to unlock all
resources underneath the node by calling Node::startFrame. The
default implementation calls Node::startFrame.
Node::frameDrawFinish
Called after the last Channel::frameDraw call of the node
thread. The default implementation waits for all pipes to release the local
synchronization, and then releases the node's local synchronization by
calling releaseFrameLocal. The application might
call releaseFrameLocal earlier or later during task execution,
when other task methods need synchronization with the node thread. To
completely disable per-node frame synchronization,
call Node::releaseFrameLocal from Node::frameStart.
Node::frameFinish
This method is the last method called for a given frame in the node
thread. Its purpose is to update frame-specific data after a frame has been
finished rendering, and to unlock the parent by
calling Node::releaseFrame. The default implementation
calls Node::releaseFrame.
Pipe
The pipe represents a graphic card. It is instantiated
during Config::init on the render nodes. All pipe, window and
channel task methods are currently called from the pipe thread.
Pipe::configInit
This method is called during Config::init on the render
clients. Its purpose is to initialize pipe-specific application data and the
handle to the graphic card, if applicable for the current window system. The
default implementation calls a windows-system specific task method,
e.g. configInitGLX, which initializes the handle to the graphic
card. The application typically allocates a renderer and other
rendering-specific data for each pipe, since each pipe runs in a separate
thread. A return value of false causes the config initialization
to fail.
Pipe::configExit
This method is called during Config::exit on the render
clients. Its purpose is to de-initialize pipe-specific application data and
the handle to the graphic card, if applicable. The default implementation
calls a window-system specific task method, e.g. configExitGLX,
which closes the handle to the graphic card. A return value
of false causes the config exit to fail.
Pipe::frameStart
This method is the first method called for a given frame in the pipe
thread. Its purpose is to wait for the local frame start synchronization, to
update all frame-specific data to the version corresponding to the started
frame, and to unlock all resources underneath the pipe by
calling Pipe::startFrame. The default implementation
calls Node::waitFrameStarted
and Pipe::startFrame. To disable per-node frame synchronization,
do not call Node::waitFrameStarted.
Pipe::frameFinish
This method is the last method called for a given frame in the pipe
thread. Its purpose is to update frame-specific data after a frame has been
finished rendering, and to unlock the parent by
calling Pipe::releaseFrame. The default implementation
calls Pipe::releaseFrame.
Pipe::frameDrawFinish
Called directly after the last Channel::frameDraw call of the
pipe. Normally this releases the parent's process-local synchronization by
calling releaseFrameLocal. The application might
call releaseFrameLocal earlier or later during task execution, in
case other task methods need synchronization with the node thread. See
also Node::frameDrawFinish.
Pipe::initEventHandler
This method is called when a new window system-specific pipe handle was set to initialize the event handling for this pipe. It can be overriden to instantiate a custom or no event handler. The event handling is window system-specific and should work together with the child window event handlers. Using no event handler disables event processing. In this case, the window's event handling and potentially the pipe's message pump should also be disabled.
Pipe::exitEventHandler
This method is called before a new window system-specific pipe handle is set to de-initialize the event handling for this pipe.
Window
The window represents an OpenGL drawable. It is instantiated
during Config::init on the render nodes. All window and
channel task methods are called from the pipe thread, with the exception of
processEvent, which might be called from a separate event thread.
Window::configInit
This method is called during Config::init on the render
clients. Its purpose is to initialize an OpenGL drawable and context, to setup
the OpenGL state, as well as to initialize window-specific application
data. The default implementation calls a windows-system specific task method,
e.g. configInitGLX, which creates a drawable and context
according to the window's attributes, and then calls configInitGL
if the context creation was successful. A return value of false
causes the config initialization to fail.
Window::configExit
This method is called during Config::exit on the render
clients. Its purpose is to destroy the OpenGL context and drawable, as wall as
to de-initialize window-specific application data. The default implementation
calls a windows-system specific task method, e.g. configExitGLX,
which destroyes the context and drawable. A return value of false
causes the config exit to fail.
Window::frameStart
This method is the first window task method called for a given frame. Its
purpose is to update all frame-specific data for this window, and to unlock
the resources underneath by calling Window::startFrame. The
default implementation calls Window::startFrame.
Window::frameFinish
This method is the last method called for a given frame in the window
thread. Its purpose is to update frame-specific data after the window has
finished rendering a frame, and to unlock its parent by
calling Window::releaseFrame. The default implementation
calls Window::releaseFrame.
Window::makeCurrent
Makes the OpenGL context for the window current. The default implementation
calls a window-specific method to attach the OpenGL context, e.g.,
glXMakeCurrent.
Window::swapBuffers
Swap the back and front rendering buffer. The default implementation
calls a window-specific method to swap the buffers, e.g.,
glXSwapBuffers.
Window::frameDrawFinish
Called directly after the last Channel::frameDraw call of the
window. Normally this releases the parent's process-local synchronization by
calling releaseFrameLocal. Note that there is currently no local
synchronization with the pipe, since the window and pipe tasks are executed
from the same thread.
Window::finish
Complete the rendering of all OpenGL commands. The purpose of this method is to
ensure that the rendering has been finished, for example to ensure a
simultaneous buffer swap of multiple windows. The default implementation
calls a glFinish.
Window::initEventHandler
This method is called after a new window system-specific window handle was set to initialize the event handling for this window. It can be overriden to instantiate a custom or no event handler. The event handling is window system-specific and should work together with the parent pipe event handler. Using no event handler disables event processing. In this case, the pipe's event handling should also be disabled.
Window::configExitEventHandler
This method is called before a new window system-specific window handle is set to de-initialize the event handling for this window.
Window::processEvent
Process a single event received by this window. The default implementation
either processes the event locally or converts it to
a ConfigEvent, which is send application thread by
using Config::sendEvent. This method may be called from the
window thread or from a seperate event thread, depending on the window system.
Channel
The channel is a viewport in a window. It executes the rendering tasks. All
channel methods are called from the pipe thread. The channel rendering methods
are given contextual information which are to be used during rendering, either
by using the convenience apply functions, e.g., applyViewport, or
by getting the values and calling the appropriate OpenGL functions.
Channel::configInit
This method is called during Config::init on the render
clients. Its purpose is to initialize channel-specific application data. The
default implementation is empty. A return value of false causes
the config initialization to fail.
Channel::configExit
This method is called during Config::exit on the render
clients. Its purpose is to de-initialize channel-specific application
data. The default implementation is empty. A return value
of false causes the config exit to fail.
Channel::frameStart
This method is the first channel task method called for a given frame. Its
purpose is to unlock the resources underneath by
calling Channel::startFrame. The default implementation
calls Channel::startFrame.
Channel::frameFinish
This method is the last method called for a given frame in the channel
thread. Its purpose is to update frame-specific data after the channel has
finished rendering a frame, and to unlock its parent by
calling Channel::releaseFrame. The default implementation
calls Channel::releaseFrame.
Channel::frameClear
Clear the frame buffer. The function has to use the provided draw buffer
(see getBuffer) and viewport (see getViewport). The
default method applies the draw buffer and viewport and clears the color and
depth buffer.
Channel::frameDraw
Render the scene. The function has to use the provided draw buffer
(see getBuffer), viewport (see getViewport), frustum
(see getFrustum, head transformation
(see getHeadTransform) and range for sort-last rendering
(see getRange). The default implementation applies the buffer,
viewport, frustum and head transform and draw a quad.
Channel::frameDrawFinish
Called directly after the last frameDraw call of the
channel. Normally this releases the parent's process-local synchronization by
calling releaseFrameLocal. Note that there is currently no local
synchronization with the window, since the channel and window tasks are
executed from the same thread.
Channel::frameAssemble
Assemble all provided input frames. The function has to use the provided draw
buffer (see getBuffer), viewport (see getViewport)
and input frames (see getInputFrames). The default method applies
the draw buffer and viewport, calls setupAssemblyState, assembles
the input frames using glDrawPixels and
calls resetAssemblyState. If the input frame has depth
information, it is z-composited using the stencil buffer with the information
in the channel's frame buffer. The frames are assembled in an arbitrary order
as they become available.
Channel::frameReadback
Readback the frame buffer. The function has to use the provided draw buffer
(see getBuffer), viewport (see getViewport) and
output frames (see getOutputFrames). The output frames specify
the frame buffer attachments (color, depth) to read back. The default method
applies the draw buffer and viewport, calls setupAssemblyState,
reads back the output frames using glReadPixels and
calls resetAssemblyState.
Channel::frameViewStart
This method is called before updating a channel with a view for a given frame. It is only called on channels which are used for display output, that is, for the destination channels created on view/segment intersections. The default implementation is empty.
Channel::frameViewFinish
This method is called after a destination channel has been updated. It is only called on channels which are used for display output, that is, for the destination channels created on view/segment intersections. It is typically used to do operations on the output channel after it has been fully updated, e.g., to draw a 2D overlay. The default implementation is empty.
Channel::setupAssemblyState
Setup the OpenGL state for a readback or assemble operation. The default
implementation is very conservative and saves any state which is potentially
changed by the assembly routines. This method is always called in conjunction
with a later resetAssemblyState.
Channel::resetAssemblyState
Reset the OpenGL state after an assembly operation.
