IDCompositionVisual3::SetTransformMode method
Specifies the transform style to be applied to a visual.
HRESULT SetTransformMode(
[in, ref] const DCOMPOSITION_TRANSFORM_MODE &mode
);
mode [in, ref]
Type: const DCOMPOSITION_TRANSFORM_MODEThe mode to use when composing surfaces in this visual's sub-tree to the screen.
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.
When the transform mode is set to DCOMPOSITION_TRANSFORM_MODE_3D_TRANSFORM_AND_VISIBILITY or inherits from a DCOMPOSITION_TRANSFORM_MODE_3D_TRANSFORM_AND_VISIBILITY parent, the sub-tree elements are stacked according to the z-index of each element. Setting transform style DCOMPOSITION_TRANSFORM_MODE_3D_TRANSFORM_AND_VISIBILITY on a visual will default the opacity mode to Multiply, see SetOpacityMode method. In multiply mode the opacity is applied individually to each surface as it is composed, so surfaces blend with each other.
Normally DirectComposition simply flattens a 3D transform to the z = 0 plane and visuals are rendered in the same order as they are added. The result does not represent a 3D state with correct depth and sorting (see diagram below). In order to achieve the desired effect independently from the UI thread, DirectComposition supports 3D objects in a sorted and unsorted style.
.png "Example of preserve 3D mode and flat mode")
SetTransform Mode provides the ability for objects to overlap with transparency and intersect. This requires additional computation to correctly sort the visuals and a new type of tree specifically for the Transform and Visibility visuals, the Binary Space Partitioning tree.
There is a known added cost to setting the transform mode to DCOMPOSITION_TRANSFORM_MODE_3D_TRANSFORM_AND_VISIBILITY using DirectComposition. This is due to the added complexity of creating and sorting a Binary Space Partitioning Tree (BSP). The BSP tree is created for the 3d visual and all its children. This tree is calculated to determine the drawing order of the 3d visuals. The BSP tree is created during pre-compute for all the visuals using DCOMPOSITION_TRANSFORM_MODE_3D_TRANSFORM_AND_VISIBILITY and is re-calculated every time a transform property value of a visual within the tree is updated. This is to ensure that all the child visuals draw correctly.
Note that only DCOMPOSITION_TRANSFORM_MODE_3D_TRANSFORM_AND_VISIBILITY requires a BSP tree.
Minimum supported client |
Windows 8 [desktop apps only] |
Minimum supported server |
Windows Server 2012 [desktop apps only] |
Header |
Dcomp.h |
Library |
Dcomp.lib |
DLL |
Dcomp.dll |
IDCompositionTranslateTransform