DragonFly On-Line Manual Pages

Search: Section:  

RLE_GETROW(3)         DragonFly Library Functions Manual         RLE_GETROW(3)


NAME

       rle_getrow - Read a scanline of pixels from an RLE file.


SYNOPSIS

       #include <rle.h>

       rle_getrow( the_hdr, rows );
       rle_hdr * the_hdr;
       rle_pixel ** rows;


DESCRIPTION

       Rle_getrow reads information for a single scanline from the input file
       each time it is called.  The_hdr should point to the structure
       initialized by rle_get_setup(3).  The array rows should contain
       pointers to arrays of characters, into which the scanline data will be
       written.  There should be as many elements in rows as there are primary
       colors in the input file (typically 1 or 3), and the scanline arrays
       must be indexable up to the maximum X coordinate, as specified by
       the_hdr->xmax.  rle_getrow returns the y value of the scanline just
       read.  This will always be 1 greater than the y value from the scanline
       previously read, and starts at the_hdr->ymin.  Only those channels
       enabled by the_hdr->bits will be returned.


NOTES

       If an alpha channel is present in the input and enabled (by
       RLE_SET_BIT, see rle_hdr(3)), then rows should include a -1 entry.
       (I.e., rows[-1] should point to a valid scanline array.)  The easiest
       way to ensure this is to use rle_row_alloc(3) to allocate rows.

       Rle_getrow will continue to return scanlines even after the end of the
       input file has been reached, incrementing the return scanline number
       each time it is called.  The calling program should use some other
       termination criterion (such as the scanline number reaching
       the_hdr->ymax, or explicitly testing testing for end of file on the
       input with feof(infile).  The second test may fail if rle_getrow has
       encountered a logical EOF in the file.  The first will always work
       eventually.)


EXAMPLE

       The code below reads the first two 3 color scanlines of 512 pixels from
       an RLE file on the standard input.

                 char scanline[2][3][512], *rows[3];
                 int row, i;
                 rle_dflt_hdr.rle_file = stdin;
                 rle_get_setup( &rle_dflt_hdr );
                 for ( row = 0; row < 2; row++ )
                 {
                      for ( i = 0; i < 3; i++ )
                           rows[i] = scanline[row][i];
                      rle_getrow( &rle_dflt_hdr, rows );
                 }


SEE ALSO

       rle_hdr(3), rle_row_alloc(3), rle_row_free(3), rle_get_setup(3),
       rle_getraw(3), rle_getskip(3), rle_putrow(3), librle(3), RLE(5).


AUTHOR

       Spencer W. Thomas, Todd Fuqua
       University of Utah

4th Berkeley Distribution           2/2/87                       RLE_GETROW(3)

Search: Section: