Glide provides several functions to initialize Glide and to detect and configure a Voodoo Graphics subsystem.
Two routines,

grSstQueryHardware() and

grSstQueryBoards()

detect the presence of Voodoo Graphics subsystems.

Three functions,

grGlideInit(),

grSstSelect(), and

grSstWinOpen(),

initialize Glide and the hardware and must be called, in the order listed, before calling any other Glide routines (except grSstQueryHardware() and grSstQueryBoards()). Failing to do this will cause the system to operate in an undefined (and, most likely, undesirable) state.

grSstQueryBoards() determines the number of installed Voodoo Graphics subsystems and stores this number in

hwConfig->num_sst.

No other information is stored in the structure at this time:

grSstQueryHardware() can be called after grGlideInit() to fill in t he rest of the structure.

grSstQueryBoards() is the only Glide routine that can be called before grGlideInit();

it does not change the state of any hardware, nor does it render any graphics.

grSstQueryHardware() detects the presence of one or more Voodoo Graphics subsystems and determines how they are configured.It should be called immediately after grGlideInit() but before any other Glide functions.

grSstQueryHardware() returns a Boolean value: FXTRUE indicates that at least one Voodoo Graphics subsystem was found.

The argument, hwConfig, is a pointer to a structure that will be filled in with information about the number and configuration of the Voodoo Graphics subsystems it found. Note that when two Voodoo Graphics subsystems are configured as a single scan-line interleaved system they are viewed by Glide and an application as a single subsystem.

The first initialization function, grGlideInit(), sets up the Glide library and thus must be called before any other Glide functions are executed.
It :

allocates memory,

sets up pointers, and

initializes library variables and counters.

There are no arguments, and no value is returned.

The next function called to initialize the system is grSstSelect(), which makes a specific Voodoo Graphics subsystem “current”.
It must be called AFTER grSstQueryHardware() and grGlideInit() but BEFORE grSstWinOpen().

The argument is the ordinal number of the subsystem that will be made active and must be in the range [0..hwconfig.num_sst] where hwConfig is the structure that holds the system configuration information returned by the preceding call to grSstQueryHardware ().
If whichSST is outside the proper range of values and the debugging version of Glide is used, a run-time error will be generated. If the release version of Glide is loaded, use of an inappropriate value for whichSST will result in undefined behavior.

The final initialization function, grSstWinOpen(), initializes the currently active Voodoo Graphics subsystem, specified by the most recent call to grSstSelect(), to the default state. All hardware special effects (depth buffering, fog, chroma-key, alpha blending, alpha testing, etc.) are disabled. All global state constants (the chroma-key reference value, the alpha test reference, the constant depth value, the constant alpha value, the constant color value, etc.) and pixel rendering statistic counters are initialized to 0.

grSstWinOpen() should be called once per installed Voodoo Graphics subsystem (note that scan-line interleaved subsystems are treated as a single Voodoo Graphics subsystem) and must be executed after grGlideInit(), grSstQueryHardware() and grSstSelect(). It returns FXTRUE if the initialization was successful and FXFALSE otherwise.

The arguments to grSstWinOpen() configure the frame buffer.
The first argument, win, specifies a handle for the window in which the graphics will be displayed. The interpretation of win depends on the system environment. DOS applications must specify NULL. Applications run on SST-1 graphics hardware must specify NULL as well. Win32 full screen applications running on a SST-96 system must specify a window handle; a NULL value for win will cause the application’s real window handle (i.e. what is returned by Microsoft’s GetActiveWindow API) to be used. Since Win32 pure console applications do not have a window handle, they can be used only with SST-1 and a NULL window handle is required. Finally, GlideWin32 applications that run in a window may either specify NULL (if there is only one window), or the correct win, cast to FxU32.

Table  3.1  Specifying a window handle in grSstWinOpen().

The interpretation of the win argument to grSstWinOpen() depends on the system environment, as shown below.

 The screen resolution and refresh rate are specified in the first two arguments, res and refresh. Both variables are given values chosen from enumerated types defined in the sst1vid.h header file. A typical application might set

