Provided SPU's

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

Example of setting SPU parameters are:

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 index

• API Histogram
• Array
• Binaryswap
• Distributed Texture
• Expando
• Feedback
• Fps
• Grabber
• Hiddenline
• Injector
• Matte
• Motionblur
• Nop
• Pack
• Perf
• Print
• Readback
• Render
• Replicate
• Saveframe
• Simplequery
• Tilesort
• Tracker
• VNC
• Window Tracker
• 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
[...]

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).

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.

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.

Grabber SPU

The grammer SPU intercepts calls to MakeCurrent to grab window IDs. The window ID is then sent to the mothership to set a "current window ID" variable. The value of that variable can then be queried by other SPUs for various purposes.

Hiddenline SPU

The hiddenline SPU draws objects in hidden-line mode.

Injector SPU

XXX no description?

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.

Motionblur SPU

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

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.

Perf SPU

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

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

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:

Render SPU

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

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.

Saveframe SPU

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

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.

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.

Tracker SPU

The tracker SPU allows for integration of a (head) tracking device with Chromium. This is useful for example in a cave environment where the projection reference points needs to be updated according to the viewer's head position and orientation. For detailed information see Head Tracking and Integrating Head Tracking with Chromium.

The tracker SPU listens on an UDP socket for positional data from a tracking device. It uses the screen configurations supplied by the mothership to calculate updated view and projection matrices for each screen. A screen configuration consists of the location, orientation and extension of a screen. Finally the new matrices are sent to the rendering servers using Chromium's ChromiumParametervCR() API with GL_SERVER_VIEW_MATRIX_CR and GL_SERVER_PROJECTION_MATRIX_CR.

Limitation

There is no documented way to force OpenGL to redraw. That is, to force an OpenGL application to call its display function. In order to get a timely update of the projection reference point it is however necessary that the display function is called frequently. An application will not run smoothly with the tracking device otherwise.

Examples

VNC SPU

The vnc SPU allows one to view Chromium rendering remotely with a VNC viewer. The VNC SPU is derived from the Passthrough SPU. It should normally be followed by a Render SPU in the SPU chain. The basic idea is the VNC SPU maintains a simulated framebuffer which contains images rendered by the Render SPU. The framebuffer is updated upon SwapBuffers() and glFinish/Flush(). In another thread, a VNC server is running. It accepts connections from VNC viewers and returns an image of the VNC SPU's framebuffer.

For more information about VNC see RealVNC, or TightVNC.

Window Tracker SPU

The Window Tracker SPU tracks the position and size of an arbitrary window given its display and title string. The position and size information can be obtained by an upstream SPU by calling glGetChromiumParametervCR() with target GL_WINDOW_POSITION_CR.

Wet SPU

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

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)