Multipipe SDK 3.2 Reference

Name

MPKChannel - MPKChannel functional interface.

Header File

#include <mpk/channel.h>

Synopsis

Creating and Destroying

MPKChannel* mpkChannelNew(void );
void mpkChannelDelete(MPKChannel* channel);

Fields Access

void mpkChannelSetName(MPKChannel* c, char* name);
const char* mpkChannelGetName(MPKChannel* c);
void mpkChannelSetUserData(MPKChannel* channel, void* userData);
void* mpkChannelGetUserData(MPKChannel* c);
void mpkChannelSetViewport(MPKChannel* c, float vp[4]);
void mpkChannelGetViewport(MPKChannel* c, float vp[4]);
void mpkChannelSetNearFar(MPKChannel* c, float n, float f);
void mpkChannelGetNearFar(MPKChannel* c, float* n, float* f);
MPKConfig* mpkChannelGetConfig(MPKChannel* c);
MPKPipe* mpkChannelGetPipe(MPKChannel* c);
MPKWindow* mpkChannelGetWindow(MPKChannel* c);
MPKChannel* mpkChannelGetProxy(MPKChannel* c);

void mpkChannelSetProjection(MPKChannel* c, const float* origin, float distance, const float* fov, const float* hpr);
int mpkChannelGetProjection(MPKChannel* c, float* origin, float* d, float* fov, float* hpr);
void mpkChannelSetWall(MPKChannel* c, const float bl[3], const float br[3], const float tl[3]);
int mpkChannelGetWall(MPKChannel* c, float* bl, float* br, float* tl);
void mpkChannelSetOrthoWall(MPKChannel* c, const float bl[3], const float br[3], const float tl[3]);
int mpkChannelGetOrthoWall(MPKChannel* c, float* bl, float* br, float* tl);

Attributes

void mpkChannelSetAttribute(MPKChannel* channel, int attr, int value);
void mpkChannelUnsetAttribute(MPKChannel* channel, int attr);
void mpkChannelResetAttribute(MPKChannel* channel, int attr);
int mpkChannelTestAttribute(MPKChannel* channel, int attr);
int mpkChannelGetAttribute(MPKChannel* channel, int attr, int* value);

Callbacks

void mpkChannelSetDrawCB(MPKChannel* c, int which, MPKChannelDrawCB cb);

MPKChannelDrawCB mpkChannelGetDrawCB(MPKChannel* c, int which);
void mpkChannelSetCullCB(MPKChannel* c, int which, MPKChannelCullCB cb);

MPKChannelCullCB mpkChannelGetCullCB(MPKChannel* c, int which);

Operations

void mpkChannelApplyBuffer(MPKChannel* c);
void mpkChannelApplyViewport(MPKChannel* c);
void mpkChannelApplyNearFar(MPKChannel* c, float n, float f);
void mpkChannelApplyFrustum(MPKChannel* c);
void mpkChannelApplyHeadTransform(MPKChannel* c);
void mpkChannelApplyViewTransform(MPKChannel* c);
void mpkChannelApplyOrtho(MPKChannel* c, int orthomode, const float zoom[2]);
void mpkChannelGetOrtho(MPKChannel* c, int orthomode, const float zoom[2], float ortho[6], float xform[16]);
void mpkChannelGetFrustum(MPKChannel* c, int eye, float frust[6], float xform[16]);
int mpkChannelGetEye(MPKChannel* c);
void mpkChannelGetPixelViewport(MPKChannel* c, int* pvp);
void mpkChannelUpdatePixelViewport(MPKChannel* c);
int mpkChannelGetRange(MPKChannel* c, float* range);

Custom Assembly

void mpkChannelPushGLState(MPKChannel* c, int state);
void mpkChannelPopGLState(MPKChannel* c);
void mpkChannelAssembleFrame(MPKChannel* c, MPKFrame* frame);
void mpkChannelDrawImage(MPKChannel* channel, MPKImage* image, float region[4]);

Adaptive Readback

void mpkChannelDeclareROI(MPKChannel* c, float region[4]);
void mpkChannelReadFrame(MPKChannel* c, MPKFrame* frame, float region[4]);

