Multipipe SDK 3.2 Reference

Name

MPKConfig - MPKConfig functional interface.

Header File

#include <mpk/config.h>

Synopsis

Creating and Destroying

MPKConfig* mpkConfigNew(void );
void mpkConfigDelete(MPKConfig* config);
MPKConfig* mpkConfigLoad(const char* fileName);
void mpkConfigOutput(MPKConfig* config, int tab);

Fields Access

void mpkConfigSetName(MPKConfig* config, const char* name);
const char* mpkConfigGetName(MPKConfig* config);
void mpkConfigSetRunon(MPKConfig* config, int cpu);
int mpkConfigGetRunon(MPKConfig* config);
void mpkConfigSetMode(MPKConfig* config, int mode);
int mpkConfigGetMode(MPKConfig* config);
void mpkConfigSetMonitor(MPKConfig* config, int mode, const char* cmd);
const char* mpkConfigGetMonitor(MPKConfig* config, int mode);
void mpkConfigSetUserData(MPKConfig* config, void* data);
void* mpkConfigGetUserData(MPKConfig* config);
int mpkConfigNPipes(MPKConfig* config);
MPKPipe* mpkConfigGetPipe(MPKConfig* config, int i);
void mpkConfigAddPipe(MPKConfig* config, MPKPipe* p);
int mpkConfigRemovePipe(MPKConfig* config, MPKPipe* p);
int mpkConfigNCompounds(MPKConfig* config);
MPKCompound* mpkConfigGetCompound(MPKConfig* config, int i);
void mpkConfigAddCompound(MPKConfig* config, MPKCompound* c);
int mpkConfigRemoveCompound(MPKConfig* config, MPKCompound* c);
MPKCompound* mpkConfigFindCompound(MPKConfig* config, const char* name);
MPKPipe* mpkConfigFindPipe(MPKConfig* config, const char* name);
MPKWindow* mpkConfigFindWindow(MPKConfig* config, const char* name);
MPKChannel* mpkConfigFindChannel(MPKConfig* config, const char* name);
MPKWindow* mpkConfigMatchWindow(MPKConfig* config, XID drawable);

Callbacks

void mpkConfigSetPipeInitCB(MPKConfig* config, MPKConfigPipeCB cb);
void mpkConfigSetPipeExitCB(MPKConfig* config, MPKConfigPipeCB cb);
void mpkConfigSetWindowInitCB(MPKConfig* config, MPKConfigWindowCB cb);
void mpkConfigSetWindowExitCB(MPKConfig* config, MPKConfigWindowCB cb);
void mpkConfigSetChannelInitCB(MPKConfig* config, MPKConfigChannelCB cb);
void mpkConfigSetChannelExitCB(MPKConfig* config, MPKConfigChannelCB cb);
void mpkConfigSetDataFreeCB(MPKConfig* config, MPKConfigDataCB cb);
void mpkConfigSetFrameDataRefCB(MPKConfig* config, MPKConfigFrameDataCB cb);
void mpkConfigSetFrameDataUnrefCB(MPKConfig* config, MPKConfigFrameDataCB cb);
void mpkConfigSetIdleCB(MPKConfig* config, MPKConfigIdleCB cb);
void mpkConfigSetEventCB(MPKConfig* config, MPKConfigEventCB cb);
void mpkConfigSetCompoundPreAssembleCB(MPKConfig* config, MPKCompoundAssembleCB cb);
void mpkConfigSetCompoundPostAssembleCB(MPKConfig* config, MPKCompoundAssembleCB cb);
void mpkConfigSetCompoundReadOutputCB(MPKConfig* config, MPKCompoundReadOutputCB cb);
void mpkConfigSetCompoundClearCB(MPKConfig* config, MPKCompoundClearCB cb);

MPKConfigPipeCB mpkConfigGetPipeInitCB(MPKConfig* config);
MPKConfigPipeCB mpkConfigGetPipeExitCB(MPKConfig* config);
MPKConfigWindowCB mpkConfigGetWindowInitCB(MPKConfig* config);
MPKConfigWindowCB mpkConfigGetWindowExitCB(MPKConfig* config);
MPKConfigChannelCB mpkConfigGetChannelInitCB(MPKConfig* config);
MPKConfigChannelCB mpkConfigGetChannelExitCB(MPKConfig* config);
MPKConfigDataCB mpkConfigGetDataFreeCB(MPKConfig* config);
MPKConfigFrameDataCB mpkConfigGetFrameDataRefCB(MPKConfig* config);
MPKConfigFrameDataCB mpkConfigGetFrameDataUnrefCB(MPKConfig* config);
MPKConfigIdleCB mpkConfigGetIdleCB(MPKConfig* config);
MPKConfigEventCB mpkConfigGetEventCB(MPKConfig* config);
MPKCompoundAssembleCB mpkConfigGetCompoundPreAssembleCB(MPKConfig* config);
MPKCompoundAssembleCB mpkConfigGetCompoundPostAssembleCB(MPKConfig* config);
MPKCompoundReadOutputCB mpkConfigGetCompoundReadOutputCB(MPKConfig* config);
MPKCompoundClearCB mpkConfigGetCompoundClearCB(MPKConfig* config);

Operations

int mpkConfigInit(MPKConfig* config, int setmon);
void mpkConfigExit(MPKConfig* config);
void mpkConfigFreeze(MPKConfig* config, int freeze);
void mpkConfigFrame(MPKConfig* config, void* framedata);
void mpkConfigFrameBegin(MPKConfig* config, void* framedata);
void mpkConfigFrameEnd(MPKConfig* config);
int mpkConfigChangeMode(MPKConfig* config, int mode);
int mpkConfigGetLatency(MPKConfig* config);
int mpkConfigIsIdle(MPKConfig* config);

View Matrix Control

void mpkConfigSetViewPosition(MPKConfig* config, const float* pos);
void mpkConfigSetViewOrientation(MPKConfig* config, const float* hpr);
void mpkConfigSetViewMatrix(MPKConfig* config, const float* matrix);

Stereo & Head-Tracking

void mpkConfigSetHeadPosition(MPKConfig* config, const float* pos);
void mpkConfigSetHeadOrientation(MPKConfig* config, const float* hpr);
void mpkConfigSetHeadMatrix(MPKConfig* config, const float* matrix);
void mpkConfigSetEyeOffset(MPKConfig* config, float offset);
float mpkConfigGetEyeOffset(MPKConfig* config);
void mpkConfigEyeUpdate(MPKConfig* config);

Timing

void mpkConfigTimerEnable(MPKConfig* config, int mode);
void mpkConfigTimerDisable(MPKConfig* config, int mode);
void mpkConfigTimerSetTime(MPKConfig* config, int mode, double t);
double mpkConfigTimerGetTime(MPKConfig* config, int mode);

Events

void mpkConfigSelectInput(MPKConfig* config, long event_mask);
MPKEvent* mpkConfigNextEvent(MPKConfig* config, double time);
int mpkConfigCheckEvent(MPKConfig* config);
void mpkConfigHandleEvents(MPKConfig* config);

Culling

void mpkConfigFrameData(MPKConfig* config, void* data);
void mpkConfigFrameFlush(MPKConfig* config);

Description

The MPKConfig data structure primarily describes the rendering resources of an OpenGL Multipipe SDK application, as a hierarchy of:


It may also describe various parallelization schemes (MPKCompound) of the rendering across channels, in order to scale performances.

The MPKConfig can be read from an ASCII file via mpkConfigLoad and launched via mpkConfigInit. Rendering threads are then spawned and the MPKConfig initialization callbacks invoked. These should in turn specify the rendering callbacks that will be triggered by mpkConfigFrame.

