PALclass(3DTM)

NAME
PALclass - A message class for handling palettes.

SYNOPSIS
#include <ris.h>

PALheaderLength(char *header)

PALHL(char *header)

PALsetClass(char *header)

PALcompareClass(char *header)

PALsetSize(char *header, int num_elements)

PALgetSize(char *header, int *num_elements)

PALsetTitle(char *header, char *title)

PALgetTitle(char *header, char *title, int title_length)

DESCRIPTION
This message class is to be used for sending pallette (color table) information via DTM. Palettes in this message class are represented by three one-byte (unsigned character) triples where the first byte represents the intensity of the red color; the second, the intensity of the green; and the third, the intensity of the blue. The entries in the palette are assumed to be in contiguous order, that is, the numbering of each triple is implicit: the first triple received is the first color table value (Fig. 1).
           Implicit Order Index Color Table
           -------------- ----- +---+---+---+
           First palette value-> 0 | 0| 0| 0|
           Second value--------> 1 | 16| 0| 0|
                        2 | 32| 0| 0|
                        ...
           Last value----------> N | 0| 0|255|
                        +---+---+---+
                       (Fig. 1) The macros and functions that are associated with this class include:

PALheaderLength:
PALHL: These two macros are equivalent. They both return the exact length of the supplied character string header, counting the null character at the end.

PALsetClass: inserts the message class constant PALclass into the character string header indicating that the data to follow should be interpreted as a palette. The PALclass constant is declared in the file ris.h, and though it is accessible at all times, it is recommended that the macro PALsetClass be used to correctly insert this message type tag into the header.

PALcompareClass: returns a non-zero value if the character string header contains the PALclass constant. Though the constant PALclass is accessible at all times, users should use the macro PALcompareClass to determine whether or not a header indicates palette data.

PALsetSize inserts into the character string header the tag PALentries followed by the value num_elements that is supposed to indicate the number of color triples available in the palette. It is up to the user to ensure that the exact number of entries specified are actually contained within the data portion of the message.

PALgetSize examines the character string header and sets the integer num_elements to be the size of the palette contained in the dataset that is supposed to follow the receipt of the header. If no size is found within the header, and since palettes are typically comprised of 256 elements, the value num_elements is assigned the value 256. It is the user's responsibility to ensure that the value returned by num_elements exactly matches the number of elements that are actually contained in the data.

PALsetTitle inserts the DTM title tag followed by the null-terminated character string title into the string header. The title is delimited by single quotation marks so that it's contents will not affect the interpretation of the header.

PALgetTitle examines the string header and determines the title string that it contains. Memory for the character string title must be allocated by the user before attempting to extract the title from the header. If there is insufficient memory allocated to store the entire title as contained in the header, the title string is truncated.

SEE ALSO
DTM

DIAGNOSTICS
PALgetSize returns the error DTMERROR if the header does not contain the tag PALentries or if no value follows the PALentries tag. In either case, the value of num_elements still defaults to 256.

PALgetTitle returns the error DTMERROR if the DTM title tag is not contained within the header, or if following the tag there is no delimited title string. Otherwise, PALgetTitle returns the value DTM_OK (DTMNOERROR).

BUGS
With this class, support for sending portions of palettes with their positions in the new color map explicitly defined does not exist. This problem is due to the fact that the ordering of the colors is implicit in the data.

X likes to have it's color triples specified in the range 0-65535 per electron gun (color value) even though it is much more common to have a range of 0-255. Therefore, it's the user's responsibility to massage the data into the correct format needed for whatever is required by the correct visual type.

PALsetClass, PALsetSize, PALsetTitle, each have no way of determining if the character string header contains sufficient space to hold all of the necessary tags and other information. The results of attempting to store this information beyond the end of the allocated space are undefined.