Performer Integration

pfChannel* mpkChannelGetPfChannel(MPKChannel* c);

Culling

void* mpkChannelNextData(MPKChannel* channel);
int mpkChannelCheckData(MPKChannel* channel);
void mpkChannelPassData(MPKChannel* channel, void* data);
void mpkChannelFlushData(MPKChannel* channel);
void mpkChannelPutData(MPKChannel* channel, void* data);

Description

The MPKChannel data structure essentially describes a viewport in an MPKWindow. The corresponding projection rectangle can be specified in real-world coordinates via mpkChannelSetWall or mpkChannelSetProjection. The application can then be written independently from the current stereo pass, from the viewer's head-position and from the decomposition specified by the current MPKCompound.

This genericity is illustrated by the typical code below :


    main( int argc, char *argv[] )
    {
        ...
        mpkConfigSetChannelInitCB( config, initChannel );
        ...
        mpkConfigInit( config );
        while ( !exit ) {
            ...
            mpkConfigSetHeadPosition( config, head.position );
            mpkConfigFrame( config, framedata );
        }
    }

    void initChannel( MPKChannel *c )
    {
        mpkChannelSetDrawCB(c, MPK_CHANNEL_DRAWCB_INIT, loadChannel);
        mpkChannelSetDrawCB(c, MPK_CHANNEL_DRAWCB_CLEAR, clearChannel);
        mpkChannelSetDrawCB(c, MPK_CHANNEL_DRAWCB_UPDATE, updateChannel);
        mpkChannelSetNearFar( c, 0.001, 100.0 );
    }

    void loadChannel( MPKChannel *c, void *framedata )
    {
        myLoadTextures( framedata );
    }

    void clearChannel( MPKChannel *c, void *framedata )
    {
        mpkChannelApplyBuffer(c);
        mpkChannelApplyViewport(c);

        glClear( GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT );
    }

    void updateChannel( MPKChannel *c, void *framedata )
    {
        glMatrixMode( GL_PROJECTION );
        glLoadIdentity();
        mpkChannelApplyFrustum(c);

        glMatrixMode( GL_MODELVIEW );
        glLoadIdentity();
        mpkChannelApplyHeadTransform(c);

        myDrawData( framedata );
    }

Function descriptions

Creating and Destroying

mpkChannelNew creates and returns a handle to an MPKChannel.

mpkChannelDelete deletes the passed MPKChannel.
Fields Access

mpkChannelSetName sets the name of the passed MPKChannel to name. This is done by copy and not by reference.

mpkChannelGetName returns the name of the passed MPKChannel.

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

mpkChannelGetUserData enables the application to retrieve the passthrough data specified by mpkChannelSetUserData().

mpkChannelSetViewport sets the fractional viewport values of the passed MPKChannel to the values pointed to by vp.

mpkChannelGetViewport reads the fractional viewport values of the passed MPKChannel in vp.

mpkChannelSetNearFar sets the near and far distances of the passed MPKChannel's frustum to the arguments n and f.

mpkChannelGetNearFar reads the near and far distances of the passed MPKChannel's frustum.

mpkChannelGetConfig returns the MPKChannel's parent configuration.

mpkChannelGetPipe returns the MPKChannel's parent pipe.

mpkChannelGetWindow returns the MPKChannel's parent window.

mpkChannelGetProxy returns the MPKChannel's Xinerama meta channel, or NULL if this channel in not a channel of a Xinerama base window.

mpkChannelSetProjection sets the MPKChannel's physical layout.

Here the channel is assimilated to the rectangle which would be produced by a hypothetical projection system located at origin, in the attitude characterized by the hpr angles, and projecting orthogonally onto a wall situated at distance. The horizontal and vertical fields of view of this projector are specified by the argument fov.


    projection {
        origin      [ 0., 0., 0. ]
        distance    3.
        fov         [ 54., 47. ]
        hpr         [ 0., 0., 0. ]   # CENTRE WALL
        # hpr       [  50., 0., 0. ] # LEFT WALL
        # hpr       [ -50., 0., 0. ] # RIGHT WALL
    }

