ICE-T(7)

NAME
ICE-T - Image Composition Engine for Tiles

SYNOPSIS
#include <GL/ice-t.h>

DESCRIPTION
The Image Composition Engine for Tiles (ICE-T) is an API designed to enable OpenGL applications to perform Sort-Last parallel rendering on very large displays. The displays are assumed to be tile displays. The overall resolution of the display may be several times larger than any viewport that may be rendered by a single machine. It is also assumed that several processes in the parallel application are display processes. That is, their entire display window makes up part of the display.

The design philosophy behind ICE-T was to allow very large sets of polygons to be displayed on very high resolution displays. As such, fast frame rates have been sacrificed in lieu of very scalable and very high polygon/second rendering rates. In applications that require only moderate size data to be rendered on high-resolution tile displays, the user may best be suited with API's with approaches offering potentially higher frame rates such as Wire-GL or Chromium.

ICE-T is designed to take advantage of spatial decomposition of the geometry being rendered. That is, it works best if all the geometry on each process is located in as small a region of space as possible. When this is true, each process usually projects geometry on only a small section of the screen. This results in less work for the compositing engine.

ICE-T can also be used to perform sort-last parallel rendering to a single display. Such single-tile rendering is simply a special case of the multi-tile display ICE-T was designed for. Many of the optimizations done by ICE-T apply to the single-tile mode. Using ICE-T for this purpose is quite worthwhile. ICE-T's performance should rival that of other such software image compositors.

The rest of this document describes the use of the ICE-T API. There are also separate manual pages for each of the functions described here. For more details on ICE-T's algorithms, see:

Moreland, Wylie, and Pavlakos. ``Sort-last parallel rendering for viewing extremely large data sets on tile displays,'' In Proceedings of IEEE Symposium on Parallel and Large-Data Visualization and Graphics, October 2001, pp. 85-154.

COMMUNICATORS
Before ICE-T can function, it must have a communicator. A communicator is described by an ``object'' of type IceTCommunicator. (Here we are using the term object loosely since it is actually implemented as a C struct.) IceTCommunicator is an abstract object that can potentially be implemented with a wide variety of communication APIs. An implementation of IceTCommunicator that uses MPI is provided with ICE-T. To use it, include icet-t_mpi.h. An ICE-T communicator can be built from an MPI communicator with icetCreateMPICommunicator and a later deleted with icetDestroyMPICommunicator.

INITIALIZATION
Before an application can use ICE-T, it must create a context. This can be done with a call to icetCreateContext. A context may be deleted with a call to icetDestroyContext. Failing to create a context will make the behaviors of all other ICE-T functions undefined (and will probably result in a segmentation fault).

The typical application will probably need only one context, so calling icetCreateContext at program startup and calling icetDestroyContext at program exit is usually sufficient. See the section CONTEXTS below for more information on using contexts.

A context also requires a bit of setup before rendering and image composition can begin. A strategy, tile layout, and drawing function must all be set. See the following sections for more details.

STRATEGIES
ICE-T provides several different strategies for composing multiple tile images in an efficient manner. The strategy used must be set with icetStrategy before any rendering and image composition may be performed with ICE-T. If no particular strategy is clearly the best choice, ICET_STRATEGY_REDUCE is a good generic strategy to use. A textual description of the current strategy can be retrieved with icetGetStrategyName.

TILE DISPLAY LAYOUT
Before ICE-T can do its compositing, it must know the topology of the tile display. The display is defined as a set of tiles. Each tile is defined as a rectangular region of pixels in a large, logical window, much like a viewport in OpenGL is a region of pixels in a physical window. Each tile is also associated with a unique process. The pixels in the physical window are assumed to be projected as the described tile in the overall display.

The set of tiles used in the display are described through the use of two functions. First, icetResetTiles is called to clear out any previous tile definitions. Then, icetAddTile is called multiple times, each time adding a new tile to the display. icetAddTile specifies the layout of an additional tile in the overall display and the rank of the processor whose output is plugged into that part of the display.

The current ICE-T algorithms were designed around the assumption that all of the tiles are of the same size, so for the moment it is best to follow this convention. Otherwise, there are no restrictions on how tiles are lain out. Mullions and overlaps can be implemented simply by laying tiles out properly. It is also usually assumed that each processes' rendering viewport is the same size as the tiles. However, there may be a significant advantage to having a rendering viewport that is larger then the tiles. So if the size of a rendering window does not match the size of a tile, use icetRenderableSize to inform ICE-T on the actual size of the rendering viewport.

RENDERING
Because ICE-T does image compositions on large tile displays, it is a requirement that ICE-T be able to render the same frame with multiple projections (for the various tiles). It does this through the use of callbacks. The application sets the drawing callback function with icetDrawFunc. When ICE-T needs a tile rendered, it will set the appropriate projection matrix and call the drawing callback.

