Multipipe SDK 3.2 Reference

Name

MPKCompound - MPKCompound functional interface.

Header File

#include <mpk/compound.h>

Synopsis

Creating and Destroying

MPKCompound* mpkCompoundNew(void );
void mpkCompoundDelete(MPKCompound* compound);

Traversal

void mpkCompoundTraverseAll(MPKCompound* compound, MPKCompoundCB preCB, MPKCompoundCB leafCB, MPKCompoundCB postCB, void* userdata);
void mpkCompoundTraverseActive(MPKCompound* compound, MPKCompoundCB preCB, MPKCompoundCB leafCB, MPKCompoundCB postCB, void* data);
void mpkCompoundTraverseCurrent(MPKCompound* compound, MPKCompoundCB preCB, MPKCompoundCB leafCB, MPKCompoundCB postCB, void* data);

Fields Access

void mpkCompoundSetMode(MPKCompound* compound, int mode, int flags);
void mpkCompoundGetMode(MPKCompound* compound, int* mode, int* flags);
void mpkCompoundSetOperation(MPKCompound* compound, int operation);
int mpkCompoundGetOperation(MPKCompound* compound);
void mpkCompoundSetName(MPKCompound* compound, char* name);
const char* mpkCompoundGetName(MPKCompound* compound);
void mpkCompoundSetSplit(MPKCompound* compound, char* split);
const char* mpkCompoundGetSplit(MPKCompound* compound);
void mpkCompoundSetDisplayName(MPKCompound* compound, char* name);
const char* mpkCompoundGetDisplayName(MPKCompound* compound);
void mpkCompoundSetChannel(MPKCompound* compound, MPKChannel* c);
MPKChannel* mpkCompoundGetChannel(MPKCompound* compound);
void mpkCompoundSetViewport(MPKCompound* compound, float* vp);
void mpkCompoundGetViewport(MPKCompound* compound, float* vp);
void mpkCompoundSetEye(MPKCompound* compound, int eye);
int mpkCompoundGetEye(MPKCompound* compound);
void mpkCompoundSetFormat(MPKCompound* compound, int format);
int mpkCompoundGetFormat(MPKCompound* compound);
void mpkCompoundSetRange(MPKCompound* compound, float range[2]);
void mpkCompoundGetRange(MPKCompound* compound, float range[2]);
int mpkCompoundNChildren(MPKCompound* c);
MPKCompound* mpkCompoundGetChild(MPKCompound* c, int i);
void mpkCompoundAddChild(MPKCompound* compound, MPKCompound* child);
int mpkCompoundRemoveChild(MPKCompound* c, MPKCompound* child);
MPKCompound* mpkCompoundGetNext(MPKCompound* c);
MPKCompound* mpkCompoundGetParent(MPKCompound* c);
MPKConfig* mpkCompoundGetConfig(MPKCompound* c);
MPKCompound* mpkCompoundFindChild(MPKCompound* c, const char* name);
void mpkCompoundSetUserData(MPKCompound* compound, void* userData);
void* mpkCompoundGetUserData(MPKCompound* c);

Custom Compound Interface

MPKFrame* mpkCompoundGetAssemblyFrame(MPKCompound* compound, int i);
void mpkCompoundPreAssemble(MPKCompound* compound, void* data);
void mpkCompoundPostAssemble(MPKCompound* compound, void* data);

Adaptive Readback Interface

MPKFrame* mpkCompoundGetOutputFrame(MPKCompound* compound);
void mpkCompoundReadOutputFrame(MPKCompound* compound);

Custom Compound Clear Interface

void mpkCompoundClear(MPKCompound* compound, void* data);

Description

The MPKCompound data structure is essentially a container for children of MPKCompound, each associated with an existing MPKChannel. The rendering of the top-most MPKChannel in the hierarchy will be parallelized among the child channels, by either:


Recomposition of the destination channel's image is done automatically, and can be customised using the Custom Assembly interface.

Drawing and Culling

The operation field of the MPKCompound data structure defines what tasks are executed. Given the following compound specification:


    compound {
        mode     [ CULL ]
        channel  "dest"

        region { cull channel "cull" }
        region { draw channel "dest" }
    }

MPK would invoke the associated update cull callback on the channel "cull", and the update draw callback on channel "dest". These two operations are executed in parallel, if the two channels are associated to two different rendering threads.

The default operation is cull-draw, ie. MPK invokes first the update cull callback, and then the update draw callback on each leaf node.

The operation mode can be set using mpkCompoundSetOperation() The functions mpkConfigFrameData(), mpkChannelNextData(), mpkChannelCheckData(), mpkChannelPassData() and mpkChannelPutData() provide a generic mechanism to pass data through the application.

