IDCompositionVirtualSurface::Trim method (dcomp.h)
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 |