mpkChannelApplyFrustum() will use the last specified wall or projection description to compute its OpenGL frustum and modeling transformation.

mpkChannelGetProjection enables the application to retrieve the data specified by mpkChannelSetProjection().

mpkChannelSetWall describes the physical layout of the passed MPKChannel providing the real-world coordinates of the bottom-left, bottom-right and top-left corners of its projection rectangle.


     # 80cm x 60cm screen located 1m in front of the viewer

     wall {
         bottom_left     [ -.4, -.3, -1. ]
         bottom_right    [  .4, -.3, -1. ]
         top_left        [ -.4,  .3, -1. ]
     }

mpkChannelApplyFrustum() will use the last specified wall or projection description to compute its OpenGL frustum and modeling transformation.

mpkChannelGetWall enables the application to retrieve the data specified by mpkChannelSetWall().

mpkChannelSetOrthoWall specifies an alternate wall description, to be used by mpkChannelApplyOrtho() to compute its OpenGL ortho and modeling transformation.

mpkChannelGetOrthoWall enables the application to retrieve the data specified by mpkChannelSetOrthoWall().
Attributes

See the MPKGlobal man page for a description of all MPKChannel attributes and their default or possible values.

mpkChannelSetAttribute sets the value of the MPKChannel attribute specified by attr to value.

mpkChannelUnsetAttribute unsets the attribute specified by attr or, if attr is MPK_CATTR_ALL, unsets all attributes for the passed MPKChannel.

mpkChannelResetAttribute resets the attribute specified by attr to its corresponding default value or, if attr is MPK_CATTR_ALL, it resets all attributes for the passed MPKChannel to their default value.

mpkChannelTestAttribute returns 1 if the attribute specified by attr is set for the passed MPKChannel, 0 otherwise.

mpkChannelGetAttribute reads the current value of the attribute specified by attr and returns 1 if the attribute is set for the passed MPKChannel, 0 otherwise.
Callbacks

mpkChannelSetDrawCB sets the MPKChannel draw callback specified by which to the passed function, of type:

void (*MPKChannelDrawCB)(MPKChannel*, void*);

Accepted values for which are

MPK_CHANNEL_DRAWCB_INIT, MPK_CHANNEL_DRAWCB_CLEAR or MPK_CHANNEL_DRAWCB_UPDATE

mpkChannelGetDrawCB returns the MPKWindow draw callback function specified by which.

mpkChannelSetCullCB sets the MPKChannel cull callback specified by which to the passed function, of type :

void (*MPKChannelCullCB)(MPKChannel*, void*);

Accepted values for which are

MPK_CHANNEL_CULLCB_INIT, MPK_CHANNEL_CULLCB_UPDATE

mpkChannelGetCullCB returns the MPKWindow cull callback function specified by which.
Operations

mpkChannelApplyBuffer applies the current GL_DRAW_BUFFER and GL_READ_BUFFER for the passed MPKChannel with respect to the current stereo mode and eye pass.

mpkChannelApplyViewport applies the current OpenGL viewport and scissor area for the passed MPKChannel. The channel's pixel viewport is computed from the parent window's pixel viewport (ie. width and height) and channel's fractional viewport using the formula:


   #define IRND(a) ((int)((a)+.5))

   // compute first pixel position of the channel
   channel.pvp[0] = IRND(channel.vp[0] * window.pvp[2]);
   channel.pvp[1] = IRND(channel.vp[1] * window.pvp[3]);

   // compute last pixel position of the channel
   channel.pvp[2] = IRND((channel.vp[0]+channel.vp[2]) * window.pvp[2]);
   channel.pvp[3] = IRND((channel.vp[1]+channel.vp[3]) * window.pvp[3]);

   // compute channel's dimension
   channel.pvp[2] -= channel.pvp[0];
   channel.pvp[3] -= channel.pvp[1];

This method honors positions over dimensions in order to ensure adjacency whenever possible, e.g. in a 1280x1024 window :


    vp(1): [0.     0. 0.3333 1. ]    pvp(1): [0   0 427 1024]
    vp(2): [0.3333 0. 0.3333 1. ]    pvp(2): [427 0 426 1024]

