To initialize DMX, do the following:

After DMX has initialized, you will see a new session covering all the screens. At this point, you can start using OpenGL Multipipe (see “Running Applications with OpenGL Multipipe”).

Notes About the Behavior of ompstartdmx

This section lists some noteworthy items about the behavior and command-line options of the ompstartdmx script:

DMX Limitations on Linux

When using a GNOME session with an aware window manager, the session will not be saved; the default session will be used at each login. This happens because the gnome-wm script does not pass the session ID parameter to any aware window manager, only to those which are supported by the GNOME environment (sawfish, metacity, twm, and their like). When using a KDE or GNOME session without aware window management, the session will be saved and restord at the next login.

A DMX configuration file is simply a text file that describes the configuration of a virtual display, the real displays it manages, and the geometry of the virtual screen. This section provides some short examples of configuration files. These and other example configuration files may be found in the directory /usr/share/omp/examples/dmx .

To start DMX with one of these configurations, do the following:

The following example configuration file specifies a vertical layout:

virtual updown 1280x2048 {
    display :0.0 1280x1024;
    display :0.1 1280x1024 @0x1024;
}

This configuration file defines a virtual screen configuration named updown of size 1280x2048. The virtual screen includes the following two real back-end displays:

You may also define some overlap between each of the screens, as in the following horizontal layout:

virtual overlap 2460x1024 {
    display :0.0 1280x1024;
    display :0.1 1280x1024 @1180x0;
}

This configuration file defines two screens of 1280x1024, each with 100 pixels of overlap, resulting in a virtual screen size of 2460x1024.

The display value specified can be any valid display value, including a display value that specifies a remote machine, as in the following example:

virtual remote 2560x1024 {
    display localhost:0.0 1280x1024;
    display remotehost:0.1 1280x1024 @1280x0;
}

There is also a graphical tool to create and edit configuration files. You can find documentation for this tool in /usr/share/omp/doc/user/xdmxconfig.1.html. The tool is installed in /usr/share/omp/X11/bin/xdmxconfig.

More information about the configuration file format can be found in the file /usr/share/omp/doc/user/Xdmx.1.html.

The full name of each OpenGL Multipipe resource has the following format:

OMP.app_name.resource_name

The app_name field is the application name, defined to be the last component in the running executable path name. The resource_name is one of the available OpenGL Multipipe resources.

You can specify a resource with loose binding—that is, matching the resource for all applications—by using an asterisk in the following manner:

OMP*resource_name

For more information on the X11 resources and their scope, see the X(1) and XrmInitialize(3) man pages.

The following ordered list of resource files indicates the search path OpenGL Multipipe uses to assign values to the resources:

The first match found will be used. However, resources set with the full-name format will always precede resources set with loose binding even if the full-name format is found later in the search path. Resources set with the omprun command always have precedence. For information of the use of the omprun command, see section “Setting Run-Time Options”.

If a resource is not specified in the preceding search path, then the defined default value for that resource will be used.

When you set the environment variable SGIOMP_PRINT_CONFIG to 1, OpenGL Multipipe prints the configuration values it uses to stdout when an application runs through OpenGL Multipipe. This is useful to ensure that any overrides you have specified are being honored.

Each resource value can have one of the following types:

Table 3-1 lists all resources with their default values.

Notes:

This section briefly describes each of the OpenGL Multipipe tunable resources:

aa2Jitter.X and aa2Jitter.Y
Controls the jittering offset for each input pipe when the hardware compositor configured for pixel averaging with two pipes. The value must include two values for both X and Y to specify the frustum offset in pixels on the x and y axes to be applied for the first and second pipe participating in the pixel averaging.

aa4Jitter.X and aa4Jitter.Y
Controls the jittering offset for each input pipe when the hardware compositor configured for pixel averaging with four pipes. The value must include four values for both X and Y to specify the frustum offset in pixels on the x and y axes to be applied for the first, second, third, and fourth pipes participating in the pixel averaging.

activeScreens
Specifies the back-end screens to be active. OpenGL Multipipe will render OpenGL primitives only on those pipes. For example, when Xdmx manages three physical screens (pipes), setting the activeScreens resource to 0,1 will make OpenGL rendering to be visible on screens 0 and 1 only. On screens 2 and 3, the OpenGL part of the application windows will be either black or garbage. By default, all managed screens will be active with respect to OpenGL.

culling
Specifies the enable switch for the geometry culling feature of OpenGL Multipipe. It can be either off or on. When this resource is enabled OpenGL Multipipe will draw to each pipe only the geometry primitives that are visible on that pipe. The default value for this switch is off. For more information, see section “Geometry Culling” in Chapter 5.

culling.cullUserClipPlanes
Enables culling against user-defined clip planes when one of GL_CLIP_PLANEi is enabled. The default value is off, in which case OpenGL Multipipe will cull only against the viewing frustum.

culling.minPixels
Specifies approximate culling—that is, the minimum object size in pixels that should be drawn. All objects smaller than this size will be culled. For more information, see section “Small Object Culling” in Chapter 5.

culling.showStat
Enables the drawing of culling statistics. The following are the possible values:

culling.texCulling
Enables or disables texture culling. When texture culling is enabled, texture loads will be postponed until the texture is really viewable on each specified pipe. In that case only, the relevent part from the texture will be downloaded to the pipe. The resource OMP*culling should be turned on for this feature. For more information and current limitations of this feature, see the release notes.

dlSplit
Allows OpenGL Multipipe to split a display list into smaller display lists based on a geometry spatial sort to acheive better culling. The smaller display lists can be distributed among the rendering pipes. This feature is usually used when culling is turned on. The valid values for dlSplit are on and off; the default is off. For more information, see section “Display List Partitioning” in Chapter 5.

dlSplit.maxBoundAspectRatio
Controls the initial cube cell size and, hence, the initial number of grid divisions produced by the dlSplit algorithm. As part of the dlSplit algorithm, the display list geometry is spatially sorted into an oct tree data structure by iteratively dividing the geometry bound to the grid of cube cells. Normally, the cell size is taken to be equal to the smallest bounding box dimension. However, for models where the aspect ratio of the bounding box is large (for example, 2D surfaces), the algorithm would produce a large number of initial cells, which would lead to a high-memory footprint. The default value is 8.

Note that setting maxBoundAspectRatio to a value less than or equal to 1.0 suppresses the splitting operation. Negative values are not allowed.

dlSplit.maxDepth
Limits the number of recursive subdivisions by the dlSplit algorithm, which is an adaptive subdivision algorithm. After the specified number of recursive subdivisions are made, the process will end even if it does not meet the dlSplit.maxTris criterion. The default value is 8.

dlSplit.maxStripLen
Controls the amount of triangulation. By default with dlSplit enabled, geometry is triangulated into separate triangles before applying the splitting algorithm. This resource can be used to preserve the application-supplied strips so that fewer vertices are generated at the cost of less efficient splitting. When the value of this resource is set to -1 (the default), all geometry will be triangulated before applying the dlSplit algorithm. When set to 0, each strip given by the application will be considered atomic for splitting purposes and will not be triangulated. When set to a positive value, each application-supplied strip will not be triangulated but will be split into multiple strips of dlSplit.maxStripLen vertices, of which each will then be considered atomic for splitting purposes.

dlSplit.maxTotalTris
Limits the number of triangles that will be considered by the dlSplit algorithm at each iteration. If a display list contains more triangles than the specified number, then the splitting algorithm will be applied multiple times, once for each group that contains the specified number of triangles. The default value is 400000.

dlSplit.maxTris
Limits the number of triangles to the specified maximum for each bounding box of subordinate display lists. Display lists that have fewer triangles (or other primitives) than the specified number will not be split by the dlSplit algorithm. The default value is 800.

dlSplit.showRandomColors
Allows OpenGL Multipipe to randomly assign a different color for each divided geometry partition. For testing and debugging purposes, this coloring allows you to better see the divisions made by the dlSplit algorithm. This may not work for all applications as it simply uses glColor() to set the color for each partition. The default is off.

drawPixelsClipping
Controls whether the glDrawPixels() operation will be clipped such that only the viewable rectangle of pixels will be sent to each pipe.

masterMode
Specifies if and how the master process needs to use one of the graphics pipes. The following are the valid values:

masterScreen
Specifies which managed screen (pipe) will be used by the master application for either rendering or state tracking when running OpenGL Multipipe in master mode render or track (available only when using the omprun command). By default, it will be the first managed screen of the Xdmx server.

maxFramesLatency
Specifies the maximum latency (in frames) allowed between the application and rendering slaves. The application process might pack a few frames ahead in the framebuffer while the slave processes are still drawing the previous frames. This introduces some latency between the application and the real drawing by the slave but helps overall throughput of master and slaves. The latency is always 0 when using masterMode render and is undefined if swapSyncMode is set to none. The default value for this resource is 4. For more information, see section “Frame Latency Control” in Chapter 5.

pbuffers.disable
Disables pbuffers support. When this resource is enabled, all pbuffer-capable framebuffer configurations will be filtered out and will not be exposed to the application. The default value is off.

pbuffers.layout
Controls how the rendering into a pbuffer is split among the rendering slaves. Each rendering slave can be configured to draw only to a sub-region of each pbuffer. The following are the valid values:

duplicate
All slaves renders to all regions of the pbuffer, That makes the content of the pbuffer to be duplicated on all rendering pipes. Use this configuration when your application uses glCopy*() to copy the pixels from the pbuffer to some other pixel buffer on the pipe. The other options might be better if you are using glReadPixels() to read back the pbuffer content into your process memory. This is the default value.

horizSplit
The area of the pbuffer is split into N horizontal strips, where N is the number of pipes. Each slave then limits the rendering to only one strip.

