This chapter contains the following topics:
This section describes the format you must use to create an MPK configuration file. The format of the configuration file closely follows the conventions for the Open Inventor file format. The following items are described:
MPK considers any items between a number sign (#) and the end of the line to be a comment. The number sign can be anywhere on the line.
White space delimits most elements in the configuration file—for example, a field name and its value. Exceptions are noted where they apply. Extra white space created by spaces, tabs, and new lines is ignored.
An MPK data structure consists of the following sequence of elements:
Data structure type (config, pipe, window, channel, or compound)
Open brace ({)
Field specifications (if any), followed by child structures (if any)
Close brace (})
The following lines show the syntax symbolically:
data-structure-type {
field-specs
child-specs
}
|
The following is an example of a channel data structure:
channel {
viewport [ 0., 0., 1., 1. ]
projection {
origin [ 0., 0., 0. ]
distance 3.
fov [ 54., 47. ]
hpr [ 0., 0., 0. ]
}
}
|
The later section “Defining MPK Data Structures” describes the special requirements for defining each of the data structures.
There are three types of MPK fields:
Single-value fields
These fields have the following syntax:
name value
Multiple-value fields
These fields have the following syntax:
name [value1, value2, . . . valuen]
Composite fields
These fields have the following syntax:
name {
subfields-specs
}
The fields can appear in any order.
The values you specify in a field are determined by the field type. The field types and accepted formats are described in Table 6-1.
Table 6-1. Field Types and Formats
Field Type | Accepted Format |
|---|---|
int | Use an integer in decimal, hexadecimal, or octal format. Examples: 55 0xff 0177 |
float | Use an integer or floating point number. Examples: 10 10. 10.3 1.3e–2 |
string | Use double quotation marks (“ “) around the value. Example: name “3-pipes” |
enum | Use a mnemonic. Examples: true-color direct-color |
boolean | Use a mnenomic (y or n) or an integer (0 or 1). |
The earlier section “Specifying MPK Data Structures” describes the general format of an MPK data structure as follows:
data-structure-type {
field-specs
child-specs
}
|
This section describes the field specifications and child specifications required to define the following MPK data structures:
config
pipe
window
channel
compound
Additionally, you can include a global data structure to define defaults for global attributes. The later section “Specifying Global Attributes” describes how you do so.
The config data structure encapsulates the other data structures and as such defines the overall configuration. It has the following form:
config {
name “config-name”
mode stereo-mono
mono “shell command1”
stereo “shell command2”
runon processor-spec
pipe-1-specs
pipe-2-specs
.
.
.
pipe-n-specs
compound-specs
}
|
Every config data structure requires a pipe data entry for each pipe you want to use in your system. Section “The pipe Data Structure” describes the pipe-i-specs fields, section“The compound Data Structure” describes the compound-specs field, and Table 6-2 describes the other config fields.
A pipe data structure has the following form:
pipe {
name “pipe-name”
display “display-name”
attributes {
mono {
width w
height h
}
stereo {
type stereo-type
width w
height h
offset o
}
}
window-spe
}
|
Every pipe data structure must contain a window entry. The section “The window Data Structure” describes the window-specs field. Table 6-3 describes the other fields of a pipe data structure.
Field | Description |
|---|---|
name | The name field is a string identifier for the current pipe. |
display | The display field specifies the name of the X display for the current pipe. |
attributes | The attributes field is a composite field with the following subfields: mono These subfields are in turn composite fields. The subfield mono has the following fields: width w The values for w and h must be integers. The subfield stereo has the following fields: type stereo-type width w offset o The values for w, o, and h must be integers. The value for stereo-type can be one of the following: quad If no stereo type is specified, quad is used. |
Example 6-1 is an example of a pipe definition:
Example 6-1. A Sample pipe Definition
pipe {
display “:0.0”
window {
runon 2
viewport [ 0., 0., 1., 1. ]
channel {
viewport [ 0., 0., 1., 1. ]
projection {
origin [ 0., 0., 0. ]
distance 3.
fov [ 54., 47. ]
hpr [ 0., 0., 0. ]
}
}
}
}
|
A window data structure has the following form:
window {
name “win-name”
viewport [x, y, width, height]
runon processor-spec
attributes attribute-specs
channel-specs
}
|
Every window data structure requires a channel entry. The section “The channel Data Structure” describes the channel-specs field. Table 6-4 describes the other fields of a window data structure.
Field | Description |
|---|---|
name | The name field is a string identifier for the current window. |
viewport | The viewport field specifies the fractional viewport (position and size) of the current window relative to the display dimensions. The fractional viewport format is [ x, y, width, height ] with all parameters in the range 0.0 to 1.0. See the section “Specifying Global Attributes” for more information on the following related global variables:
MPK_PATTR_MONO_HEIGHT |
runon | If the runon field contains a processor ID, that processor will be the default processor for the current window thread—that is, the processor to which the window thread will be assigned. A runon value of -1 means the thread is bound to a processor according to the default run-on policy. If the value is set to auto, then MPK will bind the window thread to a processor on the node for this pipe, if possible. If the value is set to free, then the operating system decides on what processor to execute the thread. The default is –1. |
attributes | The attributes field specifies the X Window System default visual attributes and other related information, such as whether window managers decorations should be present or not. The attributes field is a composite field with the following subfields: hints These subfields are in turn composite fields. which are described in the tables that follow. |
Table 6-5 describes the structure and values of the hints subfields.
Table 6-5. Window Attributes— hints Subfields
Subfield | Valid Values | Description |
|---|---|---|
visual | true-color | Specifies the type of GLX visual to be used. Related global variable: |
caveat | none | Specifies a caveat for selecting the framebuffer, such as one of the following: MPK_GLX_SLOW Related global variable: |
transparent | y or n | Determines if a visual should be opaque or transparent. Related global variable: |
X-renderable | y or n | Determines which visuals are selected. If true, only visuals which have an associated X visual are selected. Related global variable: |
rgba | y or n | Specifies if an RGBA or color-index visual is selected. Related global variable: |
doublebuffer | y or n | Specifies if a double- or single-buffer visual is selected. Related global variable: |
stereo | y or n | Specifies if a stereo-capable visual is selected Related global variable: |
drawable | window | Specifies the type of drawable to be used for rendering. For the value none, MPK executes no draw operation. Related global variable: |
direct | y or n | Specifies if a direct or indirect context is created. Related global variable: |
largest | y or n | Determines whether the largest available pbuffer is allocated. It will be if a pbuffer drawable is used and this flag is set. Related global variable: |
preserved | y or n | Determines whether the content of the framebuffer is preserved. It will be if a pbuffer drawable is used and this flag is set. Related global variable: |
decoration | y or n | Determines if the window should have window manager decorations. Related global variable: |
Table 6-6 describes the structure and values of the planes subfields. In all instances in this table, the variables denote integers.
Table 6-6. Window Attributes—planes Subfields
Table 6-7 describes the structure and values of the transparent subfields. In all instances in this table, the variables denote integers.
Table 6-7. Window Attributes—transparent Subfields
A c hannel data structure has the following form:
channel {
name “channel-name”
viewport [x,y, width, height]
ortho-wall ortho-wall-specs
wall wall-specs
projection projection-specs
channel-attrs
|
} |
In the context of framebuffer resources, the channel data structure is conceptually the lowest level in the config-pipe-window-channel hierarchy. Functionally, however, the channel data structure has a child, attributes, shown as channel-attrs in the preceding syntax description. The attributes data structure has the following syntax:
attributes {
read {
depth {
format GL-format-enum
type GL-type-enum
}
color {
format GL-format-enum
type GL-type-enum
}
stencil {
format GL-format-enum
type GL-type-enum
}
}
}
|
Table 6-8 describes the fields of a channel data structure.
Field | Description |
|---|---|
name | The name field is a string identifier for the current channel. You must specify the name field if your configuration file contains a compound that references this channel. |
viewport | The viewport field specifies the fractional viewport (position and size) of the channel relative to the parent window dimensions. The fractional viewport format is [ x, y, width, height ] with all parameters in the range 0.0 to 1.0. |
wall | The wall field contains the modeling coordinates of the bottom-left, bottom-right, and top-left corners of the channel's projection rectangle in the real world. This field is a composite field with the following subfields: bottom_left [x, y, z] bottom_right [x, y, z] top_left [x, y, z] See Example 3-1 for an example of specifying the wall field. You must specify one of the modeling coordinates fields: wall, projection, or ortho-wall. MPK uses the last specified modeling transformation—that is, either wall or projection—unless you set the channel to orthographic projection by specifying the ortho-wall field. |
ortho-wall | The ortho-wall field contains an alternate wall description that, if specified, will be used when the channel orthographic frustum is applied. The format for the field values is the same as that of the wall field. You must specify one of the modeling coordinates fields: wall, projection, or ortho-wall. MPK uses the last specified modeling transformation—that is, either wall or projection—unless you set the channel to orthographic projection by specifying the ortho-wall field. |
projection | The projection field contains the modeling coordinates and characteristics of an imaginary projection system that would produce the channel's projection rectangle. This is a composite field with the following subfields: origin [x, y, z] The hpr field represents the head, pitch, and roll and describes Euler angles with respect to the OpenGL convention—that is, the counter-clockwise rotation around the Y axis (head), X axis (pitch), and Z axis (roll) viewed from the positive side of the axis. See Example 3-2 for an example of specifying the projection field. You must specify one of the modeling coordinates fields: wall, projection, or ortho-wall. MPK uses the last specified modeling transformation—that is, either wall or projection—unless you set the channel to orthographic projection by specifying the ortho-wall field. |
channel-attrs | The channel-attrs field is itself a data structure, attributes, with a single read field. The read field has subfields, which are described in Table 6-9 . |
Table 6-9 describes the subfields of read, which is the single field for the attributes data structure.
Table 6-9. Channel Attributes—read Subfields
Primary Subfield | Secondary Subfield | Valid Values | Description |
|---|---|---|---|
color |
|
|
|
| format | Any GL format enum | Defines the color format to be used by this channel when reading color images. The default value is GL_BGRA. See the glReadPixels man page for a list of supported values. |
| type | Any GL type enum | Defines the 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. |
depth |
|
|
|
| format | Any GL format enum | Defines the depth format to be used by this channel when reading color images. The default value is GL_DEPTH_COMPONENT. See the glReadPixels man page for a list of supported values. |
| type | Any GL type enum | Defines the depth type to be used by this channel when reading color images. The default value is GL_FLOAT. See the glReadPixels man page for a list of supported values. |
stencil |
|
|
|
| format | Any GL format enum | Defines the 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. |
| type | Any GL type enum | Defines the 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. |
A compound data structure is not a part of the pipe-window-channel hierarchy. The compound data structure is subordinate only to the config or another compound data structure.
A compound data structure has the following form:
compound {
name “compound-name”
channel “channel-name”
mode [ mode flags ]
format [ format1 format2 ... formatn ]
split “splitString”
region region-specs
}
|
Table 6-10 describes the fields of a compound data structure.
Table 6-10. The compound Fields
Field | Description |
|---|---|
name | The name field is a string identifier for the current compound. |
channel | The channel field identifies the destination channel for the compound. You must specify the name as defined in the name field of the associated channel data structure. If you do not specify this field and the compound has a parent, then its value is inherited from the parent. If the resulting channel is still unspecified, then the compound will simply maintain time consistency of the views across all of its regions with respect to their respective frame latency. Once a channel is involved in a compound, you must explicitly specify any other use of that channel with another compound. This is true also for mode-selective compounds. |
mode | The mode field specifies the decomposition mode (2D, 3D, CULL, DB, DPLEX, EYE, FSAA, or HMD) and optionally mode flags (ADAPTIVE, ASYNC, HW, MONO, NOCOPY, or STEREO). The following are examples: mode [ 3D ] For descriptions of the decomposition modes, see section “Building Compounds” in Chapter 4 . For the use of 2D, FSAA, HW , DPLEX, and NOCOPY in scalable hardware solutions, see Chapter 5, “Using Scalable Graphics Hardware” . For the use of ADAPTIVE, see section “Automatic Load Balancing for Compounds” in Chapter 4 . ASYNC indicates that the pixel transfer from the regions to the destination channel should be delayed to the next frame. Despite an additional one-frame latency, this setting may have a noticeable influence on the compound performance— especially for 2D and DB decompositions. MONO or STEREO indicates that the decomposition should only be activated when the configuration is in the corresponding stereo mode. Note that a window containing only STEREO-active channels will simply not be launched when the configuration is in MONO mode. NOCOPY indicates that no pixel transfer should occur between the compound and its regions; this is typically useful when you use hardware video compositing equipment.
|
format | The format field specifies the format of the pixel data that has to be transferred between the compound and its regions as a combination of COLOR, DEPTH, and STENCIL. It will be inherited by the compound regions. The following are the possible combinations: format [ COLOR ] # default
|
split | The split field specifies the tiling scheme (or z-axis split) used when the compound is used in ADAPTIVE mode. The split value is a string, as shown in the following example: split “[[1 | 2] - [3 | 4]]” The numbers 1, 2, 3, and 4 represent the regions in the compound (source channels). These numbers map the regions declared in the compound data structure in the order of declaration. All the regions declared in the compound data structure must be included into the split string. The axis that is split is represented by the following operators: | axis x – axis y / axis z The split operators | and – can be used only with 2D compounds and the operator /, only with 3D or DB compounds. The formal syntax of the split field is following: split “splitString” splitString :[ group axis group] group :region | splitString axis : `|' | `–' | `/' region : [ integer ] For the use of the ADAPTIVE mode and examples of tiling schemes, see the section “Automatic Load Balancing for Compounds” in Chapter 4 . |
region | The region field specifies a portion of the compound destination channel and the channel where this portion should be rendered. Depending on the compound mode field, the portion described can be either a sub-viewport of the destination channel [2D], a portion of the application database [DB or 3D], a specific eye view [EYE or HMD], a pipelined, de-multiplexed rendering cycle [DPLEX], or the operation to be executed [CULL]. The format for each follows: 2D: viewport [ x, y ,width, height ] 2D HW NOCOPY: CULL: [cull |draw |cull-draw] DB or 3D: range [ a ,b ] EYE eye left-right HMD eye left-right DPLEX channel “channel-name” |
See Chapter 4, “Compounds” for examples of compound definitions.
A global data structure allows you to specify default values for MPK attributes:
Stereo and pipe display attributes
Window attributes
Channel attributes
To specify a default value for an attribute in the configuration file, use the following construct:
global {
attribute1 value
attribute2 value
.
.
.
attributen value
}
|
Your default declarations should precede the definition of the config data structure in the configuration file. The following is an example of default declarations:
global {
MPK_DEFAULT_EYE_OFFSET .035
MPK_WATTR_PLANES_ALPHA 1
}
|
Table 6-11 provides the data type, default value, and description for the MPK global attributes.
Table 6-11. MPK Global Attributes
You can find more information about the window attributes specifications in the glXChooseFBConfig(3G) and glXChooseVisual(3G) man pages.