RLE-FB(1)

NAME
rle-fb - decode run-length encoded image onto a frame buffer

SYNOPSIS
rle-fb [-Ocdh] [-F framebuffer] [-C r/g/b] [-S squarescrsize] [-W scr_width] [-N scr_height] [-X scr_xoff] [-Y scr_yoff] [file.rle]

DESCRIPTION
rle-fb decodes a University of Utah standard (Edition-3, or "Utah Raster Toolkit") Run-Length Encoded (RLE) format file (saved with fb-rle(1) or a similar program) to a frame buffer. If file.rle is not specified, standard input is read.

Each RLE file contains an image rectangle. The Utah Raster Toolkit semantics specify that the rle-fb program is to clip the RLE image rectangle to the screen of the current framebuffer, only modifying pixels in that area. In the case where the RLE file contains a rectangle of size greater than or equal to that of the current screen, then all pixels on the screen are modified. In the case where the RLE file contains a rectangle smaller than the screen, or where a portion of that rectangle has been positioned outside the bounds of the screen, then this program will only modify those screen pixels underneath the RLE image rectangle. While this is behavior can be a great boon when creating a montage of smaller images, it behoves the user to arrange for a suitable background.

If the screen size is explicitly specified by a command line option, the framebuffer is opened with exactly that size, and the RLE image rectangle is clipped to that size, even if the framebuffer hardware could support a larger size. If the screen size is not specified, then this program attempts to open the framebuffer with a size large enough to hold the entire RLE image rectangle. If the open succeeds, but the full size request is not honored, then the RLE image rectangle is silently clipped to the available screen. The RLE image rectangle can be repositioned on the screen with the -X and -Y command line options, as well as by using repos(1).

-h  changes the screen size to 1024x1024.

-W scr_width
    specifies the desired width of the screen, in pixels.

-N scr_height
    specifies the desired height of the screen, in scanlines.

-S squarescrsize
    sets the screen width and height to the indicated value.

-F framebuffer
    This option specifies which framebuffer the image is to be diplayed on. If not given, the environment variable FB_FILE is used to select the display device (see brlcad(1)). If FB_FILE has not been set, the default device for your system will be used.

-c  The ``crunch colormap'' option. If the RLE file contains a colormap, rather than loading that colormap into the framebuffer and allowing the framebuffer to apply the colormap to produce the final image, this option causes the colormap to be applied to the pixel data before it is sent to the framebuffer. In this case, the colormap in the framebuffer is undisturbed. This can be useful to preserve dramatic images created with wierd color maps such that Gamma correction (eg, for film) can also be applied. This option is recommended when producing images for export to other display systems, so that variations in the interpretation of color maps between different types of display hardware do not affect the displayed image.

-d  Debug option, provides a verbose description of the input file structure and image decoding process, written on standard error.

-O  Restores the image data in overlay mode. Only areas of the original image which were not the background color are decoded. The rest of the image already in the frame buffer is undisturbed. That this mode uses twice as many DMAs to the frame buffer as the normal mode. This is because each scanline of the previous image must be read from the framebuffer, the overlay portions of the new image written on top, and the composite scanline must be written back to the framebuffer.

-C r/g/b
    If the image is not being decoded in overlay mode, the background is normally set to the value recorded in the RLE file. This option permits the user to specify an alternate background color as a red/green/blue tripple, separated by slashes (``/''). The color intensity in each channel ranges from 0 (dark) to 255 (bright).

-X scr_xoff
    Specify a screen X offset, which will offset the file onto the screen by the given amount. (ie, -X 10 would place (0,0) in the RLE image rectangle at screen coordinate (10,0). The offset may be negative or positive. The RLE image rectangle will be clipped to the screen, as required.

-Y scr_yoff
    Specify a screen Y offset, which will offset the file onto the screen by the given amount.

file.rle
    Name of file to decode, in RLE format. If not specified, standard input is used instead.

The run length encoded image format is best used for the long-term storage of images, as it uses less disk storage than a pix(5) file, at the expense of requiring more processing for the encoding and decoding. This program is also useful when using the Utah Raster Toolkit utilities, which only operate on RLE encoded files; this program will display their results on a framebuffer.

Simple compositing of images can be done with the -O overlay flag on rle-fb(1). More sophisticated compositing can be achieved using some of the other tools. For RLE files, comp(1), crop(1), repos(1), rlepatch(1), and rlebox(1) can be used. For pix(5) files, pixrect(1), pixscale(1), and pixmerge(1) are used.

EXAMPLES
    rle-fb truck.rle
    rle-fb -O text.rle
    rle-fb -C 0/255/0 <car.rle

DIAGNOSTICS

``rle-fb:  excess arguments ignored''.
    More than one RLE file name was specified.

``rle-fb:  Error reading setup information''.
    The subroutine rle_get_setup() returned an error code. Either the file is not in Edition-2 or Edition-3 RLE format, or the file has been damaged or truncated. If the file is in Edition-1 RLE format, the orle-fb(1) program can be used to display the file.

``rle-fb: Warning: RLE image rectangle entirely off screen''
    The combined effects of the RLE image rectangle definition stored in the RLE file and any -X and -Y command line options have resulted in the RLE image rectangle being shifted entirely off the screen. While this is not an error, no screen pixels were changed. This may not have been the intent of the user, so the message is printed.

``rle-fb: correcting for old style colormap''.
    The only change between the Edition-2 and Edition-3 RLE file formats that is not upwards compatible is the format of the colormap. Edition-2 stored eight bits of data right justified in a 16-bit field, while Edition-3 stores a full 16-bit field. In order to allow this program to decode images stored in the Edition-2 format, any colormap which has the upper eight bits all zero in all colormap entries is assumed to be an Edition-2 colormap, and is adjusted for suitable display. While this heuristic may be ``tricked'' with an Edition-3 colormap with degenerate values, the picture would have been very dark, and the benefits of full upwards compatability from Edition-2 format files were deemed worth this risk.

SEE ALSO
brlcad(1), fb-rle(1), rle-pix(1), pix-rle(1), pixrect(1), pixscale(1), pixmerge(1), comp(1), crop(1), repos(1), rlepatch(1), rlebox(1), librle(3).

AUTHORS
Michael John Muuss
Paul R. Stay

SOURCE
SECAD/VLD Computing Consortium, Bldg 394
The U. S. Army Ballistic Research Laboratory
Aberdeen Proving Ground, Maryland 21005

BUG REPORTS
Reports of bugs or problems should be submitted via electronic mail to <devs@brlcad.org>.