Equalizer  1.12.0
Parallel Rendering Framework
eq::Config Class Reference

A configuration is a visualization session driven by an application. More...

#include <config.h>

+ Inheritance diagram for eq::Config:
+ Collaboration diagram for eq::Config:

Public Types

typedef fabric::Config< Server, Config, Observer, Layout, Canvas, Node, ConfigVisitorSuper
 base class
 
- Public Types inherited from eq::fabric::Config< Server, Config, Observer, Layout, Canvas, Node, ConfigVisitor >
typedef std::vector< Observer * > Observers
 A vector of observers.
 
typedef std::vector< Layout * > Layouts
 A vector of layouts.
 
typedef std::vector< Canvas * > Canvases
 A vector of canvases.
 
typedef std::vector< Node * > Nodes
 A vector of nodes.
 
enum  FAttribute
 Floating-point attributes.
 
enum  IAttribute
 Integer attributes. More...
 
- Public Types inherited from eq::fabric::Object
enum  DirtyBits {
  DIRTY_NAME = Serializable::DIRTY_CUSTOM << 0, DIRTY_USERDATA = Serializable::DIRTY_CUSTOM << 1, DIRTY_TASKS = Serializable::DIRTY_CUSTOM << 2, DIRTY_REMOVED = Serializable::DIRTY_CUSTOM << 3,
  DIRTY_SERIAL = Serializable::DIRTY_CUSTOM << 4, DIRTY_CUSTOM = Serializable::DIRTY_CUSTOM << 6, DIRTY_OBJECT_BITS = DIRTY_NAME | DIRTY_USERDATA
}
 The changed parts of the object since the last pack(). More...
 

Public Member Functions

EQ_API Config (ServerPtr parent)
 Construct a new config. More...
 
virtual EQ_API ~Config ()
 Destruct a config. More...
 
void setupMessagePump (Pipe *pipe)
 
void setupServerConnections (const std::string &connectionData)
 
Data Access
EQ_API ClientPtr getClient ()
 
EQ_API ConstClientPtr getClient () const
 
EQ_API co::NodePtr getApplicationNode ()
 
EQ_API co::CommandQueue * getMainThreadQueue ()
 
EQ_API co::CommandQueue * getCommandThreadQueue ()
 
EQ_API uint32_t getCurrentFrame () const
 
EQ_API uint32_t getFinishedFrame () const
 
EQ_API GLStats::Data getStatistics () const
 
EQ_API bool isRunning () const
 
EQ_API void stopRunning ()
 Stop the config. More...
 
EQ_API int64_t getTime () const
 Get the current time in milliseconds. More...
 
EQ_API MessagePumpgetMessagePump ()
 
const ChannelfindChannel (const std::string &name) const
 
Operations
virtual EQ_API bool init (const uint128_t &initID)
 Initialize this configuration. More...
 
virtual EQ_API bool exit ()
 Exit this configuration. More...
 
EQ_API bool update ()
 Update the configuration. More...
 
EQ_API void setLatency (const uint32_t latency) override
 
Object registry.
EQ_API bool registerObject (co::Object *object) override
 Register a distributed object. More...
 
EQ_API void deregisterObject (co::Object *object) override
 Deregister a distributed object. More...
 
virtual EQ_API bool mapObject (co::Object *object, const uint128_t &id, const uint128_t &version=co::VERSION_OLDEST)
 Map a distributed object. More...
 
virtual EQ_API uint32_t mapObjectNB (co::Object *object, const uint128_t &id, const uint128_t &version=co::VERSION_OLDEST)
 Start mapping a distributed object. More...
 
EQ_API uint32_t mapObjectNB (co::Object *object, const uint128_t &id, const uint128_t &version, co::NodePtr master) override
 Start mapping a distributed object from a known master. More...
 
EQ_API bool mapObjectSync (const uint32_t requestID) override
 Finalize the mapping of a distributed object. More...
 
EQ_API void unmapObject (co::Object *object) override
 Unmap a mapped object. More...
 
EQ_API f_bool_t syncObject (co::Object *object, const uint128_t &id, co::NodePtr master, const uint32_t instanceID=CO_INSTANCE_ALL) override
 Synchronize the local object with a remote object. More...
 
Frame Control
virtual EQ_API uint32_t startFrame (const uint128_t &frameID)
 Request a new frame of rendering. More...
 
virtual EQ_API uint32_t finishFrame ()
 Finish the rendering of a frame. More...
 
virtual EQ_API uint32_t finishAllFrames ()
 Finish rendering all pending frames. More...
 
