Home COM GDI+ WebBrowser Data Access 

PathGradientBrush Functions (GDI+)

 

 

The PathGradientBrush functions allow to set the attributes of a color gradient that you can use to fill the interior of a path with a gradually changing color. A path gradient brush has a boundary path, a boundary color, a center point, and a center color. When you paint an area with a path gradient brush, the color changes gradually from the boundary color to the center color as you move from the boundary path to the center point.

 

Return Values

If the function succeeds, it returns Ok, which is an element of the Status enumeration.

 

If the function fails, it returns one of the other elements of the Status enumeration.

 

GdipCreatePathGradient

 

Description

Creates a PathGradientBrush object based on an array of points.

Syntax

GpStatus WINGDIPAPI GdipCreatePathGradient(

    GDIPCONST GpPointF* points,

    INT count,

    GpWrapMode wrapMode,

    GpPathGradient **polyGradient

);

PowerBASIC Syntax

DECLARE FUNCTION GdipCreatePathGradient ( _

    BYREF pPoints AS PointF, _

    BYVAL count AS LONG, _

    BYVAL wrapMode AS LONG, _

    BYREF polyGradient AS DWORD _

) AS LONG

Parameters

 

points

[in] Pointer to an array of points that specifies the boundary path of the path gradient brush.

count

[in] Integer that specifies the number of elements in the points array.

wrapMode

[in] Element of the WrapMode enumeration that specifies how areas painted with the path gradient brush will be tiled. The default value is WrapModeClamp.

polyGradient

[out] Pointer to a variable that receives a pointer to the new PathGradientBrush object.

 

GdipCreatePathGradientFromPath

 

Description

Creates a PathGradientBrush object based on a GraphicsPath object.

Syntax

GpStatus WINGDIPAPI GdipCreatePathGradientFromPath(

    GDIPCONST GpPath* path,

    GpPathGradient **polyGradient

);

PowerBASIC Syntax

DECLARE FUNCTION GdipCreatePathGradientFromPath ( _

    BYVAL path AS DWORD, _

    BYREF polyGradient AS DWORD _

) AS LONG

Parameters

 

path

[in] Pointer to a GraphicsPath object that specifies the boundary path of the path gradient brush.

polyGradient

[out] Pointer to a variable that receives a pointer to the new PathGradientBrush object.

 

GdipCreatePathGradientI

 

Description

Creates a PathGradientBrush object based on an array of points.

Syntax

GpStatus WINGDIPAPI GdipCreatePathGradientI(

    GDIPCONST GpPoint* points,

    INT count,

    GpWrapMode wrapMode,

    GpPathGradient **polyGradient

);

PowerBASIC Syntax

DECLARE FUNCTION GdipCreatePathGradientI ( _

    BYREF pPoints AS PointL, _

    BYVAL count AS LONG, _

    BYVAL wrapMode AS LONG, _

    BYREF polyGradient AS DWORD _

) AS LONG

Parameters

 

points

[in] Pointer to an array of points that specifies the boundary path of the path gradient brush.

count

[in] Integer that specifies the number of elements in the points array.

wrapMode

[in] Element of the WrapMode enumeration that specifies how areas painted with the path gradient brush will be tiled. The default value is WrapModeClamp.

polyGradient

[out] Pointer to a variable that receives a pointer to the new PathGradientBrush object.

 

GdipGetPathGradientBlend

 

Description

