Renderer Reference

hfb_host -c command -p npes -iinputfile-Ddestname: [-O] [-n commands[,status]] [-o file_prefix] [-d commandfilename] [-tportnum]

Description

The RIVA Renderer has two parts: hfb_host, which is a communications front end, and flit, which is the parallel renderer. The user never executes flit directly, as it requires hfb_host for its input and output. The following documentation describes how to execute the RIVA renderer using hfb_host. Otherwise, the existence of the two separate programs is ignored except when absolutely necessary. Some of the described activity happens in one program, and some in the other.

Given an input terrain dataset, the Renderer consumes viewpoints and produces perspective images of the input terrain from those viewpoints. Viewpoints (and other commands) may be read from a local text file or from a network resource, such as the Flexible Flyer. The output images may be written to disk as PPM files, or sent to a remote display by means of a socket or router.

Once started, the Renderer continues to operate until it reaches the end of its command file or processes a 'BYE' command. The Renderer's command language is fully documented in the Renderer Command Language document.

Options

-c command: command is the name of the rendering program hfb_host will load onto the MPP. It is almost invariably flit.
-p npes: The number of MPP PE's on which command must be loaded. npes must be a power of 2.
-i inputfile: The name of the renderer configuration file, which defines the input terrain database.
-D destname: Names the destination for the rendered frames. The destination defines the physical device (disk, socket, or router) which will receive the frames, and the resolution of the frames. Destination names are defined in the flitrc file.
-O: Oversample. This option will render frames at quadruple the desired resolution (double in each dimension), and average the result down to the desired resolution. This technique decreases aliasing.
-n commands [status]: Directs the Renderer to read commands from a Router Resource called commands, and write status messages as the Router Resource status. status is optional, and takes the value 'RENDER_STATUS' by default. The Renderer and the Flexible Flyer must agree on the resource names to be used.
-o file_prefix: Any frames written to disk will use file_prefix as the root file name. File names will be constructed by concatenating the prefix and the frame number. For example, -o /tmp/movie would result in frame files called "/tmp/movie0000", "/tmp/movie0001", etc. This option should always be specified when frames are to be written to disk.
-d commandfilename: The Renderer will read its commands from the named file. This option and the -n option are mutually exclusive.
-t portnum: The portnum is the socket port number between hfb_host and flit.

Usage

Before the Renderer can be executed, the user must prepare a terrain database, and describe it in a configuration file. Once these have been created, the Renderer can be executed in several different ways. For example, the following command loads the terrain database described by 'earth.set', reads a series of renderer commands from 'earth.flit', and writes out rendered frames to disk as the files 'tmp/earth0000', 'tmp/earth0001', and so on. The rendered frames are 640x512 pixels, and were oversampled. The resolution was determined by checking the definition of 'diskmed' in flitrc.

% hfb_host -c flit -npes 64 -i earth.set -D diskmed -O -o tmp/earth -d earth.flit

This next example, on the other hand, reads its commands from a net resource called 'RENDERER', which is presumably the Flexible Flyer. It writes the rendered frames to a socket with port number 7000. The frames are 1280x1024 pixels. Again, the resolution and destination were determined by looking up 'sockethigh' in flitrc.

% hfb_host -c flit -npes 64 -i earth.set -D sockethigh -n RENDERER

The hfb_host command line is long, and easy to misstype, so the Renderer is usually executed via a shell script. Here is a sample script which gives easy access to a number of terrain databases in both interactive and batch modes:

