Glide 2.2 Reference Manual

Document Release 015

22 May 1997

Copyright ã 1995-1997 3Dfx Interactive, Inc.

All Rights Reserved

3Dfx Interactive, Inc.

4435 Fortran Drive

San Jose, CA 95134

Introduction

This document is the official programming reference for version 2.0 of 3Dfx Interactive Glide Rasterization Library. The Glide Library is a low-level rendering and state management sub-routine library that serves as a thin layer over the register level int erface of the Voodoo Graphics™ family of graphics hardware. Glide permits easy and efficient implementation of 3D rendering libraries, games, and drivers on the Voodoo Graphics hardware. Glide only implements operations that are natively supported by the V oodoo Graphics family of graphics hardware. Higher level operations are located in the Glide Utility Library, which is currently part of Glide.

Glide serves three primary purposes:

• It relieves programmers from hardware specific issues such as timing, maintaining register shadows, and working with hard-coded register constants and offsets.
• It defines an abstraction of the graphics hardware to facilitate ease of software porting.
• It acts as a delivery vehicle for sample source code providing in-depth optimizations.

By abstracting the low level details of interfacing with the Voodoo Graphics family of graphics hardware into a set of C-callable APIs, Glide allows developers targeting the Voodoo Graphics family of graphics hardware to avoid working with hardware registe rs and memory directly, enabling faster development and lower probability of bugs. Glide also handles mundane and error prone chores, such as initialization and shutdown.

Glide currently consists of Glide APIs as well as Glide Utility APIs. All Glide APIs begin with the gr prefix, all Glide Utility APIs being with the gu prefix. Glide Utility APIs do not directly communicate with hardware registers; they are strictly layere d on Glide APIs. Therefore, their functionality could be performed just as easily by application code. Glide Utility APIs are included in Glide for convenience.

Voodoo Graphics consists of a Pixelfx chip which performs pixel rendering operations and manages the video frame buffer, and one or more Texelfx chips which perform texture mapping operations. Each Texelfx chip contains one Texture Mapping Unit, or TMU. Th e term TMU is used throughout the rest of this manual.

Voodoo Graphics was internally code-named SST-1, or SST for short. Some of the API names, e.g. grSstWinOpen, still reflect the internal code name. In general, Voodoo Graphics is used in the API description, but SST is used in the API names.

Base Types

All 3Dfx Interactive programming libraries use a common set of platform-independent signed and unsigned types. These types can be found in 3dfx.h and are described in the table below:

Predefined Constants

Glide predefines several constants and is also dependent upon several externally defined constants. These are documented in full in glide.h.

API Reference

The following is an API reference that lists the APIs provided by Glide, their purpose, usage, parameters, and notes describing their implementation.

grAADrawLine

Name

grAADrawLine – draw an anti-aliased line segment

C Specification

void grAADrawLine(GrVertex *va, GrVertex *vb)

Parameters

va, vb Vertices describing the line segment.

Description

Glide draws an anti-aliased line segment between the two vertices by setting up the alpha iterator so that it represents pixel coverage. grAlphaCombine must select iterated alpha and grAlphaBlendFunction should select GR_BLEND_SRC_ALPHA, GR_BLEND_ONE_MINUS _SCR_ALPHA as the RGB blend functions and GR_BLEND_ZERO, GR_BLEND_ZERO as the alpha blend functions if sorting from back to front and GR_BLEND_ALPHA_SATURATE, GR_BLEND_ONE as the RGB blend functions and GR_BLEND_SATURATE, GR_BLEND_ONE as the alpha blend fu nctions if sorting from front to back. Opaque anti-aliased primitives must set alpha=255 in the vertex data. Transparent anti-aliased primitives are drawn by setting alpha to values less than 255; this alpha value is multiplied by the pixel coverage to obt ain the final alpha value for alpha blending.

Notes

Resultant lines will be somewhat ‘fatter’ than expected.

See Also

grAADrawPoint, grAADrawTriangle, grAlphaBlendFunction, grAlphaCombine

grAADrawPoint

Name

grAADrawPoint – draw an anti-aliased point

C Specification

void grAADrawPolygon(GrVertex *p)

Parameters

p The point to draw.

Description

Glide draws an anti-aliased point by rendering four pixels and setting up the alpha iterator so that it represents pixel coverage. grAlphaCombine must select iterated alpha and grAlphaBlendFunction should select GR_BLEND_SRC_ALPHA, GR_BLEND_ONE_MINUS_SCR_A LPHA as the RGB blend functions and GR_BLEND_ZERO, GR_BLEND_ZERO as the alpha blend functions if sorting from back to front and GR_BLEND_ALPHA_SATURATE, GR_BLEND_ONE as the RGB blend functions and GR_BLEND_SATURATE, GR_BLEND_ONE as the alpha blend function s if sorting from front to back. Opaque anti-aliased primitives must set alpha=255 in the vertex data. Transparent anti-aliased primitives are drawn by setting alpha to values less than 255; this alpha value is multiplied by the pixel coverage to obtain th e final alpha value for alpha blending.

Notes

See Also

grAADrawLine, grAADrawTriangle, grAlphaBlendFunction, grAlphaCombine

grAADrawPolygon

Name

grAADrawPolygon – draw an anti-aliased convex polygon

C Specification

void grAADrawPolygon(int nVerts, const int ilist[], const GrVertex vlist[])

Parameters

nVerts Number of vertices in the polygon.

ilist Array of indices into vlist.

vlist Array of vertices indexed by ilist.

Description

Glide draws an anti-aliased polygon from an array of vertices and indices into this array.

Notes

See notes on grAADrawTriangle for the limitations of this routine. Further limitations are:

• All exterior polygon edges are anti-aliased
• Only convex polygons are drawn properly.

See Also

grAADrawPolygonVertexList, grAADrawTriangle

grAADrawPolygonVertexList

Name

grAADrawPolygonVertexList – draw an anti-aliased convex polygon

C Specification

void grAADrawPolygonVertexList(int nVerts, const GrVertex vlist[])

Parameters

nVerts Number of vertices in the polygon.

vlist Array of vertices in the polygon.

Description

Glide draws an anti-aliased polygon from an array of vertices.

Notes

See notes on grAADrawTriangle for the limitations of this routine. Further limitations are:

• All exterior polygon edges are anti-aliased.
• Only convex polygons are drawn properly.
• Vertices are drawn in the order presented in vlist[].

See Also

grAADrawPolygon, grAADrawTriangle, grAADrawLine, grAADrawPoint

grAADrawTriangle

Name

grAADrawTriangle – draw an anti-aliased triangle

C Specification

void grAADrawTriangle( GrVertex *a, GrVertex *b, GrVertex *c,
FxBool antialiasAB, FxBool antialiasBC, FxBool antialiasCA)

Parameters

a Vertex a.

b Vertex b.

c Vertex c.

antialiasAB If FXTRUE, anti-alias the AB edge.

antialiasBC If FXTRUE, anti-alias the BC edge.

antialiasCA If FXTRUE, anti-alias the CA edge.

Description

Glide draws a triangle with the specified edges anti-aliased by setting up the alpha iterator so that it represents pixel coverage. grAlphaCombine must select iterated alpha and grAlphaBlendFunction should select GR_BLEND_SRC_ALPHA, GR_BLEND_ONE_MINUS_SCR_ ALPHA as the RGB blend functions and GR_BLEND_ZERO, GR_BLEND_ZERO as the alpha blend functions if sorting from back to front and GR_BLEND_ALPHA_SATURATE, GR_BLEND_ONE as the RGB blend functions and GR_BLEND_SATURATE, GR_BLEND_ONE as the alpha blend functio ns if sorting from front to back. Opaque anti-aliased primitives must set alpha=255 in the vertex data. Transparent anti-aliased primitives are drawn by setting alpha to values less than 255; this alpha value is multiplied by the pixel coverage to obtain t he final alpha value for alpha blending.

