RISclass(3DTM)

NAME
RISclass - Raster Image Set DTM message class.

SYNOPSIS
#include <ris.h>

RISheaderLength(char *header)

RISHL(char *header)

RISsetClass(char *header)

RIScompareClass(char *header)

void RISsetDimensions(char *header, int xdim, int ydim)

int RISgetDimensions(char *header, int *xdim, int *ydim)

RISsetTitle(char *header, char *title)

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

RISsetType(char *header, RISTYPE raster_type)

RISgetType(char *header, RISTYPE *raster_type)

DESCRIPTION
The RIS message class is a DTM class designed specifically for the transmission of raster images. Each of the macros and functions listed above places information that describes the qualities of the raster image into the header. Several constants have been defined to be used as tags that identify particular properties of this class. While these constants are available for use at any time following the inclusion of ris.h, it is highly recommended that programmers use the functions and macros listed above to correctly manipulate the headers for this class. The tags include:

RISclass - The tag that identifies the message as belonging to the raster image class of messages.

RISsize - A constant for declaring raster image header sizes. Though the size of the header can be arbitrary, it's doubtful that the header length will exceed this value.

RISdims - The pair of integers in the header following this flag indicates the expected dimensions of the image in pixels.

PALtype - The tag that identifies the subsequent value as being the type of image being sent: either RIS8BIT or RIS24BIT. RIS24BIT assumes that each pixel is composed of three, closely packed, eight-bit number representing the red, green, and blue color components of the color. I.e. RGBRGBRGB... where each or R, G, and B is a value between 0 and 255. Twenty-four bit images are considered "direct color" images because there is no need for a palette. On the other hand, the type RIS8BIT assumes that each byte of data is one of 256 possible entries into some non- specified colormap. RIS functions make no assumptions about the existance of colormaps so it is up to the user to supply a colormap if one is needed. See PALclass for more information on palettes.

Certain graphics libraries, require raster image data to be in a format different from what is described above. If a different format is required, then it is the user's responsibility to pack/unpack the data into the format desired.

It is also important to be aware that the RISclass is theoretically a sub-class of the scientific data set class of messages (SDS). The RISclass of messages has been provided to distinguish raster images from other form of scientific data, though that distinction is not necessary.

The RISclass contains the following supported functions and macros:

RISheaderLength:
RISHL: Macros for determining a view control header length. These two macros are equivalent. They both return the exact length of the supplied character string header, counting the null character at the end.

RISsetClass: inserts the message class constant RISclass into the character string header indicating that the data to follow should be considered some form of a raster image. The RISclass constant is declared in the file ris.h, and though it is accessible at all times, it is recommended that the macro RISsetClass be used to correctly insert this message type tag into the header.

RIScompareClass: returns a non-zero value if the character string header contains the RISclass constant. Though the constant RISclass is accessible at all times, it is recommended that the macro RIScompareClass to determine whether or not a header indicates raster image data.

RISsetDimensions: inserts into the string header the RISdims flag followed by the two dimensions xdim and ydim of the raster image. It is the user's responsibility to ensure that the dimensions specified here match the actual dimensions of the data.

RISgetDimensions: examines the string header and returns the specified dimensions, xdim and ydim, of the raster image. There is no guarantee that the dimensions read from the header will match the dimensionality of the data received since RISgetDimensions has no way of reviewing and interpreting the data.

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

RISgetTitle examines the string header and determines the title string that it contains. Memory for the title string 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.

RISsetType: inserts into the string header the tag RIStype immediately followed by a tag identifying the raster_type of the image. The tag type should be either RIS8BIT or RIS24BIT. It the user's responsibility to ensure that the data type specified matches the data sent. RISsetType also inserts the DTM type tag followed by the tag for the type DTM_CHAR. This is set to ensure that each RISclass message can still be considered a full-blown SDSclass with the data type DTM_CHAR.

RISgetType examines the string header, and if the RIStype tag is found, sets the argument raster_type to be the next value. The two defined values that can be returned are RIS8BIT and RIS24BIT. If the RIStype tag was not found within the header, the raster_type argument receives a default value of RIS24BIT.

SEE ALSO
The DTM Programming Manual

DIAGNOSTICS
RISgetDimensions, RISgetTitle, and RISgetType all return a value of 0 upon successful parsing of the header. If the tag that each is searching for is not present in the header, the functions return the error value DTMERROR. In general, no values are assigned to any of the arguments with the exception of the RISgetType's argument raster_type: in this case the default value of RIS24BIT is returned.

BUGS
None of the RISset* functions and macros have any way of determining if the header contains sufficient space to hold the data-specific tag and the associated data. The results of attempting to store this information beyond the end of the allocated space are undefined.

RISgetDimensions assumes that two dimensions follow the RISdims flag. If less than two integers follow the tag, the results are undefined.