Appendix A. MPK Attributes

Appendix A. MPK Attributes
Prev		Next

MPK uses attributes to specify certain properties for pipes, windows, and channels. In general, you can specify these attribute values in the following places:

Individual data structures
The MPKGlobal data structure (defaults only)
The configuration file

The SGI OpenGL Multipipe User's Guide describes how you specify the attributes in the configuration file. This appendix describes the attributes and how you specify them in the individual data structures and in the special MPKGlobal data structure. The following sections are included:

MPK Attribute Names

As described in the section “MPK Naming Conventions” in Chapter 2, MPK attribute names have three or more parts, the first two of which are the following:

MPK prefix

Attribute type

`CATTR`		Specifies a channel attribute.
`PATTR`		Specifies a pipe attribute.
`WATTR`		Specifies a window attribute.
`DEFAULT`		Used only in the case of the stereo-related attribute `MPK_DEFAULT_EYE_OFFSET`.

The remaining parts contain additional attribute descriptors. The following are examples of attribute names:

MPK_CATTR_FAR
MPK_PATTR_STEREO_WIDTH
MPK_WATTR_HINTS_RGBA

Managing Attributes

As cited in the introduction, you can programmatically manage the attributes in the individual data structures or in the MPKGlobal data structure. This section describes how you manage the attributes in the individual data structures, and the later section “MPKGlobal Attributes” describes how you do so from the MPKGlobal data structure.

The individual data structures of interest are the MPKChannel, MPKPipe, and MPKWindow data structures. The management of channel attributes is covered in the later section “MPKGlobal Attributes”.

MPK provides the functions shown in Table A-1 to manage attributes in the MPKChannel, MPKPipe, and MPKWindow data structures.

Table A-1. Attribute-Managing Functions for Individual Data Structures

Function	Description
mpkChannelSetAttribute() mpkPipeSetAttribute() mpkWindowSetAttribute()	Sets the specified attribute.
mpkChannelUnsetAttribute() mpkPipeUnsetAttribute() mpkWindowUnsetAttribute()	Unsets the specified attribute. No value is assigned to that variable. The special `enum` value `MPK_PATTR_ALL` or `MPK_WATTR_ALL` can be used to unset all attributes of the respective data structure.
mpkChannelResetAttribute() mpkPipeResetAttribute() mpkWindowResetAttribute()	Sets the attribute to the default value obtained from the MPKGlobal structure. If the default value is `MPK_UNDEFINED`, the attribute is unset. The special `enum` value `MPK_CATTR_ALL`, `MPK_PATTR_ALL`, or `MPK_WATTR_ALL` can be used to unset all attributes of the respective data structure.
mpkChannelTestAttribute() mpkPipeTestAttribute() mpkWindowTestAttribute()	Returns `1` if the attribute is set and `0` if unset.
mpkChannelGetAttribute() mpkPipeGetAttribute() mpkWindowGetAttribute()	Gets the value of the specified attribute if set and returns `1`. If the value is not set, the function returns `0`.

To set the attributes of a MPKChannel, MPKPipe, or MPKWindow data structure to their default values, MPK calls the function mpkChannelResetAttribute(channel, MPK_CATTR_ALL), mpkPipeResetAttribute( pipe, MPK_PATTR_ALL ) or mpkWindowResetAttribute( window, MPK_WATTR_ALL ) upon creation of the data structure.

MPKPipe Attributes

Table A-2 describes the MPKPipe attributes.

Table A-2. MPKPipe Attributes

