Multipipe SDK 3.2 Reference

Name

MPKWindow - MPKWindow functional interface.

Header File

#include <mpk/window.h>

Synopsis

Creating and Destroying

MPKWindow* mpkWindowNew(void );
void mpkWindowDelete(MPKWindow* window);

Fields Access

void mpkWindowSetName(MPKWindow* window, const char* name);
const char* mpkWindowGetName(MPKWindow* window);
void mpkWindowSetRunon(MPKWindow* window, int cpu);
int mpkWindowGetRunon(MPKWindow* window);
void mpkWindowSetViewport(MPKWindow* window, float vp[4]);
void mpkWindowGetViewport(MPKWindow* window, float vp[4]);
int mpkWindowNChannels(MPKWindow* window);
MPKChannel* mpkWindowGetChannel(MPKWindow* window, int i);
void mpkWindowAddChannel(MPKWindow* window, MPKChannel* c);
int mpkWindowRemoveChannel(MPKWindow* window, MPKChannel* c);
MPKPipe* mpkWindowGetPipe(MPKWindow* window);
MPKConfig* mpkWindowGetConfig(MPKWindow* window);
MPKChannel* mpkWindowFindChannel(MPKWindow* window, const char* name);
MPKWindow* mpkWindowGetProxy(MPKWindow* w);

Attributes

void mpkWindowSetAttribute(MPKWindow* window, int attr, int value);
void mpkWindowUnsetAttribute(MPKWindow* window, int attr);
void mpkWindowResetAttribute(MPKWindow* window, int attr);
int mpkWindowTestAttribute(MPKWindow* window, int attr);
int mpkWindowGetAttribute(MPKWindow* window, int attr, int* value);

Callbacks

void mpkWindowSetEventCB(MPKWindow* window, int which, MPKWindowEventCB cb);
void mpkWindowSetDrawCB(MPKWindow* window, int which, MPKWindowDrawCB cb);
void mpkWindowSetCullCB(MPKWindow* window, int which, MPKWindowCullCB cb);

MPKWindowEventCB mpkWindowGetEventCB(const MPKWindow* window, int which);
MPKWindowDrawCB mpkWindowGetDrawCB(const MPKWindow* window, int which);
MPKWindowCullCB mpkWindowGetCullCB(const MPKWindow* window, int which);

Operations

int mpkWindowInit(MPKWindow* window);
void mpkWindowExit(MPKWindow* window);
void mpkWindowFreeze(MPKWindow* window, int freeze);
void mpkWindowResize(MPKWindow* window);
void mpkWindowApplyViewport(MPKWindow* window);
void mpkWindowUpdatePixelViewport(MPKWindow* window);
void mpkWindowSetPixelViewport(MPKWindow* window, int pvp[4]);
void mpkWindowGetPixelViewport(MPKWindow* window, int pvp[4]);
int mpkWindowGetMode(MPKWindow* window);
void mpkWindowSetUserData(MPKWindow* window, void* userData);
void* mpkWindowGetUserData(MPKWindow* window);

Events

void mpkWindowSelectInput(MPKWindow* window, long event_mask);
void mpkWindowProcessEvent(MPKWindow* window, MPKEvent* event);

X11/GLX Interface

void mpkWindowCreate(MPKWindow* window);
void mpkWindowDestroy(MPKWindow* window);
void mpkWindowOpenDisplay(MPKWindow* window);
void mpkWindowCloseDisplay(MPKWindow* window);
void mpkWindowCreateDrawable(MPKWindow* window);
void mpkWindowDestroyDrawable(MPKWindow* window);
void mpkWindowMapDrawable(MPKWindow* window);
void mpkWindowCreateContext(MPKWindow* window);
void mpkWindowDestroyContext(MPKWindow* window);
int mpkWindowMakeCurrent(MPKWindow* window);
int mpkWindowMakeCurrentNone(MPKWindow* window);
void mpkWindowSwapBuffers(MPKWindow* window);
void mpkWindowSetDisplay(MPKWindow* window, Display* display);
Display* mpkWindowGetDisplay(MPKWindow* window);
void mpkWindowSetInputDisplay(MPKWindow* window, Display* display);
Display* mpkWindowGetInputDisplay(MPKWindow* window);
void mpkWindowSetParent(MPKWindow* window, XID parent);
XID mpkWindowGetParent(MPKWindow* window);
void mpkWindowSetScreen(MPKWindow* window, int screen);
int mpkWindowGetScreen(MPKWindow* window);
GLXFBConfig* mpkWindowChooseFBConfig(MPKWindow* window, int* nitems);
void mpkWindowSetFBConfig(MPKWindow* window, GLXFBConfig fbConfig);
GLXFBConfig mpkWindowGetFBConfig(MPKWindow* window);
XVisualInfo* mpkWindowChooseVisual(MPKWindow* window);
void mpkWindowSetVisual(MPKWindow* window, XVisualInfo* visInfo);
XVisualInfo* mpkWindowGetVisual(MPKWindow* window);
void mpkWindowSetPixmap(MPKWindow* window, Pixmap pixmap);
Pixmap mpkWindowGetPixmap(MPKWindow* window);
void mpkWindowSetDrawable(MPKWindow* window, XID drawable);
XID mpkWindowGetDrawable(MPKWindow* window);
void mpkWindowSetContext(MPKWindow* window, GLXContext context);
GLXContext mpkWindowGetContext(MPKWindow* window);