The role of the application is then simply to update the database and package the data pertaining to each frame, as illustrated below :


     main( int argc, char *argv[] )
     {
         mpkInit();
         MPKConfig *config = mpkConfigLoad( "1-window" );

         mpkConfigSetPipeInitCB( config, ... );
         mpkConfigSetWindowInitCB( config, ... );
         mpkConfigSetChannelInitCB( config, ... );
         mpkConfigSetDataFreeCB( config, ... );

         mpkConfigInit( config );
         while ( !exit ) {
             ...
             // update database
             ...
             framedata = newFrameData( db );
             mpkConfigFrame( config, framedata );
         }

         mpkConfigSetPipeExitCB( config, ... );
         mpkConfigSetWindowExitCB( config, ... );
         mpkConfigSetChannelExitCB( config, ... );

         mpkConfigExit( config );
     }

     static FrameData *frameDataBuffer = NULL;
     FrameData *newFrameData( Database *db )
     {
         FrameData *framedata;
         if ( frameDataBuffer == NULL ) {
             framedata = (FrameData *) mpkMalloc( sizeof(FrameData) );
         }
         else {
             framedata = frameDataBuffer;
             frameDataBuffer = framedata->next;
         }
         framedata->next = NULL;
     
         // copy relevant information from database into framedata
         ...
         return framedata;
     }

     void freeFrameData( MPKConfig *config, void *data )
     {
         FrameData *framedata = (FrameData *)data;
         framedata->next = frameDataBuffer;
         frameDataBuffer = framedata;
     }

Function descriptions

Creating and Destroying

mpkConfigNew creates and returns a handle to an MPKConfig.

mpkConfigDelete deletes the passed MPKConfig.

mpkConfigLoad reads in and returns a handle to the MPKConfig described in file, or NULL upon any parsing error. The environment variable MPK_PARSER_CMD can be used in order to specify a pre-processing command to be applied to the file, typically /usr/lib/cpp. The environment variable MPK_CONFIG_PATH can be used to describe a search path for file.

mpkConfigOutput outputs the passed MPKConfig on stdout, with a left margin of tab tabulations.
Fields Access

mpkConfigSetName sets the name of the passed MPKConfig to name. This is done by copy and not by reference.

mpkConfigGetName returns the name of the passed MPKConfig.

mpkConfigSetRunon assigns all threads of the passed MPKConfig to be executed on the specified cpu, unless specified otherwise by mpkWindowSetRunon(). In addition, the following symbolic values can be used:
MPK_RUNON_AUTOThe window threads will be automatically placed on a CPU close to their respective graphics pipe, if possible.
 
MPK_RUNON_FREEAll threads are free to execute on whatever processor the system deems suitable.
 
MPK_UNDEFINEDThe thread placement is defined by the MPK_DEFAULT_RUNON_POLICY, set using mpkGlobalSetAttributei()

mpkConfigGetRunon returns the cpu assignment specified with mpkConfigSetRunon() or -1 if no assignment was specified.

mpkConfigSetMode sets the stereo mode of the passed MPKConfig to mode. Valid values for mode are MPK_STEREO and MPK_MONO.

mpkConfigGetMode returns the current stereo mode of the passed MPKConfig as either MPK_STEREO or MPK_MONO.

mpkConfigSetMonitor specifies the shell cmd to be executed when switching to the specified stereo mode. Valid values for mode are MPK_STEREO and MPK_MONO.

mpkConfigGetMonitor returns the monitor command for mode cmd specified with mpkConfigGetMonitor() or NULL. Accepted modes are MPK_STEREO and MPK_MONO.

mpkConfigSetUserData enables the application to specify passthrough data to be transported within the config structure. Transport is done by reference and not by copy.

mpkConfigGetUserData enables the application to retrieve the passthrough data specified by mpkConfigSetUserData().

mpkConfigNPipes returns the number of MPKPipe in passed config.

mpkConfigGetPipe returns the ith MPKPipe in passed config.

mpkConfigAddPipe appends MPKPipe p to list of pipes for passed config.

mpkConfigRemovePipe searches for p in list of MPKPipe for passed config and removes it from the list if it is found.

mpkConfigNCompounds returns the number of top-level MPKCompound in config.

