-------------------------------------------------------------------------------
GLS reference implementation (GLSREF) release notes
Craig Dunwoody
dunwoody@sgi.com
-------------------------------------------------------------------------------

GLSREF is a reference implementation of the GLS API.  It is NOT a
sample implementation or a product-quality implementation, and it is
therefore NOT suitable for shipping unmodified to customers as a
product.

The full GLS API specification document is not yet available.  The
primary reason for releasing GLSREF at this time is to allow vendors
to begin the development of product-quality implementations of the GLS
API.

For more details on how to use GLSREF as the starting point in the
development of a product-quality implementation of the GLS API, see
the file doc/porting.txt.

GLSREF has been built and minimally tested on the following platforms:

    ---------------------------------------------------------------------------
    OS                  ISA/ABI     Build environment
    ---------------------------------------------------------------------------
    AIX 3.2.5           IBM-POWER   AIX XL C Compiler/6000 3.2.5

    Digital Unix 3.0    ALPHA       Digital Unix C 3.0

    HP-UX 9.05          PA-RISC     HP-UX C 9.0.5

    IRIX 5.3            MIPS-1      IDO 5.3
    IRIX 5.3            MIPS-1      gcc 2.6.3, IDO 5.3
    IRIX 6.2            MIPS-3/32   IDO 6.2
    IRIX 6.2            MIPS-3/64   IDO 6.2

    Linux 1.1.95        X86         binutils 2.5.21.17,
                                    gcc 2.7.0,
                                    ld.so 1.7.3,
                                    libc 5.0.9

    Solaris 2.4         SPARC       SPARCompiler C 3.0.1

    Windows NT 3.5      ALPHA       SDK 3.5
    Windows NT 3.5      MIPS-1      Visual C++ 2.0, SDK 3.5
    Windows NT 3.5      X86         Visual C++ 2.0, SDK 3.5
    ---------------------------------------------------------------------------

If you need to bring up GLSREF on a platform that is not one of those
listed, see the file doc/porting.txt.

After building and installing the GLS library, commands, and tests,
perform a sanity check by running the following commands:

    cmd/glscat data/1.gls

    test/tcallarr data/1.gls

    test/tcapture

    test/tparser

You should put GLSREF under source code control so you can easily
track your changes and integrate them with future GLSREF releases from
SGI.

-------------------------------------------------------------------------------
File type recognition
-------------------------------------------------------------------------------

On Unix-type platforms, append one of the following two files to /etc/magic:

    filetype/magic.lsb (little-endian systems)
    filetype/magic.msb (big-endian systems)

-------------------------------------------------------------------------------
Known problems
-------------------------------------------------------------------------------

-   The documentation of the GLS API and encodings is quite inadequate.  SGI is
    developing a specification document for the GLS API and encodings, and
    will release this document as soon as possible.

-   There is not yet any documentation on how to extend GLS to support
    vendor-specific GL extensions.  If you need to do this, contact SGI
    to allocate a block of GLS opcodes in the GLS opcode registry that
    SGI maintains.

-   Mutual exclusion and thread local storage are not supported by GLSREF
    on the following platforms:
    
    AIX 3.2.5
    HP-UX 9.05
    IRIX 5.3, 6.2 (GLSREF only; SGI product implementation has full support)
    Linux 1.1.95

    This is due to a lack of adequate support for threads on these platforms.

-   On the AIX 3.2.5 and HP-UX 9.05 platforms, 64-bit integers (types GLlong
    and GLulong) in a GLS_TEXT stream can be parsed only if they appear in
    the hexadecimal form 0xdddddddddddddddd.  This is due to a  lack of
    adequate 64-bit integer support on these platforms, and could be
    remedied by enhancing the 64-bit integer parsing code in GLSREF.

-   On the AIX 3.2.5 and HP-UX 9.05 platforms, 64-bit integers (types GLlong
    and GLulong) in a generated GLS_TEXT stream are always formatted in
    the hexadecimal form 0xdddddddddddddddd, even in cases where the GLS
    spec requires decimal formatting.  This is due to a lack of adequate
    64-bit integer support on these platforms, and could be remedied by
    enhancing the 64-bit integer formatting code in GLSREF.

-------------------------------------------------------------------------------
End
-------------------------------------------------------------------------------