Notes

If there is a steep gradient in a particular color space (i.e., green goes from 255.0 to 0.0 in a small number of pixels), then there will be visual anomalies at the edges of the resultant anti-aliased triangle. The workaround for this ‘feature’ is to redu ce the gradient by increasing small color components and decreasing large ones. This can be demonstrated by changing the values of maxColor and minColor in test25 of the Glide distribution. Note that this ‘feature’ is only present when the color combine mo de includes iterated RGB or alpha as one of the parameters in the final color.

See Also

grAADrawLine, grAADrawPoint, grAlphaBlendFunction, grAlphaCombine

grAlphaBlendFunction

Name

grAlphaBlendFunction – specify the alpha blending function

C Specification

void grAlphaBlendFunction( GrAlphaBlendFnc_t rgb_sf,

GrAlphaBlendFnc_t rgb_df,

GrAlphaBlendFnc_t alpha_sf,

GrAlphaBlendFnc_t alpha_df

)

Parameters

rgb_sf Specifies the red, green, and blue source blending factors. Nine symbolic constants are accepted:

rgb_df Specifies the red, green, and blue destination blending factors. Eight symbolic constants are accepted:

alpha_sf Specifies the alpha source blending factor. Nine symbolic constants are accepted:

alpha_df Specifies the alpha destination blending factor. Eight symbolic constants are accepted:

Description

Alpha blending blends the RGBA values for rendered pixels (source) with the RGBA values that are already in the frame buffer (destination). grAlphaBlendFunction defines the operation of blending. rgb_sf and alpha_sf specifies which of nine methods is used to scale the source color and alpha components. rgb_df and alpha_df specifies which of eight methods is used to scale the destination color and alpha components.

Alpha blending is defined by the equations:

where R_s, G_s, B_s, A_s are the source color and alpha components, R_d, G_d, B_d, A_d are the destination color and alpha components, s_R, s_G, s_B s_A are the source blending factors, and d_R, d_G, d_B, d_A are the destination blending factors.

The blending factors are as follows:

where C_s and C_d are the corresponding R_s, G_s, B_s, A_s and R_d, G_d, B_d, A_d components respectively.

To disable alpha blending, call

grAlphaBlendFunction(GR_BLEND_ONE, GR_BLEND_ZERO, GR_BLEND_ONE, GR_BLEND_ZERO)

Notes

The source of incoming alpha and color are determined by grAlphaCombine and grColorCombine respectively.

Alpha blending that requires a destination alpha is mutually exclusive of either depth buffering or triple buffering. Attempting to use GR_BLEND_DST_ALPHA, GR_BLEND_ONE_MINUS_DST_ALPHA, or GR_BLEND_ALPHA_SATURATE when depth buffering or triple buffering ar e enabled will have undefined results.

For alpha source and destination blend function factor parameters, Voodoo Graphics supports only GR_BLEND_ZERO and GR_BLEND_ONE.

See Also

grAADrawLine, grAADrawPoint, grAADrawTriangle, grAlphaCombine, grColorCombine

grAlphaCombine

Name

grAlphaCombine – configure the alpha combine unit

C Specification

void grAlphaCombine( GrCombineFunction_t func,

GrCombineFactor_t factor,

GrCombineLocal_t local,

GrCombineOther_t other,

FxBool invert

)

Parameters

func Specifies the function used in source alpha generation. Valid parameters are described below. The combine function names are prefixed with the string “GR_COMBINE_FUNCTION_”: e.g. GR_COMBINE_FUNCTION_ZERO or GR_COMBINE_FUNCTION_BLEND_LOCAL.

factor Specifies the scaling factor used in alpha generation. Valid parameters are described below:

local Specifies the local alpha used in source alpha generation. Valid parameters are described below:

other Specifies the other alpha used in source alpha generation. Valid parameters are described below:

invert Specifies whether the generated alpha should be bitwise inverted as a final step.

Description

grAlphaCombine configures the alpha combine unit of the graphics subsystem’s hardware pipeline. This provides a low level mechanism for controlling all rendering modes within the hardware without manipulating individual register bits. The alpha combine uni t computes the source alpha for the remainder of the rendering pipeline. The default mode is

grAlphaCombine( GR_COMBINE_FUNCTION_SCALE_OTHER, GR_COMBINE_FACTOR_ONE, GR_COMBINE_LOCAL_NONE, GR_COMBINE_OTHER_CONSTANT, FXFALSE);

The alpha combine unit computes the function specified by the combine function on the inputs specified by the local combine source, other combine source, and the combine scale factor. The result is clamped to [0..255], and then a bitwise inversion may be a pplied, controlled by the invert parameter.

The constant color parameters are the colors passed to grConstantColorValue. If the texture has no alpha component, then texture alpha is 255.

grAlphaCombine also keeps track of required vertex parameters for the rendering routines. GR_COMBINE_FACTOR_NONE, GR_COMBINE_LOCAL_NONE and GR_COMBINE_OTHER_NONE are provided to indicate that no parameters are required. Currently they are the same as GR_CO MBINE_FACTOR_ZERO, GR_COMBINE_LOCAL_CONSTANT, and GR_COMBINE_OTHER_CONSTANT respectively.

Notes

The local alpha value specified by the local parameter and the other alpha value specified by the other parameter are used by the color combine unit.

Inverting the bits in a color is the same as computing (1.0 – color) for floating point color values in the range [0..1] or (255 – color) for 8-bit color values in the range [0..255].

See Also

grColorCombine, grConstantColorValue, grDrawTriangle

grAlphaControlsITRGBLighting

Name

grAlphaControlsITRGBLighting – enables/disables alpha controlled lighting

C Specification

void grAlphaControlsITRGBLighting( FxBool enable )

Parameters

enable Specifies whether the mode is enabled or disabled.

Description

When enabled, the normal color combine controls for local color (C_local) are overridden, and the most significant bit of texture alpha (A_texture) selects between iterated vertex RGB and the constant color set by grConstantColorValue. By default, alpha cont rolled lighting mode is disabled.

Notes

Some possible uses for this mode are self-lit texels and specular paint. If a texture contains texels that represent self-luminous areas, such as windows, then multiplicative lighting can be disabled for these texels as follows. Choose a texture format tha t contains one bit of alpha and set the alpha for each texel to 1 if the texel is self-lit. Set the Glide constant color to white and enabled alpha controlled lighting mode. Finally, set up texture lighting by multiplying the texture color by iterated RGB where iterated RGB is the local color in the color combine unit. When a texel’s alpha is 0, the texture color will be multiplied by the local color which is iterated RGB. This applies lighting to the texture. When a texel’s alpha is 1, the texture color wi ll be multiplied by the Glide constant color which was previously set to white, so no lighting is applied.

If the color combine unit is configured to add iterated RGB to a texture for the purpose of a specular highlight, then texture alpha can be used as specular paint. In this example, the Glide constant color is set to black and iterated RGB iterates the spec ular lighting. If a texel’s alpha is 0, the texture color will be added to iterated RGB, and specular lighting is applied to the texture. If the texel’s alpha is 1, the texture color will be added to the Glide constant color which was previously set to bla ck, so no lighting is applied. The result is that the alpha channel in the texture controls where specular lighting is applied to the texture and specularity can be painted onto the texture in the alpha channel.