mpkConfigGetCompound returns the ith top-level MPKCompound in config.

mpkConfigAddCompound appends the top-level MPKCompound c to config.

mpkConfigRemoveCompound searches for c in the list of top-level MPKCompound for the passed config and removes it from the list if found.

mpkConfigFindCompound searches for MPKCompound with specified name in the passed MPKConfig and returns the match if found or NULL otherwise.

mpkConfigFindPipe searches for MPKPipe with specified name in the passed MPKConfig and returns the match if found or NULL otherwise.

mpkConfigFindWindow searches for MPKWindow with specified name in the passed MPKConfig and returns the match if found or NULL otherwise.

mpkConfigFindChannel searches for MPKChannel with specified name in the passed MPKConfig and returns the match if found or NULL otherwise.

mpkConfigMatchWindow searches for MPKWindow with the same drawable in the passed MPKConfig and returns the match if found or NULL otherwise.
Callbacks

mpkConfigSetPipeInitCB sets the MPKConfig pipes initialization callback to the passed function, of type :

void (*MPKConfigPipeCB)(MPKPipe*);

mpkConfigSetPipeExitCB sets the MPKConfig pipes exit callback to the passed function, of type :

void (*MPKConfigPipeCB)(MPKPipe*);

mpkConfigSetWindowInitCB sets the MPKConfig windows initialization callback to the passed function, of type :

void (*MPKConfigWindowCB)(MPKWindow*);
Default setting is to invoke mpkWindowCreate().

mpkConfigSetWindowExitCB sets the MPKConfig windows exit callback to the passed function, of type :

void (*MPKConfigWindowCB)(MPKWindow*);
Default setting is to invoke mpkWindowDestroy().

mpkConfigSetChannelInitCB sets the MPKConfig channels initialization callback to the passed function, of type :

void (*MPKConfigChannelCB)(MPKChannel*);

mpkConfigSetChannelExitCB sets the MPKConfig channels exit callback to the passed function, of type :

void (*MPKConfigChannelCB)(MPKChannel*);

mpkConfigSetDataFreeCB sets the MPKConfig de-allocation callback to the passed function, of type :

void (*MPKConfigDataCB)(MPKConfig*, void*);
This function gets invoked when the frame data which was passed to mpkConfigFrameBegin() is not used any more.

mpkConfigSetFrameDataRefCB sets the MPKConfig frame data referenciation callback to the passed function, of type :

void (*MPKConfigFrameDataCB)(MPKConfig*, void*);

This function can be used in conjunction with the frame data dereferenciation callback to implement memory handling for data passed to mpkConfigFrameData(), mpkChannelPassData() or mpkChannelPutData().

mpkConfigSetFrameDataUnrefCB sets the MPKConfig frame data dereferenciation callback to the passed function, of type :

void (*MPKConfigFrameDataCB)(MPKConfig*, void*);

This function can be used in conjunction with the frame data referenciation callback to implement memory handling for data passed to mpkConfigFrameData(), mpkChannelPassData() or mpkChannelPutData().

mpkConfigSetIdleCB sets the MPKConfig idle callback to the passed function, of type :

void (*MPKConfigIdleCB)(MPKConfig*);
This function gets invoked by the application during the idle time after all non-threaded windows have been updated, as shown by the time diagram below:


  
   Application                   MPKWindow 1            MPKWindow 2
 ________________________________________________________________

   mpkConfigFrameBegin           .
   .                             Update channels        Update channels
   mpkConfigFrameEnd             Update channels        Update channels
   update non-threaded windows   Update channels        Update channels
   idle callback                 Update channels        Update channels
   idle callback                 .                      Update channels
   idle callback                 .                      .
   .                             mpkWindowSwapBuffers   mpkWindowSwapBuffers

The function mpkConfigIsIdle() can be used to determine if windows are still beeing updated.

mpkConfigSetEventCB sets the MPKConfig event callback to the passed function, of type :

