|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]|
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 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).
-hchanges the screen size to 1024x1024.
-WÂ scr_widthspecifies the desired width of the screen, in pixels.
-NÂ scr_heightspecifies the desired height of the screen, in scanlines.
-SÂ squarescrsizesets the screen width and height to the indicated value.
-FÂ framebufferThis 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.
-cThe â€ś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.
-dDebug option, provides a verbose description of the input file structure and image decoding process, written on standard error.
-ORestores 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/bIf 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_xoffSpecify 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_yoffSpecify a screen Y offset, which will offset the file onto the screen by the given amount.
file.rleName 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.
â€‰rle-fb â€‰truck.rle â€‰rle-fb â€‰-O â€‰text.rle â€‰rle-fb â€‰-C 0/255/0 â€‰<car.rle
â€ś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 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).
This software is Copyright (c) 1988-2013 by the United States Government as represented by U.S. Army Research Laboratory.
Reports of bugs or problems should be submitted via electronic mail to <email@example.com>.