See Also

grColorCombine, grConstantColorValue

grAlphaTestFunction

Name

grAlphaTestFunction – specify the alpha test function

C Specification

void grAlphaTestFunction( GrCmpFnc_t function )

Parameters

function The new alpha comparison function.

Description

The alpha test discards pixels depending on the outcome of a comparison between the incoming alpha value and a constant reference value. grAlphaTestFunction specifies the comparison function and grAlphaTestReferenceValue specifies the constant reference va lue.

The incoming alpha value is compared to the constant alpha test reference value using the function specified by function. If the comparison passes, the pixel is drawn, conditional on subsequent tests, such as depth buffer and chroma-key. If the comparison fails, the pixel is not drawn. The default function is GR_CMP_ALWAYS.

The comparison functions are as follows:

Alpha testing is performed on all pixel writes, including those resulting from scan conversion of points, lines, and triangles, and from direct linear frame buffer writes. Alpha testing is implicitly disabled during linear frame buffer writes if linear fra me buffer bypass is enabled (see grLfbLock).

Notes

The incoming alpha is the output of the alpha combine unit which is configured with grAlphaCombine.

See Also

grAlphaCombine, grAlphaTestReferenceValue, grLfbLock

grAlphaTestReferenceValue

Name

grAlphaTestReferenceValue – specify the alpha test reference value

C Specification

void grAlphaTestReferenceValue( GrAlpha_t value )

Parameters

value The new alpha test reference value.

Description

The alpha test discards pixels depending on the outcome of a comparison between the pixel’s incoming alpha value and a constant reference value. grAlphaTestFunction specifies the comparison function and grAlphaTestReferenceValue specifies the constant refe rence value. The default reference value is 0x00.

The incoming alpha value is compared to the value using the function specified by grAlphaTestFunction. If the comparison passes, the pixel is drawn, conditional on subsequent tests such as depth buffer and chroma-key. If the comparison fails, the pixel is not drawn.

Alpha testing is performed on all pixel writes, including those resulting from scan conversion of points, lines, and triangles, and from direct linear frame buffer writes. Alpha testing is implicitly disabled during linear frame buffer writes if linear fra me buffer bypass is enabled (see grLfbLock).

Notes

The incoming alpha is the output of the alpha combine unit which is configured with grAlphaCombine.

See Also

grAlphaCombine, grAlphaTestFunction, grLfbLock

grBufferClear

Name

grBufferClear – clear the buffers to the specified values

C Specification

void grBufferClear( GrColor_t color, GrAlpha_t alpha, FxU16 depth )

Parameters

color The color value used for clearing the draw buffer.

alpha The alpha value used for clearing the alpha buffer (ignored if alpha buffering is not enabled, i.e. a destination alpha is not specified in grAlphaBlendFunction).

depth 16-bit unsigned value used for clearing the depth buffer (ignored if depth buffering is not enabled).

Description

Clears the appropriate buffers with the given values. grClipWindow defines the area within the buffer to be cleared. Any buffers that are enabled are cleared by grBufferClear. For example, if depth buffering is enabled, the depth buffer will be cleared. If an application does not want a buffer to be cleared, then it should mask off writes to the buffer using grDepthMask and/or grColorMask as appropriate.

Although color, alpha, and depth parameters are always specified, the parameters actually used will depend on the current configuration of the hardware; the irrelevant parameters are ignored.

The depth parameter can be one of the constants GR_ZDEPTHVALUE_NEAREST, GR_ZDEPTHVALUE_FARTHEST, GR_WDEPTHVALUE_NEAREST, GR_WDEPTHVALUE_FARTHEST, or a direct representation of a value in the depth buffer. In the latter case the value is either a 1/z value (for GR_DEPTHBUFFER_ZBUFFER mode) or a 16-bit floating point format w value (for GR_DEPTHBUFFER_WBUFFER mode). The 16-bit floating point format is described in detail in the Glide Programming Manual.

Notes

A buffer clear fills pixels at twice the rate of triangle rendering, therefore the performance cost of clearing the buffer is half the cost of rendering a rectangle. Clearing buffers is not always necessary and should be avoided if possible. When depth buf fering is disabled and every visible pixel is rendered each frame, simply draw each frame on top of whatever was previously in the frame buffer. When depth buffering is enabled, a sorted background that covers the entire area can be drawn with the depth bu ffer compare function set to GR_CMP_ALWAYS so that all pixel colors and depth values are replaced, and then normal depth buffering can be resumed.

The constants GR_ZDEPTHVALUE_NEAREST and GR_ZDEPTHVALUE_FARTHEST assume that depth values decrease as they get further away from the eye. However, any linear function of 1/z can be used for computing depth buffer values and therefore they can either increa se or decrease with distance from the eye.

See Also

grClipWindow, grColorMask, grDepthMask, grRenderBuffer

grBufferNumPending

Name

grBufferNumPending – return the number of queued buffer swap requests

C Specification

int grBufferNumPending( void )

Parameters

none

Description

Voodoo Graphics has a large command queue located in off-screen memory. When time-consuming commands, such as large triangles or buffer swaps are executing, subsequent commands are placed in a command queue, including buffer swap requests. grBufferNumPendi ng returns the number of queued buffer swap requests. An application typically wants to monitor this value and not get too far ahead of the rendering process.

Notes

The maximum value returned is 7, even though there may be more buffer swap requests in the queue. To minimize rendering latency in response to interactive input, grBufferNumPending should be called in a loop once per frame until the returned value is less than some small number such as 1, 2, or 3.

See Also

grBufferSwap

grBufferSwap

Name

grBufferSwap – exchange front and back buffers

C Specification

void grBufferSwap( int swap_interval )

Parameters

swap_interval The number of vertical retraces to wait before swapping the front and back buffers.

Description

grBufferSwap exchanges the front and back buffers in the graphics subsystem after swap_interval vertical retraces. If the swap_interval is 0, then the buffer swap does not wait for vertical retrace. Otherwise, the buffers are swapped after swap_interval ve rtical retraces. For example, if the monitor frequency is 60 Hz, a swap_interval of 3 results in a maximum frame rate of 20 Hz.

The exchange takes place during the next vertical retrace of the monitor, rather than immediately after grBufferSwap is called. If the application is double buffering, the Voodoo Graphics subsystem will stop rendering and wait until the swap occurs before executing more commands. If the application is triple buffering and the third rendering buffer is available, rendering commands will take place immediately in the third buffer.

Notes

A swap_interval of 0 may result in visual artifacts, such as ‘tearing’, since a buffer swap can occur during the middle of a screen refresh cycle. This setting is very useful in performance monitoring situations, as true rendering performance can be measur ed without including the time buffer swaps spend waiting for vertical retrace.

grBufferSwap waits until there are fewer than 7 pending buffer swap requests in the Voodoo Graphics command FIFO before returning.

See Also

grBufferNumPending

grChromakeyMode

Name

grChromakeyMode – enable/disable hardware chroma-keying

C Specification

void grChromakeyMode( GrChromakeyMode_t mode )

Parameters

mode specifies whether chroma-keying should be enabled or disabled. Valid values are GR_CHROMAKEY_ENABLE and GR_CHROMAKEY_DISABLE.

Description

Enables and disables chroma-keying. When chroma-keying is enabled, color values are compared to a global chroma-key reference value (set by grChromakeyValue). If the pixel’s color is the same as the chroma-key reference value, the pixel is discarded. The c hroma-key comparison takes place before the color combine function. By default, chroma-keying is disabled.