EQ_API void releaseFrameLocal (const uint32_t frameNumber)
 Release the local synchronization of the config for a frame. More...
 
EQ_API void stopFrames ()
 Asynchronously signal all channels to interrupt their rendering. More...
 
Event handling
EQ_API const ConfigEventnextEvent ()
 Get the next event. More...
 
EQ_API const ConfigEventtryNextEvent ()
 Try to get the next event. More...
 
EQ_API void sendEvent (ConfigEvent &event)
 Send an (old) event to the application node. More...
 
virtual EQ_API bool handleEvent (const ConfigEvent *event)
 Handle one (old) config event. More...
 
EQ_API EventOCommand sendEvent (const uint32_t type)
 Send an event to the application node. More...
 
EQ_API EventOCommand sendError (const uint32_t type, const Error &error)
 Send an error event to the application node. More...
 
EQ_API Errors getErrors ()
 
EQ_API EventICommand getNextEvent (const uint32_t timeout=LB_TIMEOUT_INDEFINITE) const
 Get the next event. More...
 
virtual EQ_API bool handleEvent (EventICommand command)
 Handle one config event. More...
 
EQ_API bool checkEvent () const
 
virtual EQ_API void handleEvents ()
 Handle all config events. More...
 
void addStatistic (const uint32_t originator, const Statistic &stat)
 Add an statistic event to the statistics overlay. More...
 
- Public Member Functions inherited from eq::fabric::Config< Server, Config, Observer, Layout, Canvas, Node, ConfigVisitor >
virtual void output (std::ostream &) const
 
void create (Observer **observer)
 
void create (Layout **layout)
 
void create (Canvas **canvas)
 
void create (Node **node)
 
void release (Observer *observer)
 
void release (Layout *layout)
 
void release (Canvas *canvas)
 
void release (Node *node)
 
EQFABRIC_INL lunchbox::RefPtr< ServergetServer ()
 
EQFABRIC_INL lunchbox::RefPtr< const ServergetServer () const
 
const ObserversgetObservers () const
 
const LayoutsgetLayouts () const
 
const CanvasesgetCanvases () const
 
EQFABRIC_INL uint32_t getTimeout () const
 
const NodesgetNodes () const
 
EQFABRIC_INL NodefindAppNode ()
 
EQFABRIC_INL const NodefindAppNode () const
 
EQFABRIC_INL VisitorResult accept (ConfigVisitor &visitor)
 Perform a depth-first traversal of this config. More...
 
EQFABRIC_INL VisitorResult accept (ConfigVisitor &visitor) const
 Const-version of accept(). More...
 
EQFABRIC_INL T * find (const uint128_t &id)
 
EQFABRIC_INL const T * find (const uint128_t &id) const
 
EQFABRIC_INL T * find (const std::string &name)
 
EQFABRIC_INL const T * find (const std::string &name) const
 
void find (const uint128_t &id, T **result)
 
void find (const std::string &name, const T **result) const
 
ObservergetObserver (const ObserverPath &path)
 
LayoutgetLayout (const LayoutPath &path)
 
CanvasgetCanvas (const CanvasPath &path)
 
virtual void updateCanvas (Canvas *)
 
virtual void exitCanvas (Canvas *)
 
uint32_t getLatency () const
 
virtual EQFABRIC_INL void restore ()
 
void setFAttribute (const FAttribute attr, const float value)
 
void setIAttribute (const IAttribute attr, const int32_t value)
 
float getFAttribute (const FAttribute attr) const
 
int32_t getIAttribute (const IAttribute attr) const
 
- Public Member Functions inherited from eq::fabric::Object
virtual EQFABRIC_API bool isDirty () const
 
virtual EQFABRIC_API void backup ()
 
virtual EQFABRIC_API void setName (const std::string &name)
 Set the name of the object. More...
 
EQFABRIC_API const std::string & getName () const
 
EQFABRIC_API void setUserData (co::Object *userData)
 Set user-specific data. More...
 
EQFABRIC_API co::Object * getUserData ()
 
EQFABRIC_API const co::Object * getUserData () const
 
EQFABRIC_API uint32_t getTasks () const
 Return the set of tasks this channel might execute in the worst case. More...
 
EQFABRIC_API uint32_t getSerial () const
 

Protected Member Functions

EQ_API void attach (const uint128_t &id, const uint32_t instanceID) override
 
EQ_API void notifyAttached () override
 
EQ_API void notifyDetach () override
 
EQ_API void changeLatency (const uint32_t latency) override
 
EQ_API bool mapViewObjects () const override
 
