ID2D1RadialGradientBrush interface (d2d1.h)

Article
08/03/2021

Paints an area with a radial gradient.

Inheritance

The ID2D1RadialGradientBrush interface inherits from ID2D1Brush. ID2D1RadialGradientBrush also has these types of members:

Methods

Methods

The ID2D1RadialGradientBrush interface has these methods.


ID2D1RadialGradientBrush::GetCenter Retrieves the center of the gradient ellipse.
ID2D1RadialGradientBrush::GetGradientOriginOffset Retrieves the offset of the gradient origin relative to the gradient ellipse's center.
ID2D1RadialGradientBrush::GetGradientStopCollection Retrieves the ID2D1GradientStopCollection associated with this radial gradient brush object.
ID2D1RadialGradientBrush::GetRadiusX Retrieves the x-radius of the gradient ellipse.
ID2D1RadialGradientBrush::GetRadiusY Retrieves the y-radius of the gradient ellipse.
ID2D1RadialGradientBrush::SetCenter Specifies the center of the gradient ellipse in the brush's coordinate space.
ID2D1RadialGradientBrush::SetGradientOriginOffset Specifies the offset of the gradient origin relative to the gradient ellipse's center.
ID2D1RadialGradientBrush::SetRadiusX Specifies the x-radius of the gradient ellipse, in the brush's coordinate space.
ID2D1RadialGradientBrush::SetRadiusY Specifies the y-radius of the gradient ellipse, in the brush's coordinate space.

Remarks

The ID2D1RadialGradientBrush is similar to the ID2D1LinearGradientBrush in that they both map a collection of gradient stops to a gradient. However, the linear gradient has a start and an end point to define the gradient vector, while the radial gradient uses an ellipse and a gradient origin to define its gradient behavior. To define the position and size of the ellipse, use the SetCenter, SetRadiusX, and SetRadiusY methods to specify the center, x-radius, and y-radius of the ellipse. The gradient origin is the center of the ellipse, unless a gradient offset is specified by using the SetGradientOriginOffset method.

The brush maps the gradient stop position 0.0f of the gradient origin, and the position 1.0f is mapped to the ellipse boundary. When the gradient origin is within the ellipse, the contents of the ellipse enclose the entire [0, 1] range of the brush gradient stops. If the gradient origin is outside the bounds of the ellipse, the brush still works, but its gradient is not well-defined.

The start point and end point are described in the brush space and are mapped to the render target when the brush is used. Note the starting and ending coordinates are absolute, not relative to the render target size. A value of (0, 0) maps to the upper-left corner of the render target, while a value of (1, 1) maps just one pixel diagonally away from (0, 0). If there is a nonidentity brush transform or render target transform, the brush ellipse and gradient origin are also transformed.

It is possible to specify an ellipse that does not completely fill area being painted. When this occurs, the D2D1_EXTEND_MODE and setting (specified by the brush ID2D1GradientStopCollection) determines how the remaining area is painted.

Creating ID2D1RadialGradientBrush Objects

To create a radial gradient brush, use the ID2D1RenderTarget::CreateRadialGradientBrush method of the render target on which the brush will be used. The brush may be used only with the render target that created it or with the compatible targets for that render target.

A radial gradient brush is a device-dependent resource: your application should create radial gradient brushes after it initializes the render target with which the brushes will be used, and recreate the brushes whenever the render target needs recreated. (For more information about resources, see Resources Overview.)

Examples

For an example on how to create a radial gradient brush, see the How to Create a Radial Gradient Brush topic.

Requirements

Requirement	Value
Minimum supported client	Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	d2d1.h