IDCompositionVirtualSurface::Trim method (dcomp.h)

Article
02/22/2024

Discards pixels that fall outside of the specified trim rectangles.

Syntax

HRESULT Trim(
  [in, optional] const RECT *rectangles,
  [in]           UINT       count
);

Parameters

[in, optional] rectangles

Type: const RECT*

An array of rectangles to keep.

[in] count

Type: UINT

The number of rectangles in the rectangles array.

Return value

Type: HRESULT

If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. See DirectComposition Error Codes for a list of error codes.

Remarks

A virtual surface might not have enough storage for every pixel in the surface. An application instructs the composition engine to allocate memory for the surface by calling the IDCompositionSurface::BeginDraw method, and to release memory for the surface by calling the IDCompositionVirtualSurface::Trim method. The array of rectangles represents the regions of the virtual surface that should remain allocated after this method returns. Any pixels that are outside the specified set of rectangles are no longer used for texturing, and their memory may be reclaimed.

If the count parameter is zero, no pixels are kept, and all of the memory allocated for the virtual surface may be reclaimed. The rectangles parameter can be NULL only if the count parameter is zero.

This method fails if IDCompositionSurface::BeginDraw was called for this bitmap without a corresponding call to IDCompositionSurface::EndDraw.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	dcomp.h
Library	Dcomp.lib
DLL	Dcomp.dll