Edit

Share via

Bitmap source effect

  • Article

Use the bitmap source effect to generate an ID2D1Image from a IWICBitmapSource for use as an input in an effect graph. This effect performs scaling and rotation on the CPU. It can also optionally generate a system memory mipmap, which can be a performance optimization for actively scaling very large images at various reduced resolutions.

Note

The bitmap source effect takes its input as a property, not as an image input. You must use the SetValue method, not the SetInput method. The WicBitmapSource property is where you specify the image input data.

The CLSID for this effect is CLSID_D2D1BitmapSource.

Effect properties

Display name and index enumeration Description
WicBitmapSource
D2D1_BITMAPSOURCE_PROP_WIC_BITMAP_SOURCE
 The IWICBitmapSource containing the image data to be loaded.
The type is IWICBitmapSource.
The default value is NULL.
Scale
D2D1_BITMAPSOURCE_PROP_SCALE
 The scale amount in the X and Y direction. The effect multiplies the width by the X value and the height by the Y value. This property is a D2D1_VECTOR_2F defined as: (X scale, Y scale). The scale amounts are FLOAT, unitless, and must be positive or 0.
The type is D2D1_VECTOR_2F.
The default value is {1.0f, 1.0f}.
InterpolationMode.
D2D1_BITMAPSOURCE_PROP_INTERPOLATION_MODE
 The interpolation mode used to scale the image. See Interpolation modes for more info.
If the mode disables the mipmap, then BitmapSouce will cache the image at the resolution determined by the Scale and EnableDPICorrection properties.
The type is D2D1_BITMAPSOURCE_INTERPOLATION_MODE.
The default value is D2D1_BITMAPSOURCE_INTERPOLATION_MODE_LINEAR.
EnableDPICorrection
D2D1_BITMAPSOURCE_PROP_ENABLE_DPI_CORRECTION
 If you set this to TRUE, the effect will scale the input image to convert the DPI reported by IWICBitmapSource to the DPI of the device context. The effect uses the interpolation mode you set with the InterpolationMode property. If you set this to FALSE, the effect uses a DPI of 96.0 for the output image.
The type is BOOL.
The default value is FALSE.
AlphaMode
D2D1_BITMAPSOURCE_PROP_ALPHA_MODE
 The alpha mode of the output. This can be either premultiplied or straight. See Alpha modes for more info.
The type is D2D1_BITMAPSOURCE_ALPHA_MODE.
The default value is D2D1_BITMAPSOURCE_ALPHA_MODE_PREMULTIPLIED.
Orientation
D2D1_BITMAPSOURCE_PROP_ORIENTATION
 A flip and/or rotation operation to be performed on the image. See Orientation for more info.
The type is D2D1_BITMAPSOURCE_ORIENTATION.
The default value is D2D1_BITMAPSOURCE_ORIENTATION_DEFAULT.

Interpolation modes

The effect interpolates using this mode when it scales an image or when it corrects the DPI. The interpolation modes this effect uses are calculated by the CPU, not the GPU.

Name Description
D2D1_BITMAPSOURCE_INTERPOLATION_MODE_NEAREST_NEIGHBOR Samples the nearest single point and uses that. Doesn't generate a mipmap.
D2D1_BITMAPSOURCE_INTERPOLATION_MODE_LINEAR Uses a four point sample and linear interpolation. Doesn't generate a mipmap.
D2D1_BITMAPSOURCE_INTERPOLATION_MODE_CUBIC Uses a 16 sample cubic kernel for interpolation. Doesn't generate a mipmap.
D2D1_BITMAPSOURCE_INTERPOLATION_MODE_FANT Uses the WIC fant interpolation, the same as the IWICBitmapScaler interface. Doesn't generate a mipmap.
D2D1_BITMAPSOURCE_INTERPOLATION_MODE_MIPMAP_LINEAR Generates mipmap chain in system memory using bilinear interpolation. For each mipmap the effect scales to the nearest multiple of 0.5 using bilinear interpolation and then scales the remaining amount using linear interpolation.

Orientation

The Orientation property can be used to apply an EXIF orientation flag that is embedded within an image.

