windows-xp/Source/XPSP1/NT/multimedia/opengl/gls/doc/gls.txt

-------------------------------------------------------------------------------
GLS:  Stream encoding for OpenGL commands

Craig Dunwoody
[email protected]
-------------------------------------------------------------------------------

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