.TH INTRO 3P local "Silicon Graphics, Inc."
.PP
The graphics binary interface manual pages describe the collection of macros in
gbi.h that build the graphics display list.
.SH NAME
.upperok
gbi \- Graphics Binary Interface
.SH g*, gs* Macros
.PP
The gbi interface is a collection of 64-bit commands that
are interpreted by either the geometry engine of the RSP
or the RDP hardware directly. The macros that are presented
as an API, are really just a convenient tool for packing
the bitstream of the actual gbi.
.PP
There are two macros for each command (g* and gs* macros).  The gs*
macros represent the graphics static macros.  These macros are used to
define the static graphics display list using initialized C data
structures.
.PP
The g* macros are for display list construction at runtime.  The g*
macros have a display list pointer as the first argument follow by the
identical arguments as the gs* macros. This display list pointer
should always be of the form
.I glistp++. 
For macros that produce a single word, the increment
operator moves the pointer to the next free position. Macros
which generate multiple words (expanding into multiple gbi commands)
depend on the convention that the display list pointer is
incremented by the caller.
.PP
There is a third type of macro, gd*. These macros are used for
defining gbi data structures.
.PP
The macros hide many optimizations for the RSP geometry engine.  The
man pages describe these macros as an API for an application program;
someone who wishes a complete understanding of the gbi bitstream (to
program in a language other than C/C++, for example) should really
study the details of all of the macros to determine the precise bit
packing required for each command.
.SH Data Structures
.PP
The predefined gbi data structures force the compiler to ensure the
data is 64 bit aligned.  All of the DMA engines, including the one
inside the RSP that the microcode uses to get the display list,
require 64 bit aligned addresses.