Attribute Name	Valid Values	Description
`MPK_PATTR_MONO_HEIGHT`	`int`	Specifies the height of the display to be used by the function mpkWindowUpdatePixelViewport() for mono mode instead of that returned by `th`e X11 DisplayHeight() function. If no value is set, 492 is used for `MPK_STEREO_RECT`, `MPK_STEREO_BOT`, and `MPK_STEREO_TOP`.
`MPK_PATTR_MONO_WIDTH`	`int`	Specifies the width of the display to be used by the function mpkWindowUpdatePixelViewport() for mono mode instead of that returned by `th`e X11 DisplayWidth() function.
`MPK_PATTR_STEREO_HEIGHT`	`int`	Specifies the height of the display to be used by the function mpkWindowUpdatePixelViewport() for stereo mode instead of that returned by `th`e X11 DisplayHeight() function.
`MPK_PATTR_STEREO_OFFSET`	`int`	Specifies the offset of the display to be used by the function mpkWindowUpdatePixelViewport() for `rect` and `bottom` stereo modes. The default value is 532.
`MPK_PATTR_STEREO_TYPE`	`MPK_STEREO_USER MPK_STEREO_QUAD` `MPK_STEREO_RECT` `MPK_STEREO_TOP` `MPK_STEREO_BOT`	Specifies one of the following stereo types: `none`, `user`, `quad`, `rect`, `top`, or `bottom`.
`MPK_PATTR_STEREO_WIDTH`	`int`	Specifies the width of the display to be used by the function mpkWindowUpdatePixelViewport() for stereo mode instead of that returned by `th`e X11 DisplayWidth() function.

MPKWindow Attributes

Table A-3 describes the MPKWindow attributes.

Table A-3. MPKWindow Attributes

