------------------------------------------------------------------------------- GLS: Stream encoding for OpenGL commands Craig Dunwoody dunwoody@sgi.com ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- Introduction ------------------------------------------------------------------------------- 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, differing only in syntax. GLS byte streams can therefore be converted 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 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, 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 byte 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 encoding and decoding services in such a way that higher-level services can efficiently be built on top. ------------------------------------------------------------------------------- Status ------------------------------------------------------------------------------- SGI is developing a GLS specification document for presentation to the GL ARB as a proposed standard for the GL community. As soon as the first draft of this document is complete, SGI will distribute it to all interested parties for comment. SGI has developed GLSREF, a portable ISO C reference implementation of the GLS API. SGI has also developed a simple utility program called glscat that makes it easy to convert a GLS byte stream from one encoding to another. ------------------------------------------------------------------------------- GLS Encodings ------------------------------------------------------------------------------- Each of the GLS encodings is capable of representing all GL commands, without exception. This includes "get" commands that return data to the GL client and all other commands that are not allowed in GL display lists. In addition to GL commands, a subset of the commands in the GLS API are "encodable", meaning that 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 word-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 32-bit words 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. 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. --------------------------------------------------------------------------- GLuint glsGenContext(void); void glsDeleteContext(GLuint inContext); void glsContext(GLuint inContext); /* set thread's current GLS context */ --------------------------------------------------------------------------- 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. 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 GLuint. Each GLS command is classified as either global, immediate, or encodable: --------------------------------------------------------------------------- Category Uses GLS context state Encodable --------------------------------------------------------------------------- Global Immediate X Encodable X 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 are no-ops, and non-global GLS commands that return a value will 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. --------------------------------------------------------------------------- GLboolean glsBeginCapture( const GLubyte *inStreamName, GLSenum inStreamType, GLbitfield 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 currently open GLS stream. inStreamType 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 */ inWriteFlags is 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_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. The command glsWritePrefix() (not described here) can be used to replace the value of the write-prefix string. If inStreamType is GLS_BINARY_LSB_FIRST, GLS_BINARY_MSB_FIRST, or GLS_TEXT, and inStreamName is not the empty string (""), the command glsBeginCapture() will use 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, 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() (not described here) can be used to replace the value of the default write channel. 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() (not described here) to specify a write callback function, that function will be used in place of the standard C library function fwrite() when bytes are to be written to the stream. --------------------------------------------------------------------------- void glsCaptureFlags(GLSopcode inOpcode, GLbitfield inFlags); --------------------------------------------------------------------------- A GLS context contains two capture-mode control bits for each opcode: GLS_CAPTURE_WRITE_BIT /* write command to open stream */ GLS_CAPTURE_EXECUTE_BIT /* execute command */ The command glsCaptureFlags() allows the GLS client to specify on a per-opcode basis whether a captured GL or encodable GLS command should be written to the open stream and/or executed by GL or GLS. --------------------------------------------------------------------------- GLSenum glsCallStream(const GLubyte *inStreamName); --------------------------------------------------------------------------- This command 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. 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 command glsReadPrefix() (not described here) 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 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() will use a default read channel of type FILE* that is stored in the current GLS context (initial value: stdin). The command glsChannel() (not described here) 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() (not described here) to specify a read callback function, that function will be 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. --------------------------------------------------------------------------- void glsCommandFunc(GLSopcode inOpcode, GLScommandFunc inFunc); --------------------------------------------------------------------------- This command registers the client callback function inFunc for the GL or encodable GLS command designated by inOpcode. When a GLS decoder reads this command from a GLS stream, the decoder will call inFunc instead of issuing the command. Command arguments 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. Certain encodable GLS commands (not described here) 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 present in IrisGL but not in core GL. --------------------------------------------------------------------------- void glsUnsupportedCommand(void); --------------------------------------------------------------------------- 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 SGI. To guarantee successful interchange of GLS streams, it is required that any GLS implementation be able to read any GLS stream, even if the GLS stream contains extension commands that are not recognized by the GLS implementation. If a GLS 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 client callback function for the command glsUnsupportedCommand(). ------------------------------------------------------------------------------- Implementation Considerations ------------------------------------------------------------------------------- Platform-specific mechanisms are required to implement the capture of GL commands without compromising immediate-mode GL performance when GLS is not in capture mode. Otherwise, GLSREF is quite portable. ------------------------------------------------------------------------------- End -------------------------------------------------------------------------------