GradientFill

[This is preliminary documentation and subject to change.]

The GradientFill function fills rectangle and triangle structures.

BOOL GradientFill(
  HDC hdc,
  CONST PTRIVERTEX pVertex,
  DWORD dwNumVertex,
  CONST PVOID pMesh,
  DWORD dwNumMesh,
  DWORD dwMode
); 
 

Parameters

hdc

Handle to the destination device context.

pVertex

Pointer to an array of TRIVERTEX structures that each define a triangle vertex.

dwNumVertex

Number of vertices.

pMesh

Array of GRADIENT_TRIANGLE structures in triangle mode, or an array of GRADIENT_RECT structures in rectangle mode.

dwNumMesh

The number of elements (triangles or rectangles) in pMesh.

dwMode

Specifies gradient fill mode. This parameter can contain one of the following values.

Value	Meaning
GRADIENT_FILL_RECT_H	In this mode, two endpoints describe a rectangle. The rectangle is defined to have a constant color (specified by the TRIVERTEX structure) for the left and right edges. GDI interpolates the color from the top to bottom edge and fills the interior.
GRADIENT_FILL_RECT_V	In this mode, two endpoints describe a rectangle. The rectangle is defined to have a constant color (specified by the TRIVERTEX structure) for the top and bottom edges. GDI interpolates the color from the top to bottom edge and fills the interior.
GRADIENT_FILL_TRIANGLE	In this mode, an array of TRIVERTEX structures is passed to GDI along with a list of array indexes that describe separate triangles. GDI performs linear interpolation between triangle vertices and fills the interior. Drawing is done directly in 24- and 32-bit-per-pixel modes. Dithering is performed in 16-, 8.4-, and 1-bit-per-pixel mode.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Windows NT: To get extended error information, call GetLastError.

Remarks

To add smooth shading to a triangle, call the GradientFill function with the three triangle endpoints. GDI will linearly interpolate and fill the triangle.

To add smooth shading to a rectangle, call GradientFill with the upper-left and lower-right coordinates of the rectangle. There are two shading modes used when drawing a rectangle. In horizontal mode, the rectangle is shaded from left to right. In vertical mode, the rectangle is shaded from top to bottom.

The GradientFill function uses a mesh method to specify the endpoints of the object to draw. All vertices are passed to GradientFill in the pVertex array. The pMesh parameter specifies how these vertices are connected to form an object. When filling a rectangle, pMesh points to an array of GRADIENT_RECT structures. Each GRADIENT_RECT structure specifies the index of two vertices in the pVertex array. These two vertices form the upper-left and lower-right boundary of one rectangle.

In the case of filling a triangle, pMesh points to an array of GRADIENT_TRIANGLE structures. Each GRADIENT_TRIANGLE structure specifies the index of three vertices in the pVertex array. These three vertices form one triangle.

In order to simplify hardware acceleration, this routine is not required to be pixel-perfect in the triangle interior.

For more information, see Smooth Shading, Drawing a Shaded Triangle, and Drawing a Shaded Rectangle.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Requires Windows 98 or later.
  Windows CE: Unsupported.
  Header: Declared in wingdi.h.
  Import Library: Included as a resource in msimg32.dll.

See Also

Bitmaps Overview, Bitmap Functions, EMRGRADIENTFILL, GRADIENT_RECT, GRADIENT_TRIANGLE, TRIVERTEX