Attribute Name	Valid Values	Description
`MPK_WATTR_HINTS_CAVEAT`	`MPK_GLX_SLOW` `MPK_GLX_NOCAVEAT` `MPK_GLX_NON_CONFORMANT`	Specifies the caveats associated with the window framebuffer configuration.
`MPK_WATTR_HINTS_DECORATION`	`boolean`	Specifies whether the window should have window manager decorations.
`MPK_WATTR_HINTS_DIRECT`	`boolean`	Specifies whether the window GLX context should be direct.
`MPK_WATTR_HINTS_DOUBLEBUFFER`	`boolean`	Specifies whether the window framebuffer configuration should be double-buffered. Note that setting this attribute on a window will affect the behavior of the function mpkWindowSwapBuffers(). The default is `1`.
`MPK_WATTR_HINTS_DRAWABLE`	`MPK_GLX_WINDOW` `MPK_GLX_PBUFFER` `MPK_GLX_PIXMAP MPK_GLX_NONE`	Specifies the window drawable type. For `MPK_GLX_NONE`, MPK executes no draw operation.
`MPK_WATTR_HINTS_LARGEST`	`boolean`	Specifies the MPKWindow pbuffer characteristics. This attribute will be ignored by windows for which the `DRAWABLE` hint is not set to `MPK_GLX_PBUFFER`.
`MPK_WATTR_HINTS_PRESERVED`	`boolean`	Specifies the MPKWindow pbuffer characteristics. This attribute will be ignored by windows for which the `DRAWABLE` hint is not set to `MPK_GLX_PBUFFER`.
`MPK_WATTR_HINTS_RGBA`	`boolean`	Specifies whether RGBA visuals are used. If the hint is not set, a color-index visual is used. The default is `1`.
`MPK_WATTR_HINTS_STEREO`	`boolean`	Specifies whether the window framebuffer configuration should support quad-buffer stereo.
`MPK_WATTR_HINTS_THREAD`	`boolean`	Specifies whether the window should be made a separate thread from the application.
`MPK_WATTR_HINTS_TRANSPARENT`	`boolean`	Specifies whether the window framebuffer configuration should be transparent.
`MPK_WATTR_HINTS_VISUAL`	`MPK_GLX_TRUE_COLOR` `MPK_GLX_PSEUDO_COLOR` `MPK_GLX_DIRECT_COLOR` `MPK_GLX_STATIC_COLOR` `MPK_GLX_GRAYSCALE` `MPK_GLX_STATIC_GRAY`	Specifies the window visual type.
`MPK_WATTR_HINTS_X_RENDERABLE`	`boolean`	Specifies whether only framebuffer configuration that have associated X visuals (and can be used to render to windows and/or GLX pixmaps) should be considered.
`MPK_WATTR_HINTS_XINERAMA`	`boolean`	Determines if a window should be created using Xinerama (if enabled). Setting it to `1` causes the window to be created using Xinerama and setting it to `0` causes a Xinerama-aware window to be created. The default value is `1` if the `XINERAMA_AWARE` environment variable is not set. If `XINERAMA_AWARE` is set, the default value is the opposite value of `XINERAMA_AWARE`.
`MPK_WATTR_PLANES_ACCUM_ALPHA`	`int`	Specifies the minimum number of accumulation alpha bitplanes. This attribute is ignored if the `RGBA` hint of the window is not set.
`MPK_WATTR_PLANES_ACCUM_BLUE`	`int`	Specifies the minimum number of accumulation blue bitplanes. This attribute is ignored if the `RGBA` hint of the window is not set.
`MPK_WATTR_PLANES_ACCUM_GREEN`	`int`	Specifies the minimum number of accumulation green bitplanes. This attribute is ignored if the `RGBA` hint of the window is not set.
`MPK_WATTR_PLANES_ACCUM_RED`	`int`	Specifies the minimum number of accumulation red bitplanes. This attribute is ignored if the `RGBA` hint of the window is not set.
`MPK_WATTR_PLANES_ALPHA`	`int`	Specifies the minimum number of alpha bitplanes. This attribute is ignored if the `RGBA` hint of the window is not set. The default is `0`.
`MPK_WATTR_PLANES_AUX`	`int`	Specifies the number of auxiliary buffers.
`MPK_WATTR_PLANES_BLUE`	`int`	Specifies the minimum number of blue bitplanes. This attribute is ignored if the `RGBA` hint of the window is not set. The default is `1`.
`MPK_WATTR_PLANES_COLOR`	`int`	Specifies the minimum color-index buffer size. This attribute is ignored if the `RGBA` hint of the window is set to 1.
`MPK_WATTR_PLANES_DEPTH`	`int`	Specifies the minimum size of the depth buffer. The default is `1`.
`MPK_WATTR_PLANES_GREEN`	`int`	Specifies the minimum number of green bitplanes. This attribute is ignored if the `RGBA` hint of the window is not set. The default is `1`.
`MPK_WATTR_PLANES_LEVEL`	`int`	Specifies the window buffer level. The default is `0`.
`MPK_WATTR_PLANES_RED`	`int`	Specifies the minimum number of red bitplanes. This attribute is ignored if the `RGBA` hint of the window is not set. The default is `1`.
`MPK_WATTR_PLANES_SAMPLES`	`int`	Specifies the minimum number of samples required in the multi-sample buffer.
`MPK_WATTR_PLANES_STENCIL`	`int`	Specifies the minimum size of the stencil buffer.
`MPK_WATTR_TRANSPARENT_ALPHA`	`int`	Specifies the alpha component of the window transparent color. This attribute is ignored if the `RGBA` hint of the window is not set or if the `TRANSPARENT` hint of the window is not set.
`MPK_WATTR_TRANSPARENT_GREEN`	`int`	Specifies the green component of the window transparent color. This attribute is ignored if the `RGBA` hint of the window is not set or if the `TRANSPARENT` hint of the window is not set.
`MPK_WATTR_TRANSPARENT_BLUE`	`int`	Specifies the blue component of the window transparent color. This attribute is ignored if the `RGBA` hint of the window is not set or if the `TRANSPARENT` hint of the window is not set.
`MPK_WATTR_TRANSPARENT_INDEX`	`int`	Specifies the window transparent index. This attribute is ignored if the `RGBA` hint of the window is set or if the `TRANSPARENT` hint of the window is not set.
`MPK_WATTR_TRANSPARENT_RED`	`int`	Specifies the red component of the window transparent color. This attribute is ignored if the `RGBA` hint of the window is not set or if the `TRANSPARENT` hint of the window is not set.

MPKChannel Attributes

The MPKChannel attributes MPK_CATTR_NEAR and MPK_CATTR_FAR, described in “MPKGlobal Attributes”, are set using the function mpkChannelSetNearFar() . The remaining MPKChannel attributes, described in Table A-4, are set using the functions described in Table A-1.

Table A-4. MPKChannel Attributes

