.\" Copyright (c) 1986, University of Utah
.TH RLE_HDR 3 2/2/87 3
.UC 4
.SH NAME
rle_hdr \- Structure for communication with RLE functions.

.SH SYNOPSIS
.B
#include <rle.h>
.sp
.B
rle_hdr rle_dflt_hdr;
.sp
.B
RLE_SET_BIT(the_hdr,bit)
.br
.B
RLE_CLR_BIT(the_hdr,bit)
.br
.B
RLE_BIT(the_hdr,bit)
.br
.B
rle_hdr the_hdr;
.SH DESCRIPTION
This data structure provides communication to and between all the 
.IR RLE (5)
file routines.  It describes the parameters of the image being saved
or read, and contains some variables describing file state that are
private to the routines.  The public components are described below.

.nf
.ta 1i 1.8i 2.8i
     typedef unsigned char rle_pixel;
     typedef unsigned short rle_map;

     rle_hdr {
	int	ncolors,	/* Number of colors being saved */
		*bg_color,	/* Background color array */
		alpha,	/* if \(!= 0, save alpha channel (color -1) */
			/* alpha channel background is always 0 */
		background,	/* if = 0, no background processing */
			/* if = 1 or 2, save only non-bg pixels */
			/* If 2, set clear-to-bg flag in file */
		xmin,	/* Min X bound of saved raster */
		xmax,	/* Max X bound */
		ymin,	/* Min Y bound */
		ymax,	/* Max Y bound */
		ncmap,	/* number of color channels in color map */
			/* if = 0, color map is not saved */
		cmaplen;	/* Log2 of the number of entries in */
			/* each channel of the color map */
	rle_map	*cmap;	/* pointer to color map, stored as 16-bit */
			/* words, with values left justified */
	char	**comments;	/* Pointer to array of pointers */
			/* to comment strings. */
	FILE *	rle_file;	/* I/O to this file */
	/* 
	 * Bit map of channels to read/save.  Indexed by (channel mod 256).
	 */
	char    bits[256/8];
    };
.fi

A global variable,
.IR rle_dflt_hdr ,
is available, conveniently initialized with default values.
.SH FIELDS
.TP
.I ncolors
The number of colors (exclusive of the alpha channel) in the image.
This is one greater than the largest channel index (i.e.,
\fIncolors\fP would be 3 if channels 0, 1, and 2 were saved, or if
only channel 2 were saved.)
.TP
.I bg_color
A pointer to an array of \fIncolors\fP integers, defines the
background color (if used).  The background alpha value is always 0,
so is not included in the \fIbg_color\fP array.
.TP
.I alpha
If non-zero, an alpha channel is present as channel \-1.  This
should always be 0 or 1.  \fIRle_get_setup\fP and \fIrle_put_setup\fP
enforce this constraint.  The alpha channel will only be actually read
or written if the corresponding bit in \fIbits\fP is also set.
.TP
.I background
Controls whether background color processing is done.  If 0, no
background processing is done at all (and \fIbg_color\fP is ignored).
If 1 or 2, then runs of 3 or more pixels in the background color are
not saved at all.  If 2, then these runs will be restored by
\fIrle_getrow\fP; if 1, they will not (this can lead to some strange
images).
.TP
.I xmin, xmax, ymin, ymax
The bounds of the image.  All pixels from \fIxmin\fP to \fIxmax\fP,
inclusive, in rows numbered from \fIymin\fP to \fIymax\fP, inclusive,
will be saved.  Thus the dimensions of the image are
.br
.I
	(xmax - xmin + 1) \(mu (ymax - ymin + 1)
.TP
.I ncmap, cmaplen
The size of the saved colormap (if any).  The color map will have
\fIncmap\fP channels, each \fI2^cmaplen\fP long.  If \fIncmap\fP is
zero, no color map is present.
.TP
.I cmap
A pointer to colormap data, if present.  The data is stored in
"channel major" order, so that all the values for channel 0 precede
all the values for channel 1, etc.  Each individual value is
left-justified in 16 bits (i.e., the range of values is 0\-65535).
.TP
.I comments
A pointer to picture comment data, if present.  Use the functions
.IR rle_putcom (3),
.IR rle_getcom (3),
and
.IR rle_delcom (3)
to manipulate this field.
.TP
.I rle_file
The standard I/O \fIFILE\fP pointer for the file containing this
image.
.TP
.I bits
A bitmap that selects the channels that are actually written to/read
from the file.  The macros below are used to modify this bitmap.
.SH MACROS
The macro
.IR RLE_BIT 
will retrieve the state of one of the bits in the
.I bits
map.
.IR RLE_SET_BIT ,
and
.I RLE_CLR_BIT
set and clear bits in the 
.I bits
map.  The predefined symbols
.IR RLE_RED ,
.IR RLE_GREEN ,
.IR RLE_BLUE ,
and
.IR RLE_ALPHA ,
or an integer value from \-1 to 254
may be used in these macros.
.SH SEE ALSO
.IR librle (3),
.IR RLE (5).
.SH AUTHOR
Spencer W. Thomas, Todd Fuqua