Notes

The chroma-key comparison compares the chroma-key reference value to the other color specified in the configuration of the color combine unit.

See Also

grColorCombine, grChromakeyValue

grChromakeyValue

Name

grChromakeyValue – set the global chroma-key reference value

C Specification

void grChromakeyValue( GrColor_t value )

Parameters

value The new chroma-key reference value.

Description

Sets the global chroma-key reference value as a packed RGBA value. The color format should be in the same format as specified in the cformat parameter to grSstWinOpen.

Notes

The chroma-key comparison compares the chroma-key reference value to the other color specified in the configuration of the color combine unit.

See Also

grColorCombine, grChromakeyMode

grClipWindow

Name

grClipWindow – set the size and location of the hardware clipping window

C Specification

void grClipWindow(FxU32 minx, FxU32 miny, FxU32 maxx, FxU32 maxy )

Parameters

minx The lower x screen coordinate of the clipping window.

miny The lower y screen coordinate of the clipping window.

maxx The upper x screen coordinate of the clipping window.

maxy The upper y screen coordinate of the clipping window.

Description

grClipWindow specifies the hardware clipping window. Any pixels outside the clipping window are rejected. Values are inclusive for minimum x and y values and exclusive for maximum x and y values. The clipping window also specifies the area grBufferClear cl ears.

At startup the default values for the clip window are the full size of the screen, e.g. (0,0,640,480) for 640×480 mode and (0,0,800,600) for 800×600 mode. To disable clipping simply set the size of the clip window to the screen size. The clipping window sh ould not be used for general purpose primitive clipping; since clipped pixels are processed but discarded, proper geometric clipping should be done by the application for best performance. The clipping window should be used to prevent stray pixels that app ear from imprecise geometric clipping. Note that if the pixel pipeline is disabled (see grLfbLock), clipping is not performed on linear frame buffer writes.

Notes

See Also

grBufferClear, grLfbLock

grColorCombine

Name

grColorCombine – configure the color combine unit

C Specification

void grColorCombine( GrCombineFunction_t func,

GrCombineFactor_t factor,

GrCombineLocal_t local,

GrCombineOther_t other,

FxBool invert

)

Parameters

func Specifies the function used in source color generation. Valid parameters are described below:

factor Specifies the scaling factor f used in source color generation. Valid parameters are described below:

local Specifies the local color used in source color generation. Valid parameters are described below:

other Specifies the other color used in source color generation. Valid parameters are described below:

invert Specifies whether the generated source color should be bitwise inverted as a final step.

Description

grColorCombine configures the color combine unit of the Voodoo Graphics subsystem’s hardware pipeline. This provides a low level mechanism for controlling all modes of the color combine unit without manipulating individual register bits.

The color combine unit computes the function specified by the combine function on the inputs specified by the local combine source, other combine source, and the combine scale factor. The result is clamped to [0..255], and then a bitwise inversion may be a pplied, controlled by the invert parameter. The resulting color goes to the alpha and depth units.

The default color combine mode is grColorCombine(GR_COMBINE_FUNCTION_SCALE_OTHER, GR_COMBINE_FACTOR_ONE, GR_COMBINE_LOCAL_ITERATED, GR_COMBINE_OTHER_ITERATED).

GR_COMBINE_LOCAL_CONSTANT and GR_COMBINE_OTHER_CONSTANT select the constant color specified in a previous call to grConstantColorValue. The iterated color selected by GR_COMBINE_LOCAL_ITERATED or GR_COMBINE_OTHER_ITERATED are the red, green, blue, and alph a values associated with a drawing primitive’s vertices.

grColorCombine also keeps track of required vertex parameters for the rendering routines. GR_COMBINE_FACTOR_NONE, GR_COMBINE_LOCAL_NONE and GR_COMBINE_OTHER_NONE are provided to indicate that no parameters are required. Currently they are the same as GR_CO MBINE_FACTOR_ZERO, GR_COMBINE_LOCAL_CONSTANT, and GR_COMBINE_OTHER_CONSTANT respectively.

Notes

In the tables above, A_local is the local alpha value selected by grAlphaCombine and A_other is the other alpha value selected by grAlphaCombine.

Inverting the bits in a color is the same as computing (1.0 – color) for floating point color values in the range [0..1] or (255 – color) for 8-bit color values in the range [0..255].

See Also

grAlphaCombine, grConstantColorValue, grDrawTriangle

grColorMask

Name

grColorMask – enable/disable writing into the color and alpha buffers

C Specification

void grColorMask( FxBool rgb, FxBool alpha )

Parameters

rgb The new color buffer mask.

alpha The new alpha buffer mask.

Description

grColorMask specifies whether the color and/or alpha buffers can or cannot be written to during rendering operations. If rgb is FXFALSE, for example, no change is made to the color buffer regardless of the drawing operation attempted. The alpha parameter i s ignored if depth buffering is enabled since the alpha and depth buffers share memory.

The value of grColorMask is ignored during linear frame buffer writes if the pixel pipeline is disabled (see grLfbLock). The default values are all FXTRUE, indicating that the associated buffers are writable.

Notes

See Also

grBufferClear, grDepthMask, grLfbLock

grConstantColorValue

Name

grConstantColorValue – set the global constant color

C Specification

void grConstantColorValue( GrColor_t color )

Parameters

color The new constant color.

Description

Glide refers to a global constant color in the color combine unit and alpha combine unit if GR_COMBINE_LOCAL_CONSTANT or GR_COMBINE_OTHER_CONSTANT are specified. This constant color is set with grConstantColorValue. The color format should be in the same f ormat as specified in the cformat parameter to grSstWinOpen. The default value is 0xFFFFFFFF.

Notes

See Also

grAlphaCombine, grColorCombine

grCullMode

Name

grCullMode – set the cull mode

C Specification

void grCullMode( GrCullMode_t mode )

Parameters

mode The new culling mode. Valid parameters are GR_CULL_DISABLE, GR_CULL_NEGATIVE, and GR_CULL_POSITIVE.

Description

Specifies the type of backface culling, if any, that Glide performs when rendering a triangle. Glide computes the signed area of a triangle prior to rendering, and the sign of this area can be used for backface culling operations. If the sign of the area m atches the mode, then the triangle is rejected. grCullMode assumes that GR_CULL_POSITIVE corresponds to a counter-clockwise oriented triangle when the origin is GR_ORIGIN_LOWER_LEFT and a clockwise oriented triangle when the origin is GR_ORIGIN_TOP_LEFT.

Notes

grCullMode has no effect on points and lines, but does effect all triangle rendering primitives including polygons.

See Also

grDrawTriangle

grDepthBiasLevel

Name

grDepthBiasLevel – set the depth bias level

C Specification

void grDepthBiasLevel( FxI16 level )

Parameters

level The new depth bias level.

Description

grDepthBiasLevel allows an application to specify a depth bias used when rendering coplanar polygons. Specifically, if two polygons are coplanar but do not share vertices, e.g. a surface detail polygon sits on top of a larger polygon, artifacts such as “po ke through” may result. To remedy such artifacts an application should increment or decrement the depth bias level, as appropriate for the depth buffer mode and function, per coplanar polygon. For left handed coordinate systems where 0x0000 corresponds to “nearest to viewer” and 0xFFFF corresponds “farthest from viewer” depth bias levels should be decremented on successive rendering of coplanar polygons.

Depth biasing is mutually exclusive of linear frame buffer writes.

Notes

