glsIntro(3G)
glsIntro - Introduction to the OpenGL Stream Codec
As shipped in IRIX 6.5.30. Unchanged since IRIX 6.5.
NAME glsIntro - Introduction to the OpenGL Stream Codec OVERVIEW The OpenGL Stream Codec (GLS) is a facility for encoding and decoding streams of 8-bit bytes that represent sequences of OpenGL (henceforth, "GL") commands. The GLS specification has two components: 1. A set of three byte-stream encodings for GL and GLS commands: human-readable text, big-endian binary, and little-endian binary. The three encodings are semantically identical; they differ only in syntax. It is therefore possible to convert GLS byte streams freely among the three encodings without loss of information. 2. An API that provides commands for encoding and decoding GLS byte 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 encodings and API are platform independent and window system independent. In particular, the GLS encodings are not tied to the X Window System protocol encoding used by the GLX extension. GLS is designed to work equally well in UNIX, Windows, and other environments. GLS can be used in a variety of situations, for example: * GL command streams for resolution-independent storage, interchange, viewing, and printing of pictures * GL command files for persistent storage of textures, display lists, images, and so on * GL trace streams for debuggers, performance analyzers, and simulators * GL test-vector streams that test correctness of GL implementations * Transfer of GL commands between application processes via byte- stream connections * Client-side display lists that can contain client callbacks Some of these applications 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 encoding and decoding services in such a way that higher-level services can efficiently be built on top of it. GLS Encodings Each of the GLS encodings (human-readable text, big-endian binary, and little-endian binary) can represent all GL commands, without exception. This includes "get" commands that return data to the GL client and other commands that are not allowed in GL display lists. If a GL command has both a scalar form (for example glColor3f()) and a vector form (for example, 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", that is, they can be represented in GLS streams. These GLS commands make it possible to encode various kinds of non-GL data in GLS streams. The binary encodings represent most commands as 16 bits of opcode, followed by 16 bits of byte-count, followed by zero or more 32-bit words of argument data. An alternate encoding is used for opcodes larger than 65535 and commands that require more than 65535 bytes to encode. The text encoding looks like C source code, except that array arguments are represented as lists of elements delimited by braces. Enumerants are represented symbolically. Here's an example of a GLS text stream: glsBeginGLS(1, 0); # arguments are major, minor GLS version glClear(GL_DEPTH_BUFFER_BIT | GL_COLOR_BUFFER_BIT); glBegin(GL_POINTS); glVertex3fv({1.2, 3.4, 5.6}); glEnd(); glsEndGLS(); 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 GLS encoding. GLS API This section provides a brief overview of the core of the GLS API. It consists of three subsections: "Working with Contexts", "Basic Stream Capture" "Basic Stream and Playback", and "Modifying Stream Capture and Playback". Working with Contexts Like GL, GLS defines a state machine. A GLS context is an instantiation of this state machine. GLS contexts and GL contexts are completely independent. 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 either global, immediate, or encodable. All immediate and encodable commands use the GLS context state. The commands glsGenContext(), glsDeleteContext(), and glsContext() (see below) are global. All other GLS commands described on this page 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 are no-ops, and non-global GLS commands that return a value return zero. * 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. The following functions are available for working with contexts: GLint glsGenContext(void); void glsDeleteContext(GLint inContext); void glsContext(GLint inContext); /* set thread's current GLS context */ Basic Stream Capture For basic stream capture, call glsBeginCapture(). Between a glsBeginCapture() command and the following glsEndCapture() command, the current GLS context is in capture mode. In capture mode, all commands are captured instead of executed: * All GL commands are captured by GLS instead of being sent directly to GL and executed. * All encodable GLS commands are 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 currently open GLS stream. glsBeginCapture() and glsEndCapture() have the following prototypes: GLboolean glsBeginCapture( const GLSchar *inStreamName, GLSenum inStreamType, GLint inWriteFlags ); void glsEndCapture(void); The inStreamType argument to glsBeginCapture() is 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 */ The inWriteFlags argument to glsBeginCapture() is a mask. Zero or more attributes can be OR'ed together to set various options: GLS_WRITE_APPEND_BIT /* if stream exists, don't truncate */ GLS_WRITE_BARE_BIT /* don't encode glsBeginGLS/glsEndGLS */ Here's how the different values for inStreamType affect the capture process: * If inStreamType is GLS_CONTEXT, glsBeginCapture() opens 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_LSB_FIRST, GLS_BINARY_MSB_FIRST, 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. Use glsWritePrefix() to replace the value of the write-prefix string. See "Modifying Stream Capture and Playback" below. * If inStreamType is GLS_BINARY_LSB_FIRST, GLS_BINARY_MSB_FIRST, or GLS_TEXT, and inStreamName is not the empty string (""), the command glsBeginCapture() uses the standard C library command fopen() to create a write channel of type FILE*. * If inStreamType is GLS_BINARY_LSB_FIRST, GLS_BINARY_MSB_FIRST, or GLS_TEXT, and inStreamName is the empty string, and the GLS client has used the command glsWriteFunc() specify a write callback function, that function is used in place of the standard C library function fwrite() to write bytes to the stream. * If inStreamType is GLS_BINARY_LSB_FIRST, GLS_BINARY_MSB_FIRST, or GLS_TEXT, and inStreamName is the empty string, and if glsWriteFunc() is not defined, glsBeginCapture() uses a default write channel of type FILE* that is stored in the current GLS context (initial value: stdout). In that case, use glsChannel() to replace the value of the default write channel. See "Modifying Stream Capture and Playback" below. Basic Stream Playback glsCallStream() decodes a named GLS stream (which may be in any GLS 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. GLSenum glsCallStream(const GLSchar *inStreamName); What happens when you call glsCallStream() depends on the value of inStreamName and other factors: * If inStreamName is the name of a GLS_CONTEXT in-memory stream stored in the current GLS context, glsCallStream() decodes 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 last name in the sequence is formed by appending inStreamName to the write-prefix string. Use the commands glsAppendReadPrefix() and glsPrependReadPrefix() to modify the contents of the read-prefix string list. See "Modifying Stream Capture and Playback" for more information. Beginning with the first potential external stream name, glsCallStream() tries each successive name until either a readable stream is found or all of the names have been tried. For each name, the command fopen() is issued with the name as an argument, in an attempt to create a read channel of type FILE*. * If inStreamName is the empty string, the command glsCallStream() uses a default read channel of type FILE* that is stored in the current GLS context (initial value: stdin). Use command glsChannel() (see "Modifying Capture and Playback") 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 is used in place of the standard C library function fread() when bytes are to be read from the stream. The command glsCallStream() is encodable. When a GLS decoder reads this command from a GLS stream, the decoder recursively decodes the GLS 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. Modifying Capture and Playback You can modify stream capture and playback in several ways, all discussed in more detail below: * Call glsCaptureFlags() to specify the destination of a command. * Call glsCommandFunc() to register a callback function. * Call glsAppendReadPrefix() or glsPrependReadPrefix() to modify the read prefix string list. * Call glsWritePrefix() to replace the value of the write prefix string. * Call glsChannel() to replace the value of the default write channel glsCaptureFlags() allows a GLS client to specify on a per-opcode basis whether a captured GL or encodable GLS command is written to the open stream and/or executed by GL or GLS. void glsCaptureFlags(GLSopcode inOpcode, GLint inFlags); A GLS context contains the following capture-mode control bits for each opcode, set with the inFlags parameter: GLS_CAPTURE_WRITE_BIT /* write command to open stream */ GLS_CAPTURE_EXECUTE_BIT /* execute command */ glsCommandFunc() registers the client callback function inFunc for the GL or encodable GLS command designated by inOpcode. There are two types of callback function: GLS_CALL_FUNC and GLS_CAPTURE_FUNC. The parameter inAttrib identifies the type of function to be registered. When a GLS decoder reads a command from a GLS stream, and a GLS_CALL_FUNC function has been registered for that command, the decoder calls that function instead of issuing the command. When GLS captures a command, and a GLS_CAPTURE_FUNC function has been registered for that command, GLS calls that function instead of the standard GLS capture function for that command. If desired, the callback function may call the standard GLS capture function, which is named GLScapture_<commandname>. void glsCommandFunc(GLSenum inAttrib, GLSopcode inOpcode, GLScommandFunc inFunc); Command arguments are passed to inFunc just as they be passed to the function that implements the GL or GLS command. The function inFunc is free to perform arbitrary computations, including issuing GL and GLS commands. Certain encodable GLS commands are provided for the sole purpose of encoding arrays of arbitrary client data as command arguments in a GLS stream. If a GLS client provides a callback function for one or more of these encodable GLS commands, the client can use GLS_CONTEXT in-memory streams to create client-side display lists that contain client callbacks. This functionality is available in IrisGL but not in core GL. void glsUnsupportedCommand(const GLSchar *inCommand); The GLS encodings and API are designed to handle GL extensions. Extension commands are encoded and decoded in the same way as GL 1.0 commands. Extension opcodes for the binary encodings will be allocated on demand in blocks of 16 from a registry maintained by Silicon Graphics. To guarantee successful interchange of GLS streams, any GLS implementation has to be able to read any GLS stream, even if that stream contains extension commands that are not recognized by that GLS implementation. If a GLS decoder reads a command that it cannot decode from a GLS stream, the decoder issues the encodable GLS command glsUnsupportedCommand(). Use glsCommandFunc() to register a client callback function for the command glsUnsupportedCommand(). glsWritePrefix() lets you replace the value of the write prefix string. The function has the following prototype: void glsWritePrefix (const GLSchar *inPrefix); The write prefix string is appended to inStreamName by glsBeginCapture(). Here's an example of using glsWritePrefix(). This example captures into the file "/usr/tmp/foo.gls glsWritePrefix("/usr/tmp/"); glsBeginCapture("foo.gls"); glBegin(GL_POINTS); glVertex3f(1., 2., 3.); glEnd(); glsEndCapture(); glsAppendReadPrefix() and glsPrependReadPrefix() can be used to change the name given to glsCallStream(). They have the following prototypes: void glsPrependReadPrefix (const GLSchar *inPrefix) void glsAppendReadPrefix (const GLSchar *inPrefix) Here's an example that calls the stream /usr/tmp/foo.gls: glsAppendReadPrefix("/tmp/"); glsAppendReadPrefix("/usr/tmp/"); glsCallStream("foo.gls"); NOTES The GLS API and encodings are subject to change during the OpenGL ARB multivendor standardization process for GLS, which is not yet complete. Due to the multivendor standardization process, the GLS API and binary stream encodings that are supported in this release are NOT compatible with the GLS API and binary stream encodings that were supported in IRIX 6.2. The GLS text stream encoding supported in this release is compatible with the GLS text stream encoding that was supported in IRIX 6.2. To convert an IRIX 6.2 GLS binary stream to the new format, use the utility /usr/sbin/glscat on an IRIX 6.2 system to convert to text format, then use the version of /usr/sbin/glscat in the current release to convert back to binary format: irix6.2> /usr/sbin/glscat -t t < inStream > outStream irix6.X> /usr/sbin/glscat -t b < inStream > outStream IRIX 6.2 applications that use GLS must be recompiled to run with the new version of GLS. Note that the new parameter inAttrib has been added to the command glsCommandFunc. For existing code, the value of inAttrib should be GLS_CALL_FUNC.