void (*MPKConfigEventCB)(MPKConfig*);
This function gets invoked by the application after all windows have drawn and swapbuffered. The default event callback is mpkConfigHandleEvents().

mpkConfigSetCompoundPreAssembleCB sets the config's compounds pre assemble callback to the passed function, of type :

void (*MPKCompoundAssembleCB)(MPKCompound*, void*);

The default callback is mpkCompoundPreAssemble().

mpkConfigSetCompoundPostAssembleCB sets the config's compounds post assemble callback to the passed function, of type :

void (*MPKCompoundAssembleCB)(MPKCompound*, void*);

The default callback is mpkCompoundPostAssemble().

mpkConfigSetCompoundReadOutputCB sets the config's compounds read output callback to the passed function, of type :

void (*MPKCompoundReadOutputCB)(MPKCompound*);

The default callback is mpkCompoundReadOutputFrame().

mpkConfigSetCompoundClearCB sets the config's compounds clear callback to the passed function, of type :

void (*MPKCompoundClearCB)(MPKCompound*, void*);

The default callback is mpkCompoundClear().

mpkConfigGetPipeInitCB returns the config's pipes init callback.

mpkConfigGetPipeExitCB returns the config's pipes exit callback.

mpkConfigGetWindowInitCB returns the config's windows init callback. Default setting is to invoke mpkWindowCreate().

mpkConfigGetWindowExitCB returns the config's windows exit callback. Default setting is to invoke mpkWindowDestroy().

mpkConfigGetChannelInitCB returns the config's channels init callback.

mpkConfigGetChannelExitCB returns the config's channels exit callback.

mpkConfigGetDataFreeCB returns the config's de-allocation callback.

mpkConfigGetFrameDataRefCB returns the config's frame data referenciation callback.

mpkConfigGetFrameDataUnrefCB returns the config's frame data dereferenciation callback.

mpkConfigGetIdleCB returns the config's idle callback.

mpkConfigGetEventCB returns the config's event callback.

mpkConfigGetCompoundPreAssembleCB returns the config's compounds pre-assemble callback. Default setting is to invoke mpkCompoundPreAssemble().

mpkConfigGetCompoundPostAssembleCB returns the config's compounds post-assemble callback. Default setting is to invoke mpkCompoundPostAssemble().

mpkConfigGetCompoundReadOutputCB returns the config's compounds read output callback. Default setting is to invoke mpkCompoundReadOutputFrame().

mpkConfigGetCompoundClearCB returns the config's compounds clear callback. Default setting is to invoke mpkCompoundClear().
Operations

mpkConfigInit launches the passed MPKConfig and spawns the MPKWindow loop threads. The config's initialization callbacks are invoked in the order described by the pseudo-code below :


    for each MPKPipe in the config
        invoke config's pipes initialization callback
        for each MPKWindow in the pipe
           launch the window thread, which :

             invoke config's windows initialization callback
             for each MPKChannel in the window
                 invoke config's channels initialization callback
             end for
             enter lifelong loop

        end for
    end for

mpkConfigInit() will block until all MPKWindow threads have entered their lifelong loop. It then returns the number of threads launched.

If the argument flag setmon is set, then the shell commands will be invoked that have been specified via mpkConfigSetMonitor(), if any. Note that the config's windows initialization callback is set by default to mpkWindowCreate().

mpkConfigExit exit's the given config, according to the pseudo-code below:


    for each MPKPipe in the config
        for each MPKWindow in the pipe
           exit the window thread, which :

             for each MPKChannel in the window
                 invoke config's channels exit callback
             end for
             invoke config's windows exit callback
             exit window thread

        end for
        invoke config's pipes exit callback
    end for

Note that the config's windows exit callback is set by default to mpkWindowDestroy().

mpkConfigFreeze with a non-zero freeze argument causes subsequent mpkConfigFrame() to perform without invoking any rendering callback, ie. the windows will be "frozen". Otherwise, frames will be rendered as usual.