In the specification above, data passed from the update cull callback of the channel "cull" will be available in the update draw callback of channel "draw". Likewise, the data available to the update cull callback of channel "cull" originates from the application.

Custom Assembly

The purpose of the MPK custom compound interface is to allow customization of the MPK compound pre- and post- assembly pass.

Given the following compound specification:


    compound {

        mode [2D]
        channel "destination"

        region {
            viewport [ 0. 0. .5 1. ]
            channel  "source::0"
        }

        region {
            viewport [ .5 0. .5 1. ]
            channel  "source::1"
        }
     }

This compound specification corresponds to the following tree:


                     "destination"
                           o
                           |
                +----------+----------+
                |                     |
                |                     |
                o                     o
            "source::0"           "source::1"

Upon mpkConfigFrameBegin() each MPK window thread traverses the config's compound tree[s] and updates each compound whose channel belongs to the window: if the compound is a leaf node then MPK invokes the user-specified clear and update callbacks on the associated [source] channel. Otherwise, ie. if the compound is not a leaf node, then MPK assembles the frames output from the compound children into its associated [destination] channel.

This traversal actually occurs in several passes:

  1. clear all source channels
  2. invoke pre-assemble callback on all destination channels using top-bottom, left-right traversal order. Example of pre-assemble callback is the above 2D-decomposition in mode ASYNC: then the images output from the source channels during last frame are assembled in the destination channel prior to any rendering.
  3. update source channels (user-specified clear and update CB)
  4. invoke post-assemble callbacks on all destination channels using bottom-up, left-right traversal order. Example of post-assemble callback is the above 2D-decomposition in mode not ASYNC: then the images from the source channels are assembled in the destination channel during the same frame, as soon as they have been produced.

Neither the pre- nor post- assemble callback are invoked if any of the following conditions are true:


The default pre- and post-assemble callbacks do not perform any assembly if the following conditions are true:


If the compound channel is identical to its parent channel then no output frame is generated for this compound.

The functions mpkConfigSetCompoundPreAssembleCB() and mpkConfigSetCompoundPostAssembleCB() are used to specify the pre- or post- assemble compound callbacks.

Adaptive readback

This interface enables the programmer to customize the frame buffer readback of a compound input channel. The default callback, mpkCompoundReadOutputFrame(), uses the information provided by mpkChannelDeclareROI() to optimize the data to be read back, transported and assembled during compound operations, using mpkChannelReadFrame() on the handle returned by mpkCompoundGetOutputFrame().

Custom Compound Clear

The compound clear callback is invoked on all destination compounds. The default callback, mpkCompoundClear(), only clears the framebuffer in special cases for example, when the adaptive readback callback is used. This callback should only be customized if really necessary since mpkCompoundClear() optimizes the clear as extensively as possible. The compound clear callback can be specified using the function mpkConfigSetCompoundClearCB().

Function descriptions

Creating and Destroying

mpkCompoundNew creates and returns a handle to an MPKCompound.

mpkCompoundDelete deletes the pass MPKCompound.
Traversal

The following functions provide a general mechanism for traversing a compound hierarchy in a top-to-bottom, left-to-right order.


 typedef int (*MPKCompoundCB)( MPcompound *, void *userdata );

 void mpkCompoundTraverseAll(MPKCompound *, MPKCompoundCB preCB,
         MPKCompoundCB leafCB, MPKCompoundCB postCB, void *userdata );
 void mpkCompoundTraverseActive(MPKCompound *, MPKCompoundCB preCB,
         MPKCompoundCB leafCB, MPKCompoundCB postCB, void *userdata );
 void mpkCompoundTraverseCurrent(MPKCompound *, MPKCompoundCB preCB,
         MPKCompoundCB leafCB, MPKCompoundCB postCB, void *userdata );

The leafCB function will be applied only on the leaf nodes of the compound tree, ie. on compounds without any children. The preCB and postCB functions will be applied when traversing parent compounds.

The return values must be either MPK_TRAV_CONT, MPK_TRAV_PRUNE or MPK_TRAV_TERM to indicate that the traversal should continue, skip this node or terminate, respectively. MPK_TRAV_PRUNE is equivalent to MPK_TRAV_CONT for the postCB function.

mpkCompoundTraverseAll will traverse all children of the specified MPKCompound, regardless of any state information.

mpkCompoundTraverseActive will only traverse the active children of the passed MPKCompound with respect to the current stereo mode.

mpkCompoundTraverseCurrent will only traverse the active and current children of the passed MPKCompound with respect to the current stereo mode and current DPLEX cycle.
Fields Access

mpkCompoundSetMode sets the passed MPKCompound's mode attributes.

