IDCompositionVisual::SetClip(constD2D_RECT_F&) method (dcomp.h)

Article
02/22/2024

Sets the Clip property of this visual to the specified rectangle. The Clip property restricts the rendering of the visual subtree that is rooted at this visual to the specified rectangular region.

Syntax

HRESULT SetClip(
  [in, ref] const D2D_RECT_F & rect
);

Parameters

[in, ref] rect

Type: const D2D_RECT_F

The rectangle to use to clip this visual. All properties of the rect parameter have a numerical limit of -2^21 to 2^21. The API accepts numbers outside of this range, but they are always clamped to this range.

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

Setting the Clip property clips this visual along with all visuals in the subtree that is rooted at this visual. The clip is transformed by the OffsetX, OffsetY, and Transform properties.

If the Clip property previously specified a clip object, the newly specified clip rectangle replaces the clip object.

This method fails if any members of the rect structure are NaN, positive infinity, or negative infinity.

If the clip rectangle is empty, the visual is fully clipped; that is, the visual is included in the visual tree, but it does not render anything. To exclude a particular visual from a composition, remove the visual from the visual tree instead of setting an empty clip rectangle. Removing the visual results in better performance.

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