In order for ICE-T to efficiently perform large screen compositions, it must know the bounds of the geometry on each process. The geometry bounds are set with icetBoundingVertices (or with one of the icetBoundingBox convenience functions). The geometry drawn by the drawing callback must fit within the hull of the bounding vertices. Otherwise the geometry may be culled in unexpected ways. If the bounds are not specified, ICE-T will assume that the geometry spans the entire display. For single-tile applications, this may be perfectly acceptable, but for large, multi-tile displays, this will probably result in abysmal performance.

After the tiles, rendering callback, and geometry bounds are set up, ICE-T is ready to render a frame. To render a frame, set up the OpenGL projection and modelview matrices and then call icetDrawFrame. icetDrawFrame will transform the geometry bounds and determine into which tiles the geometry may project. It then calls the rendering callback multiple times with different projections to get the tile images, and composes these images together.

STATE
Like OpenGL, ICE-T operates as one big state machine. Also like OpenGL, ICE-T provides a means to retrieve information about the current state. The icetGet functions (icetGetDoublev, icetGetFloatv, icetGetIntegerv, icetGetBooleanv, and icetGetPointerv) will retrieve data pertaining to a given state.

In addition, the icetEnable and icetDisable functions can be used to change the part of the state that controls how ICE-T behaves. The icetIsEnabled function will return the current state of one of these flags.

IMAGE COMPOSITION
ICE-T supports two image composition operations. The first is the Z-compare operation. In this operation, the OpenGL depth buffer is read as part of the pixels. When two pixels are compared, the one with that is closest (that is, has the minimum depth value) is selected for the output.

The second operation is the color blend operation. In this operation, the pixel colors are blended with the Porter and Duff OVER operator (or equivocally the UNDER operator depending on which is on top). See Porter and Duff, SIGGRAPH 1984 for more information on how this color blending operation works. This composition operation is not commutative; that is, order matters. Therefore, when using the color blend operation, it is wise to enable ICET_ORDERED_COMPOSITE and specify a composite order. See icetCompositeOrder for more details.

The image composition method is chosen implicitly by which buffers ICE-T is asked to compose. If a depth buffer is selected as an input buffer, then Z-compare is used. If a depth buffer is not selected as an input buffer, then color blending is used. This scheme was chosen because color blending makes no sense on a depth buffer, and Z comparison makes no sense without a depth buffer. The input (and output) buffer may be selected with icetInputOutputBuffers.

DATA REPLICATION
ICE-T supports K-way data replication. That is, if two or more processors draw exactly the same geometry, ICE-T can use this to its advantage to reduce the amount of image composition work that is required. Groups of processors that share data can be specified with the icetDataReplicationGroup and icetDataReplicationGroupColor functions.

TIMING
ICE-T keeps several timing statistics for testing purposes and for monitoring by user applications. The timing statistics are stored in a set of state parameters which can be retrieved with the icetGet functions. The following statistics are available:

ICET_RENDER_TIME
    Time spent in the rendering callback.

ICET_BUFFER_READ_TIME
    Time spent while reading OpenGL buffers.

ICET_BUFFER_WRITE_TIME
    Time spent while writing OpenGL buffers.

ICET_COMPRESS_TIME
    Time spent compressing image data with active pixel encoding.

ICET_COMPARE_TIME
    Time spent performing Z comparisons.

ICET_COMPOSITE_TIME
    Total time spent compositing images.

ICET_TOTAL_DRAW_TIME
    Total time spent in the last call to icetDrawFrame.

ICET_BYTES_SENT
    Total number of bytes sent while transferring images.

All of these statistics are reset at the begining of a call to icetDrawFrame. They are also all local to each processor. So, for example, ICET_TOTAL_DRAW_TIME may give a smaller than expected time if the calling processor had less work to do than others. Except for ICET_BYTES_SENT, all these statistics are given in seconds and stored as doubles.

DIAGNOSTICS AND ERRORS
ICE-T has two mechanisms to deal with anomalous conditions: diagnostics and errors. During its operation, ICE-T has the ability to print diagnostic messages to standard output. Use icetDiagnostics to set which diagnostics are printed. Also, if an anomalous condition occurs, ICE-T will set an error flag. This flag can be retrieved with icetGetError.

CONTEXTS
It is conceivable that ICE-T may be used in several configurations at one time. A user may, for example, wish to swap between separate tile layouts. This functionality is facilitated by contexts. Each context has its own state. At any given point in time, a single context is in use. Contexts may be changed to swap states quickly.

When ICE-T is initialized, a default context is created. Additional contexts may be created with icetCreateContext and destroyed with icetDestroyContext. A handle for the current context can be retrieved with icetGetContext, and the context may be changed with icetSetContext. Also, an entire state may be copied from one context to another with icetCopyState.

COPYRIGHT
Copyright © 2003 Sandia Corporation
Under the terms of Contract DE-AC04-94AL85000, there is a non-exclusive license for use of this work by or on behalf of the U.S. Government. Redistribution and use in source and binary forms, with or without modification, are permitted provided that this Notice and any statement of authorship are reproduced on all copies.

SEE ALSO
ICE-T_buckets