VCTRLclass(3DTM)

NAME
VCTRLclass - A view control message class.

SYNOPSIS
#include <sdl.h>

VCTRLheaderLength(char *header)

VCTRLHL(char *header)

VCTRLsetClass(char *header)

VCTRLcompareClass(char *header)

VCTRLsetGTM(char *header)

VCTRLgetGTM(char *header)

VCTRLsetTitle(char *header, char *title)

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

DESCRIPTION
This message class was designed to be used as a method of communicating view control matrices via DTM. The view control matrices used are the 4x4 floating point matrices interpretable by SGI's GL (graphics library). This class is fairly limited in scope and is provided without any guarantees of further development or support.

The macros and functions that are included with this class include:

VCTRLheaderLength:
VCTRLHL: - 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.

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

VCTRLcompareClass: returns a non-zero value if the character string header contains the VCTRLclass constant. Though the constant VCTRLclass is accessible at all times, it is recommended that the macro VCTRLcompareClass to determine whether or not a header indicates a view control matrix.

VCTRLsetGTM: inserts into the character string header the tag VCTRLgtm identifying this message as containing a global transformation matrix.

VCTRLgetGTM: examines the character string header, and if the VCTRLgtm tag if found, returns a non-zero value. If the VCTRLgtm tag is not found, then zero is returned.

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

VCTRLgetTitle: examines the character string header and determines the title string that is contained. 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.

SEE ALSO
The DTM Programming Manual

DIAGNOSTICS
VCTRLgetTitle 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, VCTRLgetTitle returns a 0 value.

BUGS
None of the VCTRLset* 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.