- Protected Member Functions inherited from eq::fabric::Config< Server, Config, Observer, Layout, Canvas, Node, ConfigVisitor >
EQFABRIC_INL Config (lunchbox::RefPtr< Server > parent)
 
virtual EQFABRIC_INL void serialize (co::DataOStream &os, const uint64_t dirtyBits)
 
virtual EQFABRIC_INL void deserialize (co::DataIStream &is, const uint64_t dirtyBits)
 
virtual void _removeChild (const uint128_t &)
 
void setAppNodeID (const co::NodeID &nodeID)
 
const co::NodeID & getAppNodeID () const
 
EQFABRIC_INL EventOCommand sendError (co::NodePtr node, const uint32_t event, const Error &error)
 
virtual bool mapNodeObjects () const
 
virtual VisitorResult _acceptCompounds (ConfigVisitor &)
 
virtual VisitorResult _acceptCompounds (ConfigVisitor &) const
 
Node_findNode (const uint128_t &id)
 
virtual EQFABRIC_INL uint128_t commit (const uint32_t incarnation=CO_COMMIT_NEXT)
 
- Protected Member Functions inherited from eq::fabric::Object
EQFABRIC_API Object ()
 Construct a new Object. More...
 
EQFABRIC_API Object (const Object &)
 Construct an unmapped, unregistered copy of an object. More...
 
virtual EQFABRIC_API ~Object ()
 Destruct the object. More...
 
EQFABRIC_API Objectoperator= (const Object &from)
 NOP assignment operator. More...
 
virtual bool hasMasterUserData ()
 
virtual uint32_t getUserDataLatency () const
 
EQFABRIC_API void setTasks (const uint32_t tasks)
 
EQFABRIC_API void postRemove (Object *child)
 
virtual void removeChild (const uint128_t &)
 
template<class C , class S >
void commitChild (C *child, S *sender, uint32_t cmd, const uint32_t incarnation)
 
template<class C >
void commitChild (C *child, const uint32_t incarnation)
 
template<class C , class S >
void commitChildren (const std::vector< C * > &children, S *sender, uint32_t cmd, const uint32_t incarnation)
 
template<class C >
void commitChildren (const std::vector< C * > &children, uint32_t cmd, const uint32_t incarnation)
 
template<class C >
void commitChildren (const std::vector< C * > &children, const uint32_t incarnation)
 
template<class C >
void syncChildren (const std::vector< C * > &children)
 
template<class P , class C >
void releaseChildren (const std::vector< C * > &children)
 
EQFABRIC_API bool _cmdSync (co::ICommand &command)
 

Friends

class Node
 

Additional Inherited Members

- Static Public Member Functions inherited from eq::fabric::Config< Server, Config, Observer, Layout, Canvas, Node, ConfigVisitor >
static const std::string & getFAttributeString (const FAttribute attr)
 
static const std::string & getIAttributeString (const IAttribute attr)
 

Detailed Description

A configuration is a visualization session driven by an application.

The application Client can choose a configuration from a Server. The Config will be instantiated though the NodeFactory. The Config groups all processes of the application in a single session.

A configuration has a number of nodes, which represent the processes involved in it. While the Server drives all nodes, a Config instance in a given process only has its Node instantiated, that is, any given Config has at most one Node.

The Config in the application process has access to all Canvas, Segment, Layout, View and Observer instances. Only the active Layout of the each Canvas, the Frustum of each View and the Observer parameters are writable. Views can be sub-classed to attach application-specific data.

The render client processes have only access to the current View for each of their channels.

See also
fabric::Config for public methods

Definition at line 55 of file config.h.

Constructor & Destructor Documentation

EQ_API eq::Config::Config ( ServerPtr  parent)
explicit

Construct a new config.

Version
1.0
virtual EQ_API eq::Config::~Config ( )
virtual

Member Function Documentation

void eq::Config::addStatistic ( const uint32_t  originator,
const Statistic &  stat 
)

Add an statistic event to the statistics overlay.

Thread safe.

Parameters
originatorthe originator serial id.
statthe statistic event.
Warning
experimental, may not be supported in the future
EQ_API bool eq::Config::checkEvent ( ) const
Returns
true if events are pending. Thread safe.
Version
1.0
EQ_API void eq::Config::deregisterObject ( co::Object *  object)
override

Deregister a distributed object.

This method ensures that the data for buffered object is kept for latency frames to allow mapping on slave nodes.

Parameters
objectthe object instance.
Version
1.0
virtual EQ_API bool eq::Config::exit ( )
virtual

Exit this configuration.

This method is to be called only on the application node on an initialized configuration.

