DrvGradientFill

The DrvGradientFill function shades the specified primitives.

BOOL
  DrvGradientFill(
    IN SURFOBJ  *psoDest,
    IN CLIPOBJ  *pco,
    IN XLATEOBJ  *pxlo,
    IN TRIVERTEX  *pVertex,
    IN ULONG  nVertex,
    IN PVOID  pMesh,
    IN ULONG  nMesh,
    IN RECTL  *prclExtents,
    IN POINTL  *pptlDitherOrg,
    IN ULONG  ulMode
    );

Parameters

psoDest

Pointer to the SURFOBJ structure that identifies the surface on which to draw.

pco

Pointer to a CLIPOBJ structure . The CLIPOBJ_Xxx service routines are provided to enumerate the clip region as a set of rectangles. This enumeration limits the area of the destination that is modified. Whenever possible, GDI simplifies the clipping involved.

pxlo

Pointer to a XLATEOBJ structure. This parameter should be ignored by the driver.

pVertex

Pointer to an array of TRIVERTEX structures, with each entry containing position and color information. The TRIVERTEX structure is described in the Platform SDK documentation.

nVertex

Specifies the number of TRIVERTEX structures in the array to which pVertex points.

pMesh

Pointer to an array of structures that define the connectivity of the TRIVERTEX elements to which pVertex points.

When rectangles are being drawn, pMesh points to an array of GRADIENT_RECT structures, each of which specifies two TRIVERTEX elements that define a rectangle. The TRIVERTEX elements can represent any diagonally-opposed pair of rectangle vertices. Rectangle drawing is lower-right exclusive. Both TRIVERTEX and GRADIENT_RECT are defined in the Platform SDK documentation.

When triangles are being drawn, pMesh points to an array of GRADIENT_TRIANGLE structures, each of which specifies the three TRIVERTEX elements that define a triangle. Triangle drawing is lower-right exclusive. GRADIENT_TRIANGLE is defined in the Platform SDK documentation.

nMesh

Specifies the number of elements in the array to which pMesh points.

prclExtents

Pointer to a RECTL structure that defines the area in which the gradient drawing is to occur. The points are specified in the coordinate system of the destination surface. This parameter is useful in estimating the size of the drawing operations.

pptlDitherOrg

Pointer to a POINTL structure that defines the origin on the surface for dithering. The upper left pixel of the dither pattern is aligned with this point.

ulMode

Specifies the current drawing mode and how to interpret the array to which pMesh points. This parameter can be one of the following values:

GRADIENT_FILL_RECT_H

The pMesh parameter points to an array of GRADIENT_RECT structures. Each rectangle is to be shaded from left to right. Specifically, the upper-left and lower-left pixels are the same color, as are the upper-right and lower-right pixels.

GRADIENT_FILL_RECT_V

The pMesh parameter points to an array of GRADIENT_RECT structures. Each rectangle is to be shaded from top to bottom. Specifically, the upper-left and upper-right pixels are the same color, as are the lower-left and lower-right pixels.

GRADIENT_FILL_TRIANGLE

The pMesh parameter points to an array of GRADIENT_TRIANGLE structures.

The gradient fill calculations for each mode are documented in the Comments section.

Return Value

DrvGradientFill returns TRUE upon success. Otherwise, it returns FALSE and reports an error by calling EngSetLastError.

Headers

Declared in winddi.h. Include winddi.h.

Comments

DrvGradientFill can be optionally implemented in graphics drivers. GDI never calls this function for palletized surfaces.

The driver hooks DrvGradientFill by setting the HOOK_GRADIENTFILL flag when it calls EngAssociateSurface or EngModifySurface. If the driver has hooked DrvGradientFill and is called to perform an operation that it does not support, the driver should have GDI handle the operation by punting the data in a call to EngGradientFill.

GDI will not call DrvGradientFill for 8bpp destination surfaces.

The formulas for computing the color value at each pixel of the primitive depend on ulMode as follows:

GRADIENT_FILL_TRIANGLE

The triangle's vertices are defined as V₁, V₂, and V₃. Point P is inside the triangle. Draw lines from P to V₁, V₂, and V₃ to form three sub-triangles. Let a_i denote the area of the triangle opposite V_i for i=1,2,3. The color at point P is computed as:

RedP   = (RedV1 * a1 + RedV2 * a2 + RedV3 * a3) / (a1+a2+a3)
GreenP = (GreenV1 * a1 + GreenV2 * a2 + GreenV3 * a3) / (a1+a2+a3)
BlueP  = (BlueV1 * a1 + BlueV2 * a2 + BlueV3 * a3) / (a1+a2+a3)

GRADIENT_FILL_RECT_H

The rectangle's top-left point is V₁ and the bottom-right point is V₂. Point P is inside the rectangle. The color at point P is given by:

RedP =   (RedV2 * (Px - V1x) + RedV1 * (V2x - Px)) / (V2x-V1x)
GreenP = (GreenV2 * (Px - V1x) + GreenV1 * (V2x - Px)) / (V2x-V1x)
BlueP =  (BlueV2 * (Px - V1x) + BlueV1 * (V2x - Px)) / (V2x-V1x)

GRADIENT_FILL_RECT_V

The rectangle's top-left point is V₁ and the bottom-right point is V₂. Point P is inside the rectangle. The color at point P is given by:

RedP   = (RedV2 * (Py-V1y) + RedV1 * (V2y - Py)) / (V2y-V1y)
GreenP = (GreenV2 * (Py-V1y) + GreenV1 * (V2y - Py)) / (V2y-V1y)
BlueP  = (BlueV2 * (Py-V1y) + BlueV1 * (V2y - Py)) / (V2y-V1y)

The total error accumulated over all three color channels must not be more than eight (8). For more information about permissible error, see Special Effects in Display Drivers.

The driver should ignore the alpha value of the vertices, leaving the alpha channel unchanged for surfaces that support alpha blending.

See Also

EngAssociateSurface, EngGradientFill