mpkConfigFrame drives the passed MPKConfig to execute one frame of rendering, which causes all window threads to invoke their rendering callbacks. It is provided as a convenience function and executes the following code:


     mpkConfigFrameBegin( config, framedata );
     mpkConfigFrameEnd( config );

The framedata de-allocation should be done via a de-allocation callback function, to be specified prior to mpkConfigInit() via mpkConfigSetDataFreeCB().

mpkConfigFrameBegin triggers the rendering of a new frame. The passed framedata will be propagated to the config's channels rendering callbacks appropriately to the config's compounds latency.

The function mpkConfigFrameData() can be used after mpkConfigFrameBegin() to send data describing the frame to be rendered.

The function mpkConfigFrameEnd() is used to synchronize the end of the frame triggered by mpkConfigFrameBegin().

The framedata de-allocation should be done via a de-allocation callback function, to be specified prior to mpkConfigInit() via MPKConfigFreeDataCB().

mpkConfigFrameEnd synchronizes the frame started with mpkConfigFrameBegin(). Among other things, this function will synchronize the swapbuffer of all windows involved in the config.

mpkConfigChangeMode changes the MPKConfig's stereo mode to mode, which may involve exiting and restarting the configuration. If the new mode is the same as the old, then the change is ignored and 0 is returned. Otherwise the return value of mpkConfigInit() is returned.

mpkConfigGetLatency returns the maximum latency of the passed config. This value represents the maximum frame-delay between the config's compound source- and destination- channels updates. It also characterizes the maximum frame-delay between a user-input and the corresponding final composited frame. This function should be called on a running configuration, that is, after mpkConfigInit() has been called.

mpkConfigIsIdle is supposed to be called from the idle callback. It returns 1 if the application thread is still idle, ie. at least one window thread is still rendering. Otherwise it returns 0. When not called from the idle callback, the behaviour of this function is undefined. This function can be used to optimize the usage of the idle callback, as illustrated below:


     void configIdle( MPKConfig *config )
     {
         while( mpkConfigIsIdle( config ))
         {
             // do some processing
         }
     }

Note that no data currently used in the rendering callbacks should be modified in the idle callback.
View Matrix Control

mpkConfigSetViewPosition specifies the position of the viewer.

mpkConfigSetViewOrientation specifies the orientation of the viewer as specified by the hpr angles, hence "hpr" specify the Euler angles of the head.

mpkConfigSetViewMatrix specifies the position and orientation of the viewer.
Stereo & Head-Tracking

mpkConfigSetHeadPosition specifies the position of the viewer in the arbitrary World Coordinates System used to describe the config.

mpkConfigSetHeadOrientation specifies the hpr angles of the line-of-sight, in degrees. "hpr" stands for head-pitch-roll, and describes the Euler angles of the head in the World Coordinates System used to describe the config with respect to the OpenGL convention, ie. the counter-clockwise rotation around the Y axis [head], X axis [pitch] and Z axis [roll] viewed from the positive side of the axis.

mpkConfigSetHeadMatrix specifies the 4x4 head transformation matrix in the arbitrary World Coordinates System used to describe the config :


     head.matrix = TRANSLATE( head.position ) x
                   ROTATE( head.hpr[0], 'y' ) x
                   ROTATE( head.hpr[1], 'x' ) x
                   ROTATE( head.hpr[2], 'z' )

     where "hpr" stands for head, pitch, roll.


mpkConfigSetEyeOffset sets the offset from each eye to the "head" position, ie. half the interoccular distance, to be used by config.

mpkConfigGetEyeOffset returns the offset from each eye to the head position, ie. half the interoccular distance, used by config.

mpkConfigEyeUpdate forces the current head transformation and eye positions to be recomputed from changes made to the head position, head orientation, head matrix or eye-offset via the functions above. mpkConfigFrame() invokes mpkConfigEyeUpdate().
Timing

mpkConfigTimerEnable with mode set to MPK_TIMER_AUTO activates automatic load-balancing. This mode is enabled by default for DPLEX MPKCompound. If mode is set to MPK_TIMER_FRAME then MPK will measure the duration of subsequent frames, which can be retrieved via mpkConfigTimerGetTime(). This mode is disabled by default.