Name Description
D2D1_BITMAPSOURCE_ORIENTATION_DEFAULT Default. The effect doesn't change the orientation of the input.
D2D1_BITMAPSOURCE_ORIENTATION_FLIP_HORIZONTAL Flips the image horizontally.
D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE180 Rotates the image clockwise 180 degrees.
D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE180_FLIP_HORIZONTAL Rotates the image clockwise 180 degrees and flips it horizontally.
D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE270_FLIP_HORIZONTAL Rotates the image clockwise 270 degrees and flips it horizontally.
D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE90 Rotates the image clockwise 90 degrees.
D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE90_FLIP_HORIZONTAL Rotates the image clockwise 90 degrees and flips it horizontally.
D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE270 Rotates the image clockwise 270 degrees.

This code snippet demonstrates how to convert from EXIF orientation values (defined in propkey.h) to D2D1_BITMAPSOURCE_ORIENTATION values.

#include <propkey.h>
#include <d2d1effects.h>

D2D1_BITMAPSOURCE_ORIENTATION GetBitmapSourceOrientation(unsigned short PhotoOrientation)
{
       switch (PhotoOrientation)
       {
       case PHOTO_ORIENTATION_NORMAL:
              return D2D1_BITMAPSOURCE_ORIENTATION_DEFAULT;
       case PHOTO_ORIENTATION_FLIPHORIZONTAL:
              return D2D1_BITMAPSOURCE_ORIENTATION_FLIP_HORIZONTAL;
       case PHOTO_ORIENTATION_ROTATE180:
              return D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE180;
       case PHOTO_ORIENTATION_FLIPVERTICAL:
              return D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE180_FLIP_HORIZONTAL;
       case PHOTO_ORIENTATION_TRANSPOSE: 
              return D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE90_FLIP_HORIZONTAL;
       case PHOTO_ORIENTATION_ROTATE270:
              return D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE90;
       case PHOTO_ORIENTATION_TRANSVERSE:
              return D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE270_FLIP_HORIZONTAL;
       case PHOTO_ORIENTATION_ROTATE90:
              return D2D1_BITMAPSOURCE_ORIENTATION_ROTATE_CLOCKWISE270;
       default:
              return D2D1_BITMAPSOURCE_ORIENTATION_DEFAULT;
       }
}

Alpha modes

Name Description
D2D1_BITMAPSOURCE_ALPHA_MODE_PREMULTIPLIED The effect output uses premultiplied alpha.
D2D1_BITMAPSOURCE_ALPHA_MODE_STRAIGHT The effect output uses straight alpha.

Remarks

To optimize performance when using WIC and Direct2D together, you should use IWICFormatConverter to convert to an appropriate pixel format based your app s scenario and the image s native precision.

In most cases, either your app s Direct2D pipeline only requires 8 bits per channel (bpc) of precision, or the image only provides 8 bpc precision, and therefore you should convert to GUID_WICPixelFormat32bppPBGRA. However, if you want to take advantage of extra precision provided by an image (for example, a JPEG-XR or TIFF stored with greater than 8 bpc precision), you should use an RGBA-based pixel format. The below table provides more details.

Desired precision Native precision of the image Recommended pixel format
8 bits per channel <= 8 bits per channel GUID_WICPixelFormat32bppPBGRA
As high as possible <= 8 bits per channel GUID_WICPixelFormat32bppPBGRA
As high as possible > 8 bits per channel RGBA channel order, premultiplied alpha

Because many image formats support multiple levels of precision, you should use IWICBitmapSource::GetPixelFormat to obtain the image s native pixel format, and then use IWICPixelFormatInfo to determine how many bits per channel of precision are available for that format. Also, note that not all hardware supports high precision pixel formats. In those cases your app may need to fall back to the WARP device to support high precision.

Requirements

Requirement Value
Minimum supported client Windows 8 and Platform Update for Windows 7 [desktop apps | Windows Store apps]
Minimum supported server Windows 8 and Platform Update for Windows 7 [desktop apps | Windows Store apps]
Header d2d1effects.h
Library d2d1.lib, dxguid.lib

ID2D1Effect