In depth buffering modes GR_DEPTHBUFFER_ZBUFFER_COMPARE_TO_BIAS and GR_DEPTHBUFFER_WBUFFER_COMPARE_TO_BIAS, the depth bias level specifies the value to compare depth buffer values against, and is not added to the source depth value when writing to the dept h buffer. See grDepthBufferMode for more information.

See Also

grDepthBufferMode, grDepthMask

grDepthBufferFunction

Name

grDepthBufferFunction – specify the depth buffer comparison function

C Specification

void grDepthBufferFunction( GrCmpFnc_t func )

Parameters

func The new depth comparison function.

Description

grDepthBufferFunction specifies the function used to compare each rendered pixel’s depth value with the depth value present in the depth buffer. The comparison is performed only if depth testing is enabled with grDepthBufferMode. The choice of depth buffer function is typically dependent upon the depth buffer mode currently active.

The valid comparison functions are as follows:

The default comparison function is GR_CMP_LESS.

Notes

See Also

grDepthBufferMode, grDepthMask, grDepthBiasLevel, grLfbConstantDepth

grDepthBufferMode

Name

grDepthBufferMode – set the depth buffering mode

C Specification

void grDepthBufferMode( GrDepthBufferMode_t mode )

Parameters

mode The new depth buffering mode.

Description

grDepthBufferMode specifies the type of depth buffering to be performed. Valid modes are GR_DEPTHBUFFER_DISABLE, GR_DEPTHBUFFER_ZBUFFER, GR_DEPTHBUFFER_WBUFFER, GR_DEPTHBUFFER_ZBUFFER_COMPARE_TO_BIAS, or GR_DEPTHBUFFER_WBUFFER_COMPARE_TO_BIAS. If GR_DEPTHB UFFER_ZBUFFER or GR_DEPTHBUFFER_ZBUFFER_COMPARE_TO_BIAS is selected, then the Voodoo Graphics subsystem will perform 16-bit fixed point z buffering. If GR_DEPTHBUFFER_WBUFFER or GR_DEPTHBUFFER_WBUFFER_COMPARE_TO_BIAS is selected, then the Voodoo Graphics s ubsystem will perform 16-bit floating point w buffering. By default the depth buffer node is GR_DEPTHBUFFER_DISABLE. Refer to the Glide Programming Guide for more information about w and z buffering.

If GR_DEPTHBUFFER_ZBUFFER_COMPARE_TO_BIAS or GR_DEPTHBUFFER_WBUFFER_COMPARE_TO_BIAS is selected, then the bias specified with grDepthBiasLevel is used as a pixel’s depth value for comparison purposes only. Depth buffer values are compared against the depth bias level and if the compare passes and the depth buffer mask is enabled, the pixel’s unbiased depth value is written to the depth buffer. This mode is useful for clearing beneath cockpits and other types of overlays without effecting either the color or depth values for the cockpit or overlay.

Consider the following example: the depth buffer is cleared to 0xFFFF and a cockpit is drawn with a depth value of zero. Next, the scene beneath the cockpit is drawn with depth buffer compare function of GR_CMP_LESS rendering pixels only where the cockpit is not drawn. To clear the color and depth buffers underneath the cockpit without disturbing the cockpit, the area to be cleared is rendered using triangles (not grBufferClear) with the depth bias level set to zero, a depth buffer compare function of GR_CM P_NOTEQUAL and a depth buffer mode of GR_DEPTHBUFFER_ZBUFFER_COMPARE_TO_BIAS or GR_DEPTHBUFFER_WBUFFER_COMPARE_TO_BIAS. All pixels whose previous depth buffer values are not equal to zero will be rendered and the depth buffer will be set to either unbiased z or w depending on the mode. Using this method, the color and depth buffers can be cleared to any desired value beneath a cockpit or overlay without effecting the cockpit or overlay. Or more desirably, sorted background polygons from the scene to be rend ered that cover all of the visible area can be rendered in this mode, saving the time consuming clearing operation. After the depth buffer is cleared beneath the cockpit, the depth buffer mode is returned to either GR_DEPTHBUFFER_ZBUFFER or GR_DEPTHBUFFER_ WBUFFER and the compare function is returned to its normal setting (GR_CMP_LESS in this example). Note that since this mode of clearing is performed using triangle rendering, the fill rate is one half that of a rectangle clear using grBufferClear. In the c ase where sorted background polygons are used to clear underneath the cockpit, this method should always be faster than the alternative of calling grBufferClear and then drawing the background polygons. In the case where background polygons are not used, b oth methods:

1. clearing the buffers with grBufferClear and then repainting the cockpit
2. clearing beneath the cockpit with triangles and not repainting the cockpit

should be compared and the faster method chosen. Avoiding a cockpit repaint is important: cockpits are typically rendered with linear frame buffer writes and while the writes are individually fast, the process can be lengthy if the cockpit covers many pixe ls.

Notes

Since alpha, depth, and triple buffering are mutually exclusive of each other, enabling depth buffering when using either the alpha or triple buffer will have undefined results.

GR_DEPTHBUFFER_ZBUFFER_COMPARE_TO_BIAS and GR_DEPTHBUFFER_WBUFFER_COMPARE_TO_BIAS modes are not available in revision 1 of the Pixelfx chip (use grSstQueryHardware to obtain the revision number).

The Glide 2.1 release was the first release that supported GR_DEPTHBUFFER_ZBUFFER_COMPARE_TO_BIAS and GR_DEPTHBUFFER_WBUFFER_COMPARE_TO_BIAS.

See Also

grDepthBufferFunction, grDepthMask, grDepthBiasLevel, grLfbConstantDepth

grDepthMask

Name

grDepthMask – enable/disable writing into the depth buffer

C Specification

void grDepthMask( FxBool enable )

Parameters

enable The new depth buffer mask.

Description

grDepthMask specifies whether the depth buffer is enabled for writing. If enable is FXFALSE, depth buffer writing is disabled. Otherwise, it is enabled. Initially, depth buffer writing is disabled.

Notes

Since the alpha, depth, and triple buffers share the same memory grDepthMask should be called only if depth buffering is being used.

grDepthMask is ignored during linear frame buffer writes if the pixel pipeline is bypassed (see grLfbLock).

See Also

grBufferClear, grDepthBufferFunction, grDepthBufferMode, grDepthBiasLevel, grLfbConstantDepth, grLfbLock

grDisableAllEffects

Name

grDisableAllEffects – disable all special effects in the Voodoo Graphics subsystem

C Specification

void grDisableAllEffects( void )

Parameters

none

Description

grDisableAllEffects disables all special effects (alpha blending, alpha testing, chroma-keying, fog, depth buffering) in the Voodoo Graphics subsystem with the exception of clipping, dithering, and the color/depth masks. Effects must be re-enabled individu ally.

Notes

See Also

grAlphaBlendFunction, grAlphaTestFunction, grChromakeyMode, grDepthBufferMode, grFogMode

grDitherMode

Name

grDitherMode – sets the dithering mode

C Specification

void grDitherMode( GrDitherMode_t mode )

Parameters

mode The new dithering mode.

Description

grDitherMode selects the form of dithering used when converting 24-bit RGB values to the 16-bit RGB color buffer format. Valid values are GR_DITHER_DISABLE, GR_DITHER_2x2, and GR_DITHER_4x4. GR_DITHER_DISABLE forces a simple truncation, which may result in noticeable banding. GR_DITHER_2x2 uses a 2x2 ordered dither matrix, and GR_DITHER_4x4 uses a 4x4 ordered dither matrix.

The default dithering mode is GR_DITHER_4x4. grDitherMode is not affected by grDisableAllEffects.