Exiting a configuration calls configExit on all active render entities, releases the entities using the NodeFactory and stops the render clients.

A configuration which was not exited properly may not be re-initialized.

Returns
true if the exit was successful, false if not.
Version
1.0
virtual EQ_API uint32_t eq::Config::finishAllFrames ( )
virtual

Finish rendering all pending frames.

This method is to be called only on the application node on an initialized configuration.

Returns
the frame number of the last finished frame.
Version
1.0
virtual EQ_API uint32_t eq::Config::finishFrame ( )
virtual

Finish the rendering of a frame.

This method is to be called only on the application node on an initialized configuration.

This method synchronizes the local and global rendering. The global rendering is always synchronized to finish the frame (current - latency). The local rendering is synchronized according to the current thread model (cf. Node::IATTR_THREAD_MODEL)

Returns
the frame number of the globally finished frame, or 0 if no frame has been finished yet.
Version
1.0
EQ_API co::NodePtr eq::Config::getApplicationNode ( )
Returns
the application node.
Warning
experimental, may not be supported in the future
EQ_API ClientPtr eq::Config::getClient ( )
Returns
the local client node.
Version
1.0
EQ_API ConstClientPtr eq::Config::getClient ( ) const
Returns
the local client node.
Version
1.0
EQ_API uint32_t eq::Config::getCurrentFrame ( ) const
Returns
the frame number of the last frame started.
Version
1.0
EQ_API Errors eq::Config::getErrors ( )
Returns
the errors since the last call to this method.
Version
1.9
EQ_API uint32_t eq::Config::getFinishedFrame ( ) const
Returns
the frame number of the last frame finished.
Version
1.0
EQ_API MessagePump* eq::Config::getMessagePump ( )
Returns
the config's message pump, or 0.
Version
1.0
EQ_API EventICommand eq::Config::getNextEvent ( const uint32_t  timeout = LB_TIMEOUT_INDEFINITE) const

Get the next event.

To be called only on the application node.

The returned event command is valid until it gets out of scope. This method does not block if the given timeout is 0. Not thread safe.

Parameters
timeouttime in ms to wait for incoming events
Returns
the event command, or an invalid command on timeout
Version
1.5.1
See also
Client::processCommand()
EQ_API int64_t eq::Config::getTime ( ) const

Get the current time in milliseconds.

The clock in all processes of the config is synchronized to the Server clock. The precision of this synchronization is typically about 1 ms. The clock of the last instantiated config is used as the lunchbox::Log clock.

Returns
the global time in ms.
Version
1.0
virtual EQ_API bool eq::Config::handleEvent ( const ConfigEvent event)
virtual

Handle one (old) config event.

Thread safe.

This function handles all events which did exist in Equalizer 1.5.0. Events introduced in 1.5.1 or later are handled by the other handleEvent. Equalizer 2.0 will drop this method and send all events using EventICommand instead of the ConfigEvent struct.

Parameters
eventthe event.
Returns
true if the event requires a redraw, false if not.
virtual EQ_API bool eq::Config::handleEvent ( EventICommand  command)
virtual

Handle one config event.

Thread safe.

Parameters
commandthe event command.
Returns
true if the event requires a redraw, false if not.
Version
1.5.1
virtual EQ_API void eq::Config::handleEvents ( )
virtual

Handle all config events.

To be called only on the application node. Called automatically at the end of each frame to handle pending config events. The default implementation calls handleEvent() on all pending events, without blocking. Not thread safe.

Version
1.0
virtual EQ_API bool eq::Config::init ( const uint128_t &  initID)
virtual

Initialize this configuration.

This method is to be called only on the application node on an uninitialized configuration.

Initializing a configuration starts and connects all render clients, instantiates all active render entities (Node, Pipe, Window, Channel) using the NodeFactory of each process, and calls the configInit task methods on each of these entities, passing the given identifier.

The identifier is typically the identifier of a static Object containing initialization data.

The initialization fails if at least one of the configInit task methods fails. The application can use sendError() on the render client to pass an error string to the application process, which is received by the normal event processing.

Parameters
initIDan identifier to be passed to all init methods.
Returns
true if the initialization was successful, false if not.
Version
1.0
EQ_API bool eq::Config::isRunning ( ) const
Returns
true while the config is initialized and no exit event has happened.
Version
1.0
virtual EQ_API bool eq::Config::mapObject ( co::Object *  object,
const uint128_t &  id,
const uint128_t &  version = co::VERSION_OLDEST 
)
virtual

Map a distributed object.

Provided for symmetry with deregisterObject. Forwards mapping to local client node.

