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

src_buffer Source frame buffer. Valid values are GR_BUFFER_FRONTBUFFER, GR_BUFFER_BACKBUFFER, and GR_BUFFER_AUXBUFFER.

src_x, src_y Source x and y coordinates The y origin is always assumed to be at the upper left.

src_width, src_height Width and height of source rectangle to be copied from the frame buffer.

dst_stride Stride, in bytes, of destination user memory buffer.

dst_data Pointer to destination user memory buffer.

Description

This API copies a rectangle from a region of a frame buffer into a buffer in user memory; this is the only way to read back from the frame buffer on Scanline Interleaved systems.

A src_width by src_height rectangle of pixels is copied from the buffer specified by src_buffer, starting at the location (src_x, src_y). The pixels are copied to user memory starting at dst_data, with a stride in bytes defined by dst_stride.

The frame buffer y origin is always assumed to be at the upper left. The pixel data read will always be 16-bit 565 RGB.

The dst_stride must be greater than or equal to src_width * 2.

Notes

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

See Also

grLfbLock, grLfbUnlock, grLfbConstantAlpha, grLfbConstantDepth, grLfbWriteRegion

grLfbUnlock

Name

grLfbUnlock – unlock a frame buffer previously locked with grLfbLock.

C Specification

FxBool grLfbUnlock( GrLock_t type, GrBuffer_t buffer )

Parameters

type Lock type. Valid values are GR_LFB_READ_ONLY and GR_LFB_WRITE_ONLY.

buffer Buffer to unlock. Valid values are GR_BUFFER_FRONTBUFFER, GR_BUFFER_BACKBUFFER, and GR_BUFFER_AUXBUFFER.

Description

When an 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. When the application has completed its direct access transactions and would like restore 3D an d GUI engine access to the buffer, then it must call grLfbUnlock. It is important to note that after a successful call to grLfbUnlock, accessing the info.lfbPtr used in the grLfbLock call will have undefined results.

An application may not call any Glide routines other than grLfbLock and grLfbUnlock while any lock is active.

Notes

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

See Also

grLfbLock, grLfbConstantAlpha, grLfbConstantDepth

grLfbWriteRegion

Name

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

C Specification

FxBool grLfbWriteRegion( GrBuffer_t dst_buffer,

FxU32 dst_x, FxU32 dst_y,

GrLfbSrcFmt_t src_format,

FxU32 src_width, FxU32 src_height,

FxU32 src_stride, void *src_data

)

Parameters

dst_buffer Destination frame buffer. Valid values are GR_BUFFER_FRONTBUFFER, GR_BUFFER_BACKBUFFER, and GR_BUFFER_AUXBUFFER.

dst_x, dst_y Destination x and y coordinates The y origin is always assumed to be at the upper left.

src_format Format of source image.

src_width, src_height Width and height of source image.

src_stride Stride of source image.

src_data Pointer to image data.

Description

This API copies a rectangle from a region of memory pointed to by src_data into the linear frame buffer as efficiently as possible. The image may be in one of the following source formats:

The src_data pointer must point to the starting pixel of the rectangle to be copied. A rectangle in memory defined by src_width, src_height, and src_stride will be copied into the buffer designated by dst_buffer at the location (dst_x, dst_y). src_stride i s defined as bytes per scan line in the source image.

The frame buffer y origin is always assumed to be at the upper left.

Not all 3Dfx graphics subsystems will support all source image formats. The function will fail if the source format supplied is not supported by the detected 3D hardware.

Notes

The GR_LFB_SRC_FMT_RLE16 format is a two-word format consisting of one 16-bit count word and one 16-bit color word. The count word should be treated as a signed 16-bit integer. Negative values are currently ignored.

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

See Also

grLfbLock, grLfbUnlock, grLfbConstantAlpha, grLfbConstantDepth, grLfbReadRegion

grRenderBuffer

Name

grRenderBuffer – selects the current color buffer for drawing and clearing

C Specification

void grRenderBuffer( GrBuffer_t buffer )

Parameters

buffer Selects the current color buffer. Valid values are GR_BUFFER_FRONTBUFFER and GR_BUFFER_BACKBUFFER.

Description

grRenderBuffer selects the buffer for primitive drawing and buffer clears. The default is GR_BUFFER_BACKBUFFER.

Notes

See Also

grBufferClear, grDrawLine, grDrawPoint, grDrawTriangle

grSstControlMode

Name

grSstControlMode – perform SST-1 and SST-96 control functions

C Specification

FxBool grSstControlMode( GrSstControlMode_t mode)

Parameters

mode The control mode. Valid values are:

Description

grSstControlMode determines whether the VGA display or Voodoo Graphics display is visible, depending on the value of mode. This routine supersedes the now-obsolete grSstPassthru routine and provides the same functionality for SST-1 hardware; additional fun ctionality is provided for windowed SST-96 applications.

The variable, mode, specifies one of four values. The first two values apply to all systems. When GR_CONTROL_ACTIVATE is specified, the Voodoo Graphics frame buffer will be displayed in full screen mode. On SST-96 systems, the video tile is enabled.

If mode is GR_CONTROL_DEACTIVATE, the 2D VGA frame buffer is displayed. On SST-96 systems, the video tile is disabled.

GR_CONTROL_RESIZE is ignored under DOS, SST-1, and SST-96 in full screen mode. For windowed Glide applications, this call resizes the back buffers and auxiliary buffers, and is typically made by Win32 applications in response to WM_SIZE messages. The grSst ControlMode call may fail if there is not enough offscreen video memory to accommodate the resized buffers.

GR_CONTROL_MOVE is ignored under DOS, SST-1, and SST-96 in full screen mode. For windowed Glide applications, this call is used to validate the location and clip region associated with the front buffer when the user moves a window, and is typically made by Win32 applications in response to WM_MOVE messages. This call may fail if underlying DirectDraw implementation fails.

Notes

On SST-1, since the 3D and 3D graphics exist on different devices (and frame buffers), activating or deactivating pass through does not require you repaint either the 2D or 3D graphics. On the SST-96, the application is responsible for repainting the 2D gr aphics or 3D graphics when you use GR_CONTROL_ACTIVATE or GR_CONTROL_DEACTIVATE.

See Also

grSstIdle

Name

grSstIdle – returns when the Voodoo Graphics subsystem is idle

C Specification

void grSstIdle( void )

Parameters

none

Description

grSstIdle returns when the Voodoo Graphics subsystem is no longer busy. The system is busy when either the hardware FIFO is not empty or the graphics engine is busy.

Notes

See Also

grSstStatus

grSstIsBusy

Name

grSstIsBusy – indicates whether or not the Voodoo Graphics subsystem is busy

C Specification

FxBool grSstIsBusy( void )

Parameters

none

Description

grSstIsBusy returns FXTRUE if the Voodoo Graphics subsystem is busy; otherwise, it returns FXFALSE. The system is busy when either the hardware FIFO is not empty or the graphics engine is busy.

Notes

See Also

grSstIdle, grSstStatus, grSstVRetraceOn

grSstOrigin

Name

grSstOrigin – establishes a y origin

C Specification

void grSstOrigin( GrOriginLocation_t origin )

Parameters

origin Specifies the direction of the y coordinate axis. GR_ORIGIN_UPPER_LEFT places the screen space origin at the upper left corner of the screen with positive y going down. GR_ORIGIN_LOWER_LEFT places the screen space origin at the lower left corner of the screen with positive y going up.

Description

grSstOrigin sets the y origin for all triangle operations, fast fill, and clipping rectangles.

Notes

grSstOrigin overrides the y origin specified in grSstWinOpen.

See Also

grSstWinOpen

grSstPerfStats

Name

grSstPerfStats – get pixel rendering statistics

C Specification

void grSstPerfStats( GrSstPerfStats_t *pStats )

Parameters

pStats Pointer to a structure in which the performance statistics will be returned.

Description

The Voodoo Graphics hardware maintains a set of five counters that collect statistics about the fate of pixels as they move through the pixel pipeline. Glide provides access to these counters through the GrSstPerfStats_s structure and grSstPerfStats. The f ollowing information is returned in the structure pointed to by pStats:

All five counters are reset whenever grSstResetPerfStats is called. The hardware counters are only 24-bits wide, so regular calls to grSstResetPerfStats are required to avoid overflow. Alternatively, counter overflows can be detected and accounted for with out calling grSstResetPerfStats.

Notes

In order to account for every pixel counted and saved in pixelsOut, one must use the following equation:

pixelsOut = LFBwritePixels + bufferClearPixels + (pixelsIn – zFuncFail – chromaFail – aFuncFail)

bufferClearPixels represents the number of pixels written as a result of calls to grBufferClear and can be calculated as:

