The MPK configuration file loader allows the specification of a preprocessor through the use of the MPK_PARSER_CMD environment variable. The preprocessor command will be invoked with the configuration file name as the first argument, and its output will be parsed by the normal MPK loader. Therefore, the output of this preprocessor has to be an MPK configuration file. For example, the C preprocessor can be used to put different configurations in one ASCII file and to select one using the #define functionality.

The MPK configuration file loader is using only MPK's exposed C functional interface. Therefore, it is possible to create configurations programmatically or even write an alternate parser. The function in Example 5-1 creates a simple one-window configuration.

MPKConfig *createSimpleConfig( void )
{
    // new config
    MPKConfig *config = mpkConfigNew();
    mpkConfigSetName( config, “1-window” );
    
    // one pipe
    MPKPipe *p = mpkPipeNew();
    mpkConfigAddPipe( config, p );
    mpkPipeSetName( p, “pipe” );
    
    // one window with viewport [0.25, 0.25,0.5,0.5]
    MPKWindow *w = mpkWindowNew();
    mpkPipeAddWindow( p, w );
    mpkWindowSetName( w, “MPK: simple” );
    float vp[4] = { 0.25, 0.25, 0.5, 0.5 };
    mpkWindowSetViewport( w, vp );
    
    // one channel
    MPKChannel *c = mpkChannelNew();
    mpkWindowAddChannel( w, c );
    mpkChannelSetName( c, “channel” );
    vp[0]=0.0; vp[1]=0.0; vp[2]=1.0; vp[3]=1.0;
    mpkChannelSetViewport( c, vp );
    float bl[] = { -.5, -.5, -1},
          br[] = {.5,  -.5, -1},
          tl[] = {-.5, .5, -1};
    mpkChannelSetWall( c, bl, br, tl );
    
    // mono and stereo monitor characteristics
    mpkPipeSetAttribute( p, MPK_PATTR_STEREO_TYPE, MPK_STEREO_RECT );
} 

As described in the section “The Rendering Callbacks” in Chapter 2, the idle callback can be used to utilize the idle time in the application thread during the rendering of a frame. The exact idle time depends on a number of conditions—for example, the decomposition mode or the current viewpoint. The function mpkConfigIsIdle() can be used to optimize the usage of this idle time, as shown in Example 5-2.

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

Note that no data used in the rendering callbacks should be modified in the idle callback.

MPK currently supports two timers, MPK_TIMER_AUTO and MPK_TIMER_FRAME. By default, only the MPK_TIMER_AUTO timer is enabled. Both timers can be enabled and disabled using the functions mpkConfigTimerEnable() and mpkConfigTimerDisable(). MPK timer values are always expressed in milliseconds.

The MPK_TIMER_AUTO timer is used for automatically load-balancing DPLEX compounds. Its duration, determined by MPK, is based on the rendering time of the DPLEX children and cannot be set by the application.

The MPK_TIMER_FRAME timer is used to control the execution time of a MPKConfig frame. When the timer is enabled, mpkConfigTimerGetTime() returns the actual duration of the last MPKConfig frame. The desired minimal duration for the subsequent MPKConfig frames can be set using the function mpkConfigTimerSetTime().

MPK uses a POSIX timer to fire alarms. By default, the signal SIGALRM is used to deliver this signal. The function mpkGlobalSetTimerSignal() may be used to change this signal. When using pthread execution mode, the delivery of the timer signal has to be blocked in all threads, except the application thread. Example 5-3 shows the code used by MPK to block the timer signal in all internally created threads.

// block timer signal in this thread
if( mpkGlobalGetExecutionMode() == MPK_EXECUTION_PTHREAD )
{
    int signal = mpkGlobalGetTimerSignal();
    sigset_t set;

    sigemptyset ( &set );
    sigaddset( &set, signal );
    pthread_sigmask( SIG_BLOCK, &set, NULL );
}

MPK applications are multithreaded and may render several views and versions of the same database due to the latency imposed by some decomposition modes. Given this possibility, some types of application data have to be handled carefully. Within an MPK application, there are typically the following types of data:

MPK offers native support for compositing hardware. Eliminating the need for pixel transfers and software recomposition, this specialized hardware performs the recomposition part of an MPKCompound.

MPK provides support for the SGI Scalable Graphics Compositor. MPK handles the setup and control of the hardware by using the GLX_SGIX_hyperpipe API (see the hyperpipe(3) man page). An application written for MPK can immediatly take advantage of this hardware without having to take care of the GLX_SGIX_hyperpipe extension.

The mode flag HW is used to enable the support for DPLEX, EYE, FSAA, and 2D compounds. The mode flag NOCOPY has to be specified to disable the pixel transfer and software recomposition.

MPK provides two data structures to give access to the transported color, depth and stencil values during compound assembly:

MPKFrames for compound children can be retrieved using the function mpkCompoundGetAssemblyFrame() in the pre- and post-assemble callbacks (see the section “Custom Assembly” in Chapter 3).

---

