.\" Copyright (c) 1986, 1987, University of Utah
.TH RLE_GETROW 3 2/2/87 3
.UC 4 
.SH NAME
rle_getrow \- Read a scanline of pixels from an RLE file.
.SH SYNOPSIS
.B
#include <rle.h>
.sp
.B
rle_getrow( the_hdr, rows );
.br
.B
rle_hdr * the_hdr;
.br
.B
rle_pixel ** rows;
.SH DESCRIPTION
.I Rle_getrow
reads information for a single scanline from the input file
each time it is called.  
.I The_hdr
should point to the structure initialized by
.IR rle_get_setup (3).
The array
.I rows
should contain pointers to arrays of characters, into which the scanline
data will be written.  There should be as many elements in
.I 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
.IR the_hdr \(-> xmax .
.I 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
.IR the_hdr \(-> ymin .
Only those channels enabled by
.IR the_hdr \(-> bits
will be returned.
.SH NOTES
If an alpha channel is present in the input and enabled (by 
.IR RLE_SET_BIT ,
see
.IR rle_hdr (3)),
then \fIrows\fP should include a \-1 entry.  (I.e., \fIrows[\-1]\fP
should point to a valid scanline array.)  The easiest way to ensure
this is to use
.IR rle_row_alloc (3)
to allocate \fIrows\fP.

.I 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
.IR the_hdr \(-> ymax ,
or explicitly testing testing for end of file on the input with
.IR feof(infile) .
The second test may fail if 
.I rle_getrow
has encountered a logical EOF in the file.  The first will always work
eventually.)
.SH EXAMPLE
The code below reads the first two
3 color scanlines of 512 pixels from an RLE file on the standard input.
.PP
.nf
.ta 1i 1.5i 2i
	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 );
	}
.fi
.SH SEE ALSO
.na
.IR rle_hdr (3),
.IR rle_row_alloc (3),
.IR rle_row_free (3),
.IR rle_get_setup (3),
.IR rle_getraw (3),
.IR rle_getskip (3),
.IR rle_putrow (3),
.IR librle (3),
.IR RLE (5).
.ad b
.SH AUTHOR
Spencer W. Thomas, Todd Fuqua
.br
University of Utah