Configuration options

# Provided SPU's

This page describes the Stream Processing Units (SPUs) provided with Chromium, including all their options.

Example of setting SPU parameters are:

`spu = SPU('render')
spu.Conf('window_geometry', [0, 0, 512, 512])
spu.Conf('window_title', 'my window')
spu.Conf('resizable', 1)
`spu = SPU('tilesort')
spu.Conf('bucket_mode', 'Uniform Grid')``

Users should examine the sample Chromium configuration files to see how some of these SPUs are used.

Note that brackets must be put around configuration parameters when there's more than one value (i.e. use Python's list syntax). For example, the hiddenline SPU's fog_color parameter is specified with three floating point values. They must be contained in brackets:

`spu = SPU('hiddenline')
spu.Conf('fog_color', [ 1.0, 0.5, 0.25 ])`

### SPU index

- API Histogram
- Array
- Binaryswap
- Distributed Texture
- Expando
- Feedback
- Fps
- Hiddenline
- Injector
- Matte
- Motionblur
- Nop
- Pack
- Perf
- Print
- Readback
- Render
- Replicate
- Saveframe
- Simplequery
- Tilesort
- VNC
- Wet
- ZPix

## API Histogram SPU

The `apihistogram` SPU counts the number of calls to each OpenGL API function (like glVertex3fv, glEnable, glClear, etc). When Chromium exits, the SPU lists each GL function and the number of calls to it. The list is sorted by number of calls.

Example output:

    122350868  Vertex3fv
    13239480  DrawArrays
    7957746  Begin
    7957746  End
    2003542  Color3fv
    1718608  GetFloatv
    935986  Materialfv
    349959  PopMatrix
    349959  PushMatrix
    349262  MultMatrixf
    86148  Disable
    83088  Enable
    80162  LineStipple
    [...]

Parameter Name | Value Types | Description
log_file | String | Filename for writing results. May be a filename or `stdout` or `stderr`. The default is `stderr`.

## Array SPU

The `array` SPU implement's OpenGL's vertex arrays. If your application uses vertex arrays, the array SPU should be the first one in the SPU chain. The Array SPU has no configuration options.

## Binaryswap SPU

The `binaryswap` SPU implements the well known binary swap method of image compositing for parallel rendering. It works similar to the Readback SPU. Since the Binaryswap SPU is derived from the Render SPU, all the Render SPU options are applicable to the Binaryswap SPU. See cr/mothership/configs/psubmit_bswap.conf for an example of how to use this SPU.

For background information on the binary swap algorithm read Parallel Volume Rendering Using Binary-Swap Image Composition (pdf).

Parameter Name | Value Types | Description
local_visualization | Boolean | If true, intermediate rendering will be displayed in the binary swap SPU's window.
node_number | Integer | The number of the node in relation to the swap ordering. Binary swap compositing requires a specific ordering of the nodes to correctly do alpha compositing. A power-of-two ordering defines this order such that nodes 0 and 1 swap, 2 and 3 swap, etc. The next phase has 0 and 2 swap, then 1 and 3, etc. The number defined here specifies where in this compositing order the node should be placed. If your final image is composited incorrectly, double check the node ordering you setup here.
peers | String | A comma-separated list of peer node names of the form PROTOCOL://HOSTNAME[:PORT]. For example: "sdp://render1.foo.com" or "tcpip://render2.foo.com:7100". The port number is optional and will be automatically chosen if not present. An example list for a 4-node binary swap configuration is "tcpip://render1.foo.com,tcpip://render2.foo.com, tcpip://render3.foo.com,tcpip://render4.foo.com". The number of node names listed must be a power of two. The list of nodes must also be listed in the order the nodes are defined in, e.g. node0 must be listed before node1.
type | Enum | Controls whether depth or alpha buffers are used to composite images. Possible value are depth and alpha.

## Distributed Texture

