SDLclass(3DTM)

NAME
SDLclass - The Surface Description Language DTM message class.

SYNOPSIS
#include <sdl.h>

SDLheaderLength(char *header)

SDLHL(char *header)

SDLsetClass(char *header)

SDLcompareClass(char *header)

SDLsetPrimitive(char *header, SDLprim_t primitive_type)

SDLgetPrimitive(char *header, SDLprim_t *primitive_type)

SDLsetTitle(char *header, char *title)

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

void SDLsetBoundingBox(char *header, float min[3], float max[3])

int SDSgetBoundingBox(char *header, float min[3], float max[3])

DESCRIPTION
The SDL message class is a DTM class designed specifically for the transmission of geometric information. Each of the macros and functions listed above places information into the message header that describes how to interpret the data section of the message. Several constants have been defined to be used as tags that identify particular properties of this class. These include:

SDLclass - The tag that identifies the message as belonging to the surface description language class of messages.

SDLprimitive - The tag used to identify the primitive type being sent: SDLpoint, SDLlineseg, SDLtriangle, SDLquad, or SDLsphere

SDLbounds - A tag for identifying bounding box information.

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

While these constants are available for use at any time following the inclusion of sdl.h, it is highly recommended that programmers use the functions and macros described below to correctly manipulate the headers for this class.

There are currently five primitive types defined by the SDL message class. These five supply information about how the data possibly may be interpreted:

SDLpoint - each DTM_TRIPLET with the tag SDLposition is considered an individual vertex.

SDLlineseg - each pair of DTM_TRIPLETs with the tag SDLposition are considered endpoints of a line segment.

SDLtriangle - each triplet of DTM_TRIPLETs with the tag SDLposition are considered the three vertices of a triangle.

SDLquad - each group of four DTM_TRIPLETs with the tag SDLposition are considered the four vertices of a quadrilateral.

SDLsphere - each DTM_TRIPLET is the center of a sphere. The radius of the sphere is currently left to the user's discretion, though this fact may change in future releases.

The data for a surface description language message consists entirely of DTM_TRIPLETs. These triplets have the following structure:

      typedef struct DTM_TRIPLET {
         SDLtriplet tag;
         float x, y, z;
      } DTM_TRIPLET;

The tag value is used to interpret the three floating point values, x, y, and z. This tag can take any one of the following supported values: SDLposition, SDLcolor, SDLnormal, SDLtranslate, SDLrotate, or SDLscale. Tag values above the predefined constant SDLmaxTriplet are unreserved and can be used by the applications programmer.

The interpretation of each coordinate triple is thus:

SDLposition - the triple forms a point in 3-space. SDLcolor - the triple denotes the percent (over the range 0.0 to 1.0 inclusive) of the maximum intensity of each color value where x=red, y=green, z=blue. SDLnormal - the triple forms a surface normal. SDLtranslate - the triple specifies a translation vector. SDLrotate - the triple specifies the amount of rotation, in radians, about each of the three principle axes. SDLscale - the triple specifies the scaling factor in the direction of each principle axis.

The typical way of associating these different triplet tag types is to make the current value for the last five types hold for all SDLpositions until an updated value is encountered. Ie. the order, omitting the x, y, and z values: SDLnormal SDLposition SDLcolor SDLposition SDLposition associates the first SDLnormal with all SDLpositions, and the SDLcolor with only the last two SDLpositions. This interpretation is not required though, as applications are free to interpret this, and any data from any class, in any desired manner.

The following functions and macros are used to support the behavior of the SDL message class:

SDLheaderLength:
SDLHL: - These two macros are equivalent. They both return the exact length of the supplied character string header, including the null character at the end.

SDLsetClass inserts the message class constant SDLclass into the character string header indicating that the data to follow should be considered surface description language information.

SDLcompareClass returns a non-zero value if the character string header contains the SDLclass constant. Though the constant SDLclass is accessible at all times, it is recommended that the macro SDLcompareClass to determine whether or not a header indicates surface description data.

SDLsetPrimitive inserts into the header the tag SDLprimitive immediately followed by a tag identifying the primitive type of the data. The primitive_type should be one of the following: SDLpoint, SDLlineseg, SDLtriangle, SDLquad, or SDLsphere.

SDLgetPrimitive examines the character string header, and if the SDLprimitive tag if found, sets the argument primitive_type to be the succeeding value. The defined values that can be returned are SDLpoint, SDLlineseg, SDLtriangle, SDLquad, and SDLsphere. If the SDLprimitive tag was not found within the header, the default value returned is SDLpoint.

SDLsetTitle 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.

SDLgetTitle 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.

SDLsetBoundingBox is used to provide information about the minimum and maximum coordinate extents of the data. The vector min should contain the minimum x, y, and z values of every point in the data set. The vector max should contain the maximum x, y, and z values of every point in the data set. In this manner, the minimum and maximum vertices form opposing corners of a cube that completely encloses all of the data. In otherwords, the minimum and maximum x values (the first value in the vectors) form the left and right sides of the cube enclosing the data set. The minimum and maximum y values (the second value in the vectors) form the bottom and top sides of the cube. And, the minimum and maximum z (third) values form the near and far sides of the bounding cube. It is the caller's responsibility to ensure that the values set by SDLsetBoundingBox actually match the minimum and maximum values in the dataset.

SDLgetBoundingBox is used to retrieve information about the minimum and maximum coordinate extents of the data from the header. Upon successful completion of this funciton, the vector min will contain the values that should represent the minimum x, y, and z values of every point in the data set, and the vector max will contain the values that should represent the maximum x, y, and z values of every point in the data set. Thus, the minimum and maximum vertices form opposing corners of a cube that should completely enclose all of the data. It is impossible to ensure that the values returned by SDLgetBoundingBox match the actual minimum and maximum extents in the data; it is the user's responsibility to guarantee that the extents, when set, are correct, or to check the extents against the data received.

SEE ALSO
The DTM Programming Manual

DIAGNOSTICS
Upon successful completion of their operation, each SDL class function returns a zero value.

SDLgetBoundingBox returns a value of DTMERROR if the header lacks the SDLbounds flag or the six values that correspond to the two opposing corners of the bounding cube.

SDLgetPrimitive returns the error DTMERROR if the header does not contain the tag SDLprimitive or if no value follows the SDLprimitive tag. In either case, the value of raster_type still defaults to SDLpoint.

SDLgetTitle 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.

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