Description

The MPKWindow data structure primarily describes a thread within an MPKPipe, potentially associated with an X11 Drawable for rendering. After its creation by mpkWindowInit the thread loops through the following sequence:


wait for next mpkConfigFrameBegin()

if (first time)
    for each MPKChannel [of the window]
         invoke the channel's cull-init callback function
         invoke the channel's draw-init callback function
    end for
end if

invoke the window's draw-update callback function

for each MPKChannel [of the window]
    if ( in mono )
        for eye MPK_EYE_CYCLOP
            invoke the channel's cull-update callback function
            invoke the channel's draw-clear callback function
            invoke the channel's draw-update callback function
        end for
    else ( in stereo )
        for eye MPK_EYE_LEFT and eye MPK_EYE_RIGHT
            invoke the channel's cull-update callback function
            invoke the channel's draw-clear callback function
            invoke the channel's draw-update callback function
        end for
    end if
end for

synchronize mpkWindowSwapBuffers (through mpkConfigFrameEnd())

Function descriptions

Creating and Destroying

mpkWindowNew creates and returns a handle to an MPKWindow.

mpkWindowDelete deletes the passed MPKWindow.
Fields Access

mpkWindowSetName sets the name of the passed MPKWindow to name. This is done by copy and not by reference.

mpkWindowGetName returns the name of the passed MPKWindow.

mpkWindowSetRunon specifies the cpu on which to assign the passed MPKWindow thread. 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 config's runon value.

mpkWindowGetRunon return value indicates on which cpu the passed MPKWindow thread is assigned. A negative value means that the thread is free to execute on whatever processor the system deems suitable.

mpkWindowSetViewport sets the fractional viewport of the passed MPKWindow to the values pointed to by vp.

mpkWindowGetViewport reads the fractional viewport of the passed MPKWindow in vp.

mpkWindowNChannels returns the number of MPKChannel in passed window.

mpkWindowGetChannel returns the ith MPKChannel in passed window.

mpkWindowAddChannel appends c to list of channels for passed window.

mpkWindowRemoveChannel searches for c in list of MPKChannel for passed window and removes it from the list if it is found.

mpkWindowGetPipe returns the parent MPKPipe of the passed MPKWindow.

mpkWindowGetConfig returns the parent MPKConfig of the passed MPKWindow.

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

mpkWindowGetProxy returns the MPKWindow's Xinerama meta window, or NULL if this window is not a Xinerama base window.
Attributes

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

mpkWindowSetAttribute sets the value of the MPKWindow attribute specified by attr to value.

mpkWindowUnsetAttribute unsets the attribute specified by attr or, if attr is MPK_WATTR_ALL, unsets all attributes for the passed MPKWindow.

mpkWindowResetAttribute resets the attribute specified by attr to its corresponding default value or, if attr is MPK_WATTR_ALL, it resets all attributes for the passed MPKWindow to their default value.

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

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

mpkWindowSetEventCB sets the MPKWindow event callback specified by which to the passed function, of type:

void (*MPKWindowEventCB)( MPKWindow*, MPKEvent* );
Accepted values for which are

MPK_WINDOW_EVENTCB_ANY, MPK_WINDOW_EVENTCB_CONFIGURE, MPK_WINDOW_EVENTCB_EXPOSE, MPK_WINDOW_EVENTCB_KEYBOARD, MPK_WINDOW_EVENTCB_MOUSE, MPK_WINDOW_EVENTCB_BUTTON, MPK_WINDOW_EVENTCB_EXIT

The default config event callback, mpkConfigHandleEvents() is called at the end of each frame and will invoke the MPK_WINDOW_EVENTCB_ANY callback for each event received on that window.

By default the MPK_WINDOW_EVENTCB_ANY callback is set to mpkWindowProcessEvent().

mpkWindowSetDrawCB sets the MPKWindow draw callback specified by which to the passed function, of type:

