PathGradientBrush::SetTransform method (gdipluspath.h)

Article
10/13/2021

The PathGradientBrush::SetTransform method sets the transformation matrix of this path gradient brush.

Syntax

Status SetTransform(
  [in] const Matrix *matrix
);

Parameters

[in] matrix

Type: const Matrix*

Pointer to a Matrix object that specifies the transformation matrix.

Return value

Type: Status

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

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

Remarks

A PathGradientBrush object has a GraphicsPath object that serves as the boundary path for the brush. When you paint with a path gradient brush, only the area inside the boundary path is filled. If the brush's transformation matrix is set to represent any transformation other than the identity, then the boundary path is transformed according to that matrix during rendering, and only the area inside the transformed path is filled.

The transformation applies only during rendering. The boundary path stored by the PathGradientBrush object is not altered by the PathGradientBrush::SetTransform method.

Examples

The following example creates a PathGradientBrush object based on a triangular path. The Graphics::FillRectangle method uses the path gradient brush to paint a rectangle that contains the triangular path. Next, the code creates a Matrix object that represents a composite transformation (rotate, then translate) and passes the address of that Matrix object to the PathGradientBrush::SetTransform method of the PathGradientBrush object. The code calls FillRectangle a second time to paint the same rectangle using the transformed path gradient brush.

VOID Example_SetTransform(HDC hdc)
{
   Graphics graphics(hdc);

   Point pts[] = {
      Point(0, 0), 
      Point(100, 0), 
      Point(100, 100)};

   Color cols[] = {
      Color(255, 255, 0, 0),  // red
      Color(255, 0, 255, 0),  // green
      Color(255, 0, 0, 0)};   // black

   INT count = 3;
   PathGradientBrush pthGrBrush(pts, 3);
   pthGrBrush.SetSurroundColors(cols, &count);

   // Fill an area with the path gradient brush (no transformation).
   graphics.FillRectangle(&pthGrBrush, 0, 0, 200, 200);

   // Set the transformation for the brush (rotate, then translate).
   Matrix matrix(0.0f, 1.0f, -1.0f, 0.0f, 150.0f, 60.0f);
   pthGrBrush.SetTransform(&matrix);
   
   // Fill the same area with the transformed path gradient brush.
   graphics.FillRectangle(&pthGrBrush, 0, 0, 200, 200);  
}

Requirements

Requirement	Value
Minimum supported client	Windows XP, Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	gdipluspath.h (include Gdiplus.h)
Library	Gdiplus.lib
DLL	Gdiplus.dll