.\" Copyright (c) 1986, University of Utah
.TH BUILDMAP 3 3/6/85 3
.UC 4
.SH NAME
buildmap \- create a color map array from an RLE file header.
.SH SYNOPSIS
.B
#include <rle.h>
.na
.HP
.B
rle_pixel ** buildmap( the_hdr, minmap, orig_gamma, new_gamma )
.PD 0
.PP
.B
rle_hdr * the_hdr;
.br
.B
int minmap;
.br
.B 
double orig_gamma, new_gamma;
.PD
.SH DESCRIPTION
The color map in the 
.IR rle_hdr (3)
structure is not in the most easily used form.  The function
.I buildmap
returns a pointer to a colormap array with certain minimum dimensions,
making it a little easier to implement color mapping in a program.
The color map from first argument,
.IR the_hdr ,
is used to build the result.  If no map is present in
.IR the_hdr ,
then an identity map of the minimum size will be returned.
.PP
The returned color map will have at least
.I minmap
rows or channels, each of which is at least 256 entries long (so that
indexing into the color map with an 8 bit 
.I rle_pixel
value will always succeed.)

The color map from 
.IR the_hdr
will be composed with a gamma compensation curve to account for the
gamma of the display for which the input color map was presumably computed.
The argument
.I orig_gamma
specifies the gamma of the compensation curve.  It would typically be
the gamma of the original display.

If 
.I gamma
is 0, then if a picture comment 
.I image_gamma=i_gamma
is present, \fIgamma\fP will be set to \fI1.0/i_gamma\fP.
Otherwise, if a comment
.I display_gamma=d_gamma
is present, \fIgamma\fP will be set to \fId_gamma\fP.  The gamma
compensation value for pixel \fIi\fP is \fI255*(i/255)^gamma\fP.

If this color map will be used directly for another display, the gamma
of this new display should be passed in
.IR new_gamma .

The returned value is a pointer to an array of pointers to arrays of 
.I rle_pixel
values.  It may be doubly indexed in C code, so that if
.I cmap
is the return value, the RGB color mapping for a pixel
.I pixval
is
.IR "(cmap[0][pixval], cmap[1][pixval], cmap[2][pixval])" .
.SH NOTES
Generally, unless the user explicitly specifies the image or original
display gamma (e.g., as with the \fB\-i\fP or \fB\-I\fP flags of
.IR getx11 (1),
you should pass 0 for
.IR orig_gamma .
This lets 
.I buildmap
use the value from \fIthe_hdr\fP, if it is present.

If you are going to use the result of buildmap to generate values to
be dithered,
.I new_gamma
should always be 1.0, and the display gamma (\fB-g\fP in
.IR getx11 )
should be passed to
.IR dithermap (3).  
If you are not planning to dither, then pass the
user supplied display gamma as 
.IR new_gamma .

The color map storage allocated by \fIbuildmap\fP can be released by
calling \fIfree( map[0] )\fP.
.SH SEE ALSO
.IR dithermap (3),
.IR rle_hdr (3),
.IR librle (3),
.IR RLE (5).
.SH AUTHOR
Spencer W. Thomas,
University of Utah