Note: The function mpkFrameDelete() should not be called on MPKFrames acquired using mpkCompoundGetAssemblyFrame(), since these are managed by MPK.

---

The format field of an MPKFrame indicates which images it contains. The region defines the fractional viewport covered by this frame with respect to the destination channel.

The individual MPKImages for each MPKFrame can be retrieved using mpkFrameNImages() and mpkFrameGetImage(). For assembly frames, each MPKImage used has a buffer allocated, which holds the pixel data for this MPKImage. The format and type specify the attributes of the pixel data, as described in the man page glDrawPixels(3G). The size of the MPKImage defines the width and height of the pixel data stored in the buffer. The offset specifies the pixel offset with respect to the region of the parent MPKFrame or mpkChannelDrawImage(). If you change one parameter, you must ensure that the other parameters (especially, the allocated buffer) are adjusted accordingly.

The final pixel viewport for one MPKImage is computed as follows:

width = ChannelPixelViewport[2];
height = ChannelPixelViewport[3];

// compute frame's pixel viewport
MPKImagePixelViewport[0] = MPKFrameRegion[0] * width;
MPKImagePixelViewport[1] = MPKFrameRegion[1] * height;

MPKImagePixelViewport[2] = (MPKFrameRegion[0]+MPKFrameRegion[2]) * width;
MPKImagePixelViewport[3] = (MPKFrameRegion[1]+MPKFrameRegion[3]) * height;

MPKImagePixelViewport[2] -= MPKImagePixelViewport[0];
MPKImagePixelViewport[3] -= MPKImagePixelViewport[1];

// clip to image size
if ( MPKImagePixelViewport[2]  > MPKImageSize[0] )
    MPKImagePixelViewport[2] = MPKImageSize[0];
if ( MPKImagePixelViewport[3] > MPKImageSize[1] ) 
    MPKImagePixelViewport[3] = MPKImageSize[1];

// add image offset
MPKImagePixelViewport[0] += MPKImageOffset[0];
MPKImagePixelViewport[1] += MPKImageOffset[1];

Figure 5-1 illustrates a frame and an image within one channel.

Figure 5-1. A Frame and an Image within one Channel

One possible use of this interface is to do software-based composition, as described by the following pseudo code:

void assembleCB( MPKCompound *compound, void *userData )
{
    //====================
    // tile assembly frames :
    //
    // assembly images may have different positions and sizes.
    // Therefore we need to extract tiles in which the number of
    // contributing images is constant. For this we simply sort
    // all input image boundaries into xDim[] and yDim[] vectors,
    // so that 
    //
    // tile[i,j] = [ xDim[i], xDim[i+1]-1 ] x [ yDim[j], yDim[j+1]-1 ]

        for each assembly frame
            for each image (color, depth, stencil)

                compute image's xStart, xEnd, yStart, yEnd

                sorted-add xStart, xEnd to xDim vector
                sorted-add yStart, yEnd to yDim vector

            end for
        end for

    //====================
    // allocate output frame and image buffers :
    //
    // the output frame dimensions (ie. frame origin and images size)
    // corresponds to the bounding box of all tiles.
    // Note that we could also allocate a vector of output tiles, and
    // later perform tiled re-composition.
    // Note also that the image buffers must be initialized.

        allocate output frame
        set origin to xDim[0], yDim[0]

        allocate image buffers for output frame
        set output frame images to image buffers
        set size of output images to xDim[n]-xDim[0], yDim[m]-yDim[0]

        initialize image buffer values wrt depth, color, stencil
    
    //====================
    // compose output frame :
    //
    // loop over all tiles (boundaries), and
    //
    // 1. first setup a vector of flags that is indexed by frame#
    //    and imageType. Each element of the vector indicates whether
    //    the corresponding image contributes to the tile.
    //
    //  2. then we loop over all pixel coordinates within the tile
    //     and compose each assembly frame's pixel value, depending
    //     on the flag for this frame and image type.


        for each tile ( i, j )

            // flag image contributions for this tile

            for each assembly frame
                for each image (color, depth, stencil)

                    compare xStart, yStart with tile boundaries
                    set flag[frame#][imageType] accordingly

                end for
            end for

            if no image used in the tile
                continue
            end if

            // compose all contributing pixels

            for each x  ( xDim[i], ... xDim[i+1]-1 )
                for each y ( yDim[j], ... yDim[j+1]-1 )

                    for each assembly frame
                        for each image (color, depth, stencil)

                            if !flag[frame#][imageType]
                                continue
                            end if

                            compose image.pixel( x, y ) to output
                            frame's corresponding
                            image.pixel( x-xDim[0], y-yDim[0] )

                    end for
                end for

            end for
        end for
}

This section describes items to consider when you use MPK in conjunction with the following libraries:

// Set the allocation and deallocation callback functions
vzMemory::setMemoryManagementCallbacks(allocate, deallocate, NULL);

// The allocator callback function
void *allocate(size_t size, void *userData) {
   return mpkMalloc(size);
}

// The de-allocator callback function
void deallocate(void *pointer, void *userData) {
        mpkFree(pointer);
}