The `dist_texture` SPU supports server-side loading of texture images. The goal is to avoid the cost of transmitting texture image data over the "wire" with the Pack and Tilesort SPUs.

The dist_texture SPU is typically placed before the Render SPUs on the crservers in tilesort configurations.

The dist_texture SPU implements a new version of the glTexImage2D function. Specifically, the `type` parameter will accept two new values: GL_TRUE and GL_FALSE.

If type==GL_TRUE, then the dist_texture SPU will operate in write mode. The glTexImage2D `pixels` parameter will point to pixel data which is prefixed by a NULL-terminated filename (i.e. the pointer points to a block of data consisting of a filename, a zero byte and then tightly-packed GL_RGB/GL_UNSIGNED byte image data. The dist_texture SPU will write the image data to a PPM image file using the given name.

If type==GL_FALSE, then the dist_texture SPU will operate in read mode. The glTexImage2D `pixels` parameter will point to a NULL-terminated filename. The dist_texture SPU will read that named PPM image file and give it to OpenGL as the texture image.

The idea is that a program can use write-mode to distribute texture image data on a rendering cluster the first time the program is run. Then, the second and subsequent runs can use read-mode to quickly read the texture data from the render servers, instead of passing it all through the Chromium tilesort SPU.

See the NCSA Pixel Blaster program for an example of how this features is used.

The dist_texture SPU has no configuration options.

## Expando SPU

The `expando` SPU records the contents of display lists, then replays the commands when glCallList is called. The Expando SPU has no options.

## Feedback SPU

The `feedback` SPU implement's OpenGL's selection and feedback features. If your application needs either of these features, you should use the Feedback SPU in your configuration.

Parameter Name | Value Types | Description
default_viewport | Boolean | The feedbackSPU will answer glGet's for GL_VIEWPORT. When enabled the feedbackSPU will return the applications viewport size rather than the tilesortSPU returning the scaled viewport size. Default 0.

## FPS SPU

The `fps` SPU measures the time between calls to `glXSwapBuffers()`, and issues performance reports to `stderr` at regular intervals. It's useful for determining rendering performance of a Chromium configuration.

Parameter Name | Value Types | Description
report_seconds | Float | If the given number of seconds have passed since the last time a report was issued, a new report is issued. If set to `0.0`, time-based report triggers are disabled. The default value is `10.0`, meaning a report will be issued about every 10 seconds (although a report could be issued sooner if the `report_frames` option, below, is used).
report_frames | Integer | If the given number of frames have been rendered since the last time a report was issued, a new report is issued. If set to `0`, frame-based report triggers are disabled. The default value is `0`, meaning that frame-count-based reports are by default disabled. (Elapsed-time-based reports, as configured by `report_seconds` above, will still be in effect.)
report_at_end | Boolean | If set, an additional report with the average FPS across the entire run of the SPU is issued as the SPU is closing down. The default value is set.

## Hiddenline SPU

The `hiddenline` SPU draws objects in hidden-line mode.

Parameter Name | Value Types | Description
buffer_size | int | The size of command buffer used for recording OpenGL commands (in bytes). Default is 32768.
fog_color | 3 Floats | Sets the fog color (red, green, blue) when using silhouette mode.
line_color | 3 Floats | Sets the line color (red, green, blue). Default is pale black (0, 0, 0).
line_width | Float | Sets the line width (in pixels). Default is 3.
poly_color | 3 Floats | Sets the polygon color (red, green, blue). Default is white (1, 1, 1).
silhouette_mode | Boolean | If set, just render silhouette lines instead of all polygon edges.
single_clear | Boolean | Controls whether glClear commands are ignored when issued but later called in SwapBuffers. Default is true. You may need to set this to false for sort-last rendering.

## Injector SPU

XXX no description?

Parameter Name | Value Types | Description
oob_url | String | XXX

## Matte SPU

The `matte` SPU forces all rendering to be within a subwindow of a render window, initializing the area outside of the subwindow to a matte color.

Beyond simple visual effects (e.g. effectively having a color border around an application's rendering area), the Matte SPU can be used to meet constraints for some types of hardware tile composition. For example, consider a hardware compositor that will only use a 512x512 pixel subarea of a display, but requires that subarea to be precisely placed on the screen, with the rest of the screen completely black; this can be managed by using the Render SPU configured with a full-screen window, in conjunction with the Matte SPU to fill that window with black and place the rendering tile in the appropriate position. the accumulation buffer to simulate motion blur of moving objects.

Parameter Name | Value Types | Description
matte_region | 4 Integers | This specifies the subarea of a window that will actually be used for rendering, as an array of four integers `[x,y,width,height]`. The first two specify the lower-left corner of the subarea, relative to the lower-left corner of the parent window. The second two specify the width and height of the subarea. The default is `[0,0,1024,1024]`, a 1024x1024-pixel region with the lower-left corner aligned with the lower-left corner of the parent window.
use_matte_color | Boolean | This specifies that the matte area (the area outside the render subarea) will be initialized to a constant color (specified with the `matte_color` configuration option, below). The default value is 1, meaning that the matte area will be cleared to the given color.
matte_color | 4 Floats | This specifies the color that will be used to initialize the matte area (the area outside the render subarea), as an array of four floats representing `[red,green,blue,alpha]`. The default value of `[0.0,0.0,0.0,0.0]` means that the matte area will be painted black. `[1.0,1.0,1.0,0.0]` would mean that the matte area would be painted white.
every_clear | Boolean | This specifies whether the matte area (the area outside the render subarea) will be painted every time the application requests that the render subarea be cleared, or only the first time. The default value of `0` means that the matte area will be painted only the first time the render subarea is cleared; this value is appropriate for windows that will never need to repaint the matte area (e.g., a full-screen window that will never be obscured by other windows). A value of `1` means that the matte area will be painted every time the render subarea is cleared. This is appropriate for windows that will have to respond to exposure, or that might for any other reason have to repaint the matte area. require

## Motionblur SPU

The `motionblur` SPU uses the accumulation buffer to simulate motion blur of moving objects.

Parameter Name | Value Types | Description
blur | Enum | This specifies the amount of motion blur. Legal values are 'Little', 'Medium', 'Lots', and 'Extreme'. The default is 'Medium'.

## Nop SPU

The `nop` (No-operation) SPU effectively discards all commands sent to it. One use of the Nop SPU is to replace the Render SPU in order to measure system performance without doing any rendering.

## Pack SPU

The `pack` SPU simply packs all the OpenGL commands into buffer which are sent to the downstream server.

Parameter Name | Value Types | Description
emit_GATHER_POST_SWAPBUFFERS | Bool | Purpose?
swapbuffer_sync | Boolean | If set to 1, do a synchronization operation in SwapBuffers to that the pack SPU doesn't buffer up frames faster than can be rendered downstream. The default is 1.

## Perf SPU

The `perf` is used to collect performance statistics while running Chromium.

Parameter Name | Value Types | Description
dump_on_finish | Boolean | Will cause performance data to be 'dumped' when glFinish is called. Useful if SwapBuffers is not used. Default 0.
dump_on_flush | Boolean | Will cause performance data to be 'dumped' when glFlush is called. Useful if SwapBuffers is not used. Default 0.
dump_on_swap_count | Integer | Trigger when data is to be 'dumped' on hitting this amount of SwapBuffer calls. Default 0.
token | String | Mark 'interesting' performance data with tokens. Default is 'tab'.
log_separator | String | Field separator for logged data. Default is 'tab'.
mothership_log | Boolean | Send performance data to a mothership log file. Set CR_PERF_MOTHERSHIP_LOGFILE to a file on the mothership for data collection. This allows for gathering of data from multiple nodes. Default 0.
token | String | Mark 'interesting' performance data with tokens. Default is 'tab'.

## Print SPU

The `print` SPU prints each OpenGL command to stderr or a file. It's useful for debugging Chromium and inspecting the OpenGL commands issued by applications

Parameter Name | Value Types | Description
log_file | String | Name of log file to generate. May be a filename or `stdout` or `stderr`. The default is `stderr`. If this is a relative path, the file will be created relative to the current directory, which will usually be either the directory that the server was launched from, or the start directory specified for the application node. If no start directory was specified, the client log file will appear in the directory that `crappfaker` was run from.

## Readback SPU

The `readback` SPU is very similar to the Render SPU. It's special in that when SwapBuffers is called, the Readback SPU uses glReadPixels to read the contents of the color/depth buffer(s) and sends them to the next SPU in the chain with glDrawPixels. This SPU is commonly used to implement sort-last rendering configurations.

Since the readback SPU is derived from the render SPU, it accepts all configuration options that the render SPU accepts, plus a few more:

Parameter Name | Value Types | Description
extract_alpha | Boolean | If set to 1, the alpha values will be sent along with the RGB values. The default is 0.
extract_depth | Boolean | If set to 1, the depth buffer values will be used to do Z-compositing of the color images. This is used for sort-last configurations. The default is 0.
gather_mtu | Integer | ???
gather_url | String | ???
local_visualization | Boolean | If set to 1, SwapBuffers will be issued by the readback SPU so that you can actually see what's being rendered by the SPU. The default is 0.
visualize_depth | Boolean | If set to 1, the depth buffer values will be sent downstream as a luminance image, rather than sending the RGB image. This allows one to see the Z buffer values as a grayscale image. The default is 0.

## Render SPU

The `render` SPU renders OpenGL commands into a window. Virtually every Chromium configuration uses this SPU.

Parameter Name | Value Types | Description
borderless | Boolean | If non-zero, remove the window border/decoration. Only supported on X at this time. Default is 0.
default_visual | String | The default visual used for windows and rendering contexts can be set by specifying a comma-separated list of the following tokens: rgb, alpha, depth (or z), double, stencil, accum, stereo, multisample. The visual is normally determined by the application program, but in some cases, this option is useful. The default is "rgb".
display_string | String | Name of the X display to create windows on. The default is the null string, so the DISPLAY environment variable will be used. This option is only recognized when using the X Window System.
force_direct | Boolean | If true, do not allow the SPU to start if a direct rendering visual is not available. X-Windows ONLY. The default is 0.
fullscreen | Boolean | If this flag is set, the `window_geometry` parameters will be ignored, and the created window will cover the entire screen. The default is 0.
gather_url | String | Gatherer URL (default NULL)
gather_userbuf_size | Integer | XXX Size of Buffer to Allocate for Gathering (default 0).
is_swap_master | Boolean | Specify if this render spu is the master of a "swap group". Default value is 0. There should only be one master per group.
lut8 | 768 Integers | Specify an eight-bit/channel color lookup table. The first 256 integers makeup the red lookup values, the next 256 make up the green lookup values, and the final make up the blue lookup values. For example, spu.Conf('lut8', [0, 1, 2, ..., 255, 0, 1, 2, ..., 255, 0, 1, 2, ..., 255]) would provide the identity mapping. X-Windows ONLY.
num_swap_clients | Integer | This specifies the number of clients in a swap group, not counting the master. This should be set for all swap masters.
nv_swap_clients | Integer | XXX How many swaps to wait on (default 1).
nv_swap_group | Integer | NVIDIA Swap Group Number (default 0).
ontop | Boolean | If this flag is set, the window will appear on top of all other windows.
render_to_app_window | Boolean | If non-zero, the render SPU will render back into the original application window, instead of creating a new window. Default is 0. Note: this option only works if the render SPU is using the same X display as the application. You may have to set the display_string option to match the application display. Otherwise, the render SPU will print a warning that the application window ID is invalid for the render SPU's display.
render_to_crut_window | Bool | If set, a window ID will be obtained from the mothership and OpenGL rendering will go to that window. The window ID is set by the CRUT server. The default is 0.
resizable | Boolean | If non-zero, the render SPU window will be resizable by the user. The readback SPU also recognizes this flag and will adjust its window size accordingly. Default is 0.
title | String | Specifies the text to display in the titlebar of the window. If the string contains `%i` it'll be replaced by the window ID number. Default is "Chromium Render SPU".
try_direct | Boolean | If true, try to create a direct rendering visual. X-Windows ONLY. The default is 1.
system_gl_path | String | Specifies the directory (path to) the OpenGL library to use. Default (on IRIX/Linux) is /usr/lib.
show_cursor | Boolean | If non-zero, render a virtual cursor which tracks the location of the user's mouse pointer in the application window. This typically only works well with applications that constantly redraw the 3D window's contents. Default is 0. Note: you must also set the application node's show_cursor option to make this work.
swap_master_url | String | Specify the url to a master to attempt to better sync SwapBuffers. Setting this option also enables the attempted sync. See also `is_swap_master` and `num_swap_clients`
use_osmesa | Boolean | If set (and Chromium's compiled for it - see options.mk) use OSMesa for off-screen rendering.
window_geometry | 4 Integers | Geometry of the window to create. This is specified as four floating point numbers. The first two give the (x,y) position of the upper left corner of the window, relative to the upper left corner of the screen. The last two numbers give the width and height of the window, respectively. The default is [0, 0, 256, 256].
pbuffer_size | 2 Integers | If non-zero, specifies a fixed width and height for pbuffers. All pbuffers will be allocated at this fixed size. This can avoid graphics memory fragmentation issues. The default is [0, 0] - allow any size of pbuffers.
use_glxchoosevisual | Boolean | If zero, don't use the glXChooseVisual function. This is used as a work-around for some OpenGL drivers on Linux which seem to have a problem with symbol resolution (ATI). The default is 1 (use glXChooseVisual).

## Replicate SPU

The `replicate` SPU works in conjunction with the XF4VNC project. It gives a specially enhanced-VNC client developed by Tungsten Graphics, Inc. the ability to do direct rendering and gain the performance of the local graphics card at the viewer. Contact Tungsten Graphics, Inc. for more information.

Parameter Name | Value Types | Description
render_to_crut_window | Boolean | If set, the replicate SPU will work with the CRUT window.

## Saveframe SPU

The `savefame` SPU saves the image from the colorbuffer to a file whenever SwapBuffers is called. It's useful for "screengrabs".

Parameter Name | Value Types | Description
basename | String | Note: This option is obsolete. Use the `spec` option instead. Base of the filename to which to save files. All files will have a four-digit frame number and `.ppm` appended to them. Example: `frame0000.ppm`. This parameter allows you to modify the filename. There is no default. If both a basename and spec option are given, the spec option overrides the basename.
binary | Boolean | Specifies whether the PPM should be binary or not. If this parameter is set to true, saved images will be in "raw" PPM format. If this parameter is set to false, saved images will be in "ascii" PPM format. The default is true (binary).
enabled | Boolean | Specifies whether the SPU should start off saving images or not. If false, the SPU will not save frames until it receives a `glChromiumParameteri(GL_SAVEFRAME_ENABLED_CR, GL_TRUE)` call. The default is true.
format | String | The format option specifies the file format used to save frames. Currently, it must be "`ppm`" or "`jpeg`". The default is "`ppm`".
geometry | 4 Integers | Geometry of the frame to save. This is specified as four integer numbers. The first two give the (x,y) position of the upper left corner of the frame, relative to the upper left corner of the window. The last two numbers give the width and height of the frame, respectively. Any call to glViewport will override any settings given in this parameter. If no glViewport call has been made, and no geometry is set, the saveframe SPU does nothing.
single | Integer | Specifies saving a single frame. If this parameter is set, the saveframe SPU will only save a single frame. Set this to the frame number of the frame to save. The default is unset.
spec | String | A full specification of the filename to which to save frames. This should include a path (absolute or relative to the working directory of the crserver) and a filename. The filename should have `%d` in it to indicate where the frame number should be inserted. If the window is a stereo window, the filename should contain `%c` which will be replaced by L or R for each image. Note: In Python strings, the percent sign is interpreted, so you must insert a percent sign with `%%` instead of `%`. For example, `saveframespu.Conf( "spec", "myMovie/frame%%d.ppm" )` would save frames in the `myMovie` directory (assumed to be present in the working directory where crserver is started). Frames would be named `frame1.ppm`, `frame2.ppm`, `frame3.ppm`, ... `framen.ppm`. The default is "`frame%04d.ppm`".
format | String | The format option specifies the file format used to save frames. Currently, it must be "`ppm`" or "`jpeg`". The default is "`ppm`".
stride | Integer | Sets the number of frames to skip. The default is 1. This means that every frame is saved. Setting to 2 means to only save every other frame.

## Simplequery SPU

The `simplequery` SPU intercepts all OpenGL glGet*() functions and returns simple default values. This is useful when using file networking which records command streams to files.

## Tilesort SPU

The `tilesort` SPU is used to divide the framebuffer into tiles which are rendered by separate render servers. The tilesort SPU is usually used to drive tiled, cluster displays (murals). The tilesort SPU must be the last SPU in the chain and be connected to one or more downstream servers.

Parameter Name | Value Types | Description
auto_dlist_bbox | Boolean | If set, automatically compute/use bounding boxes for display lists and bucketing. Without bounding boxes, all glCallList calls are broadcast to all servers. The default is 0 (off).
bbox_line_width | Float | The width in pixels of the lines used to draw the bounding box. If the `draw_bbox` flag is not set, this parameter has no effect. The default is 5.
bbox_scale | Float | Specifies a scaling factor for bounding boxes. This is useful for vertex programs which perturb vertex positions. By setting the scale factor to 2.0, for example, you can be sure that warped/perturbed geometry still lies inside the bounding box. The default is 1.
bucket_mode | Enum | This option controls how primitives are bucketed or sorted among the render servers. Possible values are: 'Broadcast' - send all primitives to all servers. 'Test All Tiles' - test each primitive's bounding box against all tile's bounds. This is the default value. 'Uniform Grid' - the tiles form a regular grid with uniform column widths and row heights. Use a specially optimized bucketing algorithm. 'Non-Uniform Grid' - the tiles form a regular grid but the columns and rows don't all have the same width or height. An optimized bucketing algorithm will be used, but it's not as efficient as the Uniform Grid option. 'Random' - primitives are sent to a randomly-chosen server. 'Warped Grid' - the grid tiles do not form a uniform grid of any sort. Test primitive's bounding boxes against all tiles, without trivial rejection (slow). 'Frustum' - intended for use with non-planar tilesort. Geometry is tested for intersection with each server's viewing frustum.
dlist_state_tracking | Boolean | If set, record state changes in display lists to keep GL state consistant. There is a performance penalty for enabling state tracking. The default is 0 (off).
draw_bbox | Boolean | If this flag is set, the Tilesort SPU will add commands to the stream to draw the object-space bounding box around each block of geometry that is sent. This is useful for seeing the computed granularity of work, but it makes the stream of graphics commands more complex and uses some slow OpenGL commands like `glPushAttrib`. The default is 0.
emit_GATHER_POST_SWAPBUFFERS | Boolean | Emit a glChromiumParameteri After SwapBuffers. The default is 0 (off).
force_quad_bufferingf | Boolean | If set, force a non-stereo application into stereo mode. Each frame will be rendered twice, once with glDrawBuffer(GL_LEFT) and once with glDrawBuffer(GL_RIGHT). Off by default.
scale_to_mural_size | Boolean | If set to 1, the OpenGL viewport will be rescaled to match the mural size (usually the desired behaviour). If set to 0, the viewport will not be rescaled. This is useful for conformance testing. The default is 1.
retile_on_resize | Boolean | If non-zero, when the tilesort SPU's WindowSize() function is called, the SPU will try to find a new mural size and tile layout to match the new window size. Typically, the WindowSize() function is called only if the application node's track_window_size option is set. The default is 1. With some applications, setting track_window_size to 1 and retile_on_resize to 0 is needed to get reasonable results.
fake_window_dims | 2 Integers | Specifies the default window/mural size when the application doesn't create an X or Win32 application window (i.e. parallel applications, like psubmit). This is needed in order for `glViewport` and `glScissor` to work correctly. The Tilesort SPU's `glViewport` implementation will determine the size of the client window (if it exists) to determine what part of the output space the client is trying to restrict drawing to. However, if the Chromium context has been created out of thin air (i.e., with the crCreateContext call), the fake window dimensions will be returned. If these parameters are not set, and there is no client window, using `glViewport` or `glScissor` will cause a fatal run-time error.
glasses_type | Enum | Specifies the type of colored glasses used for anaglyph stereo mode. May be one of RedBlue, RedGreen, RedCyan, BlueRed, GreenRed, CyanRed. The default is RedBlue.
lazy_send_dlists | Boolean | Send display lists to servers only when needed (lazy). Display lists are sent to each server as needed (by testing bounding boxes) instead of broadcasting the lists to all servers. The default is 0 (off; broadcast to all servers).
local_tile_spec | Boolean | Specify Tiles Relative to Displays (see Warped Tile Sorting) . The default is 0 (off).
scale_images | Boolean | If set, the images passed to glDrawPixels and glBitmap are scaled to match the mural's size. glCopyPixels images are also scaled. The default is 0 (don't scale).
split_begin_end | Boolean | If this flag is set, the Tilesort SPU will break blocks of geometry into pieces if they happen to fall on a buffer boundary. This can happen if a lot of geometry is specified with no state changes, or if the MTU is small. If the flag is not set, then the Tilesort SPU will simply grow the geometry buffer beyond the MTU. The default is 1.
stereo_mode | Enum | Specifies the stereo rendering mode to use. May be one of None, Passive, CrystalEyes, SideBySide, Anaglyph. The default is None.
sync_on_swap | Boolean | If this flag is set, the Tilesort SPU will wait for a `SwapBuffers` call to be executed by all servers before continuing. This will keep the client application from getting more than one frame ahead of any of the servers, but it requires a round-trip network packet from each server. The default is 1.
sync_on_finish | Boolean | If this flag is set, the Tilesort SPU will wait for a `glFinish` call to be executed by all servers before continuing. The default is 1.
use_dmx | Boolean | This should be set to 1 if using DMX. When set, this option makes the tilesort SPU query the DMX server for updated window size/position information whenever the application window size/position changes. The DMX server information will be used to compute a new tile arrangment. The default is 0.
render_to_crut_window | Boolean | If set, a window ID will be obtained from the mothership and OpenGL rendering will go to that window. The window ID is set by the CRUT server. The default is 0.
display_string | String | Specifies the DMX display string. This may be used to override the setting of the DISPLAY environment variable.
track_window_position | Boolean | If set, poll DMX windows for position changes and update tiling parameters. Default is 0 (off).

#### Additional notes on the Tilesort SPU and display lists

- Normally, when display lists are created they're sent to all servers. Also, each glCallList() is sent to all servers. This inefficiency can be avoided if the display lists have associated bounding boxes.

  A display list can be given a bounding box by two methods:

  1. Call glChromiumParametervCR(GL_OBJECT_BBOX_CR, GL_FLOAT, 6, bbox) prior to glNewList() to specify a bounding box for the subsequent list. Be sure to reset the bounding box after creating the list.
  2. Set the Tilesort SPU's auto_dlist_bbox option. This causes the Tilesort SPU to automatically compute a bounding box from the glVertex commands compiled into the list. If the display list contains matrix transformations, the bounding box may be computed incorrectly.

- Normally, display lists are immediately sent to all servers as they're compiled. Instead, display lists can be sent to the servers only when they're drawn for the first time if the Tilesort SPU option lazy_send_dlists is set.

- Normally, state changes encapsulated inside display lists are ignored by the Tilesort SPU. This can result in rendering errors. To solve this, set the dlist_state_tracking option. Unfortunately, there is a performance penalty for using this option.

- There may be problems with nested display lists. Fortunately, few OpenGL applications use nested display lists.

## VNC SPU

The `vnc` SPU allows one to view Chromium rendering remotely with a VNC viewer. The VNC SPU is derived from the Render SPU. It renders the incoming OpenGL command stream into a window. Upon SwapBuffers, the window contents are read back and saved into a buffer. In another thread, a VNC server is running. It accepts connections from VNC viewers and returns the window image that was saved in the buffer.

For more information about VNC see RealVNC, or TightVNC.

Parameter Name | Value Types | Description
server_port | Integer | The VNC port number. Default is 5905.
screen_size | 2 Integers | Width and height of the screen buffer. Default is [1024, 768].
max_update_rate | Integer | Maximum frame rate at which to send updates to VNC clients/viewers. Useful for load balancing. Default is 10 frames per second.

## Wet SPU

The `wet` SPU causes the image to appear wavy, as if viewed through water.

Parameter Name | Value Types | Description
density | Integer | Description? Default is 5.
ior | Float | Index of refraction (between air and water?). Default is 1.2.
mesh_dice | Integer | Number of rows and columns of control points in the underlying quadrilateral mesh which is distorted. Default is 100 rows and columns.
raininess | Integer | Description? Default is 10.
ripple_freq | Float | Ripple frequency. Default is 2.
ripple_scale | Float | Scale factor for water ripples. Default is 1.
time_scale | Float | Time scale factor. Default is 1.

## ZPix SPU

The `zpix` SPU offers frame differencing and some simple-minded compression schemes to reduce network bandwidth for glDrawPixels. ZPix was built to work with the ReadbackSPU and currently only handles frame buffer writes which begin at 0,0. Frame differences are tracked in three logical buffers; one each for color, depth, and stenciling.

For applications with a lot of image coherence, frame differencing often results in many unchanged pixels which compress significantly.. The default GNU zlib compression scheme minimizes network bandwidth while the PLE compression scheme takes advantage of the special case of zero data values in the differenced frames to get good compression with much less CPU resource.

When multiple clients feed a server, it is necessary to track differences on a per client basis. To disambiguate multiple instances use the client_id to assign a unique integer id for each client.

Frame differencing is independent of compression and can be suppressed with the no_diff option. A useful artifact of suppressing frame differencing can be obtained by just suppressing it on the server. What results is a display where identical pixels are black and changed ones are not (although the colors may be whimsical and the depth buffer may become quite comical).

Several additional options provide for more verbose output and debugging.

Parameter Name | Value Types | Description
client_id | Int | Client identification to use for tracking differences Default = 0
debug | Bool | If TRUE, then perform additional debugging checks with each frame
no_diff | Bool | 0 - (default) do frame differencing 1 - suppress frame differencing
verbose | Bool | If TRUE, compression statistics printed for each frame
ztype | Enum | This specifies the compress algorithm to use: 0 - None 1 - GNU zlib compression (zparm -1 or 1-9) 2 - RLE (unimplemented) 3 - PLE a chromium-inspired RLE Default is 1 (GNU zlib)
ztype_parm | Int | Arbitrary parameter to pass to compression. Default = -1 (what zlib expects)