mpkConfigTimerDisable disables the timer mode for config. Valid values for mode are MPK_TIMER_AUTO and MPK_TIMER_FRAME.

mpkConfigTimerSetTime with argument mode set to MPK_TIMER_FRAME specifies the desired minimal duration in milliseconds for the subsequent config frames. Default value is 0., ie. no time constraint.

mpkConfigTimerGetTime returns either the actual duration in milliseconds of the last config frame, ie. if mode is MPK_TIMER_FRAME and this mode is enabled, or, if mode is MPK_TIMER_AUTO, it returns MPK recommended minimal duration for next frame, which will be applied if config involves DPLEX MPKCompound.
Events

mpkConfigSelectInput loops over all windows of config, and sets the window's event mask if this window has an input display and an X window drawable. Note that the window's input display is set via mpkWindowOpenDisplay() or mpkWindowSetInputDisplay().

mpkConfigNextEvent returns the next MPKEvent on the event queue. If there is no MPKEvent queued, this function blocks until a MPKEvent is received.

If time is non-zero, it specifies a maximum interval in milliseconds to wait. If time is zero, mpkConfigNextEvent blocks indefinitely.

The returned MPKEvent is valid until the next call to mpkConfigNextEvent.

mpkConfigCheckEvent returns 0 if there are no events pending, 1 otherwise.

mpkConfigHandleEvents processes pending events on all windows. Note that MPKConfig's event callback is set by default to mpkConfigHandleEvents.
Culling

mpkConfigFrameData is used to describe the current frame between mpkConfigFrameBegin() and mpkConfigFrameEnd(). MPK passes data to the cull and draw callbacks, as defined in the given config.

Latency-correct memory management for data can be done via frame data referenciation and dereferenciation callbacks, to be specified prior to mpkConfigInit() via MPKConfigSetFrameDataRefCB() and MPKConfigSetFrameDataUnrefCB().

An application using the culling infrastructure of MPK would typically be programmed as described in the pseudo-code below:


    int main(...)
    {
        ...
        while ( !exit ) {
             ...
             // update database
             ...
             framedata = newFrameData( db );
             mpkConfigFrameBegin( config, framedata );
             mpkConfigFrameData( config, data1 );
             ...
             mpkConfigFrameData( config, dataN );
             mpkConfigFrameEnd( config );
         }
         ...
    }

    void cullChannel( MPKChannel *c, void *data )
    {
         ...
         while( (data = mpkChannelNextData( c )) != NULL )
         {
             if( isVisible( data ))
             {
                  mpkChannelPassData( c, data )
             }
         }
    }

    void updateChannel( MPKChannel *c, void *data )
    {
         ...
         while( (data = mpkChannelNextData( c )) != NULL )
         {
             render( data );
         }
    }


mpkConfigFrameFlush forces a flush of the input buffer to the config's frame data queue, filled using the function mpkConfigFrameData(). The size of the buffer can be set using mpkGlobalSetAttributei() for attribute MPK_CONFIG_FRAME_CACHE_SIZE prior mpkConfigNew().

File Format/Defaults

config {
  # config FIELDS description
 
 name"config-name"
 runonprocessor-id
 
 modestereo-mode
 mono"shell-command"
 stereo"shell-command"
 
  # config PIPES description
 
 pipe { pipe-1 description }
 pipe { pipe-2 description }
 ... 
 
  # config COMPOUNDS description
 
 compound { compound-1 description }
 compound { compound-2 description }
 ... 

}

Notes

stereo-mode description accepts only the following File Format identifiers : mono [default] and stereo.

On machines with small hardware counters the timer counter wraps. MPK detects this overflow, but assumes that only one overflow happened. If the time needed for one frame is very long (around one minute), the timer interface may behave incorrect on this machines. See the clock_gettime(2) man page for further details.

See also

MPKChannel, MPKCompound, MPKEvent, MPKPipe, MPKWindow