IXpsOMGradientStop interface

Represents a single color and location within a gradient.

When to implement

Never. Custom implementation of this interface is not supported.

Members

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

• Methods

Methods

The IXpsOMGradientStop interface has these methods.

Remarks

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.

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.

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(
    __uuidof(XpsOMObjectFactory),
    NULL,
    CLSCTX_INPROC_SERVER,
    _uuidof(IXpsOMObjectFactory),
    reinterpret_cast<LPVOID*>(&xpsFactory)
    );

if (SUCCEEDED(hr))
{
    hr = xpsFactory->CreateGradientStop (
        &color,
        colorProfile,
        offset,
        &newInterface);

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

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

Requirements

See also

IXpsOMObjectFactory::CreateGradientStop

Interfaces

IXpsOMGradientBrush

XML Paper Specification