Notes

See Also

grDrawLine

Name

grDrawLine – draw a one-pixel-wide arbitrarily oriented line

C Specification

void grDrawLine( const GrVertex *a, const GrVertex *b )

Parameters

a, b Endpoints and attributes of the line.

Description

Renders a one-pixel-wide arbitrarily oriented line with the given endpoints. All current Glide attributes will affect the appearance of the line.

Notes

See Also

grDrawPoint, grDrawTriangle

grDrawPlanarPolygon

Name

grDrawPlanarPolygon – draw a convex planar polygon

C Specification

void grDrawPlanarPolygon( int nVerts, int ilist[], const GrVertex vlist[] )

Parameters

nVerts Number of vertices in the polygon.

ilist Array of indices into vlist.

vlist Array of vertices indexed by ilist.

Description

grDrawPlanarPolygon renders a convex polygon of an arbitrary number of vertices. The polygon’s coordinates and parameters are assumed to be planar, so parameter gradients will be computed only a single time for the entire polygon. It is assumed that the po lygon does not need any form of clipping.

Notes

The convex polygon is triangulated from the first vertex, vlist[ilist[0]].

See Also

grDrawPlanarPolygonVertexList, grDrawPolygon, grDrawTriangle

grDrawPlanarPolygonVertexList

Name

grDrawPlanarPolygonVertexList – draw a convex planar polygon

C Specification

void grDrawPlanarPolygonVertexList( int nVerts, const GrVertex vlist[] )

Parameters

nVerts Number of vertices in the polygon.

vlist Array of vertices in the polygon.

Description

grDrawPlanarPolygonVertexList renders a convex polygon of an arbitrary number of vertices. The polygon’s coordinates and parameters are assumed to be planar, so parameter gradients will be computed only a single time for the entire polygon. It is assumed t hat the polygon does not need any form of clipping.

Notes

The convex polygon is triangulated from the first vertex, vlist[0].

The Glide 2.1 release was the first release that supported grDrawPlanarPolygonVertexList.

See Also

grDrawPlanarPolygon, grDrawPolygon, grDrawTriangle

grDrawPoint

Name

grDrawPoint – draw a point

C Specification

void grDrawPoint( const GrVertex *a )

Parameters

a Location and attributes of the point.

Description

Renders a single point. All current Glide attributes will affect the appearance of the point. If many points need to be rendered to the screen, e.g. a sprite, use linear frame buffer writes instead.

Notes

See Also

grDrawLine, grDrawTriangle, grLfbLock

grDrawPolygon

Name

grDrawPolygon – draw a convex non-planar polygon

C Specification

void grDrawPolygon( int nVerts, int ilist[], const GrVertex vlist[] )

Parameters

nVerts Number of vertices in the polygon.

ilist Array of indices into vlist.

vlist Array of vertices indexed by ilist.

Description

grDrawPolygon renders a convex polygon with an arbitrary number of vertices. The polygon’s coordinates are assumed to be planar and to lie within the clipping window. Parameters need not be planar, and parameter gradients will be computed multiple times ac ross the face of the polygon.

Notes

The convex polygon is triangulated from the first vertex, vlist[ilist[0]].

See Also

grDrawPlanarPolygon, grDrawPolygonVertexList, grDrawTriangle

grDrawPolygonVertexList

Name

grDrawPolygonVertexList – draw a convex non-planar polygon

C Specification

void grDrawPolygonVertexList( int nVerts, const GrVertex vlist[] )

Parameters

nVerts Number of vertices in the polygon.

vlist Array of vertices in the polygon.

Description

grDrawPolygonVertexList renders a convex polygon of an arbitrary number of vertices. The polygon’s coordinates are assumed to be planar and to lie within the clipping window. Parameters need not be planar, and parameter gradients will be computed multiple times across the face of the polygon.

Notes

The convex polygon is triangulated from the first vertex, vlist[0].

See Also

grDrawPlanarPolygon, grDrawPlanarPolygonVertexList, grDrawPolygon, grDrawTriangle

grDrawTriangle

Name

grDrawTriangle – draw a triangle

C Specification

void grDrawTriangle( const GrVertex *a, const GrVertex *b, const GrVertex *c )

Parameters

a, b, c Location and attributes of the vertices defining the triangle.

Description

Renders an arbitrarily oriented triangle. All current Glide attributes will affect the appearance of the triangle. Triangles are rendered with the following filling rules:

1. Zero area triangles render zero pixels.
2. Pixels are rendered if and only if their center lies within the triangle.

A pixel center is within a triangle if it is inside all three of the edges. If a pixel center lies exactly on an edge, it is considered to be inside for the left and horizontal bottom (lower y coordinate) edges and outside for the right and horizontal top (higher y coordinate) edges. If a pixel is outside any edge, it is considered to be outside the triangle.

In the following picture, a pixel whose center is at the intersection of the 8 triangles is rendered only by triangle D. The center pixel lies on a right edge in triangles A, B, E, F, G, and H. In triangle C and H, the pixel lies exactly on a top edge (hig h Y). But triangle D, the pixel lies exactly on the bottom and left edges and is therefore considered to be inside the triangle.

Notes

These filling rules guarantee that perfect meshes will draw every pixel within the mesh once and only once.

See Also

grDrawLine, grDrawPoint, grDrawPolygon

grErrorSetCallback

Name

grErrorSetCallback – install a user-defined error-handler

C Specification

void grErrorSetCallback( void (*function)(const char *string, FxBool fatal) )

Parameters

function Pointer to a function to be called with all future errors.

Description

grErrorSetCallback allows an application to install a callback function to handle error messages generated internally by Glide. The callback function accepts a string describing the error and a flag indicating if the error is fatal or recoverable. grErrorS etCallback is relevant only for the debug build of Glide; the release build of Glide removes all internal parameter validation and error checking, thus the user installed callback will never be called.

Notes

See Also

grFogColorValue

Name

grFogColorValue – set the global fog color

C Specification

void grFogColorValue( GrColor_t value )

Parameters

value The new global fog color.

Description

grFogColorValue specifies the global fog color to be used during fog blending operations. The color format should be in the same format as specified in the cformat parameter to grSstWinOpen.

The fog operation blends the fog color (C_fog) with each rasterized pixel’s color (C_in) using a blending factor f. Factor f is derived either from iterated alpha or a user downloaded fog table based on the pixel’s w component, depending on the current grFog Mode.

The new color is computed as follows:

C_out = f C_fog + (1–f)C_in

Notes

Fog is applied after color combining and before alpha blending.

See Also

grDisableAllEffects, grFogMode, grFogTable

grFogMode

Name

grFogMode – enable/disable per-pixel fog blending operations

C Specification

void grFogMode( GrFogMode_t mode )

Parameters

mode The new fog mode.

Description

grFogMode enables/disables fog blending operations. Valid parameters are GR_FOG_DISABLE, GR_FOG_WITH_ITERATED_ALPHA, and GR_FOG_WITH_TABLE. The fog operation blends the fog color (C_fog) with each rasterized pixel’s color (C_in) using a blending factor f. A value of f = 0 indicates minimum fog density and a value of f = 255 indicates maximum fog density.

The new color is computed as follows:

C_out = f C_fog + (1–f)C_in

Factor f is determined by mode. If mode is GR_FOG_WITH_ITERATED_ALPHA, then f is equal to the integer bits of iterated alpha. If mode is GR_FOG_WITH_TABLE, then f is computed by interpolating between fog table entries, where the fog table is indexed with a floating point representation of the pixel’s w component.