id characterizes the decomposition mode, and accepts the following values: MPK_COMPOUND_2D, MPK_COMPOUND_3D, MPK_COMPOUND_DB, MPK_COMPOUND_FSAA, MPK_COMPOUND_EYE, MPK_COMPOUND_HMD, MPK_COMPOUND_DPLEX and MPK_COMPOUND_CULL.

flags specifies additional flags for the compound mode. Currently, the following flags can be specified:


MPK_COMPOUND_MONO       compound is active in mono mode.
MPK_COMPOUND_STEREO     compound is active in stereo mode.
MPK_COMPOUND_ASYNC      compound execution is asynchronous (1).
MPK_COMPOUND_ADAPTIVE   compound is automatically load balanced (2).
MPK_COMPOUND_NOCOPY     compound and subtree pixel transfer is disabled.
MPK_COMPOUND_HW         use hardware for composition (3).

(1)

The MPK_COMPOUND_ASYNC flag specifies that the passed MPKCompound execution mode must be asynchronous, ie. that recomposition and all destination channel's rendering should be postponed by one frame, eg.:


   mode=2D         Dest. Channel        Source Channel[s]   
 __________________________________________________________

   Frame N         DrawPixels[N-1]      Render[N]          
                   Render[N-1]          .                  
                   .                    .                  
                   .                    .                  
                   .                    ReadPixels[N]            
 __________________________________________________________

   Frame N+1       DrawPixels[N]        Render[N+1]        
                   Render[N]            .                  
                   .                    .                  
                   .                    .                  
                   .                    ReadPixels[N+1]

Asynchronous execution provides in general better performances by providing better load balancing and by serializing the transfers on the bus.

(2)

For the compound modes 2D, DB and 3D, all children of this compound will be automatically load balanced by MPK. The load balancing algorithm is using the times needed by all children to render the destination channel's last frame to compute the distribution for the next frame. Note that this approach improves rendering performance for most cases, in some cases static decomposition may provide better results. It is recommended the all source channels have at least the size of the destination channel. The function mpkCompoundSetSplit() can be used to define the tiling scheme or z-axis split of an adaptive compound.

(3)

The current support modes for hardware composition are MPK_COMPOUND_DPLEX, MPK_COMPOUND_FSAA, MPK_COMPOUND_EYE and MPK_COMPOUND_2D. For DPlex hardware compositing support you need the Onyx2 DPLEX Option Hardware properly installed. For 2D, EYE and FSAA hardware compositing support you need the Scalable Graphics Compositor.

mpkCompoundGetMode reads the passed MPKCompound's mode attributes in the passed arguments which are not set to NULL.

mpkCompoundSetOperation sets the compound operation to MPK_COMPOUND_OP_DRAW, MPK_COMPOUND_OP_CULL, MPK_COMPOUND_OP_CULLDRAW or MPK_UNDEFINED.

The operation specifies which callbacks are invoked when this compound is updated. If the operation is MPK_UNDEFINED, the operation is inherited from the parent compound, or set to MPK_COMPOUND_OP_CULLDRAW if compound has no parent.

mpkCompoundGetOperation returns the operation of compound.

mpkCompoundSetName sets the name of the passed MPKCompound to name. This is done by copy and not by reference.

mpkCompoundGetName returns the name of the passed MPKCompound.

mpkCompoundSetSplit sets the split string of the passed MPKCompound to split. This is done by copy and not by reference. The split string defines the tiling scheme or z-axis split for adaptive compounds. See the File Format section for the split string syntax.

mpkCompoundGetSplit returns the split string of the passed MPKCompound.

mpkCompoundSetDisplayName sets the display name of the passed MPKCompound to name. This is done by copy and not by reference. The display name is used for setting up hardware compounds to be used with Xinerama in full overlap mode. For more information about scalable graphics hardware read the MPK User's Guide.

mpkCompoundGetDisplayName returns the display name of the passed MPKCompound.

mpkCompoundSetChannel specifies the MPKChannel to be used by the passed MPKCompound for rendering. The first channel specified in the hierarchy constitutes the destination channel of the subtree below, ie. the channel conditioning the final frame.

mpkCompoundGetChannel returns the MPKCompound's channel.

mpkCompoundSetViewport sets a 2D-compound's fractional viewport with respect to its destination MPKChannel and relatively to its parent MPKCompound, if any.

mpkCompoundGetViewport reads the compound's fractional viewport in vp.

mpkCompoundSetEye specifies the eye selection of an EYE or HMD compound, one of MPK_EYE_LEFT, MPK_EYE_RIGHT or MPK_EYE_CYCLOP.

mpkCompoundGetEye returns the eye selection of the passed MPKCompound.

mpkCompoundSetFormat specifies the format of the pixels to be transferred within the MPKCompound's hierarchy. format should be a bitwise combination of MPK_COLOR_BIT, MPK_DEPTH_BIT, MPK_STENCIL_BIT.