void (*MPKWindowDrawCB)(MPKWindow*);
Accepted values for which are

MPK_WINDOW_DRAWCB_INIT_X, MPK_WINDOW_DRAWCB_INIT_GL, MPK_WINDOW_DRAWCB_EXIT_X, MPK_WINDOW_DRAWCB_EXIT_GL, MPK_WINDOW_DRAWCB_UPDATE, MPK_WINDOW_DRAWCB_RESIZE

The init and exit callbacks are specifying the functions which are invoked to initialise and exit X11 and GLX/OpenGL.

The update callback specifies a function to be invoked once a frame by the window thread, prior to any rendering.

The resize callback is invoked everytime a window resize should be performed. Currently, this can happen only in mpkConfigChangeMode(). It is called when the lightweight stereo switch is performed and the pipe resolution is different in mono and stereo mode. The default function to be invoked is mpkWindowResize().

mpkWindowSetCullCB sets the MPKWindow cull callback specified by which to the passed function, of type:

void (*MPKWindowCullCB)(MPKWindow*);
Accepted values for which are

MPK_WINDOW_CULLCB_INIT, MPK_WINDOW_CULLCB_EXIT, MPK_WINDOW_CULLCB_UPDATE

The init and exit callbacks are specifying the functions which are invoked to initialise and exit windows used for culling.

The update callback specifies a function to be invoked once a frame by the window thread, prior to any culling.

mpkWindowGetEventCB returns the MPKWindow event callback function specified by which. Accepted values for which are

MPK_WINDOW_EVENTCB_ANY, MPK_WINDOW_EVENTCB_CONFIGURE, MPK_WINDOW_EVENTCB_EXPOSE, MPK_WINDOW_EVENTCB_KEYBOARD, MPK_WINDOW_EVENTCB_MOUSE, MPK_WINDOW_EVENTCB_BUTTON, MPK_WINDOW_EVENTCB_EXIT

mpkWindowGetDrawCB returns the MPKWindow draw callback function specified by which. Accepted values for which are

MPK_WINDOW_DRAWCB_INIT_X, MPK_WINDOW_DRAWCB_INIT_GL, MPK_WINDOW_DRAWCB_EXIT_X, MPK_WINDOW_DRAWCB_EXIT_GL, MPK_WINDOW_DRAWCB_UPDATE, MPK_WINDOW_DRAWCB_RESIZE

mpkWindowGetCullCB returns the MPKWindow cull callback function specified by which. Accepted values for which are

MPK_WINDOW_CULLCB_INIT, MPK_WINDOW_CULLCB_EXIT, MPK_WINDOW_CULLCB_UPDATE
Operations

mpkWindowInit launches the passed MPKWindow and spawns the MPKWindow loop thread, which executes according to the pseudo-code below:


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

mpkWindowInit() does block until the window entered it's lifelong loop. It returns the number of threads created (see MPK_WATTR_HINTS_THREAD attribute).

mpkWindowExit exits window, which causes the window thread to execute the pseudo-code below prior to exiting:


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

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

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

mpkWindowResize resizes the given window according to the current display size and fractional viewport.

mpkWindowApplyViewport applies the latest pixel viewport specified for the passed MPKWindow as an OpenGL viewport and scissor area.

mpkWindowUpdatePixelViewport forces recomputation of the window pixel viewport. If a parent window has been specified for the window, then the computation will use the parent window's dimensions, otherwise it will use the [stereo-dependent] parent pipe's display dimensions to compute the window's pixel viewport from its fractional viewport:


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

     // compute first pixel position of the window
     window.pvp[0] = IRND(window.vp[0] * pipe.width);
     window.pvp[1] = IRND(window.vp[1] * pipe.height);

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

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

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


     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 stereo mode type MPK_STEREO_RECT the value of the MPKGlobal variable MPK_DATTR_FULLSTEREO_OFFSET is added to the window's height, whereas in mode MPK_STEREO_BOTH this offset is added to its vertical position.

The update is propagated immediately to each of the window's MPKChannels.

mpkWindowSetPixelViewport sets values for the passed MPKWindow pixel viewport. Change is immediately propagated to each of the window's MPKChannel.

mpkWindowGetPixelViewport reads the latest updated pixel viewport for the passed MPKWindow in pvp.

mpkWindowGetMode returns the current current stereo mode of the passed MPKWindow as either MPK_STEREO_NONE, MPK_STEREO_RECT, MPK_STEREO_QUAD, MPK_STEREO_TOP, MPK_STEREO_BOT or MPK_STEREO_USER.

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

mpkWindowGetUserData enables the application to retrieve the passthrough data specified by mpkWindowSetUserData().
Events

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