#!/bin/csh
#
# render
#
# Renderer command script -- all standard scenarios can be run using
# this script.
#
# FIRST, display usage if no command argument
if ($#argv < 1) then
    echo "USAGE: render scenario [npes]"
    exit
endif
# NEXT, set constants
set outdir = $RIVAHOME/output
set defaultrouterhost = alhena
# NEXT, get scenario
set scenario = $1
# NEXT, get PEs
if ($#argv < 2) then
    set npes = 32
else
    set npes = $2
endif
# NEXT, echo inputs
echo "Running $scenario on $npes PEs."
# NEXT, set the router host if it's not set.
set i=`printenv ROUTERHOST`
if ($i == "") then
    setenv ROUTERHOST $defaultrouterhost
endif
echo "ROUTERHOST is $ROUTERHOST"
# NEXT, execute the desired scenario
switch ($scenario)
    case earth.test:
        hfb_host -c flit -p $npes -i earth.set -D diskmed \
                 -d $RIVAHOME/work/earth.flit \
                 -o $outdir/earth
        breaksw
    case earth.fly:
       hfb_host -c flit -p $npes -i earth.set -D routerlow \
                 -n RENDERER \
                 -o $outdir/earth
        breaksw
    case earth1.fly:
        hfb_host -c flit -p $npes -i earth.set -D socketlow \
                 -n RENDERER -t 6500 \
                 -o $outdir/earth
        breaksw
    default:
        echo "Error -- no such scenario."
        exit 1
        breaksw
endsw
exit

Configuration File Format

The Renderer renders terrain surfaces. Each surface consists of a terrain image and a co-registered digital elevation model (DEM), both stored in RivaFiles. The Renderer can render multiple surfaces at the same time, provided they are all describe the same planet. The renderer configuration file tells the Renderer where to find the pieces of these surfaces, and how to put them all together.

A renderer configuration file (or '.set' file, for short) can contain comment lines, blank lines, and statements. Comment lines must begin with a '#' character, in typical Unix fashion. There are four different statements that can appear in a .set file:

DATA logical_name file_name [IFL ifl_file_name [ifl_image_no]]: Identifies a data file to be loaded, and assigns it a logical name. The file may be a terrain image or DEM. RIVA supports non-RIVA input files. This feature is useful if you have a huge image/DEM file in some other format and you don't have enough disk space to make another copy in RivaFile format.; If you use a non-RIVA input file, you still have to construct a tiled RIVA file with the meta information and the tile headers. You can create an empty RIVA file using rivmake andrivadd. Then create the header information using "rivtiler -t". IFL is a optional keyword to indicate the input file is a file in Image Format (IF). Almost all the image formats are supported by SGI's Image Format Library (IFL), use imgformats to find out which formats are supported. ifl_file_name is the file name and ifl_image_no is the image index stored in the file. By default, ifl_image_no is 0.
DEM terrain_image dem: Matches a terrain image with a DEM, defining a surface. This statement uses the logical names defined by previous DATA statements.
DYNAMIC lowres_dataset hires_dataset
or
DYNAMIC base_dem displacement TIME: RIVA supports two types of dynamic datasets. The first DYNAMIC case is used to support out-of-core rendering. When the high resolution dataset is too big to load into memory, a low-resolution image/DEM (lowres_dataset)will first be loaded into memory at initialization and the corresponding high-res. image/DEM (hires_dataset) can be loaded on-the-fly when needed.
The second DYNAMIC case is used to support time-varying vertical displacement. In this case, the first argument is the base DEM name and the second argument is the time-varying dataset that is used to add a displacement to the base DEM. The two dataset has to cover the same geographical area but they may have different resolutions. When the two datasets have different resolutions, (usually, the displacement has lower resolution than the base dem.) the ratio of the tile size has to match with the ratio of the pixel resolution so that one tile in both file covers the same area.
COMBINE method: When multiple surfaces are loaded, they are rendered separately; then the resulting frames are combined using the named method. This statement must be included in the set file whether there are multiple surfaces or not. There are three methods: 'OPACITY', 'REVOPACITY' and 'ZBUF'.

Examples

Here is an example .set file, which loads three surfaces:

# marscombo.set
#
# Definition for Mars planetary dataset
#
 
# FIRST, define symbolic names for files.  The name chosen for the
# terrain image is particular important, as the Flexible Flyer will
# use it as the name for the surface formed by the terrain image and
# its DEM.

DATA marsdem  tiled_marsdem.riv
DATA Mars tiled_mars.riv
 
DATA arestiudem tiled_arestiudem.riv
DATA AresTiu tiled_arestiu.riv
 
DATA geodem  tiled_marsgeodem.riv
DATA MarsGeo tiled_marsgeo.riv
 
# NEXT, combine the terrain images and DEMs into surfaces.  Order is
# important here, as the renderer will compose the surfaces in the
# order given.  Thus, AresTiu will be rendered on top of Mars, and
# MarsGeo on top of both the other two.
DEM Mars marsdem
DEM AresTiu arestiudem
DEM MarsGeo geodem
 
# NEXT, state combination method.  In general, COMBINE OPACITY is
# always right.
COMBINE OPACITY

Here is an example .set file, which loads a high-res. image dynamically.

# x33.set
#
# Definition for 6-band LANDSAT Western US dataset
#
# FIRST, define symbolic names for files
#
DATA x33dem  /tmp/peggy/rivadata/x33dem_90m_t.riv
DATA x33data /tmp/peggy/rivadata/x33shdata_90m_t.riv

# The next two datasets are 30 meter datasets 
DATA x33dem_hi  /tmp/peggy/rivadata/x33dem_30m_t.riv 
DATA x33data_hi /tmp/peggy/rivadata/x33shdata_30m_t.riv 
#
# NEXT, relate DEMs with other images.
DEM x33data x33dem
DEM x33data_hi x33dem_hi
#
# NEXT, relate high resolution datasets to its low res counterparts.
DYNAMIC x33dem x33dem_hi
DYNAMIC x33data x33data_hi
#
# NEXT, state combination method
COMBINE OPACITY

Here is an example .set file, which loads a non-RIVA image. In this case, the image file and the DEM file are usn.til and us.dem, respectively. Both of them are in a format called "tile". It is a multiple-channel, multiple-resolution, tiled format that is defined locally in JPL. In order to read it correctly, we have to supply information such as file format, image size, output channels, etc. For a well-known image format, you usually don't need to provide those information; just the file name suffices.

# minisota.set
#
# Definition for a subset of a 6-band LANDSAT US dataset
#
# FIRST, define symbolic names for files
#
DATA minisotadem  minisotadem1_til.riv IFL us.dem#tile%size=217987,94135,1,1%type=short 1
DATA minisotadata minisota1_til.riv IFL usn.til#tile%size=217987,94135,1,6%output=4,3,1 1

# NEXT, relate DEMs with other images.
DEM minisotadata minisotadem
#
# NEXT, state combination method
COMBINE REVOPACITY

The flitrc File

The flitrc file defines the places the Renderer can send the frames it produces. There are three categories of destination: disk, socket, and router. Frames written to a disk destination are written to disk at the resolution defined by the destination. The disk files are in PPM format. Frames written to socket use the designated port number and size. The port number must match the renderer output. Frames written to router use the designated ResourceName. For all output devices, the resolution defined in flitrc is the final resolution of the rendering. The byte order field in the socket and router devices specifies number of bytes per pixel, its order and orientation. By default, the byte order is RGB with the origin located at the upper left corner. Since the SGI sets the lower left corner to (0,0), we have to use RGB_REVERSE to flip the image. For X window displays (in case you want to write your own display program), you may want to use ORGB instead.
The supported byte orders are RGB, ORGB, OBGR, RGB_REVERSE, ORGB_REVERSE, and OBGR_REVERSE.

The following listing shows a sample flitrc file. It consists of command lines, blank lines, and statements. As usual, comment lines must begin with a '#' character.

# flitrc -- resource file for the Renderer.
#
# Destination definitions
#
#    Name      Samps Lines PixelAspectRatio
disk disklow     320   256
disk diskmed     640   512
disk diskhigh   1280  1024
disk abekas      720   512 1.263


# Socket
#     Name         Samps Lines Portnum Hostname ByteOrder
socket sockethigh    960  512  7000   alhena    RGB_REVERSE
socket socketlow     640  512  7000   alhena    RGB_REVERSE

# Router
#    Name         Samps Lines  ResourceName  ByteOrder
router routerlow   640   512    RenderTest     BGR

There are several important things to note in this listing. First, the PixelAspectRatio is an optional parameter; if missing, it defaults to 1.0. It is the ratio of the height of an output pixel to its width. Most devices have square pixels. For socket, hostname and portnum must be specified, as well as byte order. For the router, the resource name must match the resource name of the receive_display. Order of parameters must be followed. The preceding flitrc example shows the correct order, which is usually of the form: TYPE NAME SAMPS LINES [device specifics] BYTE_ORDER.

The flitrc file must reside in the directory from which the Renderer is executed, e.g., $(RIVAHOME)/work.

This page, http://pat.jpl.nasa.gov/RIVA//public/RIVA/renderer.html, is maintained by Peggy Li and was last modified Monday, 25-Aug-2003 17:09:18 PDT, CL 03-2169