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: Type Name Format ANSI C type FxI8 8-bit signed signed char FxU8 8-bit unsigned unsigned char FxU16 16-bit unsigned unsigned short int FxI16 16-bit signed signed short int FxU32 32-bit unsigned unsigned long int FxI32 32-bit signed signed long int value FxBool 32-bit signed long int 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: GR_BLEND_ZERO GR_BLEND_ONE GR_BLEND_DST_COLOR GR_BLEND_ONE_MINUS_DST_COLOR GR_BLEND_SRC_ALPHA GR_BLEND_ONE_MINUS_SRC_ALPHA GR_BLEND_DST_ALPHA GR_BLEND_ONE_MINUS_DST_ALPHA GR_BLEND_ALPHA_SATURATE rgb_df Specifies the red, green, and blue destination blending factors. Eight symbolic constants are accepted: GR_BLEND_ZERO GR_BLEND_ONE GR_BLEND_SRC_COLOR GR_BLEND_ONE_MINUS_SRC_COLOR GR_BLEND_SRC_ALPHA GR_BLEND_ONE_MINUS_SRC_ALPHA GR_BLEND_DST_ALPHA GR_BLEND_ONE_MINUS_DST_ALPHA alpha_sf Specifies the alpha source blending factor. Nine symbolic constants are accepted: GR_BLEND_ZERO GR_BLEND_ONE GR_BLEND_DST_COLOR GR_BLEND_ONE_MINUS_DST_COLOR GR_BLEND_SRC_ALPHA GR_BLEND_ONE_MINUS_SRC_ALPHA GR_BLEND_DST_ALPHA GR_BLEND_ONE_MINUS_DST_ALPHA GR_BLEND_ALPHA_SATURATE alpha_df Specifies the alpha destination blending factor. Eight symbolic constants are accepted: GR_BLEND_ZERO GR_BLEND_ONE GR_BLEND_SRC_COLOR GR_BLEND_ONE_MINUS_SRC_COLOR GR_BLEND_SRC_ALPHA GR_BLEND_ONE_MINUS_SRC_ALPHA GR_BLEND_DST_ALPHA GR_BLEND_ONE_MINUS_DST_ALPHA 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: R = min (255, Rs sR + Rd dR) G = min (255, Gs sG + Gd dG) B = min (255, Bs sB + Bd dB) A = min (255, As sA + Ad dA) where Rs, Gs, Bs, As are the source color and alpha components, Rd, Gd, Bd, Ad are the destination color and alpha components, sR, sG, sB sA are the source blending factors, and dR, dG, dB, dA are the destination blending factors. The blending factors are as follows: Blending Factor Component Blend Factor GR_BLEND_ZERO 0 GR_BLEND_ONE 1 GR_BLEND_SRC_COLOR Cs / 255 GR_BLEND_ONE_MINUS_SRC1 – Cs / 255 GR_BLEND_DST_COLOR Cd / 255 GR_BLEND_ONE_MINUS_DST1 – Cd / 255 GR_BLEND_SRC_ALPHA As / 255 GR_BLEND_ONE_MINUS_SRC1 – As / 255 GR_BLEND_DST_ALPHA Ad / 255 GR_BLEND_ONE_MINUS_DST1 – Ad / 255 GR_BLEND_ALPHA_SATURATmin (As / 255, 1 – Ad / 255) where Cs and Cd are the corresponding Rs, Gs, Bs, As and Rd, Gd, Bd, Ad 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. Combine Function Computed Alpha ZERO 0 LOCAL Alocal LOCAL_ALPHA Alocal SCALE_OTHER f *Aother BLEND_OTHER SCALE_OTHER_ADD_LOCAL f *Aother + Alocal SCALE_OTHER_ADD_LOCAL_ALPHA f *Aother + Alocal SCALE_OTHER_MINUS_LOCAL f *(Aother – Alocal) SCALE_OTHER_MINUS_LOCAL_ADD_Lf *(Aother – Alocal) + BLEND Alocal º f *Aother + (1– f)*Alocal SCALE_OTHER_MINUS_LOCAL_ADD_Lf *(Aother – Alocal) + Alocal SCALE_MINUS_LOCAL_ADD_LOCAL f *(– Alocal) + Alocal BLEND_LOCAL º (1– f) *Alocal SCALE_MINUS_LOCAL_ADD_LOCAL_Af *(– Alocal) + Alocal factor Specifies the scaling factor used in alpha generation. Valid parameters are described below: Combine Factor Scale Factor (f) GR_COMBINE_FACTOR_NONE Unspecified GR_COMBINE_FACTOR_ZERO 0 GR_COMBINE_FACTOR_LOCAL Alocal / 255 GR_COMBINE_FACTOR_OTHER_ALPHA Aother / 255 GR_COMBINE_FACTOR_LOCAL_ALPHA Alocal / 255 GR_COMBINE_FACTOR_TEXTURE_ALPHAAtexture / 255 GR_COMBINE_FACTOR_ONE 1 GR_COMBINE_FACTOR_ONE_MINUS_LOC1 – Alocal / 255 GR_COMBINE_FACTOR_ONE_MINUS_OTH1 – Aother / 255 GR_COMBINE_FACTOR_ONE_MINUS_LOC1 – Alocal / 255 GR_COMBINE_FACTOR_ONE_MINUS_TEX1 –E_ALPHA Atexture / 255 local Specifies the local alpha used in source alpha generation. Valid parameters are described below: Local Combine Source Local Alpha (Alocal) GR_COMBINE_LOCAL_NONE Unspecified alpha GR_COMBINE_LOCAL_ITERATEDIterated vertex alpha GR_COMBINE_LOCAL_CONSTANTConstant alpha GR_COMBINE_LOCAL_DEPTH High 8 bits from iterated vertex z other Specifies the other alpha used in source alpha generation. Valid parameters are described below: Other Combine Source Other Alpha (Aother) GR_COMBINE_OTHER_NONE Unspecified alpha GR_COMBINE_OTHER_ITERATEDIterated vertex alpha GR_COMBINE_OTHER_TEXTURE Alpha from texture map GR_COMBINE_OTHER_CONSTANTConstant alpha 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 (Clocal) are overridden, and the most significant bit of texture alpha (Atexture) selects between iterated vertex RGB and the constant color set by grConstantColorValue. By default, alpha cont rolled lighting mode is disabled. Value of enable MSB of Alpha Color Combine Local Channel Color FXTRUE 0 Iterated RGB FXTRUE 1 grConstantColorValue FXFALSE 0 Set by grColorCombine FXFALSE 1 Set by grColorCombine 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: function Comparison Function GR_CMP_NEVER Never passes. GR_CMP_LESS Passes if the incoming alpha value is less than the constant alpha reference value. GR_CMP_EQUAL Passes if the incoming alpha value is equal to the constant alpha reference value. GR_CMP_LEQUAL Passes if the incoming alpha value is less than or equal to the constant alpha reference value. GR_CMP_GREATERPasses if the incoming alpha value is greater than the constant alpha reference value. GR_CMP_NOTEQUAPasses if the incoming alpha value is not equal to the constant alpha reference value. GR_CMP_GEQUAL Passes if the incoming alpha value is greater than or equal to the constant alpha reference value. GR_CMP_ALWAYS Always passes 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: Combine Function computed color GR_COMBINE_FUNCTION_ZERO 0 GR_COMBINE_FUNCTION_LOCAL Clocal GR_COMBINE_FUNCTION_LOCAL_ALPHA Alocal GR_COMBINE_FUNCTION_SCALE_OTHER f * Cother GR_COMBINE_FUNCTION_BLEND_OTHER GR_COMBINE_FUNCTION_SCALE_OTHER_ADD_LOCAL f * Cother + Clocal GR_COMBINE_FUNCTION_SCALE_OTHER_ADD_LOCAL_Af * Cother + Alocal GR_COMBINE_FUNCTION_SCALE_OTHER_MINUS_LOCALf * (Cother – Clocal) GR_COMBINE_FUNCTION_SCALE_OTHER_MINUS_LOCALf * (Cother – Clocal) + GR_COMBINE_FUNCTION_BLEND Clocal º f * Cother + (1 – f) * Clocal GR_COMBINE_FUNCTION_SCALE_OTHER_MINUS_LOCALf * (Cother –PHA Clocal) + Alocal GR_COMBINE_FUNCTION_SCALE_MINUS_LOCAL_ADD_Lf * (– Clocal) + Clocal GR_COMBINE_FUNCTION_BLEND_LOCAL º (1 – f) * Clocal GR_COMBINE_FUNCTION_SCALE_MINUS_LOCAL_ADD_Lf * (– Clocal) + Alocal factor Specifies the scaling factor f used in source color generation. Valid parameters are described below: Combine Factor Scale Factor (f) GR_COMBINE_FACTOR_NONE Unspecified GR_COMBINE_FACTOR_ZERO 0 GR_COMBINE_FACTOR_LOCAL Clocal / 255 GR_COMBINE_FACTOR_OTHER_ALPHA Aother / 255 GR_COMBINE_FACTOR_LOCAL_ALPHA Alocal / 255 GR_COMBINE_FACTOR_TEXTURE_ALPHAAtexture / 255 GR_COMBINE_FACTOR_ONE 1 GR_COMBINE_FACTOR_ONE_MINUS_LOC1 – Clocal / 255 GR_COMBINE_FACTOR_ONE_MINUS_OTH1 – Aother / 255 GR_COMBINE_FACTOR_ONE_MINUS_LOC1 – Alocal / 255 GR_COMBINE_FACTOR_ONE_MINUS_TEX1 –E_ALPHA Atexture / 255 local Specifies the local color used in source color generation. Valid parameters are described below: Local Combine Local Color (Clocal) Source GR_COMBINE_LOCAL_NONUnspecified color GR_COMBINE_LOCAL_ITEIterated vertex color (Gouraud shading) GR_COMBINE_LOCAL_CONConstant color other Specifies the other color used in source color generation. Valid parameters are described below: Other Combine Other Color (Cother) Source GR_COMBINE_OTHER_NONUnspecified color GR_COMBINE_OTHER_ITEIterated vertex color (Gouraud shading) GR_COMBINE_OTHER_TEXColor from texture map GR_COMBINE_OTHER_CONConstant color 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, Alocal is the local alpha value selected by grAlphaCombine and Aother 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. Origin Location Triangle Signed Area Orientation GR_ORIGIN_LOWERLEFclockwise negative GR_ORIGIN_LOWERLEFcounter-clockwise positive GR_ORIGIN_UPPERLEFclockwise positive GR_ORIGIN_UPPERLEFcounter-clockwise negative 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: func Comparison Function GR_CMP_NEVER Never passes. GR_CMP_LESS Passes if the pixel’s depth value is less than the stored depth value. GR_CMP_EQUAL Passes if the pixel’s depth value is equal to the stored depth value. GR_CMP_LEQUAL Passes if the pixel’s depth value is less than or equal to the stored depth value. GR_CMP_GREATERPasses if the pixel’s depth value is greater than the stored depth value. GR_CMP_NOTEQUAPasses if the pixel’s depth value is not equal to the stored depth value. GR_CMP_GEQUAL Passes if the pixel’s depth value is greater than or equal to the stored depth value. GR_CMP_ALWAYS Always passes 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 (Cfog) with each rasterized pixel’s color (Cin) 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: Cout = f Cfog + (1–f)Cin 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 (Cfog) with each rasterized pixel’s color (Cin) 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: Cout = f Cfog + (1–f)Cin 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 (Cfog) with each rasterized pixel’s color (Cin) 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: Cout = f Cfog + (1–f)Cin 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 (RGBgamma) is computed from the RGB value read from the frame buffer (RGBfb) according to the following equation: RGBgamma = [(RGBfb/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: Hint Description GR_STWHINT_ST_DIFF_Ts and t for TMU0 are different than previous values. GR_STWHINT_ST_DIFF_Ts and t for TMU1 are different than previous values. GR_STWHINT_ST_DIFF_Ts and t for TMU2 are different than previous values. GR_STWHINT_W_DIFF_TMw for TMU0 is different than previous w values. GR_STWHINT_W_DIFF_TMw for TMU1 is different than previous w values. GR_STWHINT_W_DIFF_TMw for TMU2 is different than previous w 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: GR_LFB_READ_ONLY info.lfbPtr should only be used for read access; writing to this pointer will have undefined effects on the graphics subsystem. GR_LFB_WRITE_ONLY info.lfbPtr should only be used for write access; reading from this pointer will yield undefined data. The idle request flag can be one of: GR_LFB_IDLE The 3D engine will be idled before grLfbLock returns. This is the default behavior if no idle request flag is specified. GR_LFB_NOIDLE The 3D engine will not be idled; there is no guarantee of serialization of linear frame buffer accesses and triangle rendering or buffer clearing operations. 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: GR_LFBWRITEMODE_565 Frame buffer accepts 16-bit RGB 565 pixel data. GR_LFBWRITEMODE_555 Frame buffer accepts 16-bit RGB-555 pixel data. The MSB of each pixel is ignored. GR_LFBWRITEMODE_1555Frame buffer accepts 16-bit ARGB-1555 pixel data. The alpha component is replicated to 8-bits and copied to the alpha buffer if the alpha buffer has been enabled with grColorMask. GR_LFBWRITEMODE_888 Frame buffer accepts 24-bit RGB 888 pixel data packed into 32-bit words. The most significant byte of each word is ignored. If dithering is enabled, then color will be dithered down to the real frame buffer storage format if necessary. GR_LFBWRITEMODE_8888Frame buffer accepts 32-bit ARGB 8888 pixel data. The alpha component is copied into the alpha buffer if the alpha buffer has been enabled with grColorMask. If dithering is enabled, then color will be dithered down to the real frame buffer storage format i f necessary. GR_LFBWRITEMODE_565_Frame buffer accepts 32-bit pixels where the two most significant bytes contain 565 RGB data, and the two least significant bytes contain 16-bit depth data. GR_LFBWRITEMODE_555_Frame buffer accepts 32-bit pixels where the two most significant bytes contain 555 RGB data, the most significant bit is ignored, and the two least significant bytes contain 16-bit depth data. GR_LFBWRITEMODE_1555Frame buffer accepts 32-bit pixels where the two most significant bytes contain 1555 ARGB data, the alpha component is replicated to 8-bits and copied to the alpha buffer if alpha buffering has been enabled with grColorMask. GR_LFBWRITEMODE_ZA16Frame buffer accepts 16-bit auxiliary buffer values. This is the only writeMode that is valid when locking the auxiliary buffer. Alpha buffer values are taken from the 8 least significant bits of each sixteen bit word. GR_LFBWRITEMODE_ANY Lock will return the pixel format that most closely matches the true frame buffer storage format in the info.writeMode. 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: GR_ORIGIN_UPPER_LEFT Addressing originates in the upper left hand corner of the screen. GR_ORIGIN_LOWER_LEFT Addressing originates in the lower left hand corner of the screen. GR_ORIGIN_ANY Lock will always choose GR_ORIGIN_UPPER_LEFT 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: GR_LFB_SRC_FMT_565 RGB 565 color image GR_LFB_SRC_FMT_555 RGB 555 color image GR_LFB_SRC_FMT_1555 RGB 1555 color image GR_LFB_SRC_FMT_888 RGB 888 color image each pixel padded to 32-bits with RGB in low order 24-bits GR_LFB_SRC_FMT_8888 ARGB 8888 color image GR_LFB_SRC_FMT_565_DEPTRGB 565 and 16-bit depth value packed into each 32-bit element of image GR_LFB_SRC_FMT_555_DEPTRGB 555 and 16-bit depth value packed into each 32-bit element of image GR_LFB_SRC_FMT_1555_DEPRGB 1555 and 16-bit depth value packed into each 32-bit element of image GR_LFB_SRC_FMT_ZA16 Two 16-bit depth or alpha values. Alpha values are stored into odd bytes. GR_LFB_SRC_FMT_RLE16 16 BPP RLE Encoded image - see notes 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: mode Description GR_CONTROL_ACTIVAactivate 3D display GR_CONTROL_DEACTIactivate 2D display GR_CONTROL_RESIZEresize back buffers and auxiliary buffers (SST-96 only) GR_CONTROL_MOVE validate location after window move (SST-96 only) 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: pStats field Description FxU32 Number of pixels processed pixelsIn FxU32 Number of pixels not drawn due to chroma-key chromaFail failure FxU32 Number of pixels not drawn due to depth zFuncFail comparison failure FxU32 Number of pixels not drawn due to alpha aFuncFail comparison failure. FxU32 Number of pixels drawn. Note that this pixelsOut number includes all pixels drawn (i.e. pixels drawn by grBufferClear and LFB writes that have bypassed the pixel pipeline), not just those that have gone through the rendering pipeline. 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: Bit Description 5:0 PCI FIFO free space (0x3F=FIFO empty) 6 Vertical retrace (0=vertical retrace active; 1=vertical retrace inactive). 7 Pixelfx graphics engine busy (0=engine idle; 1=engine busy) 8 TMU busy (0=engine idle; 1=engine busy) 9 Voodoo Graphics busy (0=idle; 1=busy) 11:10Displayed buffer (0=buffer 0; 1=buffer 1; 2=auxiliary buffer; 3=reserved) 27:12Memory FIFO free space (0xFFFF=FIFO empty) 30:28Number of swap buffer commands pending 31 PCI interrupt generated (not implemented) 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. System Environment hwnd value DOS NULL Win32 Full Screen NULL or hwnd Win32 Pure Console NULL (SST-1 only) Win32 Glide Apps NULL or hwnd (SST-96 only) 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: Color Format Hex Variable Organization GR_COLORFORMAT_RGBA0xRRGGBBAA GR_COLORFORMAT_ARGB0xAARRGGBB GR_COLORFORMAT_BGRA0xBBGGRRAA GR_COLORFORMAT_ABGR0xAABBGGRR 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: Combine Function Effect GR_COMBINE_FUNCTION_ZERO 0 GR_COMBINE_FUNCTION_LOCAL Clocal GR_COMBINE_FUNCTION_LOCAL_ALPHA Alocal GR_COMBINE_FUNCTION_SCALE_OTHER f * Cother GR_COMBINE_FUNCTION_BLEND_OTHER GR_COMBINE_FUNCTION_SCALE_OTHER_ADD_LOCAL f * Cother + Clocal GR_COMBINE_FUNCTION_SCALE_OTHER_ADD_LOCAL_Af * Cother + Alocal GR_COMBINE_FUNCTION_SCALE_OTHER_MINUS_LOCALf * (Cother – Clocal) GR_COMBINE_FUNCTION_SCALE_OTHER_MINUS_LOCALf * (Cother – Clocal) + GR_COMBINE_FUNCTION_BLEND Clocal º f * Cother + (1 – f) * Clocal GR_COMBINE_FUNCTION_SCALE_OTHER_MINUS_LOCALf * (Cother –PHA Clocal) + Alocal GR_COMBINE_FUNCTION_SCALE_MINUS_LOCAL_ADD_Lf * (– Clocal) + GR_COMBINE_FUNCTION_BLEND_LOCAL Clocal º (1 – f) * Clocal GR_COMBINE_FUNCTION_SCALE_MINUS_LOCAL_ADD_Lf * (–LPHA Clocal) + Alocal rgb_factor Specifies the scaling factor f used in texture color generation. Valid parameters are described below: Combine Factor Scale Factor (f) GR_COMBINE_FACTOR_NONE Unspecified GR_COMBINE_FACTOR_ZERO 0 GR_COMBINE_FACTOR_LOCAL Clocal / 255 GR_COMBINE_FACTOR_OTHER_ALPHA Aother / 255 GR_COMBINE_FACTOR_LOCAL_ALPHA Alocal / 255 GR_COMBINE_FACTOR_DETAIL_FACTORb GR_COMBINE_FACTOR_LOD_FRACTION GR_COMBINE_FACTOR_ONE 1 GR_COMBINE_FACTOR_ONE_MINUS_LOC1 – Clocal / 255 GR_COMBINE_FACTOR_ONE_MINUS_OTH1 – Aother / 255 GR_COMBINE_FACTOR_ONE_MINUS_LOC1 – Alocal / 255 GR_COMBINE_FACTOR_ONE_MINUS_DET1 – b CTOR GR_COMBINE_FACTOR_ONE_MINUS_LOD_FRACTION alpha_function Specifies the function used in texture alpha generation. Valid parameters are described below: Combine Function Effect GR_COMBINE_FUNCTION_ZERO 0 GR_COMBINE_FUNCTION_LOCAL Alocal GR_COMBINE_FUNCTION_LOCAL_ALPHA Alocal GR_COMBINE_FUNCTION_SCALE_OTHER f * Aother GR_COMBINE_FUNCTION_BLEND_OTHER GR_COMBINE_FUNCTION_SCALE_OTHER_ADD_LOCAL f * Aother + Alocal GR_COMBINE_FUNCTION_SCALE_OTHER_ADD_LOCAL_ALf * Aother + Alocal GR_COMBINE_FUNCTION_SCALE_OTHER_MINUS_LOCAL f * (Aother – Alocal) GR_COMBINE_FUNCTION_SCALE_OTHER_MINUS_LOCAL_f * (Aother – Alocal) + GR_COMBINE_FUNCTION_BLEND Alocal º f * Aother + (1 – f) * Alocal GR_COMBINE_FUNCTION_SCALE_OTHER_MINUS_LOCAL_f * (Aother –HA Alocal) + Alocal GR_COMBINE_FUNCTION_SCALE_MINUS_LOCAL_ADD_LOf * (– Alocal) + Alocal GR_COMBINE_FUNCTION_BLEND_LOCAL º (1 – f) * Alocal GR_COMBINE_FUNCTION_SCALE_MINUS_LOCAL_ADD_LOf * (– Clocal) + Alocal alpha_factor Specifies the scaling factor f used in texture alpha generation. Valid parameters are described below: Combine Factor Scale Factor (f) GR_COMBINE_FACTOR_NONE Unspecified GR_COMBINE_FACTOR_ZERO 0 GR_COMBINE_FACTOR_LOCAL Alocal / 255 GR_COMBINE_FACTOR_OTHER_ALPHA Aother / 255 GR_COMBINE_FACTOR_LOCAL_ALPHA Alocal / 255 GR_COMBINE_FACTOR_DETAIL_FACTOR b GR_COMBINE_FACTOR_LOD_FRACTION GR_COMBINE_FACTOR_ONE 1 GR_COMBINE_FACTOR_ONE_MINUS_LOCA1 – Alocal / 255 GR_COMBINE_FACTOR_ONE_MINUS_OTHE1 – Aother / 255 GR_COMBINE_FACTOR_ONE_MINUS_LOCA1 – Alocal / 255 GR_COMBINE_FACTOR_ONE_MINUS_DETA1 – b TOR GR_COMBINE_FACTOR_ONE_MINUS_LOD_FRACTION 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 (Clocal and Alocal) and the filtered texel from the upstream T MU (Cother and Aother). 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 Clocal and Alocal are the color components generated by indexing and filtering from the mipmap stored on the selected TMU; Cother and Aother 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 2detailScale. 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: Cout = b*detail_texture + (1 – b)*main_texture Notes An LOD of n is calculated when a pixel covers approximately 22n 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 Alocal input is important because it is used in the color combine unit. The following table describes how Alocal and output alpha are computed based on the mode: mode Alpha Output Alocal GR_ALPHASOURCE_CC_ALPHA constant color constant alpha color alpha GR_ALPHASOURCE_ITERATED_ALPHA iterated iterated vertex alpha vertex alpha GR_ALPHASOURCE_TEXTURE_ALPHA texture alpha none GR_ALPHASOURCE_TEXTURE_ALPHA_TIMEtexture alphaPHAiterated * iterated vertex alpha alpha 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: Color Combine Function Effect GR_COLORCOMBINE_ZERO 0x00 per component GR_COLORCOMBINE_ITRGB Gouraud shading GR_COLORCOMBINE_DECAL_TEXTURE texture GR_COLORCOMBINE_TEXTURE_TIMES_CCRGflat-shaded texture using constant color (grConstantColorValue) as the shading value GR_COLORCOMBINE_TEXTURE_TIMES_ITRGGouraud-shaded texture GR_COLORCOMBINE_TEXTURE_TIMES_ITRGGouraud-shaded texture + alpha GR_COLORCOMBINE_TEXTURE_TIMES_ALPHtexture * alpha GR_COLORCOMBINE_TEXTURE_ADD_ITRGB texture + iterated RGB GR_COLORCOMBINE_TEXTURE_SUB_ITRGB texture – iterated RGB GR_COLORCOMBINE_CCRGB flat shading using constant color (grConstantColorValue) GR_COLORCOMBINE_CCRGB_BLEND_ITRGB_blend between constant color and iterated RGB using an alpha texture, where alpha of 0 and 1 correspond to constant color and iterated RGB respectively GR_COLORCOMBINE_DIFF_SPEC_A texture * alpha + iterated RGB GR_COLORCOMBINE_DIFF_SPEC_B texture * iterated RGB + alpha GR_COLORCOMBINE_ONE 0xFF per component 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. Clocal represents the color components generated by indexing and filtering from the mipmap stored on the selected TMU and Cother represents the incoming color componen ts from the neighboring TMU. Texture Combine Function Result Effect GR_TEXTURECOMBINE_ZERO 0 0x00 per component GR_TEXTURECOMBINE_DECAL Clocal decal texture GR_TEXTURECOMBINE_OTHER Cother pass through GR_TEXTURECOMBINE_ADD Cother + additive texture Clocal GR_TEXTURECOMBINE_MULTIPLCother * modulated texture Clocal GR_TEXTURECOMBINE_SUBTRACCother – subtractive Clocal texture GR_TEXTURECOMBINE_DETAIL blend detail textures (Cother, with detail on Clocal) selected TMU GR_TEXTURECOMBINE_DETAIL_blend detail textures (Cother, with detail on Clocal) neighboring TMU GR_TEXTURECOMBINE_TRILINEblendD LOD blended (Cother, textures with odd Clocal) levels on selected TMU GR_TEXTURECOMBINE_TRILINEblendEN LOD blended (Cother, textures with even Clocal) levels on selected TMU GR_TEXTURECOMBINE_ONE 255 0xFF per component guTexCombineFunction also keeps track of which TMUs require texture coordinates for the rendering routines. Notes Many combine functions that simultaneously use both Clocal and Cother 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