mpkWindowProcessEvent returns if the passed event's X window does not match the passed MPKWindow drawable. Otherwise mpkWindowProcessEvent invokes the user-specified related MPKEvent callback, if any.

Combined with the MPK_WINDOW_EVENTCB_ANY event callback function, mpkWindowProcessEvent() enables customization of the event-handling for an MPK-application, as shown by the example below:


     void initWindow( MPKWindow *w )
     {
         mpkWindowSetEventCB( w, MPK_WINDOW_EVENTCB_ANY, windowEvent );
         mpkWindowSetEventCB( w, MPK_WINDOW_EVENTCB_KEYBOARD, windowKB );
     }

     void windowEvent( MPKWindow *w, MPKEvent *event )
     {
         MPKEventXData *data = (MPKEventXData *)mpkEventGetData(event);
         switch ( data->x->type )
         {
             // Use my own event processing for these events
             case ClientMessage:
                 myProcessEvent( event );
                 break;

             // Use MPK event processing for other events, eg.
             // keyboard events.
             default:
                 mpkWindowProcessEvent( w, event );
         }
     }

     void windowKB( MPKWindow *w, MPKEvent *event )
     {
         // Will be invoked by MPK upon keyboard events
         MPKEventXData *data = (MPKEventXData *)mpkEventGetData(event);

         if ( data->keyboard.state == MPK_PRESS )
             printf( "key %d pressed\n", data->keyboard.key );
     }

X11/GLX Interface

mpkWindowCreate performs the following operations:


     mpkWindowOpenDisplay( window );

     GLXFBConfig *fbconfig = mpkWindowChooseFBConfig( window, &n );
     mpkWindowSetFBConfig( window, fbconfig[0] );

     mpkWindowCreateDrawable( window );
     mpkWindowMapDrawable( window );

If the GLXFBConfig interface is not supported, then the corresponding XVisualInfo interface will be used. Note that MPKConfig's windows init callback is set by default to mpkWindowCreate.

mpkWindowDestroy performs the following operations:


     mpkWindowDestroyDrawable( window );
     mpkWindowCloseDisplay( window );

     mpkWindowSetParent( window, NULL );
     mpkWindowSetScreen( window, 0 );
     mpkWindowSetFBConfig( window, NULL );

If the GLXFBConfig interface is not supported, then the corresponding XVisualInfo interface will be used. Note that MPKConfig's windows exit callback are set by default to mpkWindowDestroy.

mpkWindowOpenDisplay performs the following operations:


     MPKPipe *p = mpkWindowGetPipe(window);
     Display *display = XOpenDisplay( mpkPipeGetDisplayName(p) );

     mpkWindowSetDisplay( window, display );
     mpkWindowSetScreen( DefaultScreen(display) );

     mpkWindowUpdatePixelViewport( window );

Note that mpkWindowOpenDisplay does not invoke mpkWindowSetParent(). mpkWindowOpenDisplay may use a lock to open the display connection for Xinerama-aware and Xinerama-unaware windows (see mpkGlobalSetXinerama()).

mpkWindowCloseDisplay disconnects an MPKWindow from the X server.

mpkWindowCreateDrawable creates an X Drawable that matches the passed MPKWindow attributes and parent XID, if one has been specified via mpkWindowSetParent().

If the MPK_WATTR_HINTS_DRAWABLE attribute is set to MPK_GLX_PIXMAP and a Pixmap has been specified via mpkWindowSetPixmap() then mpkWindowCreateDrawable will use glXCreateGLXPixmap(3G) on the specified Pixmap.

Note that mpkWindowCreateDrawable does not map the resulting drawable (see mpkWindowMapDrawable()).

mpkWindowDestroyDrawable destroys the window's Drawable and Pixmap.

mpkWindowMapDrawable maps the window's drawable, if the MPK_WATTR_HINTS_DRAWABLE attribute is set to MPK_GLX_WINDOW. Otherwise it simply returns.

mpkWindowCreateContext creates an GLXContext that matches the passed MPKWindow attributes, in particular the MPK_WATTR_HINTS_DIRECT attribute.

mpkWindowDestroyContext destroys the window's GLXContext.

mpkWindowMakeCurrent attaches the window's GLXContext to its Drawable.

mpkWindowMakeCurrentNone releases the window's current GLXContext.

mpkWindowSwapBuffers exchanges the front and back buffers of a double-buffered MPKWindow provided its MPK_WATTR_HINTS_DOUBLEBUFFER attribute is not set to 0.

mpkWindowSetDisplay sets the X11 Display of the passed MPKWindow to display.

