PathGradientBrush::GetBlend method (gdipluspath.h)

Article
10/13/2021

The PathGradientBrush::GetBlend method gets the blend factors and the corresponding blend positions currently set for this path gradient brush.

Syntax

Status GetBlend(
  [out] REAL *blendFactors,
  [out] REAL *blendPositions,
  [in]  INT  count
);

Parameters

[out] blendFactors

Type: REAL*

Pointer to an array that receives the blend factors.

[out] blendPositions

Type: REAL*

Pointer to an array that receives the blend positions.

[in] count

Type: INT

Integer that specifies the number of blend factors to retrieve. Before calling the PathGradientBrush::GetBlend method of a PathGradientBrush object, call the PathGradientBrush::GetBlendCount method of that same PathGradientBrush object to determine the current number of blend factors. The number of blend positions retrieved is the same as the number of blend factors retrieved.

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 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 PathGradientBrush::SetBlend method.

Examples

The following example demonstrates several methods of the PathGradientBrush class including PathGradientBrush::SetBlend, PathGradientBrush::GetBlendCount, and PathGradientBrush::GetBlend. The code creates a PathGradientBrush object and calls the PathGradientBrush::SetBlend method to establish a set of blend factors and blend positions for the brush. Then the code calls the PathGradientBrush::GetBlendCount method to retrieve the number of blend factors. After the number of blend factors is retrieved, the code allocates two buffers: one to receive the array of blend factors and one to receive the array of blend positions. Then the code calls the PathGradientBrush::GetBlend method to retrieve the blend factors and the blend positions.

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

   // Create a path that consists of a single ellipse.
   GraphicsPath path;
   path.AddEllipse(0, 0, 200, 100);

   // Use the path to construct a brush.
   PathGradientBrush pthGrBrush(&path);

   // Set the color at the center of the path to blue.
   pthGrBrush.SetCenterColor(Color(255, 0, 0, 255));

   // Set the color along the entire boundary of the path to aqua.
   Color colors[] = {Color(255, 0, 255, 255)};
   INT count = 1;
   pthGrBrush.SetSurroundColors(colors, &count);

   // Set blend factors and positions for the path gradient brush.
   REAL fac[] = {
      0.0f, 
      0.4f,     // 40 percent of the way from aqua to blue
      0.8f,     // 80 percent of the way from aqua to blue
      1.0f};

   REAL pos[] = {
      0.0f, 
      0.3f,   // 30 percent of the way from the boundary to the center
      0.7f,   // 70 percent of the way from the boundary to the center
      1.0f};

   pthGrBrush.SetBlend(fac, pos, 4);

   // Fill the ellipse with the path gradient brush.
   graphics.FillEllipse(&pthGrBrush, 0, 0, 200, 100);

   // Obtain information about the path gradient brush.
   INT blendCount = pthGrBrush.GetBlendCount();
   REAL* factors = new REAL[blendCount];
   REAL* positions = new REAL[blendCount];

   pthGrBrush.GetBlend(factors, positions, blendCount);

   for(INT j = 0; j < blendCount; ++j)
   {
      // Inspect or use the value in factors[j].
      // Inspect or use the value in positions[j].    
   }

   delete [] factors;
   delete [] positions; 
}

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