Attribute Name	Valid Values	Description
`MPK_CATTR_READ_COLOR_FORMAT`	Any GL format `enum`	Defines the default color format to be used by this channel when reading color images. The default value is `GL_RGB`. See the `glReadPixels` man page for a list of supported values.
`MPK_CATTR_READ_COLOR_TYPE`	Any GL type `enum`	Defines the default color type to be used by this channel when reading color images. The default value is `GL_UNSIGNED_BYTE`. See the `glReadPixels` man page for a list of supported values.
`MPK_CATTR_READ_DEPTH_FORMAT`	Any GL format `enum`	Defines the default depth format to be used by this channel when reading color images. The default value is `GL_DEPTH_COMPONENT24_ SGIX` on VPro, else `GL_DEPTH_COMPONENT`. See the `glReadPixels` man page for a list of supported values.
`MPK_CATTR_READ_DEPTH_TYPE`	Any GL type `enum`	Defines the default depth type to be used by this channel when reading color images. The default value is `GL_UNSIGNED_INT` on VPro, else `GL_FLOAT`. See the `glReadPixels` man page for a list of supported values.
`MPK_CATTR_READ_STENCIL_FORMAT`	Any GL format `enum`	Defines the default stencil format to be used by this channel when reading color images. The default value is `GL_STENCIL_INDEX`. See the `glReadPixels` man page for a list of supported values.
`MPK_CATTR_READ_STENCIL_TYPE`	Any GL type `enum`	Defines the default stencil type to be used by this channel when reading color images. The default value is `GL_UNSIGNED_BYTE`. See the `glReadPixels` man page for a list of supported values.

MPKGlobal Attributes

The MPKGlobal data structure allows you to specify attribute defaults for pipes, windows, and channels. Some attributes—for example, the default eye offset—can only be specified at the MPKGlobal data structure level.

MPK provides MPKGlobal functions to manage the attributes for the various data structures. The function names have the following five parts:

The mpkGlobal prefix
The operation Set or Get
The data structure type (Pipe, Window, or Channel)
The word Attribute
A suffix to determine the data type of the attribute

The following are examples:

void mpkGlobalSetPipeAttributei(int pattr, int val);
float mpkGlobalGetChannelAttributef(int cattr);

Accessing an unset variable will either return MPK_UNDEFINED or the default value of this variable.

Table A-5 describes the MPKGlobal attributes not included in the prior sections “MPKPipe Attributes” and “MPKWindow Attributes”.

Table A-5. MPK Global Attributes

Attribute Name	Valid Values	Description
`MPK_CATTR_FAR`	`float`	Specifies the default far distance of the channel. This value is preempted by the function mpkChannelSetNearFar(). The default is `100`.
`MPK_CATTR_NEAR`	`float`	Specifies the default near distance of the channel. This value is preempted by the function mpkChannelSetNearFar().
`MPK_CHANNEL_AUTO_ACTIVATE`	`boolean`	Specifies whether channels that are not referenced by a compound should be automatically activated by mpkConfigInit(). If this hint is not set, only channels used in a compound are updated during mpkConfigFrame(). The default is `1`.
`MPK_CHANNEL_PASS_CACHE_SIZE`	`int`	Specifies the cache size for the frame data queues used for culling. This attribute affects the granularity and performance of the data processing for data passed using mpkChannelPassData(). The default value is `50`.
`MPK_CHANNEL_PUT_CACHE_SIZE`	`int`	Specifies the cache size for the cull data queues. This attribute affects the granularity and performance of the data processing for data passed using mpkChannelPutData(). The default value is `10`.
`MPK_CONFIG_FRAME_CACHE_SIZE`	`int`	Specifies the cache size for the MPKConfig's frame data queue used for culling. This attribute affects the granularity and performance of the data processing for data passed using mpkConfigFrameData(). The default value is `100`.
`MPK_DEFAULT_EYE_OFFSET`	`float`	Specifies the default value of the eye offset used by the frustum computations for the channel. The function mpkInit() sets this value to `0.035`.
`MPK_DEFAULT_RUNON_POLICY`	enum	Specifies the default run-on policy for those window threads that are not explicitly bound to a particular processor. Setting the value to `auto` causes MPK to bind the first n window threads to the n processors on the node for the respective pipe. If the value is set to `free`, the operating system decides on what processor to execute the thread. The default is `free`.
`MPK_XINERAMA`	`boolean`	Controls window-intialization performance. This variable can be set to `0` if all windows are created using Xinerama, which is the default behavior. Setting it to `0` improves window-initialization performance, but causes problems when creating Xinerama-aware windows. The default is `1`.

Prev	Table of Contents	Next
Chapter 5. Advanced MPK Programming		Index