res to GR_RESOLUTION_640x480 and
refresh to GR_REFRESH_60HZ.
The screen resolution can be specified as GR_RESOLUTION_NONE on an SST-96 system. If so, Glide will use the user specified window (see the hwnd parameter). The ref parameter is ignored when a Win32 application is running in a window. Specifying GR_RESOLUTION_NONE on an SST-1 system will cause the call to fail.

The fourth argument, cFormat , specifies the packed color RGBA ordering in the frame buffer. Different software systems assume different byte ordering formats for pixel color data. For the widest possible compatibility across a wide range of software, Glide provides :

 
“byte swizzling”, meaning that incoming pixels can have their color values interpreted in one of four different formats that are defined in the enumerated type GrColorFormat_t and are shown in Table 3.2.
 
The color format affects data written to the linear frame buffer (the subject of Chapter 11) and parameters for the following Glide functions:
1. grBufferClear() (described later in this chapter),
2. grChromakeyValue() (described in Chapter 8),
3. grConstantColorValue() (see Chapter 5), and
4. grFogColorValue() (see Chapter 8).

Table 3.2 Frame buffer color formats.

Glide supports four different color byte orderings: RGBA, ARGB, BGRA, and ABGR. Color byte ordering determines how linear frame buffer writes and color arguments passed to the constant color functions are interpreted. The first column in the table shows t he name of the format, as defined in the enumerated type GrColorFormat_t. The second column in the table shows the byte ordering of the color components within a 32-bit word.

Color Format	Byte Ordering
GR_COLORFORMAT_RGBA
GR_COLORFORMAT_ARGB
GR_COLORFORMAT_BGRA
GR_COLORFORMAT_ABGR

The fifth parameter to grSstWinOpen() specifies the location of the screen space origin.

If   locateOrigin is

GR_ORIGIN_UPPER_LEFT, the screen space origin is in the upper left corner with positive y going down (a la IBM VGA).

GR_ORIGIN_LOWER_LEFT places the screen space origin at the lower left corner with positive y going up (a la SGI GL).

Figure 3.1 shows the two possibilities for locating the origin.

Figure 3.1 Locating the origin.

The Voodoo Graphics hardware allows the origin to be in the upper left or lower left corner of the screen. The choice of co-ordinate system must be made when first initializing Glide and a Voodoo Graphics subsystem by passing the appropriate parameter to grSstWinOpen().
 

The Voodoo Graphics hardware operates on 32-bit ARGB color values internally. However, these values are eventually dithered to 16-bit RGB (5:6:5) by the hardware. Hardware dithering provides good display quality while at the same time reducing memory consumption by a third, allowing for less expensive hardware implementations.

The final two arguments to grSstWinOpen() select the buffering options.

The first one ,  numBuffers , specifies double or triple buffering and is an integer value, either 2 or 3.

The other argument ,  numAuxBuffers , specifies the number of auxiliary buffers required by an application. The auxiliary buffers are used for depth or alpha buffering. Permitted values are 0 or 1. For full screen applications, this parameter allows both SST-1 and SST-96 to validate whether the available video memory will support the application’s requirements for color and auxiliary buffers at a specified screen resolution. For a windowed application running on SST-96, this parameter allows an application to run in a larger 3D window if a depth buffer is not necessary (depth and back buffers share the same off-screen video memory).

If there is not enough memory to support the desired resolution and buffering options (e.g. 800x600 triple buffered on a 2MB system) then an error will occur.

Example 3.1  The Glide initialization sequence.

This code fragment demonstrates the four Glide functions that must be called, in order, to properly initialize both the software and the hardware subsystems. The parameters to grSstWinOpen() establish a double buffered frame buffer with 640x480 screen resolution and a 60 Hz refresh rate. Colors are stored as RGBA, the origin is in the lower left corner, and there is no auxiliary buffer.