mpkWindowGetDisplay returns the current X11 Display of the passed MPKWindow.

mpkWindowSetInputDisplay sets the X11 Display used for receiving events of the passed MPKWindow to display. Note that this display is used by MPK from the application thread. This means that in fork execution mode the Display has to be opened from the application process, not from the window rendering process.

mpkWindowGetInputDisplay returns the current X11 Input Display of the passed MPKWindow.

mpkWindowSetParent sets the parent X11 Window of the passed MPKWindow to parent. This information is used by mpkWindowCreate() when creating the X11 Window and mpkWindowUpdatePixelViewport() when computing the pixel viewport of the MPKWindow from its fractional viewport.

mpkWindowGetParent returns the parent X11 Window of the passed MPKWindow, NULL if the parent is the root window of the Display.

mpkWindowSetScreen sets the X11 Screen of passed MPKWindow to screen.

mpkWindowGetScreen returns the passed MPKWindow's X11 Screen.

mpkWindowChooseFBConfig returns a list of GLX frame buffer configurations that match the passed MPKWindow attributes. nitems returns the number of elements in the list. Use XFree to free the memory returned by this function.

mpkWindowSetFBConfig sets the frame buffer configuration of the passed MPKWindow to the passed GLXFBConfig, and its visual to the corresponding XVisualInfo if a match can be found. This information is used by mpkWindowCreateContext().

mpkWindowGetFBConfig returns the current frame buffer configuration of the passed MPKWindow.

mpkWindowChooseVisual returns a visual that matches the passed MPKWindow attributes. Use XFree to free the memory returned by this function.

mpkWindowSetVisual sets the visual of the passed MPKWindow to the passed XVisualInfo, to be used in mpkWindowCreateContext(). Note that this information gets preempted by any Frame Buffer configuration specified via mpkWindowSetFBConfig().

mpkWindowGetVisual returns the current visual of the passed MPKWindow.

mpkWindowSetPixmap specifies an optional X11 Pixmap to be used by mpkWindowCreateDrawable() when the MPK_WATTR_HINTS_DRAWABLE attribute is set to MPK_GLX_PIXMAP.

mpkWindowGetPixmap returns the current X11 Pixmap used by the passed MPKWindow.

mpkWindowSetDrawable sets the current Drawable of the passed MPKWindow, to be used by mpkWindowMapDrawable(), mpkWindowProcessEvent(), mpkWindowMakeCurrent() and mpkWindowSwapBuffers().

mpkWindowGetDrawable returns the current X11 Drawable of the passed MPKWindow.

mpkWindowSetContext sets the current GLXContext of the passed MPKWindow, to be used by mpkWindowMakeCurrent() and mpkWindowSwapBuffers().

mpkWindowGetContext returns the current GLXContext of the passed MPKWindow.

File Format/Defaults

1. MPKWindow File Format specification:

window {
  # window FIELDS description
 
 name"window-name"
 runonprocessor-id
 
 viewport[ xf, yf, wf, hf ]
 
  # window ATTRIBUTES description
 
 attributes { attributes description }
 
  # window CHANNELS description
 
 channel { channel-1 description }
 channel { channel-2 description }
 ... 

}

2. MPKWindow-attributes File Format specification:

attributes {
 hints{ window-attribute hints description }
 planes{ window-attribute planes description }
 transparent{ window-attribute transparent description }

}

3. MPKWindow-attribute-hints File Format specification:

hints {
 visualvisual-type
 drawabledrawable-type
 caveatvisual-caveat
 directy/n
 
 thready/n
 xineramay/n
 eventnone/input/inputOutput
 decorationy/n
 transparenty/n
 X-renderabley/n
 rgbay/n
 doublebuffery/n
 stereoy/n # quad-buffer only
 
 largesty/n # pbuffer only
 preservedy/n # pbuffer only

}

4. MPKWindow-attribute-planes File Format specification:

planes {
 level0
 depth1
 stencil0
 samples0
 auxiliary0
 color0
 rgba[ 1, 1, 1, 0 ]
 accum[ 0, 0, 0, 0 ]

}

5. MPKWindow-attribute-transparent File Format specification:

transparent {
 index0
 rgba[ 0, 0, 0, 0 ]

}

Notes

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

visual attribute hint specification accepts only the following File Format identifiers: true-color [default], pseudo-color, direct-color, static-color, static-gray or grayscale.

drawable attribute hint specification accepts only the following File Format identifiers: none, window [default], pbuffer and pixmap.

caveat attribute hint specification accepts only the following File Format identifiers: none [default], slow and non-conformant.

See also

MPKChannel, MPKConfig, MPKGlobal, MPKPipe