rle-fb — decode run-length encoded image onto a frame buffer
rle-fb
[-Ocd ] [-F framebuffer
] [-C r/g/b
] [-s|S squarescrsize
] [-w|W scr_width
] [-n|N scr_height
] [-X scr_xoff
] [-Y scr_yoff
] [file.rle
]
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 behavior can be a great boon when creating a montage of smaller images, it behooves 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).
-w|W
scr_width
specifies the desired width of the screen, in pixels.
-n|N
scr_height
specifies the desired height of the screen, in scanlines.
-s|S
squarescrsize
sets the screen width and height to the indicated value.
-F
framebuffer
This option specifies which framebuffer the image is to be displayed 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 weird color maps such that Gamma correction (e.g., 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. Note 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 must be 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 triple, 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. (i.e.,
-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.
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.
More than one RLE file name was specified.
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.
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.
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 compatibility from Edition-2 format files were deemed worth this risk.
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)