mpkCompoundGetFormat returns the passed MPKCompound's format, as a bitwise combination of MPK_COLOR_BIT, MPK_DEPTH_BIT, MPK_STENCIL_BIT.

mpkCompoundSetRange sets the two-dimensional range of the passed MPKCompound, as a fraction of its parent's range.

mpkCompoundGetRange reads the MPKCompound's two-dimensional range, relatively to its parent's range. The absolute "range" information can be retrieved by the application at rendering time via mpkChannelGetRange(), for the relevant portion of the database to be rendered accordingly.

mpkCompoundNChildren returns the number of MPKCompound children of the passed MPKCompound.

mpkCompoundGetChild returns the ith child of the passed MPKCompound.

mpkCompoundAddChild appends child to the list of children for the passed MPKCompound.

mpkCompoundRemoveChild searches for child in the list of children for the passed MPKCompound and removes it from the list if it is found.

mpkCompoundGetNext returns the sibling compound of an MPKCompound.

mpkCompoundGetParent returns the parent compound of an MPKCompound, or NULL if it is a top-level MPKCompound.

mpkCompoundGetConfig returns the parent config of an MPKCompound.

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

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

mpkCompoundGetUserData enables the application to retrieve the passthrough data specified by mpkCompoundSetUserUserData().
Custom Compound Interface

mpkCompoundGetAssemblyFrame returns the ith frame from the compound assembly list for the current stereo eye pass. This function should only be called from the config's compound pre- or post- assemble callback. If compound mode is 2D, DB or CULL then i matches the child index responsible for the frame (e.g. the returned frame may then be NULL if both child and parent channels are identical). For other modes i should be 0.

mpkCompoundPreAssemble takes the images output from the source channels during last frame and assembles them in the destination channel prior to any rendering. MPK sets the compound pre-assemble callback by default to this function. It does something only if the ASYNC compound mode flag is set.

mpkCompoundPostAssemble takes the images from the source channels as soon as they have been produced and assembles them in the destination channel during the same frame. MPK sets the compound post-assemble callback by default to this function. It does something only if the ASYNC compound mode flag is not set.
Adaptive Readback Interface

mpkCompoundGetOutputFrame returns the compound's current output frame. This function should only be called from the config's compound adaptive readback callback.

mpkCompoundReadOutputFrame executes the default adaptive readback callback.
Custom Compound Clear Interface

mpkCompoundClear executes the default clear callback. This callback is invoked on all destination compounds. This function only clears the framebuffer in special cases, for example when the adaptive readback callback is used.

File Format/Defaults

1. MPKCompound File Format specification:

compound {
  # compound FIELDS description
 
 name"compound-name"
 channel"compound-channel's name"
 
 mode[ compound-mode description ]
 format[ compound-format description ]
 split" compound-split description "
 
  # compound REGIONS description
 
 region { region-1 description }
 region { region-2 description }
 ... 

}

2. MPKCompound-region File Format specification:

region {
  # region FIELDS description
 
 viewport[ xf, yf, wf, hf ]
 range[ minf, maxf ]
 eyewhich
 
  # region CHANNEL or COMPOUND description
 
 channel"region-channel's name"
 compound { region-compound description }

}

viewport parameters are relative to the parent compound viewport, and therefore their values should be in the range 0.0 to 1.0

range parameters are relative to the parent compound range, and therefore their values should be in the range 0.0 to 1.0

eye field specification accepts only the following File Format identifiers: cyclop [default], left and right.

mode field specification accepts the following File Format identifiers for the mode-id: 2D, DB, 3D, FSAA, EYE, HMD, DPLEX and CULL. If none is specified, then MPK will simply synchronize the graphics update of all compound children, taking into account their respective latency. The mode's flags can be specified using the File Format identifiers ASYNC, ADAPTIVE, NOCOPY, HW, STEREO or MONO.

split field specifies the tiling scheme or z-axis split used when the compound is in ADAPTIVE mode. The split value is a string, as shown in the following example:


         split  "[[1 | 2] - [3 | 4]]"

The numbers 1, 2, 3, and 4 represent the regions in the compound (source channels). These numbers map the regions declared in the compound data structure in the order of declaration. All the regions declared in the compound data structure must be included into the split string. The axis that is split is represented by the following operators:


     |    axis x
     -    axis y 
     /    axis z

The split operators '|' and '-' can be used only with 2D compounds and the operator '/', only with 3D or DB compounds.

The formal syntax of the split field is following:


  split          "splitString"
  splitString  : [ group axis group]
  group        : region | splitString
  axis         : '|'  | '-' |  '/'
  region       : [ integer ]

Notes

See also

MPKChannel