Gets the blend factors and the corresponding blend positions currently set for this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientBlend(

    GpPathGradient *brush,

    REAL *blend,

    REAL *positions,

    INT count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientBlend ( _

    BYVAL brush AS DWORD, _

    BYREF blend AS SINGLE, _

    BYREF positions AS SINGLE, _

    BYVAL count AS LONG _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

blend

[out] Pointer to an array that receives the blend factors.

positions

[out] Pointer to an array that receives the blend positions.

count

[in] Integer that specifies the number of blend factors to retrieve. Before calling the GdipGetPathGradientBlend function, call the GdipGetPathGradientBlendCount function to determine the current number of blend factors. The number of blend positions retrieved is the same as the number of blend factors retrieved.

Remarks

A PathGradientBrush object has a boundary path and a center point. When you fill an area with a path gradient brush, the color changes gradually as you move from the boundary path to the center point. By default, the color is linearly related to the distance, but you can customize the relationship between color and distance by calling the GdipSetPathGradientBlend method.

 

GdipGetPathGradientBlendCount

 

Description

Gets the number of blend factors currently set for this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientBlendCount(

    GpPathGradient *brush,

    INT *count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientBlendCount ( _

    BYVAL brush AS DWORD, _

    BYREF count AS LONG _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

count

[out] Pointer to a variable that receives the number of blend factors currently set for this path gradient brush.

Remarks

Before you call the GdipGetPathGradientBlend function, you must allocate two buffers: one to receive an array of blend factors and one to receive an array of blend positions. To determine the size of the required buffers, call the GdipGetPathGradientBlendCount function. The size (in bytes) of each buffer should be the return value of GdipGetPathGradientBlendCount multiplied by sizeof(REAL) [4].

 

GdipGetPathGradientCenterColor

 

Description

Gets the color of the center point of this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientCenterColor(

    GpPathGradient *brush,

    ARGB* colors

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientCenterColor ( _

    BYVAL brush AS DWORD, _

    BYREF colors AS DWORD _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

colors

[out] Pointer to a variable that receives the color of the center point.

Remarks

By default, the center point of a PathGradientBrush object is the centroid of the brush's boundary path, but you can set the center point to any location, inside or outside the path, by calling the GdipSetPathGradientCenterPoint or GdipSetPathGradientCenterPointI functions.

 

GdipGetPathGradientCenterPoint

 

Description

Gets the center point of this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientCenterPoint(

    GpPathGradient *brush,

    GpPointF* points

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientCenterPoint ( _

    BYVAL brush AS DWORD, _

    BYREF pPoints AS PointF _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

points

[out] Pointer to a PointF structure that receives the center point.

Remarks

By default, the center point of a PathGradientBrush object is at the centroid of the brush's boundary path, but you can set the center point to any location, inside or outside the path, by calling the GdipSetPathGradientCenterPoint function.

 

GdipGetPathGradientCenterPointI

 

Description

Gets the center point of this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientCenterPointI(

    GpPathGradient *brush,

    GpPoint* points

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientCenterPointI ( _

    BYVAL brush AS DWORD, _

    BYREF pPoints AS PointL _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

points

[out] Pointer to a PointL structure that receives the center point.

Remarks

By default, the center point of a PathGradientBrush object is at the centroid of the brush's boundary path, but you can set the center point to any location, inside or outside the path, by calling the GdipSetPathGradientCenterPointtI function.

 

GdipGetPathGradientFocusScales

 

Description

Gets the focus scales of this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientFocusScales(

    GpPathGradient *brush,

    REAL* xScale,

    REAL* yScale

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientFocusScales ( _

    BYVAL brush AS DWORD, _

    BYREF xScale AS SINGLE, _

    BYREF yScale AS SINGLE _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

xScale

[out] Pointer to a variable that receives the x focus scale value.

yScale

[out] Pointer to a variable that receives the y focus scale value.

Remarks

By default, the center color of a path gradient is at the center point. By calling SetFocusScales, you can specify that the center color should appear along a path that surrounds the center point. For example, suppose the boundary path is a triangle and the center point is at the centroid of that triangle. Also assume that the boundary color is red and the center color is blue. If you set the focus scales to (0.2, 0.2), the color is blue along the boundary of a small triangle that surrounds the center point. That small triangle is the main boundary path scaled by a factor of 0.2 in the x direction and 0.2 in the y direction. When you paint with the path gradient brush, the color will change gradually from red to blue as you move from the boundary of the large triangle to the boundary of the small triangle. The area inside the small triangle will be filled with blue.

 

GdipGetPathGradientGammaCorrection

 

Description

Determines whether gamma correction is enabled for this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientGammaCorrection(

    GpPathGradient *brush,

    BOOL *useGammaCorrection

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientGammaCorrection ( _

    BYVAL brush AS DWORD, _

    BYREF useGammaCorrection AS LONG _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

useGammaCorrection

[out] Pointer to a variable that receives a boolean value that determines whether the gamma correction is enabled (TRUE) or not (FALSE).

 

GdipGetPathGradientPath

 

Description

Not implemented in Microsoft Windows GDI+ version 1.0.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientPath(

    GpPathGradient *brush,

    GpPath *path

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientPath ( _

    BYVAL brush AS DWORD, _

    BYREF path AS DWORD _

) AS LONG

Parameters

 

brush

[in] Pointer to a variable thatg receives a pointer to the PathGradientBrush object.

path

[out] Pointer to the GraphicsPath object.

 

GdipGetPathGradientPointCount

 

Description

Gets the number of points in the array of points that defines this brush's boundary path.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientPointCount(

    GpPathGradient *brush,

    INT* count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientPointCount ( _

    BYVAL brush AS DWORD, _

    BYREF count AS LONG _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

count

[out] Pointer that receives the number of points in the array of points that defines this brush's boundary path.

 

GdipGetPathGradientPresetBlend

 

Description

Gets the preset colors and blend positions currently specified for this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientPresetBlend(

    GpPathGradient *brush,

    ARGB *blend,

    REAL* positions,

    INT count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientPresetBlend ( _

    BYVAL brush AS DWORD, _

    BYREF blend AS DWORD, _

    BYREF positions AS SINGLE, _

    BYVAL count AS LONG _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

blend

[out] Pointer to an array that receives the preset colors. A color of a given index in the blend array corresponds to the blend position of that same index in the positions array.

positions

[out] Pointer to an array that receives the blend positions. Each blend position is a number from 0 through 1, where 0 indicates the boundary of the gradient and 1 indicates the center point. A blend position between 0 and 1 indicates the set of all points that are a certain fraction of the distance from the boundary to the center point. For example, a blend position of 0.7 indicates the set of all points that are 70 percent of the way from the boundary to the center point.

count

[in] Long integer that specifies the number of elements in the blend colors array. This is the same as the number of elements in the positions array.

Remarks

A simple path gradient brush has two colors: a boundary color and a center color. When you paint with such a brush, the color changes gradually from the boundary color to the center color as you move from the boundary path to the center point. You can create a more complex gradient by specifying an array of preset colors and an array of blend positions.

 

Before you call the GdipGetPathGradientPresetBlend function, you must allocate two buffers: one to hold the array of preset colors and one to hold the array of blend positions. You can call the GdipGetPathGradientPresetBlendCount function to determine the required size of those buffers. The size of the color buffer is the return value of GdipGetPathGradientPresetBlendCount multiplied by sizeof(Color) [4]. The size of the position buffer is the value of GdipGetPathGradientPresetBlendCount multiplied by sizeof( REAL) [4].

 

GdipGetPathGradientPresetBlendCount

 

Description

Gets the number of preset colors currently specified for this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientPresetBlendCount(

    GpPathGradient *brush,

    INT *count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientPresetBlendCount ( _

    BYVAL brush AS DWORD, _

    BYREF count AS LONG _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

count

[out] Pointer to a variable that receives the number of preset colors currently specified for this path gradient brush.

Remarks

A simple path gradient brush has two colors: a boundary color and a center color. When you paint with such a brush, the color changes gradually from the boundary color to the center color as you move from the boundary path to the center point. You can create a more complex gradient by specifying an array of preset colors and an array of blend positions.

 

You can obtain the interpolation colors and interpolation positions currently set for a PathGradientBrush object by calling the GdipGetPathGradientPresetBlend function. Before you call the GdipGetPathGradientPresetBlend function, you must allocate two buffers: one to hold the array of interpolation colors and one to hold the array of interpolation positions. You can call the GdipGetPathGradientPointCount function to determine the required size of those buffers. The size of the color buffer is the return value of GdipGetPathGradientPointCount multiplied by sizeof(Color) [4]. The size of the position buffer is the value of GdipGetPathGradientPointCount multiplied by sizeof( REAL) [4].

 

GdipGetPathGradientRect

 

Description

Gets the smallest rectangle that encloses the boundary path of this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientRect(

    GpPathGradient *brush,

    GpRectF *rect

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientRect ( _

    BYVAL brush AS DWORD, _

    BYREF pRect AS RectF _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

rect

[out] Pointer to a RectF structure that receives the bounding rectangle.

 

GdipGetPathGradientRectI

 

Description

Gets the smallest rectangle that encloses the boundary path of this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientRectI(

    GpPathGradient *brush,

    GpRect *rect

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientRectI ( _

    BYVAL brush AS DWORD, _

    BYREF pRect AS RectL _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

rect

[out] Pointer to a RectL structure that receives the bounding rectangle.

 

GdipGetPathGradientSurroundColorCount

 

Description

Gets the number of colors that have been specified for the boundary path of this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientSurroundColorCount(

    GpPathGradient *brush,

    INT* count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientSurroundColorCount ( _

    BYVAL brush AS DWORD, _

    BYREF count AS LONG _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

count

[out] Pointer to a variable thatg receives the number of colors that have been specified for the boundary path of this path gradient brush.

 

GdipGetPathGradientSurroundColorsWithCount

 

Description

Gets the surround colors currently specified for this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientSurroundColorsWithCount(

    GpPathGradient *brush,

    ARGB* colors,

    INT* count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientSurroundColorsWithCount ( _

    BYVAL brush AS DWORD, _

    BYREF pColors AS DWORD, _

    BYREF count AS LONG _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

color

[in] Pointer to an array that receives the surround colors.

count

[in, out] Pointer to a long integer that, on input, specifies the number of colors requested. If the method succeeds, this parameter, on output, receives the number of colors retrieved. If the method fails, this parameter does not receive a value.

 

GdipGetPathGradientTransform

 

Description

Gets transformation matrix of this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientTransform(

    GpPathGradient *brush,

    GpMatrix *matrix

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientTransform ( _

    BYVAL brush AS DWORD, _

    BYREF matrix AS DWORD _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

matrix

[out] Pointer to a variable that receives the transformation matrix.

Remarks

A PathGradientBrush object maintains a transformation matrix that can store any affine transformation. When you use a path gradient brush to fill an area, GDI+ transforms the brush's boundary path according to the brush's transformation matrix and then fills the interior of the transformed path. The transformed path exists only during rendering; the boundary path stored in PathGradientBrush object is not transformed.

 

GdipGetPathGradientWrapMode

 

Description

Gets the wrap mode currently set for this path gradient brush.

Syntax

GpStatus WINGDIPAPI GdipGetPathGradientWrapMode(

    GpPathGradient *brush,

    GpWrapMode *wrapmode

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetPathGradientWrapMode ( _

    BYVAL brush AS DWORD, _

    BYREF wrapMode AS LONG _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

wrapMode

[out] Pointer to a variable that receives an element of the WrapMode enumeration that indicates the wrap mode currently set for this path gradient brush.

Remarks

The bounding rectangle of a path gradient brush is the smallest rectangle that encloses the brush's boundary path. When you paint the bounding rectangle with the path gradient brush, only the area inside the boundary path gets filled. The area inside the bounding rectangle but outside the boundary path does not get filled.

 

The default wrap mode for a path gradient brush is WrapModeClamp, which indicates that no painting occurs outside of the brush's bounding rectangle. All of the other wrap modes indicate that areas outside the brush's bounding rectangle will be tiled. Each tile is a copy (possibly flipped) of the filled path inside its bounding rectangle.

 

GdipMultiplyPathGradientTransform

 

Description

Updates the brush's transformation matrix with the product of itself and another matrix.

Syntax

GpStatus WINGDIPAPI GdipMultiplyPathGradientTransform(

    GpPathGradient* brush,

    GDIPCONST GpMatrix *matrix,

    GpMatrixOrder order

);

PowerBASIC Syntax

DECLARE FUNCTION GdipMultiplyPathGradientTransform ( _

    BYVAL brush AS DWORD, _

    BYVAL matrix AS DWORD, _

    BYVAL order AS LONG _

) AS LONG

Parameters

 

brush

[in] Pointer to the PathGradientBrush object.

matrix

[in] Pointer to the matrix that will be multiplied by the brush's current transformation matrix.