Notes

Fog is applied after color combining and before alpha blending.

See Also

grFogColorValue, grFogTable

grFogTable

Name

grFogTable – download a fog table

C Specification

void grFogTable( const GrFog_t table[GR_FOG_TABLE_SIZE] )

Parameters

table The new fog table.

Description

grFogTable downloads a new table of 8-bit values that are logically viewed as fog opacity values corresponding to various depths. The table entries control the amount of blending between the fog color and the pixel’s color. A value of 0x00 indicates no fog blending and a value of 0xFF indicates complete fog.

The fog operation blends the fog color (C_fog) with each rasterized pixel’s color (C_in) using a blending factor f. Factor f depends upon the most recent call to grFogMode. If the grFogMode is set to GR_FOG_WITH_TABLE, the factor f is computed by interpolati ng between fog table entries, where the fog table is indexed with a floating point representation of the pixel’s w component. The order of the entries within the fog table correspond roughly to their distance from the viewer. The exact world w correspondin g to fog table entry i can be found by calling guFogTableIndexToW(i) or by computing:

pow(2.0,3.0+(double)(i>>2)) / (8-(i&3));

The new color is computed as follows:

C_out = f C_fog + (1–f)C_in

An exponential fog table can be generated by computing (1-e^-kw)*255 where k is the fog density and w is world distance. It is usually best to normalize the fog table so that the last entry is 255.

Notes

The difference between consecutive entries in the fog table must be less than 64.

Fog is applied after color combining and before alpha blending.

There are several Glide Utility APIs for generating fog tables.

See Also

grFogMode, grFogColorValue, guFogTableIndexToW

grGammaCorrectionValue

Name

grGammaCorrectionValue – set the gamma correction value

C Specification

void grGammaCorrectionValue( float value )

Parameters

value The new gamma value.

Description

grGammaCorrectionValue sets the gamma correction value used during video refresh. Gamma is a positive floating point value from 0.0 to 20.0. Typical values are in the range [1.3..2.2]. The default value is 1.0 (i.e. a linear ramp is used).

The displayed RGB value (RGB_gamma) is computed from the RGB value read from the frame buffer (RGB_fb) according to the following equation:

RGB_gamma = [(RGB_fb/255)^1/gamma]*255

Notes

See Also

For more information on gamma correction, refer to [FOLE90].

grGlideGetVersion

Name

grGlideGetVersion – return the version of Glide

C Specification

void grGlideGetVersion( char version[80] )

Parameters

version Character array to receive the text string describing the Glide version.

Description

grGlideGetVersion fills version with a null-terminated text string that describes the Glide version.

Notes

A sample version string is “Glide Version 2.2”.

The Glide 2.1 release was the first release to include grGlideGetVersion.

See Also

grGlideInit

grGlideGetState

Name

grGlideGetState – get the current state of the current Voodoo Graphics subsystem

C Specification

void grGlideGetState( GrState *state )

Parameters

state Pointer to a GrState structure where the state is to be stored.

Description

grGlideGetState makes a copy of the current state of the current Voodoo Graphics subsystem. This allows an application to save the state and then restore it later using grGlideSetState.

Notes

See Also

grGlideSetState

grGlideInit

Name

grGlideInit – initialize the Glide library

C Specification

void grGlideInit( void )

Parameters

none

Description

grGlideInit initializes the Glide library, performing tasks such as finding any installed Voodoo Graphics subsystems, allocating memory, and initializing state variables. grGlideInit must be called before any other Glide routines are called.

Notes

grSstQueryBoards can be called before grGlideInit.

See Also

grGlideGetVersion, grGlideShutdown, grSstWinOpen, grSstQueryBoards, grSstQueryHardware, grSstSelect

grGlideSetState

Name

grGlideSetState – set the state of the currently active Voodoo Graphics subsystem

C Specification

void grGlideSetState( const GrState *state )

Parameters

state Pointer to a GrState structure containing the new state.

Description

grGlideSetState sets the state of the currently active Voodoo Graphics subsystem. This API is typically paired with calls to grGlideGetState so that an application can save and restore the state.

See Also

grGlideGetState

grGlideShutdown

Name

grGlideShutdown – shut down the Glide library

C Specification

void grGlideShutdown( void )

Parameters

none

Description

grGlideShutdown frees up any system resources allocated by Glide, including memory, and interrupt vectors. grGlideShutdown should be called immediately before program termination.

Notes

See Also

grGlideInit

grHints

Name

grHints – informs Glide of special conditions regarding optimizations

C Specification

void grHints( GrHints_t type, FxU32 hintMask )

Parameters

type Specifies the type of hint.

hintMask A bitmask of ORed hints.

Description

grHints informs Glide of special conditions regarding optimizations and operation. Each type of hint controls a different optimization or mode of operation. Hints of a given type are ORed together into a hintMask. The default hintMask is 0x00.

The GR_HINT_STWHINT hint type controls stw parameter optimization. By default, Glide assumes that all w coordinates (oow) in the GrVertex structure are identical, and that all s and t coordinates (sow and tow) are also identical. This greatly reduces the amount of work Glide has to perform when computing gradients for s, t, and w, and transferring data to the graphics hardware. The stw hints alert Glide that specific values in the GrVertex structure are different and that gradients need to be computed for these values.

The stw hints also specify Glide’s source for the parameter values. There is an implicit ordering of TMUs within Glide, starting with TMU0, followed by TMU1, and TMU2. By default, Glide reads s and t coordinates from the GrVertex structure for the first TM U that is active. Whenever s and t coordinates are read they are transmitted to all subsequent TMUs. For example, if texturing is active in TMU1 but not active in TMU0, then s and t coordinates are read from GrVertex.tmuvtx[1] and broadcast to TMU1 and TMU 2. Once s and t coordinates are read, they will not be read again unless a hint is specified. If one of the subsequent units has a unique or different parameter value, then a hint must be used. If a hint is specified, the parameter value will be read again and sent to the specified unit and all other units following it.

The w hints inform Glide where to look for w coordinates. The rule for the w coordinate is very simple: the w coordinate is read from GrVertex.oow and broadcast to all TMUs unless a w hint is specified. If a w hint is specified, then if w buffering or tabl e-based fog is enabled, GrVertex.oow is read and sent to all TMUs first. Then w is read from the GrVertex.tmuvtx[] structure corresponding to the hint and broadcast to all subsequent TMUs.

The tables below describe the values:

The GR_HINT_ALLOW_MIPMAP_DITHER hint type controls whether or not GR_MIPMAP_NEAREST_DITHER mode can be used. If hintMask is zero, then GR_MIPMAP_NEAREST_DITHER mode cannot be enabled with grTexMipMapMode(). This is the default. To allow GR_MIPMAP_NEAREST_D ITHER mode to be used, specify a non-zero hintMask with the hint.

Dithered mipmapping is disabled by default because it can cause a performance loss of 20% to 30% in some cases. And since the presence or absence of mipmap dithering is not very noticeable, it is very hard to determine the cause of the performance loss. Th erefore, Glide disallows this mode by default, but it can be used by calling grHints.

If dithered mipmapping is used, measure performance with and without it. If there is a significant performance difference, don’t use it. The trade-off is that there may be visible mipmap bands, which can be eliminated by using trilinear mipmapping. On mult iple TMU boards this is a one-pass operation, otherwise it requires two passes. Alternatively, dithered mipmapping can be allowed but disabled for most polygons and enabled only for those polygons that require it.

