Export (0) Print
Expand All

IXpsOMGradientStop interface

Represents a single color and location within a gradient.

When to implement

Never. Custom implementation of this interface is not supported.


The IXpsOMGradientStop interface inherits from the IUnknown interface. IXpsOMGradientStop also has these types of members:


The IXpsOMGradientStop interface has these methods.


Makes a deep copy of the IXpsOMGradientStop interface.


Gets the color value and color profile of the gradient stop.


Gets the offset value of the gradient stop.


Gets a pointer to the IXpsOMGradientBrush interface that contains the gradient stop.


Sets the color value and color profile of the gradient stop.


Sets the offset location of the gradient stop.



A gradient stop is a specific color that is defined for a location within the gradient region. The color of the gradient changes between the gradient stops of the gradient. The area and absolute location of the gradient is defined by the gradient interface. The offset is a relative location within the gradient region and is measured between 0.0 and 1.0. An offset of 0.0 is the beginning of the gradient and 1.0 is the end. Gradient stops can be defined for any offset within the range, including the end points. This interface describes one and only one stop in a gradient.

The gradient path is the straight line that connects the start point and the end point of a linear gradient. The gradient region of a linear gradient consists of the area between the start point and the end point, including those points, and extends in both directions at a right angle to the gradient path. The spread area is the area outside the gradient region.

Gradient stops define the color at a specific location along the gradient path; the color is interpolated along the gradient path between the gradient stops. In the example that follows, the gradient region fills the image, so there is no spread area.

For gradient stops used in linear-gradient brushes, the offset value of 0.0 corresponds to the start point of the gradient path, and the offset value of 1.0 corresponds to the end point. To determine the location of a gradient stop between these two points, intermediate offset values are interpolated between them. The following illustration shows two intermediate gradient stops, one at an offset of 0.25 and another at 0.75.

A figure that shows the terms used in a linear gradient

For gradient stops used in radial-gradient brushes, the offset value of 0.0 corresponds to the gradient origin location, and the offset value of 1.0 corresponds to the circumference of the ellipse that bounds the gradient. Offsets between 0.0 and 1.0 define an ellipse that is interpolated between the gradient origin and the bounding ellipse. The illustration that follows has one intermediate gradient stop at an offset of 0.50 (Gradient stop 1). The gradient is using the XPS_SPREAD_METHOD_REFLECT spread method to fill the space outside of the gradient region.

A figure that shows the terms used in a radial gradient

The calculations that are used to render a gradient are described in the XML Paper Specification.

The code example that follows illustrates how to create an instance of this interface.

IXpsOMGradientStop    *newInterface;
// The following values are defined outside of 
// this example.
//  XPS_COLOR                    color;
//  IXpsOMColorProfileResource    *colorProfile;
//  FLOAT                        offset;

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

hr = CoCreateInstance(

if (SUCCEEDED(hr))
    hr = xpsFactory->CreateGradientStop (

    if (SUCCEEDED(hr))
        // use newInterface

    // evaluate HRESULT error returned in hr


Minimum supported client

Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps | Windows Store apps]





See also

XML Paper Specification



Community Additions

© 2014 Microsoft