IDCompositionVisual::SetTransform(IDCompositionTransform*) method (dcomp.h)

Article
08/31/2022

Sets the Transform property of this visual to the specified 2D transform object.

Syntax

HRESULT SetTransform(
  [in, optional] IDCompositionTransform *transform
);

Parameters

[in, optional] transform

Type: IDCompositionTransform*

The transform object that is used to modify the coordinate system of this visual. This parameter can point to an IDCompositionTransform interface or one of its derived interfaces. This parameter can be NULL.

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 Transform property transforms the coordinate system of the entire visual subtree that is rooted at this visual. If the Clip property of this visual is specified, the clip rectangle is also transformed.

If the Transform property previously specified a transform matrix, the newly specified transform object replaces the transform matrix.

A transformation specified by the Transform property is applied after the OffsetX and OffsetY properties. In other words, the effect of setting the Transform property and the OffsetX and OffsetY properties is the same as setting only the Transform property on a transform group where the first member of the group is an IDCompositionTranslateTransform object that has those same OffsetX and OffsetY values. However, you should use the IDCompositionVisual::SetOffsetX and SetOffsetY methods whenever possible because they are slightly faster.

This method fails if transform is an invalid pointer or if it was not created by the same IDCompositionDevice interface that created this visual. The interface cannot be a custom implementation; only interfaces created by Microsoft DirectComposition can be used with this method.

If the transform parameter is NULL, the coordinate system of this visual is transformed only by its OffsetX and OffsetY properties. Setting the Transform property to NULL is equivalent to setting it to an IDCompositionMatrixTransform object where the specified matrix is the identity matrix. However, an application should set the Transform property to NULL whenever possible because it is slightly faster.

If the OffsetX and OffsetY properties are set to 0, and the Transform property is set to NULL, the coordinate system of the visual is the same as that of its parent.

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