Multipipe SDK 3.2 Reference

Name

MPKPipe - MPKPipe functional interface.

Header File

#include <mpk/pipe.h>

Synopsis

Creating and Destroying

MPKPipe* mpkPipeNew(void );
void mpkPipeDelete(MPKPipe* pipe);

Fields Access

void mpkPipeSetName(MPKPipe* pipe, const char* name);
const char* mpkPipeGetName(MPKPipe* pipe);
void mpkPipeSetDisplayName(MPKPipe* pipe, const char* name);
const char* mpkPipeGetDisplayName(MPKPipe* pipe);
void mpkPipeSetUserData(MPKPipe* pipe, void* userData);
void* mpkPipeGetUserData(MPKPipe* pipe);
int mpkPipeNWindows(MPKPipe* pipe);
MPKWindow* mpkPipeGetWindow(MPKPipe* pipe, int i);
void mpkPipeAddWindow(MPKPipe* pipe, MPKWindow* w);
int mpkPipeRemoveWindow(MPKPipe* pipe, MPKWindow* w);
MPKConfig* mpkPipeGetConfig(MPKPipe* pipe);
MPKWindow* mpkPipeFindWindow(MPKPipe* pipe, const char* name);
MPKChannel* mpkPipeFindChannel(MPKPipe* pipe, const char* name);
MPKPipe* mpkPipeGetProxy(MPKPipe* p);

Operations

int mpkPipeInit(MPKPipe* pipe, int setmon);
void mpkPipeExit(MPKPipe* pipe);
void mpkPipeFreeze(MPKPipe* pipe, int freeze);
void mpkPipeApplyMonitor(MPKPipe* pipe);
void mpkPipeSelectInput(MPKPipe* pipe, long event_mask);

Attributes

void mpkPipeSetAttribute(MPKPipe* pipe, int attr, int value);
void mpkPipeUnsetAttribute(MPKPipe* pipe, int attr);
void mpkPipeResetAttribute(MPKPipe* pipe, int attr);
int mpkPipeTestAttribute(MPKPipe* pipe, int attr);
int mpkPipeGetAttribute(MPKPipe* pipe, int attr, int* value);

Description

The MPKPipe data structure primarily describes the rendering resources within an MPKConfig that are assigned to a given hardware rendering pipe. The pipe itself is characterized by the name of its corresponding X11 display, as well as the expected mono and stereo characteristics (full-screen vs quad-buffer, etc.) to be applied by its rendering threads (MPKWindow).

Note that the display sizes corresponding to the various stereo modes can be specified via the MPKGlobal attributes, otherwise the values returned by DisplayWidth(3X11) and DisplayHeight(3X11) will be used.

Function descriptions

Creating and Destroying

mpkPipeNew creates and returns a handle to an MPKPipe.

mpkPipeDelete deletes the passed MPKPipe.
Fields Access

mpkPipeSetName sets the name of the passed MPKPipe to name. This is done by copy and not by reference.

mpkPipeGetName returns the name of the passed MPKPipe.

mpkPipeSetDisplayName sets the display name of the passed MPKPipe to name. This is done by copy and not by reference.

mpkPipeGetDisplayName returns the display name of the passed MPKPipe.

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

mpkPipeGetUserData enables the application to retrieve the passthrough data specified by mpkPipeSetUserData().

mpkPipeNWindows returns the number of MPKWindow in passed pipe.

mpkPipeGetWindow returns the ith MPKWindow in passed pipe.

mpkPipeAddWindow appends MPKWindow w to list of windows for passed pipe.

mpkPipeRemoveWindow searches for w in list of MPKWindow for passed pipe and removes it from the list if it is found.

mpkPipeGetConfig returns the parent MPKConfig of passed pipe.

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

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

mpkPipeGetProxy returns the MPKPipe's Xinerama meta pipe, or NULL if this pipe in not a Xinerama base pipe.
Operations

mpkPipeInit launches the passed MPKPipe and spawns the MPKWindow threads. The MPKConfig initialization callbacks are invoked in the order described by the pseudo-code below :


    invoke the config's pipes initialization callback

    for each MPKWindow in the pipe
        launch the window thread, which :

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

    end for

mpkPipeInit does wait for all MPKWindow threads having entered their lifelong loop. It 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 MPKWindow initialization callback is set by default to mpkWindowCreate().

mpkPipeExit exits the passed MPKPipe and all the MPKWindow threads. The MPKConfig exit callbacks are invoked in the order described by the pseudo-code below :


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

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

    end for

    invoke the config's pipes exit callback

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

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

mpkPipeApplyMonitor executes the pipe's config monitor shell command, after having set the current X Display to pipe's display name. The previous display is restored before the function returns.

mpkPipeSelectInput loops over all windows of pipe, 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().
Attributes

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

mpkPipeSetAttribute sets the value of the MPKPipe attribute specified by attr to value.

mpkPipeUnsetAttribute unsets the attribute specified by attr or, if attr is MPK_PATTR_ALL, unsets all attributes for the passed MPKPipe.

mpkPipeResetAttribute resets the attribute specified by attr to its corresponding default value or, if attr is MPK_PATTR_ALL, it resets all attributes for the passed MPKPipe to their default value.

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

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

File Format/Defaults

pipe {
  # pipe FIELDS description
 
 name"pipe-name"
 display"display-name"
 
 attributes { attributes description }
 
  # pipe WINDOWS description
 
 window { window-1 description }
 window { window-2 description }
 ... 

}

1. MPKPipe-attributes File Format specification :

attributes {
 mono{ pipe-attribute mono description }
 stereo{ pipe-attribute stereo description }

}

2. MPKPipe-attribute-mono File Format specification :

mono {
 widthw
 heighth

}

3. MPKPipe-attribute-stereo File Format specification :

stereo {
 typestereo-type
 widthw
 heighth
 offseto

}

Notes

w, h and o must be integer.

stereo-type description accepts only the following File Format identifiers : none [default] quad, rect, top, bottom and user. If no stereo-type is specified, quad is used.

See also

MPKChannel, MPKConfig, MPKGlobal, MPKWindow