Note that in full-screen stereo mode (type "rect") during the left eye pass the value of the MPKGlobal variable MPK_DATTR_FULLSTEREO_OFFSET will be added to channel.pvp[1]

mpkChannelApplyNearFar applies the n and f distances used for the following frustum or ortho operations. This function can be used to dynamically adjust the near and far distance from the channel update callbacks.

mpkChannelApplyFrustum applies an OpenGL frustum matrix for the passed MPKChannel with respect to the current eye pass, eye position and latest layout from mpkChannelSetWall() or mpkChannelSetProjection().

mpkChannelApplyHeadTransform applies the modeling transformation needed to position and orient the viewing pyramid specified by the latest call to mpkChannelApplyFrustum() or mpkChannelApplyOrtho(). mpkChannelApplyHeadTransform replaces the deprecated function mpkChannelApplyTransformation().

mpkChannelApplyViewTransform applies the view transformation needed to position and orient the viewer in the current scene.

mpkChannelApplyOrtho provides an alternative to mpkChannelApplyFrustum() as it applies an OpenGL orthographic matrix for the passed MPKChannel.

mpkChannelApplyOrtho uses the layout given by mpkChannelSetOrthoWall() if one has been, otherwise it will use the latest layout specified via mpkChannelSetWall() or mpkChannelSetProjection().

If orthomode is MPK_ORTHO_STILL, then mpkChannelApplyOrtho simply uses the half-width and half-height dimensions of the channel layout to produce the distances used in glOrtho(3G).

Otherwise, if orthomode is MPK_ORTHO_TRACKED, then mpkChannelApplyOrtho uses the current view direction (e.g. from mpkConfigSetHeadOrientation) in order to produce consistent viewing across all the config's channels.

The argument zoom, if not NULL, specifies two-dimensional scaling on the X and Y Screen coordinates.

mpkChannelGetOrtho retrieves the MPKChannel's complete orthographic transformation, ie. so that the following code sequence :


    mpkChannelGetOrtho(c, orthomode, zoom, ortho, xform); 
    glOrtho( ortho[0], ortho[1], ortho[2], ortho[3], ortho[4], ortho[5] );
    glMultMatrixf( xform );

is completely equivalent to :


    mpkChannelApplyOrtho(c, orthomode, zoom);
    mpkChannelApplyHeadTransform(c);


mpkChannelGetFrustum retrieves the MPKChannel's complete frustum transformation, ie. so that the following code sequence :


    mpkChannelGetFrustum(c, mpkChannelGetEye(), frust, xform);
    glFrustum(frust[0], frust[1], frust[2], frust[3], frust[4], frust[5]);
    glMultMatrixf( xform );

is completely equivalent to :


    mpkChannelApplyFrustum(c);
    mpkChannelApplyHeadTransform(c);


mpkChannelGetEye returns the current eye pass of the channel update, ie. returns MPK_EYE_CYCLOP in mono mode, MPK_EYE_LEFT or MPK_EYE_RIGHT if the channel is rendered in stereo mode.

mpkChannelGetPixelViewport reads the latest updated pixel viewport for the passed MPKChannel in pvp.

mpkChannelUpdatePixelViewport forces update of the MPKChannel's pixel viewport from its parent window's pixel viewport (ie. width and height) and channel's fractional viewport. See above mpkChannelApplyViewport() for how these computations are done.

Note that in full-screen stereo mode (type "rect") during the left eye pass the value of the MPKGlobal variable MPK_DATTR_FULLSTEREO_OFFSET will be added to the vertical pixel viewport coordinate.

mpkChannelGetRange reads the range values of the passed MPKChannel if this is relevant, returning 0 otherwise. The range of a MPKChannel is inherited at rendering time from the currently overriding MPKCompound. This information should then be used to render only a portion of the database, e.g. :


    mpkChannelGetRange(c,range) )
    DrawDatabase( range[0], range[1] );

Note that the range of an MPKCompound is specified relatively to its hierarchy, whereas the MPKChannel inherits absolute values.
Custom Assembly

