Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

ID2D1DeviceContext::CreateGradientStopCollection method

Creates a gradient stop collection, enabling the gradient to contain color channels with values outside of [0,1] and also enabling rendering to a high-color render target with interpolation in sRGB space.

Syntax


HRESULT CreateGradientStopCollection(
  const D2D1_GRADIENT_STOP *gradientStops,
  UINT gradientStopsCount,
  D2D1_COLOR_SPACE preInterpolationSpace,
  D2D1_COLOR_SPACE postInterpolationSpace,
  D2D1_BUFFER_PRECISION bufferPrecision,
  D2D1_EXTEND_MODE extendMode,
  D2D1_COLOR_INTERPOLATION_MODE colorInterpolationMode,
  [out]  ID2D1GradientStopCollection1 **gradientStopCollection
);

Parameters

gradientStops

Type: const D2D1_GRADIENT_STOP*

An array of color values and offsets.

gradientStopsCount

Type: UINT

The number of elements in the gradientStops array.

preInterpolationSpace

Type: D2D1_COLOR_SPACE

Specifies both the input color space and the space in which the color interpolation occurs.

postInterpolationSpace

Type: D2D1_COLOR_SPACE

The color space that colors will be converted to after interpolation occurs.

bufferPrecision

Type: D2D1_BUFFER_PRECISION

The precision of the texture used to hold interpolated values.

Note  This method will fail if the underlying Direct3D device does not support the requested buffer precision. Use ID2D1DeviceContext::IsBufferPrecisionSupported to determine what is supported.

extendMode

Type: D2D1_EXTEND_MODE

Defines how colors outside of the range defined by the stop collection are determined.

colorInterpolationMode

Type: D2D1_COLOR_INTERPOLATION_MODE

Defines how colors are interpolated. D2D1_COLOR_INTERPOLATION_MODE_PREMULTIPLIED is the default, see Remarks for more info.

gradientStopCollection [out]

Type: ID2D1GradientStopCollection1**

The new gradient stop collection.

Return value

Type: HRESULT

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

HRESULTDescription
S_OKNo error occurred.
E_OUTOFMEMORYDirect2D could not allocate sufficient memory to complete the call.
E_INVALIDARGAn invalid value was passed to the method.

 

Remarks

This method linearly interpolates between the color stops. An optional color space conversion is applied post-interpolation. Whether and how this gamma conversion is applied is determined by the pre- and post-interpolation. This method will fail if the device context does not support the requested buffer precision.

In order to get the desired result, you need to ensure that the inputs are specified in the correct color space.

You must always specify colors in straight alpha, regardless of interpolation mode being premultiplied or straight. The interpolation mode only affects the interpolated values. Likewise, the stops returned by ID2D1GradientStopCollection::GetGradientStops will always have straight alpha.

If you specify D2D1_COLOR_INTERPOLATION_MODE_PREMULTIPLIED, then all stops are premultiplied before interpolation, and then un-premultiplied before color conversion.

Starting with Windows 8, the interpolation behavior of this method has changed.

The table here shows the behavior in Windows 7 and earlier.

GammaBefore Interpolation BehaviorAfter Interpolation BehaviorGetColorInteroplationGamma (output color space)
1.0Clamps the inputs and then converts from sRGB to scRGB.Converts from scRGB to sRGB post-interpolation.1.0
2.2Clamps the inputs.No Operation2.2

 

The table here shows the behavior in Windows 8 and later.

GammaBefore Interpolation BehaviorAfter Interpolation BehaviorGetColorInteroplationGamma (output color space)
sRGB to scRGBNo OperationClamps the outputs and then converts from sRGB to scRGB.1.0
scRGB to sRGBNo OperationClamps the outputs and then converts from sRGB to scRGB.2.2
sRGB to sRGBNo OperationNo Operation2.2
scRGB to scRGBNo OperationNo Operation1.0

 

Requirements

Minimum supported client

Windows 8 and Platform Update for Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2012 and Platform Update for Windows Server 2008 [desktop apps | Windows Store apps]

Minimum supported phone

Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps]

Header

D2d1_1.h

DLL

D2d1.dll

See also

ID2D1DeviceContext
ID2D1GradientStopCollection1
ID2D1RenderTarget::CreateGradientStopCollection
D2D1_GRADIENT_STOP
D2D1_GAMMA_CONVERSION
D2D1_BUFFER_PRECISION
D2D1_EXTEND_MODE

 

 

Community Additions

Show:
© 2014 Microsoft