vertSplit
The area of the pbuffer is split into N vertical strips, where N is the number of pipes. Each slave then limits the rendering to only one strip.

rectSplit
The area of the pbuffer is split into N even rectangular areas as much as possible. For example, for a four-pipe configuration, it will be split into 2x2 tiles, where each tile is of size (w/2)x(h/2) and w and h are the pbuffer width and height, respectively. Each pipe then renders to only one tile.

shmQueueSize
Sets the size in bytes for the shared memory block that will be used for master-to-slaves communication. When this resource is not specified, the default value depends on the overall resolution of the meta display as determined by the following:

( DisplayWidth * DisplayHeight * 4 ) + 32

This allows a single full-screen glDrawPixels() command to fit in the shared memory since one single OpenGL command cannot be split into multiple packets. Depending on your application, you may want to set this value to be smaller or larger. When a shared memory size larger than the default or the specified size is needed, the application will exit with an error message specifiying the minimum shared memory size needed for that application.

slaveCPUs
Specifies the CPUs to assign to the draw slave processes for each of the active screens. If there are more active screens than the size of the specified CPU list, then the remaining draw processes will not be assigned to any particular CPU. By default, the draw processes will not be assigned to any particular CPU.

swapSyncMode
Specifies what method OpenGL Multipipe will use to synchronize swap buffers on all pipes. The following are the valid values:

syncOnFlushMode
Specifies if the rendering slaves need to be synchronized with each other after the execution of the glFlush() command. This is commonly required by single-buffer applications that never calls swap; this leaves the slaves asynchronous with each other. The following are the valid values for this resource:

texShm
Controls the caching of textures in shared memory. When this switch is turned on, OpenGL Multipipe will cache a copy of each texture in shared memory that remains valid until the texture is used by all pipes. Once the texture has been downloaded to driver memory of all pipes, the shared memory cache is purged. This feature works together with texture culling (see the culling.texCulling resource). When culling.texCulling is turned on, the texShm resource is implicitly turned on. The default for the texShm resource is off.

useTmpfs
Allocates shared memory under the tmpfs filesystem (mounted under /dev/shm) rather than using mmap to map a file under the /tmp directory. Note that the /dev/shm filesystem needs to have enough space to allocate the shared memory. The default value is on.

useTmpfs.shmPlacement
Governs how OpenGL Multipipe allocates shared memory across a non-uniform memory access (NUMA) architecture. In a NUMA architecture, some memory areas have different latencies and bandwidths. This memory placement control requires that the OMP*useTmpfs resource will be set to on.

The following are the valid values for this resource:

master		Shared memory will be allocated on the application memory node.
slaves		Shared memory will be allocated on the slaves memory nodes in a round-robin fashion.
all_omp		Shared memory will be allocated on memory nodes used by OpenGL Multipipe processes (master and slaves) in a round-robin fashion.
global		Shared memory will be allocated across all the system memory nodes in a round-robin fashion.
os		Shared memory will be allocated according to the system default. Note: If resource is set to master, slaves, or all_omp, you should place OpenGL Multipipe processes on specific CPUs using the OMP*slaveCpus resource. Otherwise, the behavior of this resource reverts to the default, that of os.

viewportClippingMode
Specifies viewport clipping mode. Each rendering slave may limit the rendering region to only the portion of the window that is visible on its rendering pipe. This is required to support large viewport areas, which are allowed by a single pipe, and it also helps to scale fill rate performance. The viewportClippingMode resource selects the method OpenGL Multipipe uses to limit this rendering region. The following are the valid values:

You can use a DMX configuration file to cause DMX to manage less than a whole backend screen. When the subregions of each screen are visually assembled using a congruent static compositor tiling, the resulting logical screen will look and behave identically to the DMX displays with fully overlapping screens described previously. The following configuration file entry illustrates this feature:

virtual quadtilesubregions 1280x1024 {
    display :0.0 640x512+0+0     @0x0;
    display :0.1 640x512+640+0   @640x0;
    display :0.2 640x512+0+512   @0x512;
    display :0.3 640x512+640+512 @640x512;
}

The X mouse cursor can be made visible in the partially or fully overlapped screen regions needed for edge-blended or composited displays. As long as the logically overlapping areas of the DMX display are composed by screens of different backend X servers, DMX can utilize the mouse cursor that is available on each backend X server.

Instead of having DMX manage multiple screens of a single backend X server, you can start multiple backend X servers and specify a DMX configuration that logically overlaps areas from different backend X servers, as shown in the following:

virtual totaloverlapmulti 1280x1024 {
   display :0.0 1280x1024;
   display :1.0 1280x1024;
   display :2.0 1280x1024;
   display :3.0 1280x1024;
}

---

Note: The multiserver technique can be combined with the technique of managing screen subregions to create a logical display on which mouse cursors are visible in all overlapped and composited regions.

---