mpkChannelPushGLState pushes the current OpenGL matrices and attributes to the stack and set's up the state to perform one of the following operations:


    MPK_PIXEL_OPERATION     sets up the projection matrix to
                            perform drawing of input frames


mpkChannelPopGLState pops the last OpenGL matrices and attributes from the stack.

mpkChannelAssembleFrame assembles a frame into the specified MPKChannel, as described in the pseudo code below.


     if frame format has depth bit set
         enable depth test
         draw all depth images using mpkChannelDrawImage()
         disable depth test

     if frame format has color bit set
         draw all color images using mpkChannelDrawImage()

     if frame format has stencil bit set
         draw all stencil images using mpkChannelDrawImage()


mpkChannelDrawImage draw the image into the region of channel.
Adaptive Readback

mpkChannelDeclareROI declares the region which was updated during the current channel update draw callback. Among other optimisations, the default compound read output callback mpkCompoundReadOutputFrame() will only read the specified region. The region is interpreted as ( x, y, width, height ), and the area it describes has to be clipped to [0, 0] - [1, 1].

mpkChannelDeclareROI should only be called from the channel update draw callback.

mpkChannelReadFrame read the channel's framebuffer content into frame.

frame can be obtained by using the function mpkCompoundGetOutputFrame(). region specifies the 2D fractional viewport to be read into frame with respect to the channel c viewport.

The function reallocates new images buffers in the passed frame if they are not big enough for reading the region.
Performer Integration

mpkChannelGetPfChannel returns the Performer channel used internally by the MPKChannel whenever the execution mode MPK_EXECUTION_PERFORMER is used.
Culling

mpkChannelNextData returns the next item from the input queue. The items received from mpkChannelNextData are either produced by mpkConfigFrameData(), mpkChannelPassData() or mpkChannelPutData(), depending on how channel is involved in the configuration. Please see the MPKCompound documentation for further explanations on culling.

This function should only be called from the update cull or update draw callback.

mpkChannelCheckData returns a positive value if items are available on the input queue, 0 otherwise.

This function should only be called from the update cull or update draw callback.

mpkChannelPassData adds an item to the output queue.

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().

This function should only be called from the update cull callback.

mpkChannelFlushData forces a flush of the input buffer to the output queue, filled using the function mpkChannelPassData(). The size of the buffer can be set using mpkGlobalSetAttributei() for attribute MPK_CHANNEL_PASS_CACHE_SIZE prior mpkChannelNew().

This function should only be called from the update cull callback.

mpkChannelPutData adds an item to the input queue. This function can be used to put back items to the input queue, in order to enable parallelization between multiple cull processes. The following pseudo-code illustrates one usage:


     while( data = mpkChannelNextData( channel ))
     {
         switch( visiblity( frustum, data ))
         {
             case FULL_VISIBLE:    // draw whole tree
                 mpkChannelPassData( channel, data );
                 break;
                 
             case PARTIAL_VISIBLE: // re-test each subtree
                 foreach child of data
                     mpkChannelPutData( channel, child );
                 break;
                 
             case NOT_VISIBLE:     // discard
                 break;
         }
     }

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().

This function should only be called from the update cull callback.

File Format/Defaults

1. MPKChannel File Format specification :

channel {
  # channel FIELDS description
 
 name"channel-name"
 viewport[ xf, yf, wf, hf ]
 
  # channel WALL or PROJECTION description
 
 wall{ channel-wall description }
 projection{ channel-projection description }
 
  # channel ORTHO-WALL description
 
 ortho-wall{ channel-ortho-wall description }

}

2. MPKChannel-wall File Format specification :

wall {
 bottom_left[ x, y, z ]
 bottom_right[ x, y, z ]
 top_left[ x, y, z ]

}

3. MPKChannel-projection File Format specification :

projection {
 origin[ x, y, z ]
 distancevalue
 fov[ horizontal, vertical ]
 hpr[ head, pitch, roll ]

}

4. MPKChannel-ortho-wall File Format specification :

ortho-wall {
 bottom_left[ x, y, z ]
 bottom_right[ x, y, z ]
 top_left[ x, y, z ]

}

Notes

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

See also

MPKCompound, MPKGlobal, MPKWindow