Edit

ID2D1ImageSourceFromWic::EnsureCached(constD2D1_RECT_U&) method (d2d1_3.h)

  • Article

Ensures that a specified region of the image source cache is populated. This method can be used to minimize glitches by performing expensive work to populate caches outside of a rendering loop. This method can also be used to speculatively load image data before it is needed by drawing routines.

Syntax

HRESULT EnsureCached(
  [ref] const D2D1_RECT_U & rectangleToFill
);

Parameters

[ref] rectangleToFill

Type: const D2D1_RECT_U

Specifies the region of the image, in pixels, that should be populated in the cache. By default, this is the entire extent of the image.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This API loads image data into caches of image sources, if that data was not already cached. It does not trim pre-existing caches, if any.
More areas within the cache can be populated than actually requested.

The provided region must be constructed to include the scale with which the image source will subsequently be drawn.
These coordinates must be provided in local coordinates.
This means that they must be adjusted prior to calling the API according to the DPI and other relevant transforms, which can include the world transform and brush transforms.

This operation is only supported when the image source has been initialized using the D2D1_IMAGE_SOURCE_LOADING_OPTIONS_CACHE_ON_DEMAND option.

Requirements

Requirement Value
Target Platform Windows
Header d2d1_3.h
Library D2d1_3.lib
DLL D2d1_3.dll

See also

ID2D1ImageSourceFromWic