Version
1.0
virtual EQ_API uint32_t eq::Config::mapObjectNB ( co::Object *  object,
const uint128_t &  id,
const uint128_t &  version = co::VERSION_OLDEST 
)
virtual

Start mapping a distributed object.

Version
1.0
EQ_API uint32_t eq::Config::mapObjectNB ( co::Object *  object,
const uint128_t &  id,
const uint128_t &  version,
co::NodePtr  master 
)
override

Start mapping a distributed object from a known master.

Version
1.0
EQ_API bool eq::Config::mapObjectSync ( const uint32_t  requestID)
override

Finalize the mapping of a distributed object.

Version
1.0
EQ_API const ConfigEvent* eq::Config::nextEvent ( )

Get the next event.

To be called only on the application node.

The returned event is valid until the next call to this method. This method may block.

Returns
the event.
Deprecated:
See also
Client::processCommand()
EQ_API bool eq::Config::registerObject ( co::Object *  object)
override

Register a distributed object.

Provided for symmetry with deregisterObject. Forwards registration to local client node.

Version
1.0
EQ_API void eq::Config::releaseFrameLocal ( const uint32_t  frameNumber)

Release the local synchronization of the config for a frame.

Used by the local Node to release the process-local frame synchronization. An application typically does not call this method directly, it is called from Node::releaseFrameLocal(), which in turn is called from the appropriate task method depending on the thread model.

Parameters
frameNumberthe frame to release.
Version
1.0
EQ_API EventOCommand eq::Config::sendError ( const uint32_t  type,
const Error &  error 
)

Send an error event to the application node.

Parameters
typethe error event type
errorthe error message.
Version
1.8.0
EQ_API void eq::Config::sendEvent ( ConfigEvent event)

Send an (old) event to the application node.

Should not be used by applications, other then sending any event defined by Equalizer 1.5.0.

Parameters
eventthe event.
Deprecated:
EQ_API EventOCommand eq::Config::sendEvent ( const uint32_t  type)

Send an event to the application node.

The returned command can be used to pass additional data to the event. The event will be send after the command is destroyed, aka when it is running out of scope. Thread safe.

Parameters
typethe event type.
Returns
the event command to pass additional data to
Version
1.5.1
EQ_API void eq::Config::setLatency ( const uint32_t  latency)
overridevirtual
virtual EQ_API uint32_t eq::Config::startFrame ( const uint128_t &  frameID)
virtual

Request a new frame of rendering.

This method is to be called only on the application node on an initialized configuration. It implicitely calls update().

The server will sync to the new data, and generate all render tasks, which are queued on the render clients for execution.

Each call to startFrame() has to be completed by a finishFrame() or finishAllFrames() before the next call to startFrame().

Parameters
frameIDa per-frame identifier passed to all rendering methods.
Returns
the frame number of the new frame.
Version
1.0
EQ_API void eq::Config::stopFrames ( )

Asynchronously signal all channels to interrupt their rendering.

This method may be called from any thread in the application process. It causes Channel::notifyStopFrame() to be called immediately on all active channels.

Version
1.0
EQ_API void eq::Config::stopRunning ( )

Stop the config.

Version
1.0
EQ_API f_bool_t eq::Config::syncObject ( co::Object *  object,
const uint128_t &  id,
co::NodePtr  master,
const uint32_t  instanceID = CO_INSTANCE_ALL 
)
override

Synchronize the local object with a remote object.

Provided for symmetry. Forwards unmapping to local client node.

Version
1.7.4
EQ_API const ConfigEvent* eq::Config::tryNextEvent ( )

Try to get the next event.

To be called only on the application node.

The returned event is valid until the next call to this method. This method does not block.

Returns
a config event, or 0 if no events are pending.
Deprecated:
EQ_API void eq::Config::unmapObject ( co::Object *  object)
override

Unmap a mapped object.

Provided for symmetry with deregisterObject. Forwards unmapping to local client node.

Version
1.0
EQ_API bool eq::Config::update ( )

Update the configuration.

This method is to be called only on the application node only on an initialized configuration. Dirty objects on the config are committed, i.e., the View, Canvas and Observer, and any changes to the configuration are effected. Changes may be caused by the eq::admin API or by the application, e.g., through a layout change on a Canvas. Any change causes an implicit finish of all outstanding frames.

This function always returns false when a resource failed to initialize or exit. When robustness is not activated, the config is exited by the update upon failure. When robustness is activated, the config keeps running and may be used with reduced functionality.

Returns
true if the configuration update was successful, false if a resource failed to initialize or exit.
Version
1.0

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