bufferClearPixels = (# of times the buffer was cleared)* (clip window width) * (clip window height)

grSstPerfStats does not wait for the system to be idle, and hence does not include statistics for commands that are still in the FIFO. Call grSstIdle to empty the FIFO.

See Also

grSstResetPerfStats

grSstQueryBoards

Name

grSstQueryBoards – detect and determine the number of 3Dfx Voodoo Graphics subsystems installed in the host system

C Specification

FxBool grSstQueryBoards( GrHwConfiguration *hwConfig )

Parameters

hwConfig points to a GrHwConfiguration structure where the system’s hardware configuration will be stored.

Description

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. grSstQueryBoards may be called before grGlideInit. grSstQueryHardware can be called after grGlideInit to fill in the rest of the structure.

Notes

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

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

See Also

grGlideInit, grSstQueryHardware

grSstQueryHardware

Name

grSstQueryHardware – detect and determine the nature of any 3Dfx Voodoo Graphics subsystems installed in the host system

C Specification

FxBool grSstQueryHardware( GrHwConfiguration *hwConfig )

Parameters

hwConfig points to a GrHwConfiguration structure where the system’s hardware configuration will be stored.

Description

grSstQueryHardware determines the system’s Voodoo Graphics hardware configuration, specifically the number of installed Voodoo Graphics subsystems and each of their hardware configurations (memory, scan line interleaving, etc.). If no Voodoo Graphics hardw are can be found, grSstQueryHardware returns FXFALSE; otherwise it returns FXTRUE.

grSstQueryHardware should be called after grGlideInit and before grSstWinOpen.

The GrHwConfiguration structure is defined as follows:

typedef struct
{
int num_sst;

struct {

GrSstType type; /* Which hardware is it? */

union SstBoard_u {

GrVoodooConfig_t VoodooConfig;

GrSst96Config_t SST96Config;

GrAT3DConfig_t AT3DConfig;

} sstBoard;

} SSTs[MAX_NUM_SST]; /* configuration for each board */
} GrHwConfiguration;

The structure contains mostly information on the configuration of a Voodoo Graphics subsystem. 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 Voodoo Graphi cs. Note that each Voodoo Graphics has its own private state and texture table.

Notes

Refer to glide.h for possible values for hardware types. Current values are:

typedef int GrSstType;
#define GR_SSTTYPE_VOODOO 0
#define GR_SSTTYPE_SST96 1
#define GR_SSTTYPE_AT3D 2

See Also

grGlideInit, grSstWinOpen, grSstQueryBoards, grSstSelect

grSstResetPerfStats

Name

grSstResetPerfStats – reset the pixel statistics counters

C Specification

void grSstResetPerfStats( void )

Parameters

none

Description

grSstResetPerfStats resets the pixel counters to 0x00.

Notes

See Also

grSstPerfStats

grSstScreenHeight

Name

grSstScreenHeight – get the height (in pixels) of an SST screen

C Specification

FxU32 grSstScreenHeight( void )

Parameters

none

Description

grSstScreenHeight returns the height in pixels of the current SST board.

Notes

See Also

grSstWinOpen, grSstSelect

grSstScreenWidth

Name

grSstScreenWidth – get the width (in pixels) of an SST screen

C Specification

FxU32 grSstScreenWidth( void )

Parameters

none

Description

grSstScreenWidth returns the width in pixels of the current SST board.

Notes

See Also

grSstWinOpen, grSstSelect

grSstSelect

Name

grSstSelect – make a Voodoo Graphics subsystem current

C Specification

void grSstSelect( int which_sst )

Parameters

which_sst The ordinal number of the Voodoo Graphics subsystem to make current. This value must be between 0 and the number of installed subsystems returned by grSstQueryHardware.

Description

grSstSelect selects a particular installed Voodoo Graphics subsystem as active. If the value passed is greater than the number of installed Voodoo Graphics subsystems and you are using the debug build of Glide, a run-time error will be generated. If you ar e using the release build of Glide, undefined behavior will result.

Notes

See Also

grSstWinOpen, grSstQueryHardware

grSstStatus

Name

grSstStatus – return the value of the graphics status register

C Specification

FxU32 grSstStatus( void )

Parameters

none

Description

grSstStatus returns the value of the Voodoo Graphics status register. The bits within this register are defined as follows:

Notes

See Also

grSstIdle, grSstIsBusy, grSstSelect, grSstVRetraceOn

grSstVideoLine

Name

grSstVideoLine – returns the current line number of the display beam

C Specification

FxU32 grSstVideoLine( void )

Parameters

none

Description

grSstVideoLine returns the current line number of the display beam. This number is 0 during vertical retrace and increases as the display beam progresses down the screen.

Notes

There are a small number of video lines that are not displayed at the top of the screen; the vertical backporch. Thus, grSstVideoLine returns a small positive number when the display beam is at the top of the screen; as the beam goes off the bottom of the screen, the line number may exceed the number returned by grSstScreenHeight.

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

See Also

grSstStatus, grSstVRetraceOn, grSstScreenHeight

grSstVRetraceOn

Name

grSstVRetraceOn – return FXTRUE if vertical retrace is active

C Specification

FxBool grSstVRetraceOn( void )

Parameters

none

Description

grSstVRetraceOn returns FXTRUE if the monitor is in vertical retrace; otherwise FXFALSE is returned.

Notes

See Also

grSstStatus, grSstVideoLine

grSstWinClose

Name

grSstWinClose – close the graphics display device

C Specification

void grSstWinClose( void )

Parameters

none

Description

grSstWinClose returns the state of Glide to the one following grGlideInit, so that grSstWinOpen can be called with either a different resolution (SST-1 and SST-96), or a different hwnd parameter (SST-96 only).

Notes

See Also

grSstWinOpen, grSstControlMode

grSstWinOpen

Name

grSstWinOpen – opens the graphics display device

C Specification

FxBool grSstWinOpen( FxU32 hwnd,

GrScreenResolution_t res,
GrScreenRefresh_t ref,
GrColorFormat_t cformat,
GrOriginLocation_t org_loc,
int num_buffers,
int num_aux_buffers

)

Parameters

hwnd Specifies a handle to the window. The interpretation of this value 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 hwnd will cause the application’s real window handle (i.e. what is returned by GetActiveWindow) to be used. Since Win32 pure console applications do not have a window handle, they can be used o nly with SST-1 and a NULL window handle is required. Finally, Glide Win32 applications that run in a window may either specify NULL (if there is only one window), or the correct hwnd, cast to FxU32.

res Specifies which screen resolution to use. Refer to sst1vid.h for available video resolutions, e.g., GR_RESOLUTION_640x480 and GR_RESOLUTION_800x600. In addition, the resolution GR_RESOLUTION_NONE is permitted for the SST-96. This signals Glide to use the user specified window (see the hwnd parameter). Specifying GR_RESOLUTION_NONE on an SST-1 system will cause the call to fail.

ref Specifies the refresh rate to use. Refer to sst1vid.h for available video resolutions, e.g., GR_REFRESH_60HZ and GR_REFRESH_72HZ. The ref parameter is ignored when a Win32 application is running in a window (SST-96 systems only).

cformat Specifies the packed color RGBA ordering for linear frame buffer writes and parameters for the following APIs: grBufferClear, grChromakeyValue, grConstantColorValue, and grFogColorValue. The following table illustrates the available formats:

org_loc Specifies the direction of the y coordinate axis. GR_ORIGIN_UPPER_LEFT places the screen space origin at the upper left corner of the screen with positive y going down (a la IBM VGA). GR_ORIGIN_LOWER_LEFT places the screen space origin at the lower left corner of the screen with positive y going up (a la SGI GL).

num_buffers Specifies the number of rendering buffers to use. Supported values 2 (double-buffering) or 3 (triple buffering). If there is not enough memory to support the desired resolution (e.g. 800×600 triple buffered on a 2MB system), an error will occur .

num_aux_buffers Specifies the number of auxiliary buffers required by an application. The auxiliary buffers are used either 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 lar ger 3D window if a depth buffer is not necessary (depth and back buffers share the same off-screen video memory).

Description

grSstWinOpen initializes the graphics to a known state using the given parameters. It supports both SST-1 and SST-96, and either full-screen or windowed operation in the latter. By default all special effects of the hardware (depth buffering, fog, chroma-k ey, alpha blending, alpha testing, etc.) are disabled and must be individually enabled. All global state constants (chroma-key value, alpha test reference, constant depth value, constant alpha value, etc.) and pixel rendering statistic counters are initial ized to 0x00. Upon success, a value of FXTRUE is returned; otherwise a value of FXFALSE is returned. If grSstWinOpen is called on an already open window, FXFALSE will be returned. This routine replaces the obsolete grSstOpen call from previous versions of Glide.

Notes

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

grSstControlMode, grSstQueryHardware, grSstResetPerfStats, grSstWinClose

grTexCalcMemRequired

Name

grTexCalcMemRequired – return the texture memory consumed by a texture

C Specification

FxU32 grTexCalcMemRequired( GrLOD_t smallLod, GrLOD_t largeLod,
GrAspectRatio_t aspect, GrTextureFormat_t format )

Parameters

smallLod The smallest LOD in the mipmap.

largeLod The largest LOD in the mipmap.

aspect Aspect ratio of the mipmap.

format Format of the mipmap.

Description

grTexCalcMemRequired calculates and returns the amount of memory a mipmap of the specified LOD range, aspect ratio, and format requires. Because of the packing requirements of some texture formats the number returned may reflect padding bytes required for the mipmap.

Notes

The value returned includes memory for both the even and odd mipmap levels. In the case where a mipmap is split across two TMUs with the even levels in one TMU and the odd levels in the other TMU, use grTexTextureMemRequired to compute the memory requireme nts of each TMU.

It is possible that memory required for a mipmap is less than the sum of the memory required for its individual mipmap levels. When multiple mipmap levels are packed into one mipmap, they will be loaded into contiguous memory. If the levels are loaded indi vidually, the starting address for each level must be 8-byte aligned.

See Also

grTexTextureMemRequired

grTexClampMode

Name

grTexClampMode – set the texture map clamping/wrapping mode

C Specification

void grTexClampMode( GrChipID_t tmu,
GrTextureClampMode_t sClampMode,
GrTextureClampMode_t tClampMode )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

sClampMode The new mode for the s direction, either GR_TEXTURECLAMP_CLAMP or GR_TEXTURECLAMP_WRAP.

tClampMode The new mode for the t direction, either GR_TEXTURECLAMP_CLAMP or GR_TEXTURECLAMP_WRAP.

Description

grTexClampMode sets the texture mapping clamping/wrapping mode for both the s and t directions. If wrapping is enabled, then texture maps will tile, i.e. values greater than 255 will wrap around to 0. If clamping is enabled, then texture map indices will b e clamped to 0 and 255.

Notes

Both modes should always be set to GR_TEXTURECLAMP_CLAMP for perspectively projected textures.

See Also

grTexSource

grTexCombine

Name

grTexCombine – configure a texture combine unit

C Specification

void grTexCombine( GrChipID_t tmu,
GrCombineFunction_t rgb_function,
GrCombineFactor_t rgb_factor
GrCombineFunction_t alpha_function,
GrCombineFactor_t alpha_factor
FxBool rgb_invert,
FxBool alpha_invert )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

rgb_function Specifies the function used in texture color generation. Valid parameters are described below:

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

alpha_function Specifies the function used in texture alpha generation. Valid parameters are described below:

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

rgb_invert Specifies whether the generated texture color should be bitwise inverted as a final step.

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

Description

grTexCombine configures the color and alpha texture combine units of the Voodoo Graphics hardware pipeline. This provides a low level mechanism for controlling all the modes of the texture combine unit without manipulating individual register bits.

The texture combine unit computes the function specified by the rgb_function and alpha_function combining functions and the rgb_factor and alpha_factor scale factors on the local filtered texel (C_local and A_local) and the filtered texel from the upstream T MU (C_other and A_other). The result is clamped to [0..255], and then a bitwise inversion may be applied, controlled by the rgb_invert and alpha_invert parameters. The final result is then passed downstream, to either another TMU or the Pixelfx chip.

In the rgb_factor and alpha_factor tables, b is the detail blend factor which is computed as a function of LOD. See grTexDetailControl for further information.

grTexCombine also tracks required vertex parameters for the rendering routines. GR_COMBINE_FACTOR_NONE indicates that no parameters are required; it is functionally equivalent to GR_COMBINE_FACTOR_ZERO.

Notes

C_local and A_local are the color components generated by indexing and filtering from the mipmap stored on the selected TMU; C_other and A_other are the incoming color components from the neighboring TMU.

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

The TMU closest to the Pixelfx chip is GR_TMU0. If a TMU exists upstream from GR_TMU0, it is GR_TMU1. If a TMU exists upstream from GR_TMU1, it is GR_TMU2.

See Also

grDrawTriangle, grTexLodBiasValue, grTexDetailControl

grTexDetailControl

Name

grTexDetailControl – set the detail texturing controls

C Specification

void grTexDetailControl( GrChipID_t tmu, int lodBias,
FxU8 detailScale, float detailMax )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

lodBias Controls where the blending between the two textures begins. This value is an LOD bias value in the range [–32.. +31].

detailScale Controls the steepness of the blend. Values are in the range [0..7] are valid. The scale is computed as 2^detailScale.

detailMax Controls the maximum blending that occurs. Values in the range [0.0..1.0] are valid.

Description

Detail texturing refers to the effect where the blend between two textures in a texture combine unit is a function of the LOD calculated for each pixel. grTexDetailControl controls how the detail blending factor, b, is computed from LOD. The lodBias parame ter controls where the blending begins, the detailScale parameter controls the steepness of the blend (how fast the detail pops in), and the detailMax parameter controls the maximum blending that occurs. Detail blending factor b is calculated as

b = min( detailMax, max( 0, (lodBias – LOD) << detailScale ) / 255.0 )

where LOD is the calculated LOD before grTexLodBiasValue is added. The detail blending factor is typically used by calling grTexCombine with an rgb_function of GR_COMBINE_FUNCTION_BLEND and an rgb_factor of GR_COMBINE_FACTOR_DETAIL_FACTOR to compute:

C_out = b*detail_texture + (1 – b)*main_texture

Notes

An LOD of n is calculated when a pixel covers approximately 2²ⁿ texels. For example, when a pixel covers approximately 1 texel, the LOD is 0. When a pixel covers 4 texels, the LOD is 1, and when a pixel covers 16 texels, the LOD is 2.

Detail blending occurs in the downstream TMU. Since the detail texture and main texture typically have very different computed LODs, the detail texturing control settings depend on which texture is in the downstream TMU.

See Also

grTexCombine, grTexLodBiasValue

grTexDownloadMipMap

Name

grTexDownloadMipMap – download a complete mipmap to texture memory

C Specification

void grTexDownloadMipMap( GrChipID_t tmu, FxU32 startAddress,
FxU32 evenOdd, GrTexInfo *info )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

startAddress Offset into texture memory where the texture will be loaded.

evenOdd Which mipmap levels to download. Valid values are GR_MIPMAPLEVELMASK_EVEN, GR_MIPMAPLEVELMASK_ODD, and GR_MIPMAPLEVELMASK_BOTH.

info Format, dimensions, and image data for texture.

description

grTexDownloadMipMap downloads an entire mipmap to an area of texture memory specified by startAddress. Valid values for startAddress must be between the values returned by grTexMinAddress and grTexMaxAddress and must be 8-byte aligned.

Notes

See Also

grTexDownloadMipMapLevel, grTexMinAddress, grTexMaxAddress, grTexTextureMemRequired, grTexSource

grTexDownloadMipMapLevel

Name

grTexDownloadMipMapLevel – download a single mipmap level to texture memory

C Specification

void grTexDownloadMipMapLevel( GrChipID_t tmu, FxU32 startAddress,
GrLOD_t thisLod, GrLOD_t largeLod,
GrAspectRatio_t aspectRatio,
GrTextureFormat_t format,
FxU32 evenOdd, void *data )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

startAddress Offset into texture memory where the texture will be loaded.

thisLod Constant describing LOD to be downloaded.

largeLod Constant describing largest LOD in the complete mipmap of which thisLod is a part.

aspectRatio Constant describing aspect ratio of texture image.

format Constant describing format of color data in texture image.

evenOdd Which mipmap levels to download. Valid values are GR_MIPMAPLEVELMASK_EVEN, GR_MIPMAPLEVELMASK_ODD, and GR_MIPMAPLEVELMASK_BOTH.

data Raw texture image data.

description

grTexDownloadMipMapLevel downloads a single mipmap level to an area of texture memory specified by startAddress.

startAddress must lie between the values returned by grTexMinAddress and grTexMaxAddress and must be 8-byte aligned.

Notes

See Also

grTexDownloadMipMap, grTexDownloadMipMapLevelPartial, grTexMinAddress, grTexMaxAddress, grTexTextureMemRequired, grTexSource

grTexDownloadMipMapLevelPartial

Name

grTexDownloadMipMapLevelPartial – download part of a single mipmap level to texture memory

C Specification

void grTexDownloadMipMapLevelPartial( GrChipID_t tmu, FxU32 startAddress,
GrLOD_t thisLod, GrLOD_t largeLod,
GrAspectRatio_t aspectRatio,
GrTextureFormat_t format,
FxU32 evenOdd, void *data,
int start, int end )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

startAddress Starting offset into texture memory for download.

thisLod Constant describing LOD to be downloaded.

largeLod Constant describing largest LOD in the complete mipmap of which thisLod is a part.

aspectRatio Constant describing aspect ratio of texture image.

format Constant describing format of color data in texture image.

evenOdd Which mipmap levels to download. Valid values are GR_MIPMAPLEVELMASK_EVEN, GR_MIPMAPLEVELMASK_ODD, and GR_MIPMAPLEVELMASK_BOTH.

data Raw texture image data.

start, end Starting and ending rows of the mipmap to download.

description

grTexDownloadMipMapLevelPartial downloads part of a single mipmap level to an area of texture memory specified by startAddress. Valid values for startAddress must be between the values returned by grTexMinAddress and grTexMaxAddress and must be 8-byte alig ned. startAddress should point to the beginning of the mipmap even if the starting row to be downloaded is not the first row in the texture.

Notes

To download one row of the texture, use the same value for start and end.

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

See Also

grTexDownloadMipMap, grTexDownloadMipMapLevel, grTexMinAddress, grTexMaxAddress, grTexTextureMemRequired, grTexSource

grTexDownloadTable

Name

grTexDownloadTable – download an NCC table or color palette

C Specification

void grTexDownloadTable( GrChipID_t tmu, GrTexTable_t type, void *data )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

type Type of texture table. The valid values are:
GR_TEX_NCC0 - Narrow-channel compression table 0
GR_TEX_NCC1 - Narrow-channel compression table 1
GR_TEX_PALETTE - 256 entry color palette

data Table data, either of type GuNccTable or GuTexPalette.

description

grTexDownloadTable downloads either an NCC table or a 256-entry color palette to a TMU. There are two NCC tables and one color palette on each TMU. The color palette is referenced when rendering texture formats GR_TEXFMT_P_8 or GR_TEXFMT_AP_88. One of two NCC tables is used when decompressing texture formats GR_TEXFMT_YIQ_422 or GR_TEXFMT_AYIQ_8422. Which NCC table is used for decompression is specified by grTexNCCTable.

Notes

grTexSource does not download a texture’s table - this must be done separately using grTexDownloadTable.

grTexDownloadTable does not download an NCC table if the table address is the same as the last table downloaded. Therefore, if the table’s data has changed, it must be copied to a new address before downloading.

See Also

grTexDownloadTablePartial, grTexNCCTable, grTexSource

grTexDownloadTablePartial

Name

grTexDownloadTablePartial – download a subset of an NCC table or color palette

C Specification

void grTexDownloadTablePartial( GrChipID_t tmu, GrTexTable_t type, void *data,
int start, int end )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

type Type of texture table. Valid values are:
GR_TEX_NCC0 - Narrow-channel compression table 0
GR_TEX_NCC1 - Narrow-channel compression table 1
GR_TEX_PALETTE - 256 entry color palette

data Table data, either of type GuNccTable or GuTexPalette.

start, end Starting and ending entries to download.

description

grTexDownloadTablePartial downloads part of an NCC table or a 256-entry color palette to a TMU. Entries from start up to and including end are downloaded. There are two NCC tables and one color palette on each TMU. The color palette is referenced when rend ering texture formats GR_TEXFMT_P_8 or GR_TEXFMT_AP_88. One of two NCC tables is used when decompressing texture formats GR_TEXFMT_YIQ_422 or GR_TEXFMT_AYIQ_8422. Use grTexNCCTable to select one of the two NCC tables.

Notes

To download one entry, use the same value for start and end.

Partial downloads of NCC tables is not supported at this time.

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

See Also

grTexDownloadTablePartial, grTexNCCTable, grTexSource

grTexFilterMode

Name

grTexFilterMode – specify the texture minification and magnification filters

C Specification

void grTexFilterMode( GrChipID_t tmu,
GrTextureFilterMode_t minFilterMode,
GrTextureFilterMode_t magFilterMode )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

minFilterMode The minification filter, either GR_TEXTUREFILTER_POINT_SAMPLED or GR_TEXTUREFILTER_BILINEAR.

magFilterMode The magnification filter, either GR_TEXTUREFILTER_POINT_SAMPLED or GR_TEXTUREFILTER_BILINEAR.

Description

grTexFilterMode specifies the texture filters for minification and magnification. The magnification filter is used when the LOD calculated for a pixel indicates that the pixel covers less than one texel. Otherwise, the minification filter is used.

Notes

See Also

grTexSource

grTexLodBiasValue

Name

grTexLodBiasValue – set the LOD bias value

C Specification

void grTexLodBiasValue( GrChipID_t tmu, float bias )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

bias The new LOD bias value, a signed floating point value in the range [-8..7.75].

Description

grTexLodBiasValue changes the current LOD bias value, which allows an application to maintain fine grain control over the effects of mipmapping, specifically when mipmap levels change. The LOD bias value is added to the LOD calculated for a pixel and the r esult determines which mipmap level to use. Smaller LOD values make increasingly sharper images which may suffer from aliasing and moirè effects. Larger LOD values make increasingly smooth images which may suffer from becoming too blurry. The default LOD b ias value is 0.0.

During some special effects, an LOD bias may help image quality. If an application is not performing texture mapping with trilinear filtering or dithered mipmapping, then an LOD bias of 0.5 generally improves image quality by rounding to the nearest LOD. I f an application is performing dithered mipmapping (i.e. grTexMipMapMode is GR_MIPMAP_NEAREST_DITHER), then an LOD bias of 0.0 or 0.25 generally improves image quality. An LOD bias value of 0.0 is usually best with trilinear filtering.

Notes

The bias parameter is rounded to the nearest quarter increment.

See Also

grTexSource

grTexMinAddress

Name

grTexMinAddress – return the lowest start address for texture downloads

C Specification

FxU32 grTexMinAddress( GrChipID_t tmu )

Parameters

tmu Texture Mapping Unit to query. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

description

grTexMinAddress returns the lower bound on texture memory addresses for a specific TMU.

Notes

See Also

grTexMaxAddress, grTexDownloadMipMap, grTexDownloadMipMapLevel, grTexSource

grTexMaxAddress

Name

grTexMaxAddress – return the highest start address for texture downloads

C Specification

FxU32 grTexMaxAddress( GrChipID_t tmu )

Parameters

tmu Texture Mapping Unit to query. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

description

grTexMaxAddress returns the upper bound on texture memory addresses for a specific TMU.

Notes

The returned address is the highest valid texture start address and is valid only for the smallest mipmap level GR_LOD_1.

See Also

grTexMinAddress, grTexDownloadMipMap, grTexDownloadMipMapLevel, grTexSource

grTexMipMapMode

Name

grTexMipMapMode – set the mipmapping mode

C Specification

void grTexMipMapMode( GrChipID_t tmu, GrMipMapMode_t mode, FxBool lodBlend )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

mode The new mipmapping mode. Valid values are GR_MIPMAP_DISABLE, GR_MIPMAP_NEAREST, and GR_MIPMAP_NEAREST_DITHER.

lodBlend FXTRUE enables blending between levels of detail when doing trilinear mipmapping. FXFALSE disables LOD blending.

Description

grTexMipMapMode sets the mipmapping mode for the Voodoo Graphics hardware. The Voodoo Graphics hardware performs mipmapping with no performance penalty. Either no mipmapping, nearest mipmapping, or nearest dithered mipmapping can be performed. Nearest mipm apping (GR_MIPMAP_NEAREST) selects the nearest mipmap based on LOD. Dithered nearest mipmapping (GR_MIPMAP_NEAREST_DITHERED) dithers between adjacent mipmap levels to reduce the effects of mipmap banding but without the cost of trilinear filtering with LOD blending.

Notes

GR_MIPMAP_NEAREST_DITHERED mode can degrade fill-rate performance by 20-30%. This is not always the case, as it is very application dependent. If this mode is used, performance should be benchmarked to determine the cost of the increased quality.

GR_MIPMAP_NEAREST truncates the LOD calculated for each pixel. To round to the nearest LOD, set the LOD bias value to 0.5 with grTexLodBiasValue.

GR_MIPMAP_NEAREST should be used when lodBlend is FXTRUE.

See Also

grTexLodBiasValue, grTexSource

grTexMultibase

Name

grTexMultibase – enables or disables multibase addressing

C Specification

void grTexMultibase( GrChipID_t tmu, FxBool enable )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

enable FXTRUE enables multibase addressing, FXFALSE disables multibase addressing.

Description

grTexMultibase enables or disables multibase addressing. Normally, mipmap levels are stored sequentially in texture memory. Multibase addressing allows mipmap levels to be loaded into different texture memory locations. Multibase addressing must be enabled before downloading a multibased texture, and before rendering using a multibased texture. Multibase addressing must be disabled before downloading or rendering from a texture with a single base address.

Notes

Use grTexMultibaseAddress to specify the multiple base addresses for a multibased texture.

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

See Also

grTexMultibaseAddress, grTexSource

grTexMultibaseAddress

Name

grTexMultibaseAddress – specify one base address for a multibased texture

C Specification

void grTexMultibaseAddress( GrChipID_t tmu, GrTexBaseRange_t range,
FxU32 startAddress, FxU32 evenOdd, GrTexInfo *info )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

range Which base address to specify. Valid values are GR_TEXBASE_256, GR_TEXBASE_128, GR_TEXBASE_64 and GR_TEXBASE_32_TO_1.

startAddress Starting address in texture memory for texture.

evenOdd Which mipmap levels reside on this TMU for this texture. Valid values are GR_MIPMAPLEVELMASK_EVEN, GR_MIPMAPLEVELMASK_ODD, and GR_MIPMAPLEVELMASK_BOTH.

info Format and dimensions of the texture.

Description

grTexMultibaseAddress specifies one base address for a texture with multiple base addresses. Normally, mipmap levels are stored sequentially in texture memory. Multibase addressing allows mipmap levels to be loaded into different texture memory locations. Four different base addresses are specified for a multibased texture, one for GR_LOD_256, one for GR_LOD_128, one for GR_LOD_64, and one for GR_LOD_32 through GR_LOD_1. In each case, startAddress should point to the texture memory location for the correspo nding mipmap level.

All of the base addresses for a multibased texture should be specified before downloading the texture or rendering from the texture.

Notes

grTexSource does not restore the multiple base addresses for a multibased texture, but does set the base address for mipmap level GR_LOD_256. Therefore, it is not necessary to call grTexMultibaseAddress with a range of GR_TEXBASE_256 after a call to grTexS ource.

If a mipmap does not include some of the larger mipmap levels, then the base addresses associated with these missing levels need not be specified.

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

See Also

grTexMultibase, grTexSource

grTexNCCTable

Name

grTexNCCTable – select an NCC table

C Specification

void grTexNCCTable( GrChipID_t tmu, GrNCCTable_t table )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

table NCC table to use for decompressing compressed textures. Valid values are GR_TEXTABLE_NCC0 and GR_TEXTABLE_NCC1.

description

grTexNCCTable selects one of the two NCC tables on a TMU as the current source for NCC decompression operations. Before rendering operations commence, the appropriate NCC table should be downloaded using grTexDownloadTable.

Notes

See Also

grTexDownloadTable, grTexSource

grTexSource

Name

grTexSource – specify the current texture source for rendering

C Specification

void grTexSource( GrChipID_t tmu, FxU32 startAddress,
FxU32 evenOdd, GrTexInfo *info )

Parameters

tmu Texture Mapping Unit to modify. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

startAddress Starting address in texture memory for texture.

evenOdd Which mipmap levels have been downloaded at startAddress. Valid values are GR_MIPMAPLEVELMASK_EVEN, GR_MIPMAPLEVELMASK_ODD, and GR_MIPMAPLEVELMASK_BOTH.

info Format and dimensions of the new texture.

description

grTexSource sets up the area of texture memory that is to be used as a source for subsequent texture mapping operations. The startAddress specified should be the same as the startAddress argument to grTexDownloadMipMap, or the starting address used for the largest mipmap level when using grTexDownloadMipMapLevel.

Notes

See Also

grTexDownloadMipMap, grTexDownloadMipMapLevel, grTexMinAddress, grTexMaxAddress, grTexTextureMemRequired

grTexTextureMemRequired

Name

grTexTextureMemRequired – return the texture memory consumed by a texture

C Specification

FxU32 grTexTextureMemRequired( FxU32 evenOdd, GrTexInfo *info )

Parameters

evenOdd Which mipmap levels are included: even, odd or both. Valid values are GR_MIPMAPLEVELMASK_EVEN, GR_MIPMAPLEVELMASK_ODD, and GR_MIPMAPLEVELMASK_BOTH.

info Format and dimensions of the texture.

description

grTexTextureMemRequired calculates and returns the number of bytes required to store a given texture. The number returned may be added to the start address for a texture download to determine the next free location in texture memory.

Notes

See Also

grTexCalcMemRequired, grTexDownloadMipMap, grTexDownloadMipMapLevel, grTexMinAddress, grTexMaxAddress, grTexSource

gu3dfGetInfo

Name

gu3dfGetInfo – get information about the mipmap stored in a .3DF file

C Specification

FxBool gu3dfGetInfo( const char *filename, Gu3dfInfo *info )

Parameters

filename Name of the .3DF file.

info Pointer to a Gu3dfInfo structure to fill with information about the mipmap.

Description

gu3dfGetInfo allows an application to determine relevant information about a .3DF file located on disk. The information is assigned to the appropriate member elements of the info structure. The Gu3dfInfo structure is defined in glide.h.

After an application has determined the characteristics of a .3DF mipmap, it is responsible for allocating system memory for the mipmap. This pointer is stored in the info®data pointer and used by gu3dfLoad.

Notes

See Also

gu3dfLoad

gu3dfLoad

Name

gu3dfLoad – load a .3DF file into system memory

C Specification

FxBool gu3dfLoad( const char *filename, Gu3dfInfo *info )

Parameters

filename Name of the file to load.

info Pointer to a Gu3dfInfo structure that gu3dfLoad fills in after loading the file.

Description

gu3dfLoad loads a .3DF file specified by filename into the pointer specified by info®data. gu3dfLoad returns FXTRUE if the file was successfully loaded; otherwise it returns FXFALSE. It is assumed the info structure passed has been appropriately configured with a call to gu3dfGetInfo.

Notes

See Also

gu3dfGetInfo

guAADrawTriangleWithClip

Name

guAADrawTriangleWithClip – performs 2D clipping on triangle, and draws the resultant polygon with anti-aliasing

C Specification

void guAADrawTriangleWithClip( const GrVertex *va, const GrVertex *vb, const GrVertex *vc )

Parameters

va, vb, vc Vertices which specify the triangle.

Description

This routine performs 2D clipping on a triangle, and draws the resultant polygon with grAADrawPolygonVertexList.

Notes

All edges of the triangle are anti-aliased.

See Also

grAADrawTriangle, grAADrawPolygonVertexList, guDrawTriangleWithClip

guAlphaSource

Name

guAlphaSource – configure the alpha combine unit

C Specification

void guAlphaSource( GrAlphaSourceMode_t mode )

Parameters

mode The new alpha combine unit mode.

Description

guAlphaSource is a higher level interface to the Voodoo Graphics alpha combine unit than grAlphaCombine. The alpha combine unit has two configurable inputs and one output. The output of the alpha combine unit gets fed into the alpha testing and blending un its. The selection of the A_local input is important because it is used in the color combine unit.

The following table describes how A_local and output alpha are computed based on the mode:

Notes

Constant color alpha is the value passed to grConstantColorValue.

If texture has no alpha component, texture alpha is 255.

guAlphaSource is a compatibility layer for grAlphaCombine.

See Also

grConstantColorValue, grAlphaCombine, grColorCombine

guColorCombineFunction

Name

guColorCombineFunction – configure the color combine unit

C Specification

void guColorCombineFunction( GrColorCombineFunction_t func )

Parameters

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

Description

guColorCombineFunction configures the Voodoo Graphics subsystem’s hardware pipeline in a fashion dictated by the parameter func. This provides a high level mechanism for controlling common rendering modes without manipulating individual registers within th e hardware. The default color combine function is undefined, so an application must set the color combine function before executing any rendering commands.

GR_COLORCOMBINE_ZERO Forces the output of the color combine unit to always be black (0x00000000).

GR_COLORCOMBINE_ITRGB Uses the iterated RGB values in the GrVertex structure to render a primitive. The effect of this is a smoothly iterated color across the entire face of a triangle.

GR_COLORCOMBINE_DECAL_TEXTURE

Uses the sow and tow values to texture map onto the primitive. The texture color used at each pixel is determined by the value of guTexSource and the current guTexCombineFunction.

GR_COLORCOMBINE_TEXTURE_TIMES_CCRGB

Like GR_COLORCOMBINE_DECAL_TEXTURE, except each texel is multiplied by the constant color value set with grConstantColorValue. This allows for lit flat-shaded texture maps.

GR_COLORCOMBINE_TEXTURE_TIMES_ITRGB

Like GR_COLORCOMBINE_TEXTURE_TIMES_CCRGB, except each texel is multiplied by the current iterated RGB value. This allows for lit Gouraud-shaded texture maps.

GR_COLORCOMBINE_TEXTURE_TIMES_ITRGB_ADD_ALPHA

Like GR_COLORCOMBINE_TEXTURE_TIMES_ITRGB, except that the alpha value is added to the product of the texel and the iterated RGB color. This allows for specular highlights on Gouraud-shaded texture maps.

GR_COLORCOMBINE_TEXTURE_TIMES_ALPHA

Multiplies each texel by alpha (the local alpha within the alpha combine unit).

GR_COLORCOMBINE_TEXTURE_ADD_ITRGB

Like GR_COLORCOMBINE_DECAL_TEXTURE, except that the current iterated RGB value is added to each texel before it is passed down the pixel pipeline.

GR_COLORCOMBINE_TEXTURE_SUB_ITRGB

Like GR_COLORCOMBINE_DECAL_TEXTURE, except that the current iterated RGB value is subtracted from each texel before it is passed down the pixel pipeline.

GR_COLORCOMBINE_CCRGB Uses the color specified by grConstantColorValue to render a primitive. This is useful for flat-shaded primitives. This color combine function requires that a color value be packed into a 32-bit color value (in the format specified by the cformat argument to grSstWinOpen).

GR_COLORCOMBINE_CCRGB_BLEND_ITRGB_ON_TEXALPHA

Uses a blend between grConstantColorValue and the current iterated RGB value as the output color. The amount blended between the two colors is determined by the alpha component for the corresponding pixel in the current texture map. If the current texture map does not have an alpha component, then the alpha value used will be 0xFF.

GR_COLORCOMBINE_DIFF_SPEC_A

Like GR_COLORCOMBINE_TEXTURE_TIMES_ALPHA, except the iterated RGB is also added to the final color. This allows for colored specular highlights to be added to a white lit texture mapped polygon.

GR_COLORCOMBINE_DIFF_SPEC_A

Like GR_COLORCOMBINE_TEXTURE_TIMES_ITRGB, except that alpha is also added to the final color. This allows for white specular highlights to be added to a colored lit texture mapped polygon.

GR_COLORCOMBINE_ONE Forces the color combine unit to always output white (0xFFFFFFFF).

Notes

See Also

grConstantColorValue, grColorCombine, grTexCombine

guDrawTriangleWithClip

Name

guDrawTriangleWithClip – draw a triangle with 2D clipping.

C Specification

void guDrawTriangleWithClip(const GrVertex *va, const GrVertex *vb, const GrVertex *vc )

Parameters

va, vb, vc The three vertices of the triangle.

Description

guDrawTriangleWithClip uses Sutherland-Hodgman clipping [SUTH74] to clip the triangle to the rectangle specified by grClipWindow and then draws the resultant polygon.

Notes

See Also

grDrawTriangle

guFbReadRegion

Name

guFbReadRegion – copy a portion of frame buffer memory to system memory

C Specification

void guFbReadRegion( int src_x, int src_y, int w, int h,
void *dst, const int strideInBytes )

Parameters

src_x, src_y The initial corner of the region to be read. This maps to the lower left corner if the Voodoo Graphics subsystem’s origin mode is GR_ORIGIN_LOWER_LEFT and to the upper left corner if the Voodoo Graphics subsystem’s origin mode is GR_ORIGIN_UPP ER_LEFT.

w, h Width and height of the region to be copied.

dst Pointer where the contents of the frame buffer are to be stored.

strideInBytes The distance (in bytes) from one scan-line of the destination to the next.

Description

guFbReadRegion copies a portion of the buffer selected by grLfbGetReadPtr to system memory. Each pixel will occupy 16-bits of data in the destination buffer. The format of the pixels is 565 RGB for color buffers, the RGB ordering is dependent on the cforma t specified in grSstWinOpen. When reading the alpha buffer, the 8-bit alpha values are located in bits[7:0] of each 16-bit word. When reading the depth buffer, the format is either fixed point z values or floating point w values depending on the depth buff ering mode.

Notes

strideInBytes must be a multiple of 2.

See Also

grDepthBufferMode, grLfbLock, grLfbReadRegion, grSstWinOpen, guFbWriteRegion

guFbWriteRegion

Name

guFbWriteRegion – copy a portion of system memory to frame buffer memory

C Specification

void guFbWriteRegion( int dst_x, int dst_y, int w, int h,
const void *src, const int strideInBytes )

Parameters

dst_x, dst_y The starting corner of the region to be written. This maps to the lower left corner if the Voodoo Graphics subsystem’s origin mode is GR_ORIGIN_LOWER_LEFT and to the upper left if it is GR_ORIGIN_UPPER_LEFT.

w, h Width and height of the region to be written.

src Pointer where the source data for the copy is stored. The format of the source data must be identical to that expected for mode.

strideInBytes The distance (in bytes) from one scan-line of the source to the next.

Description

guFbWriteRegion copies a portion of system memory to frame buffer memory. The memory size and pixel format of copy is dependent on the linear frame buffer write mode set with grLfbWriteMode. The buffer written to is determined by the last call to grLfbGetW ritePtr.

Notes

For 16-bit pixel formats, strideInBytes must be a multiple of 2. For 32-bit pixel formats, strideInBytes must be a multiple of 4.

See Also

grLfbLock, grLfbWriteRegion, guFbReadRegion

guFogGenerateExp

Name

guFogGenerateExp – generate an exponential fog table

C Specification

void guFogGenerateExp( GrFog_t fogTable[GR_FOG_TABLE_SIZE], float density )

Parameters

fogTable The array to receive the generated fog table values.

density The fog density, typically between 0.0 and 1.0.

Description

guFogGenerateExp generates an exponential fog table according to the equation:

e^–density*w

where w is the eye-space w coordinate associated with the fog table entry. The resulting fog table is copied into fogTable.

Notes

The fog table is normalized (scaled) such that the last entry is maximum fog (255).

See Also

grFogMode, grFogTable, guFogGenerateExp2, guFogGenerateLinear, guFogTableIndexToW

guFogGenerateExp2

Name

guFogGenerateExp2 – generate an exponential squared fog table

C Specification

void guFogGenerateExp2( GrFog_t fogTable[GR_FOG_TABLE_SIZE], float density )

Parameters

fogTable The array to receive the generated fog table values.

density The fog density, typically between 0.0 and 1.0.

Description

guFogGenerateExp2 generates an exponential squared fog table according to the equation:

e^{–(density*w)2}

where w is the eye-space w coordinate associated with the fog table entry. The resulting fog table is copied into fogTable.

Notes

The fog table is normalized (scaled) such that the last entry is maximum fog (255).

See Also

grFogMode, grFogTable, guFogGenerateExp, guFogGenerateLinear, guFogTableIndexToW

guFogGenerateLinear

Name

guFogGenerateLinear – generate a linear fog table

C Specification

void guFogGenerateLinear( GrFog_t fogTable[GR_FOG_TABLE_SIZE],
float nearW, float farW )

Parameters

fogTable The array to receive the generated fog table values.

nearW The eye-space w coordinate where minimum fog exists.

farW The eye-space w coordinate where maximum fog exists.

Description

guFogGenerateLinear generates a linear (in eye-space) fog table according to the equation

(w – nearW)/( farW – nearW)

where w is the eye-space w coordinate associated with the fog table entry. The resulting fog table is copied into fogTable.

Notes

The fog table is clamped so that all values are between minimum fog (0) and maximum fog (255).

guFogGenerateLinear fog is linear in eye-space w, not in screen-space.

See Also

grFogMode, grFogTable, guFogGenerateExp, guFogGenerateExp2, guFogTableIndexToW

guFogTableIndexToW

Name

guFogTableIndexToW – convert a fog table index to a floating point eye-space w value

C Specification

float guFogTableIndexToW( int i )

Parameters

i The fog table index, between 0 and GR_FOG_TABLE_SIZE.

Description

guFogTableIndexToW returns the floating point eye-space w value associated with entry i in a fog table. Because fog table entries are non-linear in w, it is not straight forward to initialize a fog table. guFogTableIndexToW assists by converting fog table indices to eye-space w values.

Notes

guFogTableIndexToW returns the following:

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

See Also

grFogMode, grFogTable, guFogGenerateExp, guFogGenerateExp2, guFogGenerateLinear

guTexAllocateMemory

Name

guTexAllocateMemory – allocate texture memory for a mipmap

C Specification

GrMipMapId_t guTexAllocateMemory( GrChipID_t tmu,
FxU8 evenOddMask,
int width, int height,
GrTextureFormat_t format,
GrMipMapMode_t mmMode,
GrLOD_t smallLod, GrLOD_t largeLod,
GrAspectRatio_t aspectRatio,
GrTextureClampMode_t sClampMode,
GrTextureClampMod e_t tClampMode,
GrTextureFilterMode_t minFilterMode,
GrTextureFilterMode_t magFilterMode,
float lodBias,
FxBool lodBlend )

Parameters

tmu Texture Mapping Unit to allocate memory on. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

evenOddMask Selects whether odd levels, even levels, or all levels of the mipmap are downloaded. Valid values are GR_MIPMAPLEVELMASK_EVEN, GR_MIPMAPLEVELMASK_ODD, and GR_MIPMAPLEVELMASK_BOTH.

width, height Width and height of the largest mipmap level.

format Format of the texture. Valid values are GR_TEXFMT_RGB_332, GR_TEXFMT_YIQ_422, GR_TEXFMT_ALPHA_8, GR_TEXFMT_INTENSITY_8, GR_TEXFMT_ALPHA_INTENSITY_44, GR_TEXFMT_RGB_565, GR_TEXFMT_ARGB_8332, GR_TEXFMT_ARGB_1555, GR_TEXFMT_ARGB_4444, GR_TEXFMT_AYIQ_84 22, and GR_TEXFMT_ALPHA_INTENSITY_88.

mmMode Type of mipmapping to be performed when this texture is current. Valid values are GR_MIPMAP_DISABLE, GR_MIPMAP_NEAREST, and GR_MIPMAP_NEAREST_DITHER. This value can be overridden by a call to grTexMipMapMode.

smallLod, largeLod LOD values of the smallest and largest LOD levels in the texture. Valid parameters are GR_LOD_256, GR_LOD_128, GR_LOD_64, GR_LOD_32, GR_LOD_16, GR_LOD_8, GR_LOD_4, GR_LOD_2, and GR_LOD_1. The value in the LOD constant determines the size of the largest side of the texture. A combination of the largeLod parameter and the aspectRatio parameter determines the size of each of the mipmap levels. For example, a mipmap with largeLod of GR_LOD_64 and aspectRatio of GR_ASPECT_8x1 would have a 64×8 texture as its largest LOD. If aspectRatio were GR_ASPECT_1x4, an 16×64 texture would be its largest LOD.

aspectRatio Specifies the aspect ratio of the mipmaps as a factor of width to height. For example, a mipmap 256 texels wide by 128 texels tall has an aspect ratio of GR_ASPECT_2x1. Valid values are GR_ASPECT_8x1, GR_ASPECT_4x1, GR_ASPECT_2x1, GR_ASPECT_1x1 , GR_ASPECT_1x2, GR_ASPECT_1x4, and GR_ASPECT_1x8. A combination of this parameter and the LOD parameter smallLod determines the size of each mipmap level.

sClampMode, tClampMode

Type of texture clamping to be performed when this texture is current. Clamping can be controlled in both the s and t directions. Valid parameters are GR_TEXTURECLAMP_CLAMP or GR_TEXTURECLAMP_WRAP. Note that these parameters should always be set to GR_TEX TURECLAMP_CLAMP for projected textures.

minFilterMode Specifies the type of minification filtering to perform. Valid parameters are GR_TEXTUREFILTER_POINT_SAMPLED and GR_TEXTUREFILTER_BILINEAR

magFilterMode Specifies the type of magnification filtering to perform. Valid parameters are GR_TEXTUREFILTER_POINT_SAMPLED and GR_TEXTUREFILTER_BILINEAR.

lodBias Specifies the LOD bias value in the range [-8..7.75] to be used during mipmapping. Smaller values make increasingly sharper images, larger values make increasingly blurrier images. The lodBias parameter is rounded to the nearest quarter increment. By default the LOD bias is 0.

lodBlend Specifies whether trilinear filtering is to be performed when this texture is current. Trilinear filtering blends between LOD levels based on LOD fraction, eliminating mipmap banding artifacts. Valid parameters are FXTRUE and FXFALSE.

Description

guTexAllocateMemory allocates memory on the specified TMUs and returns a handle to the allocated memory. The amount of memory allocated will be enough to hold a mipmap of the given format, LOD ranges, and aspect ratio. If the texture memory can not be allo cated, a value of GR_NULL_MIPMAP_HANDLE is returned. After the memory has been allocated, individual mipmap levels can be downloaded one at a time using guTexDownloadMipMapLevel, or all mipmaps can be downloaded using guTexDownloadMipMap.

Whenever the texture is specified as a source texture, sClampMode, tClampMode, minFilterMode, magFilterMode, and lodBias will automatically take effect.

evenOddMask is used to selectively download LOD levels when LOD blending is to be used. Correct usage is to allocate and download the even levels onto one TMU, and the odd levels onto another, both with the lodBlend parameter set to FXTRUE. Then the textur e combine mode for the lower numbered TMU is set to GR_TEXTURECOMBINE_TRILINEAR_ODD or GR_TEXTURECOMBINE_TRILINEAR_EVEN depending on whether the odd levels or the even levels were downloaded to it.

Notes

See Also

guTexGetCurrentMipMap, guTexGetMipMapInfo, guTexSource

guTexChangeAttributes

Name

guTexChangeAttributes – change attributes of a mipmap

C Specification

FxBool guTexChangeAttributes( GrMipMapID_t mmid,
int width, int height,
GrTextureFormat_t format,
GrMipMapMode_t mmMode,
GrLOD_t smallLod, GrLOD_t largeLod,
GrAspectRatio_t aspectRatio,
GrTextureClampMode_t sClampMode,
GrTextureClampMode_t tClampMode,
GrTe xtureFilterMode_t minFilterMode,
GrTextureFilterMode_t magFilterMode )

Parameters

mmid Handle of mipmap whose attributes are being changed.

width, height New width and height of the largest mipmap level or –1 if not changed

format New format of the texture or –1 if not changed.

mmMode New type of mipmapping to be performed when this texture is in effect. Valid values are GR_MIPMAP_DISABLE, GR_MIPMAP_NEAREST, and GR_MIPMAP_NEAREST_DITHER. This value can be overridden by a call to grTexMipMapMode.

smallLod, largeLod New LOD values of the smallest and largest LOD levels or –1 if not changed. Valid parameters are GR_LOD_256, GR_LOD_128, GR_LOD_64, GR_LOD_32, GR_LOD_16, GR_LOD_8, GR_LOD_4, GR_LOD_2, and GR_LOD_1. The value of largeLod determines the si ze of the largest side of the texture. A combination of the largeLod parameter and the aspectRatio parameter determines the size of each of the mipmap levels. For example, a mipmap with largeLod of GR_LOD_64 and aspectRatio of GR_ASPECT_8x1 would have a 64 ×8 texture as its largest LOD. If aspectRatio were GR_ASPECT_1x4, an 16×64 texture would be its largest LOD.

aspectRatio New aspect ratio of the mipmap as a factor of width to height or –1 if not changed. For example, a mipmap 256 texels wide by 128 texels tall has an aspect ratio of GR_ASPECT_2x1. Valid values are GR_ASPECT_8x1, GR_ASPECT_4x1, GR_ASPECT_2x1, GR_ ASPECT_1x1, GR_ASPECT_1x2, GR_ASPECT_1x4, and GR_ASPECT_1x8. A combination of this parameter and the LOD parameter smallLod determines the size of each mipmap level.

sClampMode New type of texture clamping to be performed in the s direction or –1 if not changed. Valid parameters are GR_TEXTURECLAMP_CLAMP or GR_TEXTURECLAMP_WRAP.

tClampMode New type of texture clamping to be performed in the t direction or –1 if not changed. Valid parameters are GR_TEXTURECLAMP_CLAMP or GR_TEXTURECLAMP_WRAP.

minFilterMode New type of minification filtering to perform or –1 if not changed. Valid parameters are GR_FILTER_POINT_SAMPLED and GR_FILTER_BILINEAR.

magFilterMode New type of magnification filtering to perform or –1 if not changed. Valid parameters are GR_FILTER_POINT_SAMPLED and GR_FILTER_BILINEAR.

Description

guTexChangeAttributes changes some of the attributes of a mipmap. This allows a section of texture memory to be reused without resetting all of texture memory. Upon success, FXTRUE is returned, else FXFALSE is returned.

Notes

For projected textures the clamp modes, sClampMode and tClampMode, should always be set to GR_TEXTURECLAMP_CLAMP.

WARNING: do not use in conjunction with grTexMinAddress, grTexMaxAddress, grTexNCCTable, grTexSource, grTexDownloadTable, grTexDownloadMipMapLevel, grTexDownloadMipMap, grTexMultiBase, or grTexMultibaseAddress.

See Also

guTexAllocateMemory

guTexCombineFunction

Name

guTexCombineFunction – configure the texture combine unit on a Texture Mapping Unit

C Specification

void guTexCombineFunction( GrChipID_t tmu, GrTextureCombineFnc_t func )

Parameters

tmu Texture Mapping Unit to configure. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

func The new texture combine mode.

Description

guTexCombineFunction specifies the function used when combining textures on a TMU with incoming textures from the neighboring TMU. Texture combining operations allow for interesting effects such as detail and projected texturing as well as the trilinear fi ltering of LOD blending.

The following table describes the available texture combine functions and their effects. C_local represents the color components generated by indexing and filtering from the mipmap stored on the selected TMU and C_other represents the incoming color componen ts from the neighboring TMU.

guTexCombineFunction also keeps track of which TMUs require texture coordinates for the rendering routines.

Notes

Many combine functions that simultaneously use both C_local and C_other can be computed with two passes on a single TMU system by using the frame buffer to store intermediate results and the alpha blender to combine the two partial results.

See Also

grAlphaCombine, grColorCombine, grDrawTriangle, grTexCombine, guTexSource

guTexDownloadMipMap

Name

guTexDownloadMipMap – download a mipmap to texture memory

C Specification

void guTexDownloadMipMap( GrMipMapId_t mmid, const void *src,
const GuNccTable *nccTable )

Parameters

mmid Handle of the mipmap memory accepting the download.

src Pointer to row-major array of pixels of the format, size, and aspect ratio associated with mmid. Mipmap levels are arranged from largest to smallest size.

nccTable Pointer to a Narrow Channel Compression table. This is only valid for 8-bit compressed textures loaded with gu3dfLoad.

Description

guTexDownloadMipMap downloads an entire mipmap to an area of texture memory previously allocated with guTexAllocateMemory. The data to be downloaded must have the pixel format and aspect ratio associated with mmid.

Notes

WARNING: do not use in conjunction with grTexMinAddress, grTexMaxAddress, grTexNCCTable, grTexSource, grTexDownloadTable, grTexDownloadMipMapLevel, grTexDownloadMipMap, grTexMultiBase, and grTexMultibaseAddress.

See Also

guTexAllocateMemory, guTexDownloadMipMapLevel, guTexMemReset, guTexSource

guTexDownloadMipMapLevel

Name

guTexDownloadMipMapLevel – download one level of a mipmap

C Specification

void guTexDownloadMipMapLevel( GrMipMapId_t mmid, GrLOD_t lod, const void **src )

Parameters

mmid Handle of the mipmap memory accepting the download.

lod LOD level of the mipmap level to download. Valid parameters are GR_LOD_256, GR_LOD_128, GR_LOD_64, GR_LOD_32, GR_LOD_16, GR_LOD_8, GR_LOD_4, GR_LOD_2, and GR_LOD_1. lod must lie between mmid’s smallLod and largeLod LOD levels specified during guTexAllo cateMemory.

src Pointer to a pointer to row-major array of pixels of the format, size, and aspect ratio associated with mmid and lod.

Description

guTexDownloadMipMapLevel downloads a single mipmap level within a mipmap to an area of texture memory previously allocated with guTexAllocateMemory and updates *src to point to the next mipmap level. The data to be downloaded must have the pixel format and aspect ratio associated with mmid and must be of the correct size for lod.

Notes

WARNING: do not use in conjunction with grTexMinAddress, grTexMaxAddress, grTexNCCTable, grTexSource, grTexDownloadTable, grTexDownloadMipMapLevel, grTexDownloadMipMap, grTexMultiBase, and grTexMultibaseAddress.

See Also

guTexAllocateMemory, guTexDownloadMipMapLevel, guTexMemReset, guTexSource

guTexGetCurrentMipMap

Name

guTexGetCurrentMipMap – return the handle of the current mipmap

C Specification

GrMipMapId_t *guTexGetCurrentMipMap ( GrChipID_t tmu )

Parameters

tmu Texture Mapping Unit to query. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

Description

guTexGetCurrentMipMap returns the handle of the currently active mipmap on a selected TMU. Each TMU has one currently active mipmap. Mipmaps are made current with guTexSource.

Notes

See Also

guTexAllocateMemory, guTexSource, guTexGetMipMapInfo

guTexGetMipMapInfo

Name

guTexGetMipMapInfo – return a pointer to a structure containing information about a specific mipmap.

C Specification

GrMipMapInfo *guTexGetMipMapInfo( GrMipMapId_t mmid )

Parameters

mmid Handle of the mipmap inquired about.

Description

guTexGetMipMapInfo allows an application to retrieve information about a mipmap.

Notes

See Also

guTexAllocateMemory, guTexSource, guTexGetCurrentMipMap

guTexMemQueryAvail

Name

guTexMemQueryAvail – return the amount of unallocated texture memory on a Texture Mapping Unit

C Specification

FxU32 guTexMemQueryAvail( GrChipID_t tmu )

Parameters

tmu Texture Mapping Unit to query. Valid values are GR_TMU0, GR_TMU1, and GR_TMU2.

Description

guTexMemQueryAvail returns the amount of unallocated texture memory on a TMU. Only memory allocated with guTexAllocateMemory is taken into account.

Notes

WARNING: do not use in conjunction with grTexMinAddress, grTexMaxAddress, grTexNCCTable, grTexSource, grTexDownloadTable, grTexDownloadMipMapLevel, grTexDownloadMipMap, grTexMultiBase, and grTexMultibaseAddress.

See Also

guTexAllocateMemory, guTexMemReset

guTexMemReset

Name

guTexMemReset – free all allocated texture memory for all Texture Mapping Units

C Specification

void guTexMemReset( void )

Parameters

none

Description

guTexMemReset frees up all allocated texture memory. This allows for a simple form of texture memory management; all texture memory is allocated at once and then freed en masse. While simple, this form of memory management prevents some of the complexity a ssociated with standard memory management techniques, such as garbage collection and memory fragmentation and compaction.

Notes

WARNING: do not use in conjunction with grTexMinAddress, grTexMaxAddress, grTexNCCTable, grTexSource, grTexDownloadTable, grTexDownloadMipMapLevel, grTexDownloadMipMap, grTexMultiBase, and grTexMultibaseAddress.

See Also

guTexAllocateMemory, guTexMemQueryAvail

guTexSource

Name

guTexSource – make a mipmap current on its Texture Mapping Unit

C Specification

void guTexSource( GrMipMapId_t mmid )

Parameters

mmid Handle of the mipmap to make current.

Description

guTexSource makes current a mipmap for the TMU it resides on. Each TMU has one current mipmap. In systems with multiple TMUs, multiple mipmap sources are combined by the texture combine function and the output of the final combine is passed on to the pixel shading pipeline. By default all the TMUs have NULL texture handles associated with them.

When a mipmap is made current, all of its attributes take effect. See guTexAllocateMemory and guTexChangeAttributes for a complete listing of texture attributes. Some of these attributes can be temporarily overridden with grTexClampMode, grTexFilterMode, g rTexLodBiasValue, and grTexMipMapMode. Note, however, that these routines do not change the mipmap’s attribute, only the current mode of the rendering hardware.

Notes

WARNING: do not use in conjunction with grTexMinAddress, grTexMaxAddress, grTexNCCTable, grTexSource, grTexDownloadTable, grTexDownloadMipMapLevel, grTexDownloadMipMap, grTexMultiBase, and grTexMultibaseAddress.

See Also

guTexAllocateMemory, guTexChangeAttributes, grTexClampMode, grTexFilterMode, guTexGetCurrentMipMap, grTexLodBiasValue, grTexMipMapMode

References

FOLE90 Foley, J., A. van Dam, S. Feiner, and J. Hughes, “Computer Graphics”, Addison-Wesley, Reading, 1990

SUTH74 Sutherland, I. E. and G. W. Hodgman, “Reentrant Polygon Clipping”, CACM 17(1), 32-42

WILL83 Williams, L., “Pyramidal Parametrics”, SIGGRAPH 83, 1-11

ToDo List

Edits

• decide whether user should be instructed to call grLfbBegin/End around LFB read sequences (for SST-96)
• grTexDownloadMipMap*, is startAddress the addr of LOD 0 or what? need to describe info structure
• grTexDownloadMipMapLevel: reword “Constant” phrasing
• reword all "Voodoo Graphics", generalize (AT3D).
• describe (table?) the LFB modes in grLfbWriteMode
• guAADrawTriangleWithClip - need a version with edge flags?

GLIDE bugs (in Track) that will require doc changes

• need to specify RGBA ordering for LFB writes and reads, also byte/word swaps
  maybe grLfbWriteOrder and grLfbReadOrder? Chris wrote these routines

DONE

• check all grSstOpen(cFormat) dependencies (grep the source code):
  grBufferClear, grChromakeyValue, grFogColorValue, grConstantColorValue
• need a routine to download 1 palette entry
• lowercase Name sections, uppercase Parameter and end with period, separate gr* and gu* pages
• guTexAllocateMemory - does guTexSource set mm_mode? YES
• need to rename grTexCombineFunction to gu*
• reworded all "incoming"
• reworded all references to Texelfx chips, used TMU instead
• change all constant references (GR_*) to Codefont

grShadeModel

Name

grShadeModel – selects the current shading model

C Specification

void grShadeModel( FxU32 shadeMask )

Parameters

shadeMask A bitmask or ORed values selecting the current shading model.

Description

grShadeModel selects which parameters are flat-shaded and which parameters are smooth-shaded. Flat-shaded parameters are constant across a primitive; the value is taken from the first vertex in the primitive. Smooth-shaded parameters are iterated across a primitive. shadeMask is a bitmask constructed by ORing individual masks from the following table:

The default shading model mask is 0x00: all parameters are smooth-shaded.

Notes

If a vertex parameter is constant across a primitive, it is best to specify the parameter as flat-shaded. This can increase performance, since the parameter data does not have to be copied to each vertex in the primitive: Glide does not have to compute gra dients for the parameter and transfers less data to the graphics hardware.

If a constant color mode is selected with grColorCombine or grAlphaCombine, Glide automatically flat-shades these parameters; it is not necessary to select a flat-shading mode with grShadeModel.

See Also

grAlphaCombine, grColorCombine, grConstantColorValue, grDrawLine, grDrawPoint, grDrawTriangle

See Also

grLfbBegin

Name

grLfbBegin – enable reads and writes to the linear frame buffer

C Specification

void grLfbBegin( void )

Parameters

none

Description

grLfbBegin informs Glide that reads or writes to the linear frame buffer are enabled. This gives Glide an opportunity to update various internal registers necessary for the proper operation of the linear frame buffer. During the period of linear frame buff er reads or writes (between calls to grLfbBegin and grLfbEnd), grDepthBiasLevel is ignored.

Notes

No other Glide calls should be made between calls to grLfbBegin and grLfbEnd except Glide utility routines for reading and writing regions of pixels (e.g. guFbReadRegion and guFbWriteRegion).

See Also

grDepthBiasLevel, grLfbEnd

grLfbBypassMode

Name

grLfbBypassMode – enable/disable linear frame buffer write bypass mode

C Specification

void grLfbBypassMode( GrLfbBypassMode_t mode )

Parameters

mode The new linear frame buffer bypass mode, either GR_LFBBYPASS_DISABLE or GR_LFBBYPASS_ENABLE.

Description

grLfbBypassMode allows an application to bypass the entire pixel pipeline (except dithering) during linear frame buffer writes. This is useful when rendering overlays or text directly to the screen and the application does not wish to disable all current e ffects (such as fog, depth buffering, etc.) individually. Note that if linear frame buffer bypass is enabled then no effects are enabled with the exception of dithering. This includes clipping to the grClipWindow, so an application must be careful not to w rite outside of the visible display when grLfbBypassMode is enabled. By default, linear frame buffer bypass mode is disabled.

Notes

The values of grColorMask and grDepthMask are ignored when grLfbBypassMode is enabled.

See Also

grDisableAllEffects

grLfbEnd

Name

grLfbEnd – disable reads and writes to the linear frame buffer

C Specification

void grLfbEnd( void )

Parameters

none

Description

grLfbEnd informs Glide that reads and writes to the linear frame buffer are no longer taking place. This gives Glide an opportunity to update various internal registers necessary for the proper operation of normal rendering operations. Note that grDepthBia sLevel is ignored during LFB writes (i.e. between calls to grLfbBegin and grLfbEnd).

Notes

No other Glide calls should be made between calls to grLfbBegin and grLfbEnd except Glide utility routines for reading and writing regions of pixels (e.g. guFbReadRegion and guFbWriteRegion).

See Also

grDepthBiasLevel, grLfbBegin

grLfbGetReadPtr

Name

grLfbGetReadPtr – returns a read-only pointer to part of the linear frame buffer

C Specification

const FxU32 *grLfbGetReadPtr( GrBuffer_t buffer )

Parameters

buffer The buffer for which to return a read-only pointer. Valid parameters are: GR_BUFFER_FRONTBUFFER, GR_BUFFER_BACKBUFFER, GR_BUFFER_AUXBUFFER, GR_BUFFER_TRIPLEBUFFER, GR_BUFFER_DEPTHBUFFER, and GR_BUFFER_ALPHABUFFER.

Description

grLfbGetReadPtr returns a read-only pointer to part of the frame buffer. This pointer can be used by an application to read data directly out of the frame buffer. All data is read as two 16-bit pixels per 32-bit word. The format of the pixels is 565 RGB fo r color buffers; the RGB ordering is dependent on the cformat specified in grSstOpen. The default pixel ordering within the 32-bit read is 0xRRRRLLLL, where the left pixel in the pair is in the lower 16-bits of the 32-bit word. When reading the alpha buffe r, the 8-bit alpha values are located in bits [7:0] and [23:16] of the 32-bit word. When reading the depth buffer, the format of the two 16-bit values is either fixed point z values or floating point w values depending on the depth buffering mode.

Refer to the Glide Programming Guide for more information on linear frame buffer reading and writing.

Notes

The parameters GR_BUFFER_AUXBUFFER, GR_BUFFER_TRIPLEBUFFER, GR_BUFFER_DEPTHBUFFER, and GR_BUFFER_ALPHABUFFER are synonymous as they all share the same memory.

See Also

grDepthBufferMode, grLfbGetWritePtr, grSstOpen

grLfbGetWritePtr

Name

grLfbGetWritePtr – returns a writable pointer to part of the linear frame buffer

C Specification

void *grLfbGetWritePtr( GrBuffer_t buffer )

Parameters

buffer The buffer for which to return a writable pointer. Valid parameters are: GR_BUFFER_FRONTBUFFER, GR_BUFFER_BACKBUFFER, GR_BUFFER_AUXBUFFER, GR_BUFFER_TRIPLEBUFFER, GR_BUFFER_DEPTHBUFFER, and GR_BUFFER_ALPHABUFFER.

Description

grLfbGetWritePtr returns a writable pointer to part of the frame buffer. This pointer can be used by an application to write data directly to the frame buffer in a format specified by grLfbWriteMode. Refer to the Glide Programming Guide for more informatio n on linear frame buffer reading and writing.

Notes

The parameters GR_BUFFER_AUXBUFFER, GR_BUFFER_TRIPLEBUFFER, GR_BUFFER_DEPTHBUFFER, and GR_BUFFER_ALPHABUFFER are synonymous as they all share the same memory.

See Also

grLfbGetReadPtr

grLfbOrigin

Name

grLfbOrigin – set the origin for linear frame buffer reads and writes

C Specification

void *grLfbOrigin( GrOriginLocation_t origin )

Parameters

origin The new origin location, either GR_ORIGIN_UPPER_LEFT or GR_ORIGIN_LOWER_LEFT.

Description

grLfbOrigin allows the origin for linear frame buffer writes to be set separately from the origin for other rendering operations (drawing points, lines, triangles, and polygons, clearing buffers, etc.). This is useful in cases where images have a different origin than graphics primitives, or where different images have different origins.

Notes

The origin for the drawing routines and all rendering operations except frame buffer accesses is set with the org_loc argument to grSstOpen.

See Also

grSstOpen

grLfbWriteMode

Name

grLfbWriteMode – set the mode for linear frame buffer writes

C Specification

void grLfbWriteMode( GrLfbWriteMode_t mode )

Parameters

mode The new write mode for linear frame buffer writes. Valid modes are GR_LFBWRITEMODE_565, GR_LFBWRITEMODE_555, GR_LFBWRITEMODE_1555, GR_LFBWRITEMODE_888, GR_LFBWRITEMODE_8888, GR_LFBWRITEMODE_565_DEPTH, GR_LFBWRITEMODE_555_DEPTH, GR_LFBWRITEMODE_1555_DE PTH, GR_LFBWRITEMODE_DEPTH_DEPTH, and GR_LFBWRITEMODE_ALPHA_ALPHA.

Description

grLfbWriteMode sets the mode for linear frame buffer writes: when an application writes to a pointer retrieved with grLfbGetWritePtr. Refer to the Glide Programming Guide for more information on linear frame buffer reading and writing.

Notes

See Also

grLfbGetWritePtr