If there is no performance difference with and without dithered mipmapping, but the image quality did not improve with dithered mipmapping, don’t use it. As you enhance or extend your program, you run the risk of creating a situation in which performance l oss due to dithered mipmapping could occur. It is best to selectively enabled dithered mipmapping just for the polygons that require it.

Notes

Since TMU0 is the first functional unit with s and t coordinates, the GR_STWHINT_ST_DIFF_TMU0 hint need never be given.

grSstWinOpen initializes various Glide state variables, including hints. Thus, grHint should be called after grSstWinOpen if you want something other than the default hint settings.

see Also

grDrawLine, grDrawPoint, grDrawTriangle

grLfbConstantAlpha

Name

grLfbConstantAlpha – set the constant alpha value for linear frame buffer writes

C Specification

void grLfbConstantAlpha( GrAlpha_t alpha )

Parameters

alpha The new constant alpha value.

Description

Some linear frame buffer write modes, specifically GR_LFBWRITEMODE_555, GR_LFBWRITEMODE_888, GR_LFBWRITEMODE_555_DEPTH, and GR_LFBWRITEMODE_DEPTH_DEPTH, do not contain alpha information. grLfbConstantAlpha specifies the alpha value for these linear frame b uffer write modes. This alpha value is used if alpha testing and blending operations are performed during linear frame buffer writes. The default constant alpha value is 0xFF.

Notes

If a linear frame buffer format contains alpha information, then the alpha supplied with the linear frame buffer write is used, and the constant alpha value set with grLfbConstantAlpha is ignored.

See Also

grAlphaTestFunction, grAlphaBlendFunction

grLfbConstantDepth

Name

grLfbConstantDepth – set the constant depth value for linear frame buffer writes

C Specification

void grLfbConstantDepth( FxU16 depth )

Parameters

depth The new constant depth value.

Description

Some linear frame buffer write modes, specifically GR_LFBWRITEMODE_555, GR_LFBWRITEMODE_565, GR_LFBWRITEMODE_1555, GR_LFBWRITEMODE_888, GR_LFBWRITEMODE_8888, and GR_LFBWRITEMODE_ALPHA_ALPHA, do not possess depth information. grLfbConstantDepth specifies th e depth value for these linear frame buffer write modes. This depth value is used for depth buffering and fog operations and is assumed to be in a format suitable for the current depth buffering mode. The default constant depth value is 0x00.

Notes

If a linear frame buffer format contains depth information, then the depth supplied with the linear frame buffer write is used, and the constant depth value set with grLfbConstantDepth is ignored.

See Also

grDepthBufferMode, grFogMode

grLfbLock

Name

grLfbLock – lock a frame buffer in preparation for direct linear frame buffer accesses.

C Specification

FxBool grLfbLock( GrLock_t type,

GrBuffer_t buffer,

GrLfbWriteMode_t writeMode,

GrOriginLocation_t origin,

FxBool pixelPipeline,

GrLfbInfo_t *info

)

Parameters

type Lock type.

buffer Buffer to lock.

writeMode Requested destination pixel format.

origin Requested y origin of linear frame buffer.

pixelPipeline If FXTRUE, send linear frame buffer writes through the pixel pipeline.

info Structure to be filled with pointer and stride info.

Description

When a Glide application desires direct access to a color or auxiliary buffer, it must lock that buffer in order to gain access to a pointer to the frame buffer data. This lock may assert a critical code section which effects process scheduling and preclud es the use of GUI debuggers; therefore, time spent doing direct accesses should be minimized and the lock should be released as soon as possible using the grLfbUnlock API. An application may hold multiple simultaneous locks to various buffers, depending on the underlying hardware. Application software should always check the return value of grLfbLock and take into account the possibility that a lock may fail.

A lock type is a bit field created by the bit-wise OR of one read/write flag and an optional idle request flag. The read/write flag can be one of:

The idle request flag can be one of:

An application may attempt to lock any Glide buffer. Currently supported buffer designations are GR_BUFFER_FRONTBUFFER, GR_BUFFER_BACKBUFFER, and GR_BUFFER_AUXBUFFER.

Some 3Dfx hardware supports multiple write formats to the linear frame buffer space. An application may request a particular write format by passing a writeMode argument other than GR_LFBWRITEMODE_ANY. If the destination pixel format specified is not suppo rted on the target hardware, then the lock will fail. Supported pixels formats are:

If the application specifies GR_LFB_WRITEMODE_ANY and the lock succeeds, the destination pixel format will be returned in info.writeMode. This default destination pixel format will always be the pixel format that most closely matches the true pixel storage format in the frame buffer. On Voodoo Graphics and Voodoo Rush, this will always be GR_LFBWRITEMODE_565 for color buffers and GR_LFBWRITEMODE_ZA16 for the auxiliary buffer. The writeMode argument is ignored for read-only locks.

Some 3Dfx hardware supports a user specified y origin for LFB writes. An application may request a particular y origin by passing an origin argument other than GR_ORIGIN_ANY. If the origin specified is not supported on the target hardware, then the lock wi ll fail. If the application specifies GR_ORIGIN_ANY and the lock succeeds, the LFB y origin will be returned in info.origin. The default y origin will always be GR_ORIGIN_UPPER_LEFT for LFB writes. Currently supported y origin values are:

Some 3Dfx hardware allows linear frame buffer writes to be processed through the same set of functions as those pixels generated by the triangle rasterizer. This feature is enabled by passing a value of FXTRUE in the pixelPipeline argument of grLfbLock. If the underlying hardware is incapable of processing pixels through the pixel pipeline, then the lock will fail. When enabled, color, alpha, and depth data from the linear frame buffer write will be processed as if it were generated by the triangle iterator s. If the selected writeMode lacks depth information, then the value is derived from grLfbConstantDepth. If the writeMode lacks alpha information, then the value is derived from grLfbConstantAlpha. Linear frame buffer writes through the pixel pipeline may not be enabled for auxiliary buffer locks. The pixelPipeline argument is ignored for read only locks.

An application may not call any Glide routines other than grLfbLock and grLfbUnlock while any lock is active. Any such calls will result in undefined behavior.

Upon successful completion, the user provided GrLfbInfo_t structure will be filled in with information pertaining to the locked buffer. The GrLfbInfo_t structure is currently defined as:

typedef struct {

int size;

void *lfbPtr;

FxU32 strideInBytes;

GrLfbWriteMode_t writeMode;

GrOriginLocation_t origin;

} GrLfbInfo_t;

The size element must be initialized by the user to the size of the GrLfbInfo_t structure, e.g.:

info.size = sizeof( GrLfbInfo_t );

This size element will be used to provide backward compatibility for future revisions of the API. An unrecognized size will cause the lock to fail. The lfbPtr element is assigned a valid linear pointer to be used for accessing the requested buffer. The str ideInBytes element is assigned the byte distance between scan lines.

Notes

The Glide 2.2 release is the first release to include grLfbLock. The following APIs are obsolete in Glide 2.2: grLfbBegin, grLfbEnd, grLfbGetReadPtr, grLfbGetWritePtr, grLfbBypassMode, grLfbWriteMode, and grLfbOrigin.

See Also

grLfbUnlock, grLfbConstantAlpha, grLfbConstantDepth, grLfbReadRegion, grLfbWriteRegion

grLfbReadRegion

Name

grLfbReadRegion – efficiently copy a pixel rectangle into a linear frame buffer

C Specification

FxBool grLfbReadRegion( GrBuffer_t src_buffer,

FxU32 src_x, FxU32 src_y,

FxU32 src_width, FxU32 src_height,

FxU32 dst_stride, void *dst_data )

Parameters