------------------------------------------------------------------------------- The OpenGL Stream Codec: A Specification Craig Dunwoody Silicon Graphics Version 0.0 -- 4/10/96 ------------------------------------------------------------------------------- Note: Silicon Graphics intends to develop this document into a Version 1.0 GLS specification to be submitted to the OpenGL ARB for approval as a standard. Comments on this draft are strongly encouraged and should be sent to the opengl-licensees mailing list or to dunwoody@sgi.com. Improvements planned for Version 1.0 of this document include: - better organization - better formatting - more details on stream formats, encoders, and decoders ------------------------------------------------------------------------------- Introduction ------------------------------------------------------------------------------- The OpenGL Stream Codec (GLS) is a facility for encoding and decoding streams of 8-bit values (octets) that represent sequences of OpenGL (henceforth, "GL") commands. GLS has two components: 1. A set of three stream encodings for GL and GLS commands (human-readable text, big-endian binary, and little-endian binary). The three stream encodings are semantically identical, differing only in syntax. Streams can therefore be converted freely among the three stream encodings without loss of information. 2. An API that provides commands for encoding and decoding streams. This API is not formally an extension of the GL API. Like the GLU API, the GLS API is designed to be implemented in an optional, standalone client-side subroutine library that is separate from the subroutine library that implements the GL API. The GLS stream encodings and API are platform independent and window system independent. In particular, the stream encodings are not tied to the stream encoding used in the GLX extension to the X Window System protocol. GLS is designed to work equally well in Unix/X, Windows, and other environments. It is expected that GLS will prove useful to the GL community in a wide range of applications, including: - GL command streams for resolution independent storage, interchange, interactive viewing, and printing of pictures - GL command files for persistent storage of textures, display lists, images, etc. - GL trace streams for debuggers, performance analyzers, and simulators - GL test-vector streams for correctness testing of GL implementations - Picture-level benchmarking using GL command files to represent pictures - Transfer of GL commands between application processes via octet stream connections - Client-side display lists that can contain client callbacks Some of these applications will require the definition and implementation of higher-level APIs that are more convenient to use than the GLS API. The GLS API design is an attempt to provide basic stream encoding and decoding services in such a way that higher-level services can efficiently be built on top. ------------------------------------------------------------------------------- Stream Encodings ------------------------------------------------------------------------------- Each of the GLS stream encodings is capable of representing all GL commands. If a GL command has both a scalar form (e.g. glColor3f) and a vector form (e.g. glColor3fv), GLS always represents the command in its vector form. In addition to GL commands, a subset of the commands in the GLS API are "encodable", meaning that they can be represented in streams. These GLS commands make it possible to encode various kinds of non-GL data in streams. All GLS streams begin with the encodable GLS command glsBeginGLS and end with the encodable GLS command glsEndGLS. The concatenation of two valid GLS streams is always a valid GLS stream, even if the two streams do not have the same stream encoding. ------------------------------------------------------------------------------- API Overview ------------------------------------------------------------------------------- This section provides a brief overview of the core of the GLS API. --------------------------------------------------------------------------- GLint glsGenContext(void); void glsDeleteContext(GLint inContext); void glsContext(GLint inContext); /* set thread's current GLS context */ --------------------------------------------------------------------------- Like GL, GLS is a state machine. A GLS context is an instantiation of this state machine. GLS contexts and GL contexts are completely independent. Like GLU state, GLS contexts are stored entirely on the client side of the GL client-server connection. Each GLS context has a nonzero name of type GLint. Each GLS command is classified as global, immediate, encodable, or encodable-nop: --------------------------------------------------------------------------- Category Uses GLS context state Encodable --------------------------------------------------------------------------- Global Immediate X Encodable X X Encodable-nop X --------------------------------------------------------------------------- The commands glsGenContext, glsDeleteContext, and glsContext are global. All of the GLS commands described in the remainder of this section are non-global. Each client thread has a state variable that always contains either zero (the initial value) or the name of the thread's current GLS context. If the value is zero, all non-global GLS commands raise GLS_STATE_ERROR. If the value is nonzero, all non-global GLS commands use the state in the issuing thread's current GLS context. At any given instant, a GLS context may be current to at most one thread. --------------------------------------------------------------------------- GLboolean glsBeginCapture( const GLSchar *inStreamName, GLSenum inStreamType, GLint inWriteFlags ); void glsEndCapture(void); --------------------------------------------------------------------------- Between a glsBeginCapture command and the following glsEndCapture command, the current GLS context is in "capture mode". In capture mode, all GL commands will be captured by GLS instead of being sent directly to GL and executed, and all encodable GLS commands will be captured instead of being sent directly to GLS and executed. The command glsBeginCapture opens a stream for writing and then encodes the command glsBeginGLS. The command glsEndCapture encodes the command glsEndGLS and then closes the stream. inStreamType must be one of: GLS_CONTEXT /* in-memory stream stored in GLS context */ GLS_BINARY_LSB_FIRST /* binary stream, little-endian */ GLS_BINARY_MSB_FIRST /* binary stream, big-endian */ GLS_TEXT /* text stream */ inWriteFlags must be zero or more of: GLS_WRITE_APPEND_BIT /* if stream exists, don't truncate */ If inStreamType is GLS_CONTEXT, the command glsBeginCapture will open an in-memory stream named inStreamName that is stored in the current GLS context. Within the constraints of available memory, a GLS context can contain an arbitrary number of named GLS_CONTEXT streams. GLS_CONTEXT streams can be thought of as client-side display lists that complement the server-side display lists provided by core GL. If inStreamType is GLS_BINARY_* or GLS_TEXT, the name of the opened stream is formed by appending inStreamName to a write-prefix string that is stored in the current GLS context. The command glsWritePrefix can be used to replace the value of the write-prefix string. If inStreamType is GLS_BINARY_* or GLS_TEXT, and inStreamName is not the empty string, the command glsBeginCapture will use the ISO C library command fopen to create a write channel of type FILE*. If inStreamType is GLS_BINARY_* or GLS_TEXT, and inStreamName is the empty string, the command glsBeginCapture will use a default write channel of type FILE* that is stored in the current GLS context (initial value: stdout). The command glsChannel can be used to replace the value of the default write channel. If inStreamType is GLS_BINARY_* or GLS_TEXT, and inStreamName is the empty string, and the GLS client has used the command glsWriteFunc to specify a write callback function, that function will be used in place of the ISO C library function fwrite when data are to be written to the stream. --------------------------------------------------------------------------- void glsCaptureFlags(GLSopcode inOpcode, GLint inFlags); --------------------------------------------------------------------------- A GLS context contains two capture-mode control bits for each opcode: GLS_CAPTURE_WRITE_BIT /* write captured command to open stream */ GLS_CAPTURE_EXECUTE_BIT /* execute captured command */ The command glsCaptureFlags allows the GLS client to specify on a per-opcode basis whether a captured command should be written to the open stream and/or executed by GL or GLS. --------------------------------------------------------------------------- GLSenum glsCallStream(const GLSchar *inStreamName); --------------------------------------------------------------------------- This command decodes a named stream (which may use any GLS stream encoding) and issues the commands in the stream to GL and GLS, just as if those commands had been issued directly in immediate mode by the calling thread. The command returns the type of the stream. If inStreamName is the name of a GLS_CONTEXT in-memory stream stored in the current GLS context, the command glsCallStream will decode that stream. Otherwise, the command searches for an external stream to decode. If inStreamName is not the empty string, a sequence of potential external stream names is formed. The first names in the sequence are formed by appending inStreamName to each of the strings in a list of read-prefix strings that is stored in the current GLS context. The commands glsAppendReadPrefix, glsPrependReadPrefix, and glsRemoveReadPrefix can be used to modify the contents of the read-prefix string list. The last name in the sequence is formed by appending inStreamName to the write-prefix string. Beginning with the first potential external stream name, the command glsCallStream tries each successive name until either a valid stream is found or all of the names have been tried. For each name, the command fopen is issued with the name as a parameter, in an attempt to create a read channel of type FILE*. If inStreamName is the empty string, the command glsCallStream will use a default read channel of type FILE* that is stored in the current GLS context (initial value: stdin). The command glsChannel can be used to replace the value of the default read channel. If inStreamName is the empty string, and the GLS client has used the command glsReadFunc to specify a read callback function, that function will be used in place of the ISO C library function fread when data are to be read from the stream. The command glsCallStream is encodable. When a decoder reads this command from a stream, the decoder recursively decodes the stream named in the command. As a result, GLS streams provide the same embedding capability on the client side that GL display lists provide on the server side. --------------------------------------------------------------------------- void glsCommandFunc(GLSopcode inOpcode, GLScommandFunc inFunc); --------------------------------------------------------------------------- This command registers the command function inFunc for the GL or encodable GLS command designated by inOpcode. When a decoder reads the designated command from a stream, the decoder will call inFunc instead of issuing the command. Command parameters are passed to inFunc just as they would have been passed to the function that implements the GL or GLS command. The function inFunc is free to perform arbitrary computations, including the issuing of GL and GLS commands. GLS commands in the encodable-nop category (e.g. glsNumiv) are provided for the sole purpose of encoding arbitrary client data as command parameters in a stream. If a GLS client provides a command function for one or more of these commands, the client can use GLS_CONTEXT in-memory streams to create client-side display lists that contain client callbacks. This functionality is present in IrisGL but not in core GL. --------------------------------------------------------------------------- void glsUnsupportedCommand(const GLSchar *inCommand); --------------------------------------------------------------------------- The GLS stream encodings and API are designed to handle GL extensions. Extension commands are encoded and decoded in the same way as GL 1.1 commands. Extension opcodes for the GLS_BINARY_* stream encodings will be allocated on demand in blocks of 16 from a registry maintained by Silicon Graphics. To guarantee successful interchange of streams, it is required that any GLS implementation be able to read any GLS stream, even if the stream contains extension commands that are not recognized by the GLS implementation. If a decoder reads from a GLS stream a command that it cannot decode, the decoder issues the encodable GLS command glsUnsupportedCommand. The command glsCommandFunc can be used to register a command function for glsUnsupportedCommand. ------------------------------------------------------------------------------- Types ------------------------------------------------------------------------------- typedef void GLSchar; /* GLubyte, GLushort, or GLint */ typedef GLint GLSenum; typedef long long GLSlong; /* 64-bit signed integer */ typedef GLint GLSopcode; typedef void (*GLScaptureEntryFunc)( GLSopcode inOpcode, const GLvoid *optinParam1 ); typedef void (*GLScaptureExitFunc)( GLSopcode inOpcode, const GLvoid *optinParam1, GLvoid *optinoutReturn ); typedef size_t (*GLSreadFunc)(size_t inCount, GLvoid *outBuf); typedef size_t (*GLSwriteFunc)(size_t inCount, const GLvoid *inBuf); typedef void (*GLSfunc)(); ------------------------------------------------------------------------------- Character Codes ------------------------------------------------------------------------------- Every character code used in the GLS API and stream encodings is an element of the Universal Multiple-Octet Coded Character Set (UCS) defined the standards ISO/IEC 10646-1:1993 and Unicode 1.1. A UCS code is denoted as U+hexcode, where hexcode is a sequence of one to eight hexadecimal digits with no leading zeros and alphabetic digits in uppercase. Each UCS code corresponds to a character that has a unique name string. For example, the code U+41 corresponds to the character LATIN CAPITAL LETTER A. GLS uses several representations for strings of UCS codes. All of the representations are semantically identical, differing only in syntax. All of the UCS codes used in GLS are in the range [U+0, U+7FFFFFFF]. Strings are passed across the GLS API as zero terminated arrays of UCS codes. The interpretation of the type of each code (and the terminating zero) is determined dynamically at runtime by the value of the state variable GLS_STRING_TYPE, which is one of: #define GLS_UCS1 0x01B0 #define GLS_UCS2 0x01B1 #define GLS_UCS4 0x01B2 The initial value of GLS_STRING_TYPE is GLS_UCS1, which specifies that each code is of type GLubyte. The value GLS_UCS2 specifies that each code is of type GLushort, and the value GLS_UCS4 specifies that each code is of type GLint. GLS_STRING_TYPE affects only the format of strings passing across the GLS API. It does not affect the stream encoding or decoding of strings. If it is necessary to pass across the GLS API a UCS code that is larger than the maximum value supported by the data type that is selected by GLS_STRING_TYPE, the character is represented as a character sequence of the form \, as descibed above. Every GLS command that has a function return value of type GLSchar* returns a pointer to a string return buffer in the current GLS context. This pointer is guaranteed to be valid until the next GLS command is issued. A client that needs to use the returned string after that point must copy it to a client-provided string buffer. ------------------------------------------------------------------------------- GLS_BINARY_* Encodings ------------------------------------------------------------------------------- The GLS_BINARY_* encoders represent most commands as follows: ------------------------------------ Opcode: 16-bit unsigned integer Octet count: 16-bit unsigned integer Parameters: n * 32 bits ------------------------------------ The encoders use an alternate encoding for opcodes larger than 65535, commands that require more than 65535 octets to encode, and the commands glsBeginGLS and glsEndGLS: ------------------------------------ Opcode: 32-bit unsigned integer Octet count: 32-bit unsigned integer Parameters: n * 32 bits ------------------------------------ The encoders encode parameters in parameter list order. Parameter values are encoded as follows: 8-bit unsigned integer GLboolean GLubyte Character code 8-bit signed integer GLbyte 16-bit unsigned integer GLushort 16-bit signed integer GLshort 32-bit unsigned integer GLbitfield GLenum GLuint 32-bit signed integer GLSenum GLSopcode 32-bit signed integer GLint GLsizei 64-bit signed integer GLSlong Pointer 32-bit ANSI/IEEE 754-1985 single precision float GLclampf GLfloat 64-bit ANSI/IEEE 754-1985 double precision float GLclampd GLdouble Each parameter of string type is encoded as follows: ------------------------------------------- Octet count: 32-bit unsigned integer Character codes (UTF8 encoding): n * 8 bits Zero termination: 8 bits ------------------------------------------- Each parameter of pointer type (e.g. the pointer parameters of glGet*, glFeedbackBuffer, glSelectBuffer, and gl*Pointer) is encoded as a 64-bit signed integer. In a GLS_BINARY_* stream, n-bit values are always aligned on an n-bit boundary with respect to the beginning of the stream. This minimizes alignment overhead during stream execution on machines that require such alignment. The encoder achieves this by adding padding bits between values where necessary. The value of all padding bits is zero. For commands with 64-bit parameter values, it is also sometimes necessary for the encoder to add 32 bits of padding at the end of the previous command. When this is not possible, the encoder will achieve the same effect by encoding a no-op command (glsPad) before encoding the command that needs to be aligned. ------------------------------------------------------------------------------- GLS_TEXT Encoding ------------------------------------------------------------------------------- The GLS_TEXT encoding looks like ISO C source code, except that array parameters are represented as lists of elements delimited by braces. Example: glsBeginGLS(1, 0); # parameters are inVersionMajor, inVersionMinor glClear(GL_DEPTH_BUFFER_BIT | GL_COLOR_BUFFER_BIT); glBegin(GL_POINTS); glVertex3fv({1.2, 3.4, 5.6}); glEnd(); glsEndGLS(); A valid GLS text stream contains only octets in the ranges [U+9, U+D] and [U+20, U+7E]. Each of these values encodes one graphic or whitespace character. The whitespace characters are as follows: HORIZONTAL TAB U+9 NEW LINE U+A VERTICAL TAB U+B NEW PAGE U+C CARRIAGE RETURN U+D SPACE U+20 The decoder ignores whitespace characters between tokens. The comment character # causes GLS to ignore all following characters up to the next NEW LINE character. NEW LINE and SPACE are the only whitespace characters that the encoder generates. Command parameters are encoded and decoded as follows: --------------------------------------------------------------------------- GLenum --------------------------------------------------------------------------- If a GLenum value is one of the enumerants supported by the GLS implementation, the encoder encodes it as a name (e.g. GL_TRIANGLES). Otherwise, the encoder encodes it as a GLint value. If an enumerant is overloaded in GL 1.0 (e.g. GL_TRUE == GL_LINES), the encoder chooses the appropriate name based on the command opcode. If an enumerant has been renamed (e.g. GL_DOUBLE_EXT -> GL_DOUBLE), the encoder uses the new name. The decoder decodes a GLenum value as a name or as a GLint value. --------------------------------------------------------------------------- GLboolean --------------------------------------------------------------------------- If a GLboolean value is GL_FALSE or GL_TRUE, the encoder encodes it as a name. Otherwise, the encoder encodes it as a GLubyte value. The decoder decodes a GLboolean value as a name (GL_FALSE or GL_TRUE) or as a GLubyte value. --------------------------------------------------------------------------- GLbitfield --------------------------------------------------------------------------- The encoder encodes a GLbitfield value as a sequence of tokens separated by | characters. The sequence begins with zero or more bit position names (each corresponding to a 1 bit). If there are one or more 1 bits in bit positions for which the GLS implementation has no name, the sequence ends with a GLint value in hexadecimal form that contains these bits. The decoder decodes a GLbitfield value as a sequence of tokens separated by | characters. Each token may be a bit position name or a GLint value. --------------------------------------------------------------------------- GLbyte --------------------------------------------------------------------------- The encoder encodes a GLbyte value as a decimal integer. The decoder decodes a GLbyte value as a decimal integer in the range [-128, 127] or as a hexadecimal integer in the range [0x0, 0xFF], with the 'x' and the alphabetic digits in either upper or lower case. --------------------------------------------------------------------------- GLshort --------------------------------------------------------------------------- The encoder encodes a GLshort value as a decimal integer. The decoder decodes a GLshort value as a decimal integer in the range [-32768, 32767] or as a hexadecimal integer in the range [0x0, 0xFFFF], with the 'x' and the alphabetic digits in either upper or lower case. --------------------------------------------------------------------------- GLint, GLsizei --------------------------------------------------------------------------- The encoder encodes a GLint or GLsizei value as a decimal integer, unless it represents an enumerant (e.g. the param parameter of the command glFogi when the value of the pname parameter is GL_FOG_MODE). In that case, the value is encoded as an enumerant name. The decoder decodes a GLint or GLsizei value as a decimal integer in the range [-2147483648, 2147483647], as a hexadecimal integer in the range [0x0, 0xFFFFFFFF], with the 'x' and the alphabetic digits in either upper or lower case, or as a GL or GLS enumerant name. --------------------------------------------------------------------------- GLubyte --------------------------------------------------------------------------- The encoder encodes a GLubyte value as a decimal integer, except for the bitmap parameter of the command glBitmap and the mask parameter of the command glPolygonStipple, which are encoded as hexadecimal integers. The decoder decodes a GLubyte value as a decimal integer in the range [0, 255] or as a hexadecimal integer in the range [0x0, 0xFF], with the 'x' and the alphabetic digits in either upper or lower case. --------------------------------------------------------------------------- GLushort --------------------------------------------------------------------------- The encoder encodes a GLushort value as a decimal integer, except for the pattern parameter of the command glLineStipple, which is encoded as a hexadecimal integer. The decoder decodes a GLushort value as a decimal integer in the range [0, 65535] or as a hexadecimal integer in the range [0x0, 0xFFFF], with the 'x' and the alphabetic digits in either upper or lower case. --------------------------------------------------------------------------- GLuint --------------------------------------------------------------------------- The encoder encodes a GLuint value as a decimal integer, except for the mask parameters of the commands glIndexMask, glStencilFunc and glStencilMask, which are encoded as hexadecimal integers. The decoder decodes a GLuint value as a decimal integer in the range [0, 4294967295], as a hexadecimal integer in the range [0x0, 0xFFFFFFFF], with the 'x' and the alphabetic digits in either upper or lower case, or as a GL or GLS enumerant name. --------------------------------------------------------------------------- GLfloat, GLclampf --------------------------------------------------------------------------- The encoder encodes a GLfloat or GLclampf value as a floating-point number, unless it represents an enumerant (e.g. the param parameter of the command glFogf when the value of the pname parameter is GL_FOG_MODE). In that case, the value is encoded as an enumerant name. The encoder encodes the value as a floating-point number via the ISO C library command sprintf. If the value is finite, the format string is "%.7G", except for the parameters of the commands glLoadMatrixf and glMultMatrixf, which use the format "%-11.7G". If the value is -Infinity, it is encoded as -GLS_INF, and if it is Infinity (0x7F800000), it is encoded as GLS_INF. Finally, if the value is an IEEE 754 NaN (not a number), it is encoded as 0xdddddddd, where d is a hexadecimal digit in the range [0, F]. The decoder decodes a GLfloat or GLclampf value as a floating- point number via the ISO C library command strtod, followed by a check to insure that the value is in the range -FLT_MAX <= value <= FLT_MAX. If this fails, the decoder checks for the forms -GLS_INF, GLS_INF, and GLS_NAN. GLS_NAN specifies the value 0xFFFFFFFF. If these checks fail, the decoder checks for the hexadecimal form 0xdddddddd. --------------------------------------------------------------------------- GLdouble, GLclampd --------------------------------------------------------------------------- The encoder encodes a GLdouble or GLclampd value as a floating-point number via the ISO C library command sprintf. If the value is finite, the format string is "%.16G", except for the parameters of the commands glLoadMatrixd and glMultMatrixd, which use the format "%-17.16G". If there is an exponent, it will have three digits if it is less than -99 or greater than +99; otherwise it will have two digits. If the value is -Infinity it is encoded as -GLS_INF, and if it is Infinity, it is encoded as GLS_INF. Finally, if the value is an IEEE 754 NaN (not a number), it is encoded as 0xdddddddddddddddd, where d is a hexadecimal digit in the range [0, F]. The decoder decodes a GLdouble or GLclampd value as a floating- point number via the ISO C library command strtod. If the command fails, the decoder checks for the forms -GLS_INF, GLS_INF, and GLS_NAN. GLS_NAN specifies the value 0xFFFFFFFFFFFFFFFF. If these checks fail, the decoder checks for the hexadecimal form 0xdddddddddddddddd. --------------------------------------------------------------------------- GLSenum --------------------------------------------------------------------------- If a GLSenum value is one of the enumerants supported by the GLS implementation, the encoder encodes it as a name (e.g. GLS_FRAME). Otherwise, the encoder encodes it as a GLint value. The decoder decodes a GLSenum value as a name or as a GLint value. --------------------------------------------------------------------------- GLSlong --------------------------------------------------------------------------- The encoder encodes a GLSlong value as a decimal integer. The decoder decodes a GLSlong value as a decimal integer in the range [-9223372036854775808, 9223372036854775807], as a hexadecimal integer in the range [0x0, 0xFFFFFFFFFFFFFFFF], with the 'x' and the alphabetic digits in either upper or lower case, or as a GL or GLS enumerant name. --------------------------------------------------------------------------- GLSopcode --------------------------------------------------------------------------- If a GLSopcode value is one of the opcodes supported by the GLS implementation, the encoder encodes it as a name (e.g. GLS_OP_glBegin). Otherwise, the encoder encodes it as a GLint value. The decoder decodes a GLSopcode value as a name or as a GLint value. --------------------------------------------------------------------------- GLSchar strings --------------------------------------------------------------------------- The encoder encodes a character string as a sequence of character codes between a pair of " (QUOTATION MARK; U+22) characters. The encoder encodes every graphic and whitespace character in the ranges [U+9, U+D] and [U+20, U+7E] as itself, except " and \ (REVERSE SOLIDUS; U+5C), each of which is encoded as the second character in a two-character escape sequence that begins with REVERSE SOLIDUS. The encoder encodes every other UCS code via a character sequence of the form \, where \ is REVERSE SOLIDUS, < is LESS-THAN SIGN (U+3C), > is GREATER-THAN SIGN (U+3E), and hexcode is a sequence of one to eight hexadecimal digits with no leading zeros and alphabetic digits in uppercase. The decoder decodes a character string in the form just described. As in ISO C, strings can be concatenated to form a larger string. For example, "hello" "goodbye" is equivalent to "hellogoodbye" --------------------------------------------------------------------------- Pointers --------------------------------------------------------------------------- The encoder encodes a pointer value (e.g. the pointer parameters of glGet*, glFeedbackBuffer, glSelectBuffer, and gl*Pointer) as a GLSlong value in hexadecimal form. The encoder decodes a pointer value as a GLSlong value. ------------------------------------------------------------------------------- Command Parameter Encoding Details ------------------------------------------------------------------------------- This section describes command parameter encoding details that are common to all of the GLS stream types. Command parameters of image type (e.g. the pixels parameter of glDrawPixels) are always encoded in maximally packed form, corresponding to the following GL pixel store state values: GL_UNPACK_ALIGNMENT = 1 GL_UNPACK_LSB_FIRST = GL_FALSE GL_UNPACK_ROW_LENGTH = 0 GL_UNPACK_SKIP_ROWS = 0 GL_UNPACK_SKIP_PIXELS = 0 GL_UNPACK_SWAP_BYTES = GL_FALSE #if __GL_EXT_texture3D GL_UNPACK_IMAGE_HEIGHT_EXT = 0 GL_UNPACK_SKIP_IMAGES_EXT = 0 #endif /* __GL_EXT_texture3D */ Commands with image parameters are encoded with an image encoding parameter list preceding the normal parameter list. Examples: glTexImage1D(GLS_NONE)( GL_TEXTURE_1D, 1, 3, 2, 0, GL_RGB, GL_FLOAT, {0, 1, 2, 3, 4, 5} ); glTexImage1D(GLS_IMAGE_NULL_BIT)( GL_TEXTURE_1D, 1, 3, 2, 0, GL_RGB, GL_FLOAT, {} ); The image encoding parameter list specifies any deviations from the normal GLS image encoding. The first parameter in this list is a 32-bit options mask that specifies the encoding options that are being used. Associated with each defined bit position in the options mask is a list of zero or more additional encoding parameters. After the options mask, the remainder of the encoding parameter list is formed by concatenating the additional encoding parameters that are associated with each of the bit positions in the options mask that contains a 1, starting with the least significant bit position and proceeding to the most significant bit position. GLS 1.0 defines only one bit position in the options mask: #define GLS_IMAGE_NULL_BIT 0x00000001 This bit specifies a null image pointer. It has zero associated additional encoding parameters. In effect, the GL pixel store state variables are implicit additional parameters of the GL commands that depend on them. In GLS 1.0, all of these additional parameters are effectively "compiled out" of image data before encoding. Future GL extensions, however, may add pixel store state variables (e.g. image compression parameters) that cannot be compiled out and must be encoded by GLS along with the image data. If this happens, the image encoding parameter list will provide a way to encode these additional parameters. Like pixel data, array parameter data for GL commands with "stride" parameters (e.g. glMap1d) are encoded in maximally packed form. The encoder "compiles out" the stride and encodes values for the stride parameters that tell GL that the array is maximally packed (e.g., the stride parameter to glMap1d(GL_MAP1_VERTEX_3, ...) is always encoded as 3). ------------------------------------------------------------------------------- Opcodes ------------------------------------------------------------------------------- #define GLS_OP_glsBeginGLS 16 #define GLS_OP_glsBlock 17 #define GLS_OP_glsCallStream 18 #define GLS_OP_glsDrawVertexArray 19 #define GLS_OP_glsEndGLS 20 #define GLS_OP_glsError 21 #define GLS_OP_glsHeaderc 22 #define GLS_OP_glsHeaderf 23 #define GLS_OP_glsHeaderfv 24 #define GLS_OP_glsHeaderi 25 #define GLS_OP_glsHeaderiv 26 #define GLS_OP_glsRequireExtension 27 #define GLS_OP_glsRequireVersion 28 #define GLS_OP_glsUnsupportedCommand 29 #define GLS_OP_glsBeginObj 30 #define GLS_OP_glsComment 31 #define GLS_OP_glsEndObj 32 #define GLS_OP_glsNumbv 33 #define GLS_OP_glsNumd 34 #define GLS_OP_glsNumdv 35 #define GLS_OP_glsNumf 36 #define GLS_OP_glsNumfv 37 #define GLS_OP_glsNumi 38 #define GLS_OP_glsNumiv 39 #define GLS_OP_glsNuml 40 #define GLS_OP_glsNumlv 41 #define GLS_OP_glsNumsv 42 #define GLS_OP_glsPad 43 #define GLS_OP_glsString 44 #define GLS_OP_glsSwapBuffers 45 #define GLS_OP_glAccum 191 #define GLS_OP_glAlphaFunc 214 #define GLS_OP_glAreTexturesResident 300 #define GLS_OP_glAreTexturesResidentEXT 65502 #define GLS_OP_glArrayElement 280 #define GLS_OP_glArrayElementEXT 65493 #define GLS_OP_glBegin 55 #define GLS_OP_glBindTexture 301 #define GLS_OP_glBindTextureEXT 65503 #define GLS_OP_glBitmap 56 #define GLS_OP_glBlendColorEXT 65520 #define GLS_OP_glBlendEquationEXT 65521 #define GLS_OP_glBlendFunc 215 #define GLS_OP_glCallList 50 #define GLS_OP_glCallLists 51 #define GLS_OP_glClear 181 #define GLS_OP_glClearAccum 182 #define GLS_OP_glClearColor 184 #define GLS_OP_glClearDepth 186 #define GLS_OP_glClearIndex 183 #define GLS_OP_glClearStencil 185 #define GLS_OP_glClipPlane 128 #define GLS_OP_glColor3bv 57 #define GLS_OP_glColor3dv 58 #define GLS_OP_glColor3fv 59 #define GLS_OP_glColor3iv 60 #define GLS_OP_glColor3sv 61 #define GLS_OP_glColor3ubv 62 #define GLS_OP_glColor3uiv 63 #define GLS_OP_glColor3usv 64 #define GLS_OP_glColor4bv 65 #define GLS_OP_glColor4dv 66 #define GLS_OP_glColor4fv 67 #define GLS_OP_glColor4iv 68 #define GLS_OP_glColor4sv 69 #define GLS_OP_glColor4ubv 70 #define GLS_OP_glColor4uiv 71 #define GLS_OP_glColor4usv 72 #define GLS_OP_glColorMask 188 #define GLS_OP_glColorMaterial 129 #define GLS_OP_glColorPointer 281 #define GLS_OP_glColorPointerEXT 65494 #define GLS_OP_glConvolutionFilter1DEXT 65528 #define GLS_OP_glConvolutionFilter2DEXT 65529 #define GLS_OP_glConvolutionParameterfEXT 65530 #define GLS_OP_glConvolutionParameterfvEXT 65531 #define GLS_OP_glConvolutionParameteriEXT 65532 #define GLS_OP_glConvolutionParameterivEXT 65533 #define GLS_OP_glCopyConvolutionFilter1DEXT 65534 #define GLS_OP_glCopyConvolutionFilter2DEXT 65535 #define GLS_OP_glCopyPixels 229 #define GLS_OP_glCopyTexImage1D 294 #define GLS_OP_glCopyTexImage1DEXT 65483 #define GLS_OP_glCopyTexImage2D 295 #define GLS_OP_glCopyTexImage2DEXT 65484 #define GLS_OP_glCopyTexSubImage1D 296 #define GLS_OP_glCopyTexSubImage1DEXT 65485 #define GLS_OP_glCopyTexSubImage2D 297 #define GLS_OP_glCopyTexSubImage2DEXT 65486 #define GLS_OP_glCopyTexSubImage3DEXT 65487 #define GLS_OP_glCullFace 130 #define GLS_OP_glDeleteLists 52 #define GLS_OP_glDeleteTextures 302 #define GLS_OP_glDeleteTexturesEXT 65472 #define GLS_OP_glDepthFunc 219 #define GLS_OP_glDepthMask 189 #define GLS_OP_glDepthRange 262 #define GLS_OP_glDisable 192 #define GLS_OP_glDisableClientState 282 #define GLS_OP_glDrawArrays 283 #define GLS_OP_glDrawArraysEXT 65495 #define GLS_OP_glDrawBuffer 180 #define GLS_OP_glDrawElements 284 #define GLS_OP_glDrawPixels 231 #define GLS_OP_glEdgeFlagPointer 285 #define GLS_OP_glEdgeFlagPointerEXT 65496 #define GLS_OP_glEdgeFlagv 73 #define GLS_OP_glEnable 193 #define GLS_OP_glEnableClientState 286 #define GLS_OP_glEnd 74 #define GLS_OP_glEndList 49 #define GLS_OP_glEvalCoord1dv 206 #define GLS_OP_glEvalCoord1fv 207 #define GLS_OP_glEvalCoord2dv 208 #define GLS_OP_glEvalCoord2fv 209 #define GLS_OP_glEvalMesh1 210 #define GLS_OP_glEvalMesh2 212 #define GLS_OP_glEvalPoint1 211 #define GLS_OP_glEvalPoint2 213 #define GLS_OP_glFeedbackBuffer 172 #define GLS_OP_glFinish 194 #define GLS_OP_glFlush 195 #define GLS_OP_glFogf 131 #define GLS_OP_glFogfv 132 #define GLS_OP_glFogi 133 #define GLS_OP_glFogiv 134 #define GLS_OP_glFrontFace 135 #define GLS_OP_glFrustum 263 #define GLS_OP_glGenLists 53 #define GLS_OP_glGenTextures 303 #define GLS_OP_glGenTexturesEXT 65473 #define GLS_OP_glGetBooleanv 232 #define GLS_OP_glGetClipPlane 233 #define GLS_OP_glGetConvolutionFilterEXT 65504 #define GLS_OP_glGetConvolutionParameterfvEXT 65505 #define GLS_OP_glGetConvolutionParameterivEXT 65506 #define GLS_OP_glGetDoublev 234 #define GLS_OP_glGetError 235 #define GLS_OP_glGetFloatv 236 #define GLS_OP_glGetHistogramEXT 65509 #define GLS_OP_glGetHistogramParameterfvEXT 65510 #define GLS_OP_glGetHistogramParameterivEXT 65511 #define GLS_OP_glGetIntegerv 237 #define GLS_OP_glGetLightfv 238 #define GLS_OP_glGetLightiv 239 #define GLS_OP_glGetMapdv 240 #define GLS_OP_glGetMapfv 241 #define GLS_OP_glGetMapiv 242 #define GLS_OP_glGetMaterialfv 243 #define GLS_OP_glGetMaterialiv 244 #define GLS_OP_glGetMinmaxEXT 65512 #define GLS_OP_glGetMinmaxParameterfvEXT 65513 #define GLS_OP_glGetMinmaxParameterivEXT 65514 #define GLS_OP_glGetPixelMapfv 245 #define GLS_OP_glGetPixelMapuiv 246 #define GLS_OP_glGetPixelMapusv 247 #define GLS_OP_glGetPointerv 287 #define GLS_OP_glGetPointervEXT 65497 #define GLS_OP_glGetPolygonStipple 248 #define GLS_OP_glGetSeparableFilterEXT 65507 #define GLS_OP_glGetString 249 #define GLS_OP_glGetTexEnvfv 250 #define GLS_OP_glGetTexEnviv 251 #define GLS_OP_glGetTexGendv 252 #define GLS_OP_glGetTexGenfv 253 #define GLS_OP_glGetTexGeniv 254 #define GLS_OP_glGetTexImage 255 #define GLS_OP_glGetTexLevelParameterfv 258 #define GLS_OP_glGetTexLevelParameteriv 259 #define GLS_OP_glGetTexParameterfv 256 #define GLS_OP_glGetTexParameteriv 257 #define GLS_OP_glHint 136 #define GLS_OP_glHistogramEXT 65515 #define GLS_OP_glIndexMask 190 #define GLS_OP_glIndexPointer 288 #define GLS_OP_glIndexPointerEXT 65498 #define GLS_OP_glIndexdv 75 #define GLS_OP_glIndexfv 76 #define GLS_OP_glIndexiv 77 #define GLS_OP_glIndexsv 78 #define GLS_OP_glIndexubv 306 #define GLS_OP_glInitNames 175 #define GLS_OP_glInterleavedArrays 289 #define GLS_OP_glIsEnabled 260 #define GLS_OP_glIsList 261 #define GLS_OP_glIsTexture 304 #define GLS_OP_glIsTextureEXT 65474 #define GLS_OP_glLightModelf 141 #define GLS_OP_glLightModelfv 142 #define GLS_OP_glLightModeli 143 #define GLS_OP_glLightModeliv 144 #define GLS_OP_glLightf 137 #define GLS_OP_glLightfv 138 #define GLS_OP_glLighti 139 #define GLS_OP_glLightiv 140 #define GLS_OP_glLineStipple 145 #define GLS_OP_glLineWidth 146 #define GLS_OP_glListBase 54 #define GLS_OP_glLoadIdentity 264 #define GLS_OP_glLoadMatrixd 266 #define GLS_OP_glLoadMatrixf 265 #define GLS_OP_glLoadName 176 #define GLS_OP_glLogicOp 216 #define GLS_OP_glMap1d 198 #define GLS_OP_glMap1f 199 #define GLS_OP_glMap2d 200 #define GLS_OP_glMap2f 201 #define GLS_OP_glMapGrid1d 202 #define GLS_OP_glMapGrid1f 203 #define GLS_OP_glMapGrid2d 204 #define GLS_OP_glMapGrid2f 205 #define GLS_OP_glMaterialf 147 #define GLS_OP_glMaterialfv 148 #define GLS_OP_glMateriali 149 #define GLS_OP_glMaterialiv 150 #define GLS_OP_glMatrixMode 267 #define GLS_OP_glMinmaxEXT 65516 #define GLS_OP_glMultMatrixd 269 #define GLS_OP_glMultMatrixf 268 #define GLS_OP_glNewList 48 #define GLS_OP_glNormal3bv 79 #define GLS_OP_glNormal3dv 80 #define GLS_OP_glNormal3fv 81 #define GLS_OP_glNormal3iv 82 #define GLS_OP_glNormal3sv 83 #define GLS_OP_glNormalPointer 290 #define GLS_OP_glNormalPointerEXT 65499 #define GLS_OP_glOrtho 270 #define GLS_OP_glPassThrough 177 #define GLS_OP_glPixelMapfv 225 #define GLS_OP_glPixelMapuiv 226 #define GLS_OP_glPixelMapusv 227 #define GLS_OP_glPixelStoref 223 #define GLS_OP_glPixelStorei 224 #define GLS_OP_glPixelTransferf 221 #define GLS_OP_glPixelTransferi 222 #define GLS_OP_glPixelZoom 220 #define GLS_OP_glPointSize 151 #define GLS_OP_glPolygonMode 152 #define GLS_OP_glPolygonOffset 293 #define GLS_OP_glPolygonOffsetEXT 65522 #define GLS_OP_glPolygonStipple 153 #define GLS_OP_glPopAttrib 196 #define GLS_OP_glPopClientAttrib 307 #define GLS_OP_glPopMatrix 271 #define GLS_OP_glPopName 178 #define GLS_OP_glPrioritizeTextures 305 #define GLS_OP_glPrioritizeTexturesEXT 65475 #define GLS_OP_glPushAttrib 197 #define GLS_OP_glPushClientAttrib 308 #define GLS_OP_glPushMatrix 272 #define GLS_OP_glPushName 179 #define GLS_OP_glRasterPos2dv 84 #define GLS_OP_glRasterPos2fv 85 #define GLS_OP_glRasterPos2iv 86 #define GLS_OP_glRasterPos2sv 87 #define GLS_OP_glRasterPos3dv 88 #define GLS_OP_glRasterPos3fv 89 #define GLS_OP_glRasterPos3iv 90 #define GLS_OP_glRasterPos3sv 91 #define GLS_OP_glRasterPos4dv 92 #define GLS_OP_glRasterPos4fv 93 #define GLS_OP_glRasterPos4iv 94 #define GLS_OP_glRasterPos4sv 95 #define GLS_OP_glReadBuffer 228 #define GLS_OP_glReadPixels 230 #define GLS_OP_glRectdv 96 #define GLS_OP_glRectfv 97 #define GLS_OP_glRectiv 98 #define GLS_OP_glRectsv 99 #define GLS_OP_glRenderMode 174 #define GLS_OP_glResetHistogramEXT 65517 #define GLS_OP_glResetMinmaxEXT 65518 #define GLS_OP_glRotated 273 #define GLS_OP_glRotatef 274 #define GLS_OP_glScaled 275 #define GLS_OP_glScalef 276 #define GLS_OP_glScissor 154 #define GLS_OP_glSelectBuffer 173 #define GLS_OP_glSeparableFilter2DEXT 65508 #define GLS_OP_glShadeModel 155 #define GLS_OP_glStencilFunc 217 #define GLS_OP_glStencilMask 187 #define GLS_OP_glStencilOp 218 #define GLS_OP_glTexCoord1dv 100 #define GLS_OP_glTexCoord1fv 101 #define GLS_OP_glTexCoord1iv 102 #define GLS_OP_glTexCoord1sv 103 #define GLS_OP_glTexCoord2dv 104 #define GLS_OP_glTexCoord2fv 105 #define GLS_OP_glTexCoord2iv 106 #define GLS_OP_glTexCoord2sv 107 #define GLS_OP_glTexCoord3dv 108 #define GLS_OP_glTexCoord3fv 109 #define GLS_OP_glTexCoord3iv 110 #define GLS_OP_glTexCoord3sv 111 #define GLS_OP_glTexCoord4dv 112 #define GLS_OP_glTexCoord4fv 113 #define GLS_OP_glTexCoord4iv 114 #define GLS_OP_glTexCoord4sv 115 #define GLS_OP_glTexCoordPointer 291 #define GLS_OP_glTexCoordPointerEXT 65500 #define GLS_OP_glTexEnvf 162 #define GLS_OP_glTexEnvfv 163 #define GLS_OP_glTexEnvi 164 #define GLS_OP_glTexEnviv 165 #define GLS_OP_glTexGend 166 #define GLS_OP_glTexGendv 167 #define GLS_OP_glTexGenf 168 #define GLS_OP_glTexGenfv 169 #define GLS_OP_glTexGeni 170 #define GLS_OP_glTexGeniv 171 #define GLS_OP_glTexImage1D 160 #define GLS_OP_glTexImage2D 161 #define GLS_OP_glTexImage3DEXT 65519 #define GLS_OP_glTexParameterf 156 #define GLS_OP_glTexParameterfv 157 #define GLS_OP_glTexParameteri 158 #define GLS_OP_glTexParameteriv 159 #define GLS_OP_glTexSubImage1D 298 #define GLS_OP_glTexSubImage1DEXT 65523 #define GLS_OP_glTexSubImage2D 299 #define GLS_OP_glTexSubImage2DEXT 65524 #define GLS_OP_glTexSubImage3DEXT 65488 #define GLS_OP_glTranslated 277 #define GLS_OP_glTranslatef 278 #define GLS_OP_glVertex2dv 116 #define GLS_OP_glVertex2fv 117 #define GLS_OP_glVertex2iv 118 #define GLS_OP_glVertex2sv 119 #define GLS_OP_glVertex3dv 120 #define GLS_OP_glVertex3fv 121 #define GLS_OP_glVertex3iv 122 #define GLS_OP_glVertex3sv 123 #define GLS_OP_glVertex4dv 124 #define GLS_OP_glVertex4fv 125 #define GLS_OP_glVertex4iv 126 #define GLS_OP_glVertex4sv 127 #define GLS_OP_glVertexPointer 292 #define GLS_OP_glVertexPointerEXT 65501 #define GLS_OP_glViewport 279 ------------------------------------------------------------------------------- Errors ------------------------------------------------------------------------------- Each GLS client thread has a GLS error code variable of type GLSenum. The initial value of this variable is #define GLS_NONE 0x0000 If a GLS command raises an error and the value of the error code variable is GLS_NONE, the code of the raised error is assigned to the error code variable. Unless otherwise specified, if a GLS command raises an error it has no effect other than possibly assigning a value to the issuing thread's GLS error code variable. If an error is raised by a GLS command that has a function return value, the command returns zero. If a GLS command has a parameter of type GLSenum or GLenum, and the value of the parameter is not one of the values specified as acceptable for the command, the command raises #define GLS_PARAMETER_ERROR 0x0072 If a GLS command has a bitfield parameter of type GLint, and the value of the parameter has a 1 in one or more undefined bit positions, the command raises GLS_PARAMETER_ERROR. If a GLS command has a parameter of type GLSopcode, and the value of the parameter is not a GLS opcode, the command raises GLS_PARAMETER_ERROR. If a GLS command fails due to an I/O error, it raises #define GLS_IO_ERROR 0x0071 If a GLS command fails due to a shortage of resources (e.g. memory), it raises #define GLS_RESOURCE_ERROR 0x0073 ------------------------------------------------------------------------------- Contexts ------------------------------------------------------------------------------- Each GLS client thread has a current GLS context ID variable of type GLint (initial value: zero, which indicates that there is no current GLS context). GLS global commands do not require a current GLS context. If there is no current GLS context, GLS non-global commands raise the error #define GLS_STATE_ERROR 0x0074 ------------------------------------------------------------------------------- Environment Variables ------------------------------------------------------------------------------- The string-valued environment variable GLS_WRITE_PREFIX, if defined when a glsGenContext command is executed, determines the initial value of the state variable GLS_WRITE_PREFIX. Otherwise, the initial value of this variable is the empty string. For a description of GLS_WRITE_PREFIX, see the description of the command glsBeginCapture. The string-valued environment variable GLS_READ_PREFIX_LIST, if defined when a glsGenContext command is executed, determines the initial value of the state variable GLS_READ_PREFIX_LIST. Otherwise, the initial value of this variable is the empty list. For a description of GLS_READ_PREFIX_LIST, see the description of the command glsCopyStream. The environment variable GLS_READ_PREFIX_LIST is parsed as a list of strings separated by one or more characters chosen from a string of separator characters. Separator characters at the beginning and end of the list are accepted but not required. Example: "/tmp:/usr/tmp" If the string-valued environment variable GLS_LIST_SEPARATOR is defined, it specifies the separator string. Otherwise, the separator string is ":". ------------------------------------------------------------------------------- Global Commands ------------------------------------------------------------------------------- --------------------------------------------------------------------------- void glsContext(GLint inContext); --------------------------------------------------------------------------- This command assigns inContext to the issuing thread's current GLS context ID variable. The command raises GLS_PARAMETER_ERROR if inContext is not either zero or the ID of a GLS context. The command raises GLS_STATE_ERROR if the context identified by inContext is current to some other thread, or if inContext is not the ID of the thread's current GLS context and one or more callbacks are active in the thread's current GLS context. If inContext is the ID of the thread's current GLS context, no error is raised. As a result, the command glsContext(glsGetCurrentContext()) never raises an error. If inContext is nonzero and no error is raised, the command issues GL Get commands to determine the GL version and extensions that are supported by the underlying GL implementation, then stores the results in the context identified by inContext. The GL commands are issued in capture-execute mode, which means that they will not be captured by GLS, irrespective of whether or not GLS is in capture mode. In general, the correct execution of GLS commands that issue GL commands is guaranteed only if a GL context is current to the issuing thread. Iff the underlying GL implementation defines all GL commands to be no-ops when no GL context is current, GLS commands will execute correctly when no GL context is current. To determine the characteristics of the underlying GL implementation, the command issues the GL command glGetIntegerv(GL_MAX_LIGHTS, &outVal). If outVal is modified (indicating that a GL context is current), the command issues the GL commands glGetString(GL_VERSION) and glGetString(GL_EXTENSIONS). If outVal is not modified (indicating that no GL context is current), the underlying GL implementation is assumed to support no extensions and to support the GL version that corresponds to the GLS version. GLS 1.0 corresponds to GL 1.1, and every subsequent new GL version will induce a new GLS version. If the characteristics of the underlying GL implementation change (e.g., a GL context with different version and extension characteristics is made current), the GLS client should issue the command glsContext(glsGetCurrentContext()). As described above, this will cause the current GLS context to update its GL version and extension information. A GLS context contains a complete set of GL client state variables. If there is no current GL context when a glsContext command makes a GLS context current to a thread, GLS will execute GL commands issued by that thread that read or write GL client state, using the GL client state variables in the GLS context, until the next glsContext command. This applies only to GL commands that are captured with GLS_CAPTURE_EXECUTE_BIT set and GL commands that are issued by GLS in capture-execute mode. This feature is intended to be used in client-server applications of GLS, where there is no need for a GL context on the client side. A GLS implementation may use ISO C library commands such as sprintf and strtol to encode and decode floating point values in GLS_TEXT streams. While the decimal point character in GLS_TEXT streams is always '.', the decimal point character used by these commands depends on the current locale. As a result, a GLS implementation that uses these commands may need to modify their input and output strings when the decimal point character of the current locale is not '.'. A GLS implementation is allowed to cache locale information in each GLS context, updating the cache only when a glsContext command is executed. Correct GLS behavior is therefore guaranteed only if the GLS client issues a glsContext command (typically glsContext(glsGetCurrentContext()) after making a locale change that affects the current decimal point character. --------------------------------------------------------------------------- void glsDeleteContext(GLint inContext); --------------------------------------------------------------------------- This command marks for deletion the GLS context identified by inContext. If the marked context is not current to any thread, it is deleted immediately. Otherwise, it will be deleted when a subsequent glsContext command causes it to not be current to any thread. The command raises GLS_PARAMETER_ERROR if inContext is not the ID of a GLS context. --------------------------------------------------------------------------- GLint glsGenContext(void); --------------------------------------------------------------------------- This command creates a new GLS context and returns its ID. --------------------------------------------------------------------------- GLint* glsGetAllContexts(void); --------------------------------------------------------------------------- This command returns a zero terminated, dynamically allocated array containing one context ID of type GLint for each of the GLS contexts in the process that contains the issuing thread. The command uses the ISO C library command malloc to allocate the returned array. The GLS client should use the ISO C library command free to deallocate the array when it is no longer needed. --------------------------------------------------------------------------- GLSenum glsGetBinaryType(GLint inSwapCount); --------------------------------------------------------------------------- This command returns either GLS_BINARY_LSB_FIRST or GLS_BINARY_MSB_FIRST. If inSwapCount is even, the command returns the GLS implementation's native binary type. Otherwise, the command returns the GLS implementation's swapped binary type. --------------------------------------------------------------------------- GLint glsGetCommandi(GLSopcode inOpcode, GLSenum inAttrib); --------------------------------------------------------------------------- This command returns the value of an attribute of the encodable command identified by inOpcode. The attribute is identified by inAttrib, which must be one of: #define GLS_API 0x0080 #define GLS_IS_CLIENT_GET_COMMAND 0x0081 #define GLS_IS_CLIENT_STATE_COMMAND 0x0082 #define GLS_IS_GET_COMMAND 0x0083 The value of GLS_API must be one of: #define GLS_API_GLS 0x0020 #define GLS_API_GL 0x0021 The value of GLS_IS_CLIENT_GET_COMMAND is 1 if inOpcode identifies a command that retrieves client state, 0 otherwise. The value of GLS_IS_CLIENT_STATE_COMMAND is 1 if inOpcode identifies a command that modifies client state, 0 otherwise. The value of GLS_IS_GET_COMMAND is 1 if inOpcode identifies a command that retrieves state, 0 otherwise. --------------------------------------------------------------------------- GLint glsGetCurrentContext(void); --------------------------------------------------------------------------- This command returns the value of the issuing thread's current GLS context ID variable. --------------------------------------------------------------------------- GLSenum glsGetError(void); --------------------------------------------------------------------------- This command retrieves the value of the issuing thread's GLS error code variable, assigns the value GLS_NONE to the variable, and returns the retrieved value. --------------------------------------------------------------------------- GLSfunc glsGetNullCommandFunc(GLSopcode inOpcode); --------------------------------------------------------------------------- This command returns a pointer to a no-op function that has no effect and has the type signature of the encodable command identified by inOpcode. The returned function pointer is intended to be used as a parameter to the command glsCommandFunc. --------------------------------------------------------------------------- GLint glsGetOpcodeCount(GLSenum inAPI); --------------------------------------------------------------------------- This command returns the number of encodable commands in the API identified by inAPI. inAPI must be one of: #define GLS_API_GLS 0x0020 #define GLS_API_GL 0x0021 --------------------------------------------------------------------------- const GLSopcode* glsGetOpcodes(GLSenum inAPI); --------------------------------------------------------------------------- This command returns a zero terminated, statically allocated array containing one opcode value for each of the encodable commands in the API identified by inAPI. inAPI must be one of: #define GLS_API_GLS 0x0020 #define GLS_API_GL 0x0021 --------------------------------------------------------------------------- GLboolean glsIsClientState(GLSenum inAPI, GLSenum inAttrib); --------------------------------------------------------------------------- This command returns GL_TRUE iff inAttrib is a Get enumerant that identifies a client state variable in the API identified by inAPI. inAPI must be one of: #define GLS_API_GLS 0x0020 #define GLS_API_GL 0x0021 --------------------------------------------------------------------------- GLboolean glsIsContext(GLint inContext); --------------------------------------------------------------------------- This command returns GL_TRUE iff inContext is the ID of a GLS context. ------------------------------------------------------------------------------- Immediate Commands ------------------------------------------------------------------------------- --------------------------------------------------------------------------- void glsAbortCall(GLSenum inMode); --------------------------------------------------------------------------- This command, which is intended to be issued by client-provided command functions, assigns the value inMode to the state variable GLS_ABORT_MODE (initial value: GLS_NONE). inMode must be one of: #define GLS_NONE 0x0000 #define GLS_ALL 0x0010 #define GLS_LAST 0x0011 The value of GLS_ABORT_MODE affects the behavior of the GLS stream interpreter commands: glsCallStream, glsCallArray, and glsCopyStream. When the value of GLS_ABORT_MODE is not GLS_NONE, newly issued interpreter commands have no effect, and the most deeply nested currently executing interpreter command (if any) will exit its stream decode loop after the completion of the decoded stream command that is currently executing. Each of the stream interpreter commands takes special action if the value of GLS_ABORT_MODE is not GLS_NONE when its stream decode loop is exited. If the value is GLS_LAST, or if the value is GLS_ALL and the value of the state variable GLS_CALL_NESTING is zero (indicating that there are no more currently executing interpreter commands), the interpreter command assigns the value GLS_NONE to GLS_ABORT_MODE. This effectively ends the abort condition. From a client-provided command function, issue glsAbortCall(GLS_ALL) to abort all nested stream interpreter commands. Issue glsAbortCall(GLS_LAST) to abort only the interpreter command that is closest to the top of the call stack. Issue glsAbortCall(GLS_NONE) to end an abort condition. --------------------------------------------------------------------------- void glsAppendReadPrefix(const GLSchar *inPrefix); --------------------------------------------------------------------------- This command appends the string inPrefix to the state variable GLS_READ_PREFIX_LIST. For a description of GLS_READ_PREFIX_LIST, see the description of the command glsCopyStream. --------------------------------------------------------------------------- GLboolean glsBeginCapture( const GLSchar *inStreamName, GLSenum inCaptureStreamType, GLint inWriteFlags ); --------------------------------------------------------------------------- This command begins a new stream capture and encodes the command glsBeginGLS. The parameter inStreamName is the name of the stream that commands will be captured into. inCaptureStreamType must be one of: #define GLS_CONTEXT 0x0050 #define GLS_BINARY_LSB_FIRST 0x0051 #define GLS_BINARY_MSB_FIRST 0x0052 #define GLS_TEXT 0x0053 inWriteFlags must be zero or more of: #define GLS_WRITE_APPEND_BIT 0x00000001 Iff the value of inWriteFlags is GLS_WRITE_APPEND_BIT, the stream will be opened in append mode. If inCaptureStreamType is GLS_CONTEXT, the captured stream will be stored in the current GLS context. Otherwise, GLS will write data to an external stream. If an external stream is to be written, and inStreamName is not the empty string, GLS uses the ISO C library command fopen to create a write channel of type FILE* and uses the ISO C library function fwrite to write data to the stream. The stream name that is passed to fopen is formed by appending inStreamName to the state variable GLS_WRITE_PREFIX. The state variable GLS_WRITE_FUNC contains a pointer to a function of type GLSwriteFunc (initial value: GLS_NONE). If an external stream is to be written, and inStreamName is the empty string, and the value of GLS_WRITE_FUNC is not GLS_NONE, GLS uses GLS_WRITE_FUNC instead of fwrite to write data to the stream. The type signature of this function is typedef size_t (*GLSwriteFunc)(size_t inCount, const GLvoid *inBuf); The parameter inCount is the number of octets to be written from inBuf, and the function return value is interpreted by GLS as the number of octets actually written. If this value does not equal inCount, GLS raises GLS_IO_ERROR. The state variable GLS_DEFAULT_WRITE_CHANNEL contains a write channel of type FILE* (initial value: stdout). If an external stream is to be written, and inStreamName is the empty string, and the value of GLS_WRITE_FUNC is GLS_NONE, GLS writes data to GLS_DEFAULT_WRITE_CHANNEL instead of using fopen to create a new write channel. The parameters of a stream capture are bound during the execution of the glsBeginCapture command that creates it. Subsequent changes to GLS_WRITE_FUNC or GLS_DEFAULT_WRITE_CHANNEL have no effect on the capture. Stream captures may be nested. If the value of the state variable GLS_CAPTURE_NESTING equals the implementation specific constant GLS_MAX_CAPTURE_NESTING, the command raises GLS_STATE_ERROR. Otherwise, the command increments GLS_CAPTURE_NESTING. If inCaptureStreamType is GLS_CONTEXT and inStreamName is the name of a GLS_CONTEXT stream that is the target of a nested stream capture or a nested stream interpreter command, the command raises GLS_STATE_ERROR. The command returns GL_TRUE iff it does not raise an error. Whenever the value of GLS_CAPTURE_NESTING is nonzero, all GL commands and all encodable GLS commands are captured by GLS. If GLS_IO_ERROR or GLS_RESOURCE_ERROR is raised during a stream capture, GLS will make no further effort during the remaining lifetime of the capture to write to the stream. In this case, GLS will attempt at the end of the capture to truncate the stream to the size that it had at the beginning of the capture. If the stream did not exist before the beginning of the capture, GLS will attempt at the end of the capture to delete the stream. Before issuing the command fopen to open a write channel at the beginning of a capture, GLS issues the command fopen with the same name string in an attempt to create a read channel. If this attempt succeeds, GLS closes the channel immediately. Otherwise, GLS assumes that the file does not exist and records this fact for Some encodable commands have one or more array parameters whose size is a function of other command parameters. When one or more of the parameters that are used to compute an array size have invalid values (e.g. a negative width parameter for glDrawPixels), the encoded size of the corresponding array is zero. It is assumed that when the encoded command is decoded and issued, GL or GLS will raise an error because of the invalid parameter value and will therefore not attempt to access the array. If one or more of the captured commands has implicit parameters stored in GL client state (e.g. glDrawPixels), it is important to ensure that the capture flags values of the commands that modify this state (e.g. glPixelStore) have GLS_CAPTURE_EXECUTE_BIT set during capture. Otherwise, GL client state will not be updated, and an encoder may therefore retrieve incorrect values from GL when encoding commands that depend on this state. For this reason, the initial capture flags values for commands that modify GL client state have GLS_CAPTURE_EXECUTE_BIT set. See the description of the command glsCaptureFlags. --------------------------------------------------------------------------- void glsCallArray( GLSenum inExternStreamType, size_t inCount, const GLvoid *inArray ); --------------------------------------------------------------------------- This command interprets a stream stored in an array of inCount octets. inExternStreamType must be one of: #define GLS_BINARY_LSB_FIRST 0x0051 #define GLS_BINARY_MSB_FIRST 0x0052 #define GLS_TEXT 0x0053 A GLS_BINARY_* stream may contain values of size 8, 16, 32, and 64 bits. If inExternStreamType specifies a GLS_BINARY_* stream, the starting address of inArray must be such that the underlying processor will accept at that address any of the values in inArray. This requirement will be met if malloc is used to allocate inArray. Stream interpreter commands may be nested, via client-provided command functions and glsCallStream commands encoded in streams. If the value of the state variable GLS_CALL_NESTING equals the implementation specific constant GLS_MAX_CALL_NESTING, the command issues the command glsAbortCall(GLS_ALL) and then raises GLS_STATE_ERROR. Otherwise, the command increments GLS_CALL_NESTING at the beginning of execution and decrements it at the end of execution. The glsAbortCall command ensures rapid recovery from unbounded recursion. At the beginning of execution, a stream interpreter command saves the values of the state variables GLS_STREAM_VERSION_MAJOR and GLS_STREAM_VERSION_MINOR, then assigns the value zero to these variables. Whenever a glsBeginGLS command is executed, that command will assign the values of its parameters inVersionMajor and inVersionMinor to GLS_STREAM_VERSION_MAJOR and GLS_STREAM_VERSION_MINOR, respectively. At the end of execution, a stream interpreter command restores the saved values of GLS_STREAM_VERSION_MAJOR and GLS_STREAM_VERSION_MINOR. Each of the stream interpreter commands gives special treatment to GL commands that depend on GL pixel store state. This is necessary because the parameters of these commands are always encoded in a stream in maximally packed form, and GL pixel store state must be set up accordingly before command execution. Immediately before issuing a GL command that depends on the GL state variables GL_PACK_*, a stream interpreter command will issue the following GL commands in capture-execute mode: glPixelStorei(GL_PACK_ALIGNMENT, 1); glPixelStorei(GL_PACK_LSB_FIRST, GL_FALSE); glPixelStorei(GL_PACK_ROW_LENGTH, 0); glPixelStorei(GL_PACK_SKIP_ROWS, 0); glPixelStorei(GL_PACK_SKIP_PIXELS, 0); glPixelStorei(GL_PACK_SWAP_BYTES, GL_FALSE); #if __GL_EXT_texture3D glPixelStorei(GL_PACK_IMAGE_HEIGHT_EXT, 0); glPixelStorei(GL_PACK_SKIP_IMAGES_EXT, 0); #endif /* __GL_EXT_texture3D */ Immediately before issuing a GL command that depends on the GL state variables GL_UNPACK_*, a stream interpreter command will issue the following GL commands in capture-execute mode: glPixelStorei(GL_UNPACK_ALIGNMENT, 1); glPixelStorei(GL_UNPACK_LSB_FIRST, GL_FALSE); glPixelStorei(GL_UNPACK_ROW_LENGTH, 0); glPixelStorei(GL_UNPACK_SKIP_ROWS, 0); glPixelStorei(GL_UNPACK_SKIP_PIXELS, 0); glPixelStorei(GL_UNPACK_SWAP_BYTES, GL_FALSE); #if __GL_EXT_texture3D glPixelStorei(GL_UNPACK_IMAGE_HEIGHT_EXT, 0); glPixelStorei(GL_UNPACK_SKIP_IMAGES_EXT, 0); #endif /* __GL_EXT_texture3D */ To avoid unnecessary overhead, GLS will issue each of these GL command sequences at most once during the execution of a top-level stream interpreter command. As a result, if a client-provided command function modifies the value of a GL pixel store state variable during stream interpretation, the function must restore the value assigned by GLS before returning. When GLS issues a GL Get command from a stream, the issued command's "out" parameters are pointers to buffers allocated by GLS and guaranteed to be of sufficient size to contain the writes generated if GL (and not a client-provided command function) executes the command. In some cases (e.g. glGetTexImage) the sizes of the buffers that are needed are computed functions of GL state. In these cases, GLS issues other GL Get commands in capture-execute mode (to obtain the information needed to compute buffer sizes) before issuing the GL Get command from the stream. If there is no current GL context, the sizes of the dynamically allocated buffers will all be zero. Immediately before issuing a GL Get command from a stream, GLS saves the values of the state variables GLS_OUT_ARG_SIZE_LIST and GLS_OUT_ARG_POINTER_LIST (initial values: the empty list) and assigns to these variables values for the command to be issued (see below). After the issued command returns, GLS restores the saved values of these variables. GLS_OUT_ARG_SIZE_LIST and GLS_OUT_ARG_POINTER_LIST each have one element for each of the issued command's out parameters. The order of the elements in the lists corresponds to the order in which the out parameters appear in the issued command's parameter list. Each element of GLS_OUT_ARG_SIZE_LIST is the size of the corresponding returned result, in units of the data type of the result (e.g. number of values of type GLfloat). If the data type of the result is determined at runtime (e.g. glReadPixels), the unit is octets. Each element of GLS_OUT_ARG_POINTER_LIST is the 64-bit value that was encoded in the stream for the corresponding out parameter. If a decoder does not recognize a command (e.g. because it is from a GL extension that is not supported by the GLS implementation), it will issue the encodable command extern void glsUnsupportedCommand (const GLSchar *inCommand); where inCommand is either the command's name from a GLS_TEXT stream or a decimal string representation of the command's opcode from a GLS_BINARY_* stream. The decoder will continue with the following command. If a decoder cannot decode a command that it does recognize (e.g. due to a syntax error or a symbolic extension enumerant for an unsupported extension) it will issue the encodable command glsError(opcode, GLS_DECODE_ERROR). The decoder will attempt to continue with the following command. In some cases (e.g. GL Get commands), a decoder must dynamically allocate buffer space in order to decode a command. If the dynamic allocation fails, the decoder will issue the encodable command glsError(opcode, GLS_RESOURCE_ERROR). The decoder will continue with the following command. If a decoder encounters a GLS_BINARY_* stream that has been truncated or contains a command header with a zero opcode or length field, it raises GLS_DECODE_ERROR and does not attempt to decode any more commands from the stream. If the GLS_TEXT decoder encounters a GL command that does not accept a null image pointer yet is encoded with GLS_IMAGE_NULL_BIT set, or a GL command that is encoded with one or more undefined bits set in the image encoding options mask, the decoder issues the encodable command glsError(opcode, GLS_PARAMETER_ERROR). The decoder will continue with the following command. If the GLS_TEXT decoder encounters a GL command that has one or more stride parameters that are not set for maximal packing of array parameter data, the decoder issues the encodable command glsError(opcode, GLS_PARAMETER_ERROR. The decoder will continue with the following command. --------------------------------------------------------------------------- void glsCaptureEntryFunc(GLScaptureEntryFunc inFunc); --------------------------------------------------------------------------- This command assigns the value inFunc to the state variable GLS_CAPTURE_ENTRY_FUNC (initial value: GLS_NONE). The type signature of inFunc is typedef void (*GLScaptureEntryFunc)( GLSopcode inOpcode, const GLvoid *optinParam1 ); Whenever the value of GLS_CAPTURE_ENTRY_FUNC is not GLS_NONE and the value of GLS_CAPTURE_NESTING is nonzero, GLS_CAPTURE_ENTRY_FUNC is called immediately before each command is captured. The parameter inOpcode is the GLS opcode of the captured command. If the captured command has one or more parameters, the parameter optinParam1 is a pointer to the first parameter of the captured command. Otherwise, the value of optinParam1 is GLS_NONE. The parameter optinParam1 is intended to be used in client-server applications of GLS where the first parameter of a GL Get command determines whether the command is executed locally (client state) or remotely (server state). --------------------------------------------------------------------------- void glsCaptureExitFunc(GLScaptureExitFunc inFunc); --------------------------------------------------------------------------- This command assigns the value inFunc to the state variable GLS_CAPTURE_EXIT_FUNC (initial value: GLS_NONE). The type signature of inFunc is typedef void (*GLScaptureExitFunc)( GLSopcode inOpcode, const GLvoid *optinParam1, GLvoid *optinoutReturn ); Whenever the value of GLS_CAPTURE_EXIT_FUNC is not GLS_NONE and the value of GLS_CAPTURE_NESTING is nonzero, GLS_CAPTURE_EXIT_FUNC is called immediately after each command is captured. The parameter inOpcode is the GLS opcode of the captured command. If the captured command has one or more parameters, the parameter optinParam1 is a pointer to the first parameter of the captured command. Otherwise, the value of optinParam1 is GLS_NONE. If the captured command has a function return value, the parameter optinoutReturn is a pointer to this value. Otherwise, the value of optinoutReturn is GLS_NONE. The parameter optinParam1 is intended to be used in client-server applications of GLS where the first parameter of a GL Get command determines whether the command is executed locally (client state) or remotely (server state). The parameter optinoutReturn is intended to be used in client-server applications of GLS where the function return value is determined by sending a GL command to a remote server and storing the reply in the function return value. --------------------------------------------------------------------------- void glsCaptureFlags(GLSopcode inOpcode, GLint inFlags); --------------------------------------------------------------------------- This command assigns the value inFlags to the capture flags of the encodable command identified by inOpcode. inFlags must be zero or more of: #define GLS_CAPTURE_EXECUTE_BIT 0x00000001 #define GLS_CAPTURE_WRITE_BIT 0x00000002 Iff GLS_CAPTURE_EXECUTE_BIT is set, a captured command will be executed. Iff GLS_CAPTURE_WRITE_BIT is set, a captured command will be encoded and written to the stream of the current stream capture. The initial (and immutable) capture flags value for glsBeginGLS, glsEndGLS, and glsPad is GLS_NONE. These commands are generated automatically by an encoder, and issuing them during capture has no effect. If the value of inOpcode is GLS_OP_glsBeginGLS, GLS_OP_glsEndGLS, or GLS_OP_glsPad, the command glsCaptureFlags has no effect. The initial capture flags value for commands that modify client state is GLS_CAPTURE_EXECUTE_BIT | GLS_CAPTURE_WRITE_BIT. The initial capture flags value for all other commands is GLS_CAPTURE_WRITE_BIT. --------------------------------------------------------------------------- void glsChannel(GLSenum inTarget, FILE *inChannel); --------------------------------------------------------------------------- This command assigns the value inChannel to the GLS state variable identified by inTarget. inTarget must be one of: #define GLS_DEFAULT_READ_CHANNEL 0x0060 #define GLS_DEFAULT_WRITE_CHANNEL 0x0061 For a description of GLS_DEFAULT_READ_CHANNEL, see the description of the command glsCopyStream. For a description of GLS_DEFAULT_WRITE_CHANNEL, see the description of the command glsBeginCapture. --------------------------------------------------------------------------- void glsCommandFunc(GLSopcode inOpcode, GLSfunc inFunc); --------------------------------------------------------------------------- This command assigns the value inFunc to the command function pointer of the encodable command identified by inOpcode. The type signature of inFunc must match that of the encodable command. The initial value of all command function pointers is GLS_NONE. This causes each encodable command to be executed directly when decoded. A command function may perform arbitrary computations and may issue any sequence of GL and GLS commands, with the exception that issuing a glsContext command to change the current GLS context will raise GLS_STATE_ERROR. Note that if a client supplies a command function for an encodable command, GLS will call that function instead of issuing the command. If the effect of the "real" command is desired, the command function must issue the command. --------------------------------------------------------------------------- GLSenum glsCopyStream( const GLSchar *inSource, const GLSchar *inDest, GLSenum inDestType, GLint inWriteFlags ); --------------------------------------------------------------------------- This command decodes the stream identified by inSource and captures it into the stream identified by inDest. If client-provided command functions and capture entry and exit functions are defined, they are called in the normal fashion, thereby providing client code with an opportunity to filter the stream arbitrarily after decoding and before re-encoding. The command returns the encoding of inSource. inDestType specifies the encoding for inDest and must be one of: #define GLS_NONE 0x0000 #define GLS_CONTEXT 0x0050 #define GLS_BINARY_LSB_FIRST 0x0051 #define GLS_BINARY_MSB_FIRST 0x0052 #define GLS_TEXT 0x0053 where GLS_NONE specifies that the encoding for inDest should be the same as the encoding for inSource. inWriteFlags must be zero or more of: #define GLS_WRITE_APPEND_BIT 0x00000001 Iff the value of inWriteFlags is GLS_WRITE_APPEND_BIT, inDest will be opened in append mode. If inSource is the name of a GLS_CONTEXT stream, GLS will decode that stream. Otherwise, GLS searches for an external stream to read. If an external stream is to be read, and inSource is not the empty string, GLS forms a sequence of potential external stream names. GLS forms the first names in the sequence by appending inSource to each of the strings in GLS_READ_PREFIX_LIST. GLS forms the last name in the sequence by appending inSource to GLS_WRITE_PREFIX. Beginning with the first potential external stream name, GLS tries each successive name until either it finds a valid stream, or all of the names have been tried. For each name, GLS issues the command fopen with the name as a parameter, in an attempt to create a read channel of type FILE*. If this succeeds, GLS attempts to decode a glsBeginGLS command from the channel and verify that the inVersionMajor parameter of that command either is zero or equals the value of the implementation specific constant GLS_VERSION_MAJOR. If this succeeds, GLS considers the stream to be valid. If no valid stream is found, the command raises GLS_PARAMETER_ERROR. The state variable GLS_READ_FUNC contains a pointer to a function of type GLSreadFunc (initial value: GLS_NONE). If an external stream is to be read, and inSource is the empty string, and the value of GLS_READ_FUNC is not GLS_NONE, GLS uses GLS_READ_FUNC instead of fread to read data from the stream. The type signature of this function is typedef size_t (*GLSreadFunc)(size_t inCount, GLvoid *outBuf); The parameter inCount is the number of octets in outBuf, and the function return value is interpreted by GLS as the number of octets actually read. When this value is less than 1, GLS assumes that the end of the stream has been read. The state variable GLS_DEFAULT_READ_CHANNEL contains a read channel of type FILE* (initial value: stdin). If an external stream is to be read, and inSource is the empty string, and the value of GLS_READ_FUNC is GLS_NONE, GLS reads data from GLS_DEFAULT_READ_CHANNEL instead of using fopen to create a new read channel. The parameters of a stream decode are bound at the beginning of execution. Subsequent changes to GLS_READ_FUNC or GLS_DEFAULT_READ_CHANNEL have no effect on the decode. The methods that GLS uses in decoding inSource are the same as those described for the command glsCallArray. The methods that GLS uses in opening and writing to the stream inDest are the same as those described for the parameter inStreamName of the command glsBeginCapture. Note that if the source stream contains a command that modifies client state (e.g. glPixelStore), and if the capture flags value for this command has GLS_CAPTURE_EXECUTE_BIT set, this command will be captured (assuming a command function has not been provided) and executed, and will modify GL client state. --------------------------------------------------------------------------- void glsDataPointer(GLvoid *inPointer); --------------------------------------------------------------------------- This command assigns the value inPointer to the state variable GLS_DATA_POINTER. Client-provided callback functions can retrieve this value and use it to access client data in a thread-safe manner. --------------------------------------------------------------------------- void glsDeleteStream(const GLSchar *inName); --------------------------------------------------------------------------- This command deletes the stream identified by inName. GLS finds the stream using the same method that it uses to find the stream identified by the parameter inSource to the command glsCopyStream. If no stream is found, GLS raises GLS_PARAMETER_ERROR. If the stream is external, GLS issues the ISO C library command remove to delete the stream. If that command fails, GLS raises GLS_IO_ERROR. --------------------------------------------------------------------------- void glsDisable(GLSenum inAttrib); --------------------------------------------------------------------------- This command assigns the value GL_FALSE to the Boolean GLS state variable identified by inAttrib, which must be: #define GLS_CAPTURE_VERTEX_ARRAYS 0x0040 The initial value of GLS_CAPTURE_VERTEX_ARRAYS is GL_FALSE. When the value of this variable is GL_FALSE, GLS captures the following GL vertex array rendering commands in the normal fashion: glArrayElement glArrayElementEXT glDrawArrays glDrawArraysEXT glDrawElements While this behavior is consistent with the treatment of other commands, it is for many applications not the desired behavior. When GL executes these commands, GL uses pointer values stored in client state to access parameter data. In many GLS applications, these pointers will not be valid when a stream containing these commands is decoded. To solve this problem, a client can use the command glsEnable to assign the value GL_TRUE to GLS_CAPTURE_VERTEX_ARRAYS. This causes GLS to automatically translate GL vertex array rendering commands at capture time into encodable commands that carry the referenced data directly in their parameter lists. If the current GL vertex array format is compatible with one of the packed vertex array formats #define GL_V2F 0x2A20 #define GL_V3F 0x2A21 #define GL_C4UB_V2F 0x2A22 #define GL_C4UB_V3F 0x2A23 #define GL_C3F_V3F 0x2A24 #define GL_N3F_V3F 0x2A25 #define GL_C4F_N3F_V3F 0x2A26 #define GL_T2F_V3F 0x2A27 #define GL_T4F_V4F 0x2A28 #define GL_T2F_C4UB_V3F 0x2A29 #define GL_T2F_C3F_V3F 0x2A2A #define GL_T2F_N3F_V3F 0x2A2B #define GL_T2F_C4F_N3F_V3F 0x2A2C #define GL_T4F_C4F_N3F_V4F 0x2A2D then GLS will at capture time translate each GL vertex array rendering command into an equivalent glsDrawVertexArrays command. Otherwise, GLS will translate each such command into a sequence of fine-grained GL rendering commands, chosen from glBegin glColor*v glEdgeflagv glEnd glIndex*v glNormal3*v glTexCoord*v glVertex*v --------------------------------------------------------------------------- void glsEnable(GLSenum inAttrib); --------------------------------------------------------------------------- This command assigns the value GL_TRUE to the Boolean GLS state variable identified by inAttrib, which must be: #define GLS_CAPTURE_VERTEX_ARRAYS 0x0040 For a description of GLS_CAPTURE_VERTEX_ARRAYS, see the description of the command glsDisable. --------------------------------------------------------------------------- void glsEndCapture(void); --------------------------------------------------------------------------- This command encodes the command glsEndGLS and then ends the most deeply nested stream capture, decrementing GLS_CAPTURE_NESTING. If GLS_CAPTURE_NESTING is zero on entry, the command raises GLS_STATE_ERROR. --------------------------------------------------------------------------- void glsFlush(void); --------------------------------------------------------------------------- This command flushes buffered data to all external streams that are targets of a stream capture. --------------------------------------------------------------------------- GLint glsGetCaptureFlags(GLSopcode inOpcode); --------------------------------------------------------------------------- This command returns the capture flags of the encodable command identified by inOpcode. --------------------------------------------------------------------------- GLSfunc glsGetCommandFunc(GLSopcode inOpcode); --------------------------------------------------------------------------- This command returns the command function pointer of the encodable command identified by inOpcode. --------------------------------------------------------------------------- const GLSchar* glsGetCommandName(GLSopcode inOpcode); --------------------------------------------------------------------------- This command returns the string name of the encodable command identified by inOpcode. --------------------------------------------------------------------------- GLSopcode glsGetCommandOpcode(const GLSchar *inName); --------------------------------------------------------------------------- This command returns the opcode of the encodable command identified by inName. --------------------------------------------------------------------------- const GLSchar* glsGetEnumName(GLSenum inAPI, GLSenum inValue); --------------------------------------------------------------------------- This command returns the string name of the enumerant identified by inAPI and inValue. If an enumerant is reused with a different name in a subsequent API version (e.g. GL_DOUBLE_EXT -> GL_DOUBLE), the most recently defined name is returned. The GL API uses many names for the enumerants 0 and 1. This command returns "GL_POINTS" for 0 and "GL_LINES" for 1. --------------------------------------------------------------------------- GLint glsGetEnumValue(GLSenum inAPI, const GLSchar *inName); --------------------------------------------------------------------------- This command returns the value of the enumerant identified by inAPI and inName. --------------------------------------------------------------------------- GLSfunc glsGetFunc(GLSenum inAttrib); --------------------------------------------------------------------------- This command returns the function pointer identified by inAttrib, which must be one of: #define GLS_CAPTURE_ENTRY_FUNC 0x0090 #define GLS_CAPTURE_EXIT_FUNC 0x0091 #define GLS_READ_FUNC 0x0092 #define GLS_WRITE_FUNC 0x0093 For descriptions of GLS_CAPTURE_ENTRY_FUNC and GLS_CAPTURE_EXIT_FUNC, see the descriptions of the commands glsCaptureEntryFunc and glsCaptureEntryFunc. For a description of GLS_READ_FUNC, see the description of the command glsCopyStream. For a description of GLS_WRITE_FUNC, see the description of the command glsBeginCapture. --------------------------------------------------------------------------- const GLSchar* glsGetHeaderc(GLSenum inAttrib); --------------------------------------------------------------------------- This command returns the value of the GLS header state variable identified by inAttrib, which must be one of: #define GLS_AUTHOR 0x0150 #define GLS_TITLE 0x0151 #define GLS_VERSION 0x0152 For a description of these variables, see the description of the encodable command glsHeaderc, which can be used to be assign values to them. --------------------------------------------------------------------------- GLfloat glsGetHeaderf(GLSenum inAttrib); --------------------------------------------------------------------------- This command returns the value of the GLS header state variable identified by inAttrib, which must be one of: #define GLS_ASPECT 0x0160 #define GLS_CONTRAST 0x0161 For a description of these variables, see the description of the encodable command glsHeaderf, which can be used to be assign values to them. --------------------------------------------------------------------------- GLfloat* glsGetHeaderfv(GLSenum inAttrib, GLfloat *outVec); --------------------------------------------------------------------------- This command returns in outVec the value of the GLS header state variable identified by inAttrib, which must be one of: #define GLS_GAMMA 0x0170 #define GLS_RED_POINT 0x0171 #define GLS_GREEN_POINT 0x0172 #define GLS_BLUE_POINT 0x0173 #define GLS_WHITE_POINT 0x0174 For a description of these variables, see the description of the encodable command glsHeaderfv, which can be used to be assign values to them. If no error is raised, the function return value is outVec. --------------------------------------------------------------------------- GLint glsGetHeaderi(GLSenum inAttrib); --------------------------------------------------------------------------- This command returns the value of the GLS header state variable identified by inAttrib, which must be one of: #define GLS_ACCUM_RED_BITS 0x0180 #define GLS_ACCUM_GREEN_BITS 0x0181 #define GLS_ACCUM_BLUE_BITS 0x0182 #define GLS_ACCUM_ALPHA_BITS 0x0183 #define GLS_AUX_BUFFERS 0x0184 #define GLS_COLOR_RED_BITS 0x0185 #define GLS_COLOR_GREEN_BITS 0x0186 #define GLS_COLOR_BLUE_BITS 0x0187 #define GLS_COLOR_ALPHA_BITS 0x0188 #define GLS_DEPTH_BITS 0x0189 #define GLS_DOUBLEBUFFER 0x018A #define GLS_HEIGHT 0x018B #define GLS_STENCIL_BITS 0x018C #define GLS_STEREO 0x018D #define GLS_TILEABLE 0x018E For a description of these variables, see the description of the encodable command glsHeaderi, which can be used to be assign values to them. --------------------------------------------------------------------------- GLint* glsGetHeaderiv(GLSenum inAttrib, GLint *outVec); --------------------------------------------------------------------------- This command returns in outVec the value of the GLS header state variable identified by inAttrib, which must be: #define GLS_CREATE_TIME 0x01A0 For a description of this variable, see the description of the encodable command glsHeaderiv, which can be used to be assign values to it. If no error is raised, the function return value is outVec. --------------------------------------------------------------------------- const GLSchar* glsGetListc(GLSenum inAttrib, GLint inIndex); --------------------------------------------------------------------------- This command returns the value of an element of the list-valued GLS state variable identified by inAttrib, which must be one of: #define GLS_CONTEXT_STREAM_LIST 0x00A0 #define GLS_READ_PREFIX_LIST 0x00A1 Associated with each of these lists is a GLS state variable containing the number of elements in the list. To obtain the value of one of these variables, issue the command glsGeti with one of: #define GLS_CONTEXT_STREAM_COUNT 0x0124 #define GLS_READ_PREFIX_COUNT 0x0128 If inIndex is less than zero or is greater than or equal to the number of elements in the list, the command raises GLS_PARAMETER_ERROR. The state variable GLS_CONTEXT_STREAM_LIST is the list of all streams of type GLS_CONTEXT in the current GLS context (initial value: the empty list). For a description of GLS_READ_PREFIX_LIST, see the description of the command glsCopyStream. --------------------------------------------------------------------------- GLint glsGetListi(GLSenum inAttrib, GLint inIndex); --------------------------------------------------------------------------- This command returns the value of an element of the list-valued GLS state variable identified by inAttrib, which must be: #define GLS_OUT_ARG_SIZE_LIST 0x00B0 Associated with this list is a GLS state variable containing the number of elements in the list. To obtain the value of this variable, issue the command glsGeti with: #define GLS_OUT_ARG_COUNT 0x0127 If inIndex is less than zero or is greater than or equal to the number of elements in the list, the command raises GLS_PARAMETER_ERROR. For a description of GLS_OUT_ARG_SIZE_LIST, see the description of the command glsCallArray. --------------------------------------------------------------------------- GLSlong glsGetListl(GLSenum inAttrib, GLint inIndex); --------------------------------------------------------------------------- This command returns the value of an element of the list-valued GLS state variable identified by inAttrib, which must be: #define GLS_OUT_ARG_POINTER_LIST 0x00B0 Associated with this list is a GLS state variable containing the number of elements in the list. To obtain the value of this variable, issue the command glsGeti with: #define GLS_OUT_ARG_COUNT 0x0127 If inIndex is less than zero or is greater than or equal to the number of elements in the list, the command raises GLS_PARAMETER_ERROR. For a description of GLS_OUT_ARG_POINTER_LIST, see the description of the command glsCallArray. --------------------------------------------------------------------------- GLvoid* glsGetPointer(GLSenum inAttrib); --------------------------------------------------------------------------- This command returns the value of the GLS state variable identified by inAttrib, which must be one of: #define GLS_DEFAULT_READ_CHANNEL 0x0060 #define GLS_DEFAULT_WRITE_CHANNEL 0x0061 #define GLS_DATA_POINTER 0x00D0 For a description of GLS_DEFAULT_READ_CHANNEL, see the description of the command glsCopyStream. For a description of GLS_DEFAULT_WRITE_CHANNEL, see the description of the command glsBeginCapture. For a description of GLS_DATA_POINTER, see the description of the command glsDataPointer. --------------------------------------------------------------------------- size_t glsGetStreamSize(const GLSchar *inName); --------------------------------------------------------------------------- This command returns the number of octets in the stream identified by inName. GLS finds the stream using the same method that it uses to find the stream identified by the parameter inSource to the command glsCopyStream. If no stream is found, GLS raises GLS_PARAMETER_ERROR. If the number of octets in the stream cannot be determined (e.g. if the stream is a pipe), the command returns zero. --------------------------------------------------------------------------- const GLSchar* glsGetStreamc(GLSenum inAttrib, const GLSchar *inName); --------------------------------------------------------------------------- This command returns an attribute of the stream identified by inName. The attribute is identified by inAttrib, which must be one of: #define GLS_READ_NAME 0x00F0 #define GLS_WRITE_NAME 0x00F1 If inAttrib is GLS_READ_NAME, GLS finds the stream using the same method that it uses to find the stream identified by the parameter inSource to the command glsCopyStream. If no stream is found, GLS raises GLS_PARAMETER_ERROR. Otherwise, the returned value is the full name that was used to find the stream. If inAttrib is GLS_WRITE_NAME, the returned value is the concatenation of the value of GLS_WRITE_PREFIX and inName. For a description of GLS_WRITE_PREFIX, see the description of the command glsBeginCapture. --------------------------------------------------------------------------- GLint glsGetStreami(GLSenum inAttrib, const GLSchar *inName); --------------------------------------------------------------------------- This command returns an attribute of the stream identified by inName. The attribute is identified by inAttrib, which must be one of: #define GLS_CRC32 0x0100 #define GLS_STREAM_TYPE 0x0101 GLS finds the stream using the same method that it uses to find the stream identified by the parameter inSource to the command glsCopyStream. If no stream is found, GLS raises GLS_PARAMETER_ERROR. If inAttrib is GLS_CRC32, the returned value is CRC-32 computed over the octets of the stream. If inAttrib is GLS_STREAM_TYPE, the returned value is the encoding type of the stream, one of: #define GLS_CONTEXT 0x0050 #define GLS_BINARY_LSB_FIRST 0x0051 #define GLS_BINARY_MSB_FIRST 0x0052 #define GLS_TEXT 0x0053 #define GLS_UNKNOWN 0x00E0 GLS_UNKNOWN is returned if the stream is not seekable (e.g. if the stream is a pipe). In this case, the type of the stream cannot be determined because there is no way to read data from the stream in a non-destructive fashion. --------------------------------------------------------------------------- const GLSchar* glsGetc(GLSenum inAttrib); --------------------------------------------------------------------------- This command returns the value of the GLS state variable or implementation specific constant identified by inAttrib, which must be one of: #define GLS_EXTENSIONS 0x0110 #define GLS_RELEASE 0x0111 #define GLS_VENDOR 0x0112 #define GLS_WRITE_PREFIX 0x0113 GLS_EXTENSIONS is an implementation specific constant that lists in alphabetical order the names of the GLS extensions that are supported by the implementation. One SPACE (U+20) separates each pair of adjacent names. Example: "GLS_EXT_foo GLS_EXT_bar". Each extension name begins with "GLS_prefix_", where prefix is some string. Iff two or more vendors support the extension at the time of its introduction, the value of prefix is "EXT". Otherwise, the value of prefix is a vendor specific extension name prefix string, optionally followed by one 'S' (U+53) or one 'X' (U+58). The 'S' indicates that the extension is supported on only a subset of the vendor's products. The 'X' indicates that the extension is experimental and may be redefined or removed in future releases. One '_' (U+5F) should be used between each pair of adjacent words in an extension name. GLS_RELEASE is an implementation specific constant that identifies the vendor specific software release that contains the GLS implementation. Example: "IRIX 6.2". GLS_VENDOR is an implementation specific constant that identifies the vendor of the GLS implementation. If the vendor offers a GL implementation, the value of GLS_VENDOR must equal the value of the GL implementation dependent constant GL_VENDOR. Otherwise, the value of GLS_VENDOR must be a unique name that the vendor has allocated in the GLS vendor registry by sending email to gls-registry@sgi.com. For a description of GLS_WRITE_PREFIX, see the description of the command glsBeginCapture. --------------------------------------------------------------------------- GLint glsGeti(GLSenum inAttrib); --------------------------------------------------------------------------- This command returns the value of the GLS state variable or implementation specific constant identified by inAttrib, which must be one of: #define GLS_ABORT_MODE 0x0120 #define GLS_BLOCK_TYPE 0x0121 #define GLS_CALL_NESTING 0x0122 #define GLS_CAPTURE_NESTING 0x0123 #define GLS_CONTEXT_STREAM_COUNT 0x0124 #define GLS_MAX_CALL_NESTING 0x0125 #define GLS_MAX_CAPTURE_NESTING 0x0126 #define GLS_OUT_ARG_COUNT 0x0127 #define GLS_READ_PREFIX_COUNT 0x0128 #define GLS_STREAM_VERSION_MAJOR 0x0129 #define GLS_STREAM_VERSION_MINOR 0x012A #define GLS_STRING_TYPE 0x012B #define GLS_VERSION_MAJOR 0x012C #define GLS_VERSION_MINOR 0x012D For a description of the state variable GLS_ABORT_MODE, see the description of the command glsAbortCall. For a description of the state variable GLS_BLOCK_TYPE, see the description of the command glsBlock. The state variable GLS_CALL_NESTING (initial value: zero) contains the number of nested stream interpreter commands. The state variable GLS_CAPTURE_NESTING (initial value: zero) contains the number of nested stream captures. The state variable GLS_CONTEXT_STREAM_COUNT (initial value: zero) contains the number of GLS_CONTEXT streams. The implementation specific constant GLS_MAX_CALL_NESTING is the maximum number of nested stream interpreter commands. Its value must be at least 64. The implementation specific constant GLS_MAX_CAPTURE_NESTING is the maximum number of nested stream captures. Its value must be at least 16. The state variable GLS_OUT_ARG_COUNT (initial value: zero) contains the number of elements in each of the lists GLS_OUT_ARG_SIZE_LIST and GLS_OUT_ARG_POINTER_LIST. The state variable GLS_READ_PREFIX_COUNT (initial value: zero) contains the number of elements in the list GLS_READ_PREFIX_LIST. For a description of the state variables GLS_STREAM_VERSION_MAJOR and GLS_STREAM_VERSION_MINOR, see the description of the command glsCallArray. For a description of the state variable GLS_STRING_TYPE, see the Strings section of this document. The implementation specific constants GLS_VERSION_MAJOR and GLS_VERSION_MINOR are the major and minor version numbers of the GLS implementation. They correspond to a version X.Y of this document. In the extremely unlikely event that there is an incompatible change to GL or to the GLS API or encodings, the major version number of this document will be incremented. Whenever there is a compatible change to GL or to the GLS API or encodings, the minor version number of this document will be incremented. --------------------------------------------------------------------------- GLint* glsGetiv(GLSenum inAttrib, GLint *outVec); --------------------------------------------------------------------------- This command returns in outVec the value of the GLS state variable identified by inAttrib, which must be: #define GLS_CURRENT_TIME 0x0140 The function return value is outVec. The state variable GLS_CURRENT_TIME contains the current UTC time in the GLS time format: {utcYear, utcMonth, utcDay, utcHour, utcMinute, utcSecond} where utcYear is the number of years since the year zero, utcMonth is in the range [1, 12], utcDay is in the range [1, 31], utcHour is in the range [0, 23], utcMinute is in the range [0, 59], and utcSecond is in the range [0, 61]. If the current UTC time is unavailable to the GLS implementation, all six elements have the value zero. This command is intended to be used to generate the inVec parameter of the encodable command glsHeaderiv(GLS_CREATE_TIME, inVec); which can be used to encode in a stream the time of its creation. --------------------------------------------------------------------------- GLboolean glsIsContextStream(const GLSchar *inName); --------------------------------------------------------------------------- This command returns GL_TRUE iff inName is the name of a GLS_CONTEXT stream in the current GLS context. --------------------------------------------------------------------------- GLboolean glsIsEnabled(GLSenum inAttrib); --------------------------------------------------------------------------- This command returns the value of the Boolean GLS state variable identified by inAttrib, which must be: #define GLS_CAPTURE_VERTEX_ARRAYS 0x0040 For a description of GLS_CAPTURE_VERTEX_ARRAYS, see the description of the command glsDisable. --------------------------------------------------------------------------- GLboolean glsIsExtensionSupported(const GLSchar *inExtension); --------------------------------------------------------------------------- This command returns GL_TRUE iff the extension identified by inExtension is supported. If inExtension does not begin with the string "GLS_" or "GL_", the command returns GL_FALSE. If inExtension begins with the string "GLS_", the command returns GL_TRUE iff inExtension is a substring of the string GLS_EXTENSIONS. If inExtension begins with the string "GL_", the command returns GL_TRUE iff inExtension is a substring of the string GLS_EXTENSIONS and inExtension is also a substring of the GL_EXTENSIONS string (if any) that was retrieved by GLS from the underlying GL implementation during the execution of the most recent glsContext command. --------------------------------------------------------------------------- GLboolean glsIsVersionSupported( GLSenum inAPI, GLint inVersionMajor, GLint inVersionMinor ); --------------------------------------------------------------------------- This command returns GL_TRUE iff the major version number of the API identified by inAPI equals inVersionMajor and the minor version number of that API is greater than or equal to inVersionMinor. If inAPI is GLS_API_GL, the GL major and minor version numbers are obtained by parsing the GL_VERSION string (if any) that was retrieved by GLS from the underlying GL implementation during the execution of the most recent glsContext command. If this string was not retrieved (i.e. there was no current GL context), the GL major and minor version numbers are taken to be those that correspond to the GLS version, as was discussed in the description of the command glsContext. --------------------------------------------------------------------------- void glsPrependReadPrefix(const GLSchar *inPrefix); --------------------------------------------------------------------------- This command prepends the string inPrefix to the state variable GLS_READ_PREFIX_LIST. For a description of GLS_READ_PREFIX_LIST, see the description of the command glsCopyStream. --------------------------------------------------------------------------- void glsReadFunc(GLSreadFunc inFunc); --------------------------------------------------------------------------- This command assigns the value inFunc to the state variable GLS_READ_FUNC. For a description of GLS_READ_FUNC, see the description of the command glsCopyStream. --------------------------------------------------------------------------- void glsRemoveReadPrefix(GLint inIndex); --------------------------------------------------------------------------- This command removes the element identified by inIndex from the state variable GLS_READ_PREFIX_LIST. For a description of GLS_READ_PREFIX_LIST, see the description of the command glsCopyStream. If inIndex is less than zero or is greater than or equal to the value of GLS_READ_PREFIX_COUNT, the command raises GLS_PARAMETER_ERROR. --------------------------------------------------------------------------- void glsResetAlignment(void); --------------------------------------------------------------------------- This command clears the alignment bit in the most deeply nested stream capture. The alignment bit controls the generation of padding for the alignment of 64-bit parameter values. It is cleared at the beginning of a stream capture and has the value 1 iff the number of bits written to the stream since the alignment bit was last cleared is an odd multiple of 32. This command is intended to be used by a client that: - is writing a stream that contains one or more 64-bit values, and - is running on a processor that requires 64-bit values to be aligned to a 64-bit boundary in memory, and - is using a write callback function to write a stream into memory in multiple chunks, each allocated via malloc. When the client starts a new chunk, the client must issue this command to clear the alignment bit. Otherwise, GLS may generate padding that produces the opposite of the necessary alignment. If the value of GLS_CAPTURE_NESTING is zero, or if no GLS_BINARY_* stream is being written, the command has no effect. --------------------------------------------------------------------------- void glsStringType(GLSenum inStringType); --------------------------------------------------------------------------- This command assigns to the state variable GLS_STRING_TYPE the value inStringType, which must be one of: #define GLS_UCS1 0x01B0 #define GLS_UCS2 0x01B1 #define GLS_UCS4 0x01B2 For a description of GLS_STRING_TYPE, see the Strings section of this document. --------------------------------------------------------------------------- void glsWriteFunc(GLSwriteFunc inFunc); --------------------------------------------------------------------------- This command assigns the value inFunc to the state variable GLS_WRITE_FUNC. For a description of GLS_WRITE_FUNC, see the description of the command glsBeginCapture. --------------------------------------------------------------------------- void glsWritePrefix(const GLSchar *inPrefix); --------------------------------------------------------------------------- This command assigns the value inPrefix to the state variable GLS_WRITE_PREFIX. For a description of GLS_WRITE_PREFIX, see the description of the command glsBeginCapture. ------------------------------------------------------------------------------- Encodable Commands ------------------------------------------------------------------------------- --------------------------------------------------------------------------- void glsBeginGLS(GLint inVersionMajor, GLint inVersionMinor); --------------------------------------------------------------------------- This command is generated automatically at the beginning of a stream by an encoder, and is required by a decoder as the first command in a stream. The command assigns the values of inVersionMajor and inVersionMinor to the state variables GLS_STREAM_VERSION_MAJOR and GLS_STREAM_VERSION_MINOR, respectively. The command's capture flags value cannot be changed from its initial value of GLS_NONE. As a result, issuing the command during capture has no effect. --------------------------------------------------------------------------- void glsBlock(GLSenum inBlockType); --------------------------------------------------------------------------- This command assigns to the state variable GLS_BLOCK_TYPE (initial value: GLS_FRAME) the value of inBlockType, which must be one of: #define GLS_FRAME 0x0030 #define GLS_HEADER 0x0031