IXpsOMObjectFactory::CreateRadialGradientBrush method (xpsobjectmodel.h)

Article
10/13/2021

Creates an IXpsOMRadialGradientBrush interface.

Syntax

HRESULT CreateRadialGradientBrush(
  [in]          IXpsOMGradientStop        *gradStop1,
  [in]          IXpsOMGradientStop        *gradStop2,
  [in]          const XPS_POINT           *centerPoint,
  [in]          const XPS_POINT           *gradientOrigin,
  [in]          const XPS_SIZE            *radiiSizes,
  [out, retval] IXpsOMRadialGradientBrush **radialGradientBrush
);

Parameters

[in] gradStop1

The IXpsOMGradientStop interface that specifies the properties of the gradient at gradient origin. This parameter must not be NULL.

[in] gradStop2

The IXpsOMGradientStop interface that specifies the properties of the gradient at the end of the gradient's vector, which is the ellipse that encloses the gradient region. This parameter must not be NULL.

[in] centerPoint

The coordinates of the center point of the radial gradient ellipse.

[in] gradientOrigin

The coordinates of the origin of the radial gradient.

[in] radiiSizes

The XPS_SIZE structure whose members specify the lengths of the gradient region's radii.

Size is described in XPS units. There are 96 XPS units per inch. For example, a 1" radius is 96 XPS units.

XPS_SIZE Member	Meaning
width	Length of the radius along the x-axis.
height	Length of the radius along the y-axis.

[out, retval] radialGradientBrush

A pointer to the new IXpsOMRadialGradientBrush interface.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the table that follows. For information about XPS document API return values that are not listed in this table, see XPS Document Errors.

Return code	Description
S_OK	The method succeeded.
E_INVALIDARG	The point that is described by centerPoint, radiiSizes, or gradientOrigin is not valid. The members of the XPS_POINT structure must contain valid and finite floating-point values.
E_POINTER	gradStop1, gradStop2, centerPoint, gradientOrigin, radiiSizes, or radialGradientBrush is NULL.
XPS_E_NO_CUSTOM_OBJECTS	gradStop1 or gradStop1 does not point to a recognized interface implementation. Custom implementation of XPS Document API interfaces is not supported.

Remarks

As shown in the following illustration, the gradient region of a radial gradient is the area enclosed by the ellipse that is described by the center point and the x and y radii that extend from the center point. The spread area is the area outside of that ellipse. The gradient path (not shown) is a radial line that is drawn between the gradient origin and the ellipse that bounds the gradient region.

A figure that shows the terms used in a radial gradient

For radial-gradient brushes, the gradient stop that is set by the gradStop1 parameter corresponds to the gradient origin location and an offset value of 0.0. The gradient stop that is set by the gradStop2 parameter corresponds to the circumference of the gradient region and an offset value of 1.0. For more information on gradient stops, see IXpsOMGradientStop.

The code example that follows illustrates how this method is used to create a new interface.


IXpsOMRadialGradientBrush    *newInterface;
// The following values are defined outside of 
// this example.
//  IXpsOMGradientStop       *gradStop1, *gradStop2;
//  XPS_POINT                centerPoint, gradientOrigin;
//  XPS_SIZE                 radiiSizes;

// Note the implicit requirement that CoInitializeEx 
//  has previously been called from this thread.

hr = CoCreateInstance(
    __uuidof(XpsOMObjectFactory),
    NULL,
    CLSCTX_INPROC_SERVER,
    _uuidof(IXpsOMObjectFactory),
    reinterpret_cast<LPVOID*>(&xpsFactory)
    );

if (SUCCEEDED(hr))
{
    hr = xpsFactory->CreateRadialGradientBrush (
        gradStop1,
        gradStop2,
        &centerPoint,
        &gradientOrigin,
        &radiiSizes,
        &newInterface);

    if (SUCCEEDED(hr))
    {
        // use newInterface

        newInterface->Release();
    }
    xpsFactory->Release();
}
else
{
    // evaluate HRESULT error returned in hr
}

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	xpsobjectmodel.h