A cubic segment transitions time along a cubic polynomial. For a given time input (t), the output value is given by the following equation.

x(t) = at3 + bt2 + ct + d

This method fails if any of the parameters are NaN, positive infinity, or negative infinity.

Because animation segments must be added in increasing order, this method fails if the beginOffset parameter is less than or equal to the beginOffset parameter of the previous segment, if any.

This animation segment remains in effect until the begin time of the next segment in the animation function. If the animation function contains no more segments, this segment remains in effect indefinitely.

If all coefficients except constantCoefficient are zero, the value of this segment remains constant over time, and the animation does not cause a recomposition for the duration of the segment.

This method returns the animation function to a clean state, as when the animation was first constructed. After this method is called, the next segment to be added becomes the first segment of the animation function. Because it is the first segment, it can have any non-negative beginning offset.

By default, an animation function starts when the first frame of the animation takes effect. For example, if an application creates a simple animation function with a single primitive at offset zero, associates the animation with some property, and then calls the method, the first frame that includes the commit samples the animation at offset zero for the first primitive. This implies that the actual default start time of all animations varies depending on the time between when the application creates the animation and calls Commit, to the time it takes the composition engine to pick up the committed changes. The application can use the SetAbsoluteBeginTime method to exercise finer control over the starting time of an animation.

This method does not control when animations take effect; it only affects how animations are sampled after they start. If the application specifies the exact time of the next frame as the absolute begin time, the result is the same as not calling this method at all. If the specified begin time is different from the time of the next frame, the result is one of following:

• If the specified time is later than the next frame time, the animation start is delayed until the specified begin time.
• If the specified time is earlier than the next frame time, the beginning of the animation is dropped and sampling starts into the animation function.

A cubic segment transitions time along a cubic polynomial. For a given time input (t), the output value is given by the following equation.

x(t) = at3 + bt2 + ct + d

This method fails if any of the parameters are NaN, positive infinity, or negative infinity.

Because animation segments must be added in increasing order, this method fails if the beginOffset parameter is less than or equal to the beginOffset parameter of the previous segment, if any.

This animation segment remains in effect until the begin time of the next segment in the animation function. If the animation function contains no more segments, this segment remains in effect indefinitely.

If all coefficients except constantCoefficient are zero, the value of this segment remains constant over time, and the animation does not cause a recomposition for the duration of the segment.

This method fails if any of the parameters are NaN, positive infinity, or negative infinity, or if the beginOffset parameter is negative.

Because animation segments must be added in increasing order, this method fails if the beginOffset parameter is less than or equal to the beginOffset parameter of the previous segment, if any.

This animation segment remains in effect until the begin time of the next segment in the animation function. If the animation function contains no more segments, this segment remains in effect indefinitely.

This method fails if any of the parameters are NaN, positive infinity, or negative infinity.

Because animation segments must be added in increasing order, this method fails if the beginOffset parameter is less than or equal to the beginOffset parameter of the previous segment. This method also fails if this is the first segment to be added to the animation function.

This animation segment remains in effect until the begin time of the next segment. If the animation function contains no more segments, this segment remains in effect indefinitely.

When the specified offset is reached, the property or properties affected by this animation are set to the specified final value, and then the animation stops. If no end segment is added, the final segment of the animation function runs indefinitely. Calling this method is semantically identical to making the last segment of the animation function a cubic polynomial where the cubic, quadratic, and linear coefficients are all zeros, and the constant coefficient is the desired final value.

Because animation segments must be added in increasing order, this method fails if the endOffset parameter is less than or equal to the beginOffset parameter of the previous segment. This method also fails if this is the first segment to be added to the animation function.

After this method is called, all methods on this animation object fail except the method.

By default, an animation function starts when the first frame of the animation takes effect. For example, if an application creates a simple animation function with a single primitive at offset zero, associates the animation with some property, and then calls the method, the first frame that includes the commit samples the animation at offset zero for the first primitive. This implies that the actual default start time of all animations varies depending on the time between when the application creates the animation and calls Commit, to the time it takes the composition engine to pick up the committed changes. The application can use the SetAbsoluteBeginTime method to exercise finer control over the starting time of an animation.

This method does not control when animations take effect; it only affects how animations are sampled after they start. If the application specifies the exact time of the next frame as the absolute begin time, the result is the same as not calling this method at all. If the specified begin time is different from the time of the next frame, the result is one of following:

• If the specified time is later than the next frame time, the animation start is delayed until the specified begin time.
• If the specified time is earlier than the next frame time, the beginning of the animation is dropped and sampling starts into the animation function.

Calls to DirectComposition methods are always batched and executed atomically as a single transaction. Calls take effect only when is called, at which time all pending method calls for a device are executed at once.

An application that uses multiple devices must call Commit for each device separately. However, because the composition engine processes the calls individually, the batch of commands might not take effect at the same time.

This method retrieves timing information about the composition engine that an application can use to synchronize the rasterization of bitmaps with independent animations.

A new visual object has a static value of zero for the OffsetX and OffsetY properties, and null for the Transform, Clip, and Content properties. Initially, the visual does not cause the contents of a window to change. The visual must be added as a child of another visual, or as the root of a composition target, before it can affect the appearance of a window.

A surface factory allows an application to simultaneously use more than one single DXGI or Direct2D device with DirectComposition. Each surface factory has a permanent association with one DXGI or Direct2D device, but a DirectComposition device may have any number of surface factories.

Each surface factory manages resources independently from the others. In particular, DirectComposition pools surface allocations to mitigate surface allocation and deallocation costs. This pool is done on a per-surface factory basis.

If the function is called with a non-null renderingDevice parameter, the returned DirectComposition device object has an implicit surface factory under the covers associated with the given rendering device. This implicit surface factory is used to service the , , and methods.

A surface object remains alive as long as any of the surfaces or virtual surfaces that it created remain alive, either directly because the application holds a direct reference, or indirectly because one or more such surfaces are associated with one or more visual objects.

A Microsoft DirectComposition surface is a rectangular array of pixels that can be associated with a visual for composition.

A newly created surface object is in an uninitialized state. While it is uninitialized, the surface has no effect on the composition of the visual tree. It behaves exactly like a surface that has 100% transparent pixels.

To initialize the surface with pixel data, use the and methods. The first call to this method must cover the entire surface area to provide an initial value for every pixel. Subsequent calls may specify smaller sub-rectangles of the surface to update.

DirectComposition surfaces support the following pixel formats:

A Microsoft DirectComposition sparse surface is a logical object that behaves like a rectangular array of pixels that can be associated with a visual for composition. The surface is not necessarily backed by any physical video or system memory for every one of its pixels. The application can realize or virtualize parts of the logical surface at different times.

A newly created surface object is in an uninitialized state. While it is uninitialized, the surface has no effect on the composition of the visual tree. It behaves exactly like a surface that is initialized with 100% transparent pixels.

To initialize the surface with pixel data, use the and methods. This method not only provides pixels for the surface, but it also allocates actual storage space for those pixels. The memory allocation persists until the application returns some of the memory to the system. The application can free part or all of the allocated memory by calling the method.

DirectComposition surfaces support the following pixel formats:

This method fails if initialWidth or initialHeight exceeds 16,777,216 pixels.

A new 2D translation transform object has a static value of zero for the OffsetX and OffsetY properties.

A new 2D scale transform object has a static value of zero for the ScaleX, ScaleY, CenterX, and CenterY properties.

A new 2D rotation transform object has a static value of zero for the Angle, CenterX, and CenterY properties.

A new 2D skew transform object has a static value of zero for the AngleX, AngleY, CenterX, and CenterY properties.

A new matrix transform object has the identity matrix as its initial value. The identity matrix is the 3x2 matrix with ones on the main diagonal and zeros elsewhere, as shown in the following illustration.

When an identity transform is applied to an object, it does not change the position, shape, or size of the object. It is similar to the way that multiplying a number by one does not change the number. Any transform other than the identity transform will modify the position, shape, and/or size of objects.

The array entries in a transform group cannot be changed. However, each transform in the array can be modified through its own property setting methods. If a transform in the array is modified, the change is reflected in the computed matrix of the transform group.

The array entries in a transform group cannot be changed. However, each transform in the array can be modified through its own property setting methods. If a transform in the array is modified, the change is reflected in the computed matrix of the transform group.

A newly created 3D translation transform has a static value of 0 for the OffsetX, OffsetY, and OffsetZ properties.

A new 3D scale transform object has a static value of 1.0 for the ScaleX, ScaleY, and ScaleZ properties.

A new 3D rotation transform object has a default static value of zero for the Angle, CenterX, CenterY, CenterZ, AxisX, and AxisY properties, and a default static value of 1.0 for the AxisZ property.

The new 3D matrix transform has the identity matrix as its value. The identity matrix is the 4-by-4 matrix with ones on the main diagonal and zeros elsewhere, as shown in the following illustration.

When an identity transform is applied to an object, it does not change the position, shape, or size of the object. It is similar to the way that multiplying a number by one does not change the number. Any transform other than the identity transform will modify the position, shape, and/or size of objects.

The array entries in a 3D transform group cannot be changed. However, each transform in the array can be modified through its own property setting methods. If a transform in the array is modified, the change is reflected in the computed matrix of the transform group.

The array entries in a 3D transform group cannot be changed. However, each transform in the array can be modified through its own property setting methods. If a transform in the array is modified, the change is reflected in the computed matrix of the transform group.

An effect group enables an application to apply multiple effects to a single visual subtree.

A new effect group has a default opacity value of 1.0 and no 3D transformations.

To set the opacity and transform values, use the corresponding methods on the that was created.

A newly created clip object has a static value of FLT_MAX for the left and top properties, and a static value of ?FLT_MAX for the right and bottom properties, effectively making it a no-op clip object.

A number of DirectComposition object properties can have an animation object as the value of the property. When a property has an animation object as its value, DirectComposition redraws the visual at the refresh rate to reflect the changing value of the property that is being animated.

A newly created animation object does not have any animation segments associated with it. An application must use the methods of the interface to build an animation function before setting the animation object as the property of another DirectComposition object.

This method retrieves timing information about the composition engine that an application can use to synchronize the rasterization of bitmaps with independent animations.

A DirectComposition visual tree must be bound to a window before anything can be displayed on screen. The window can be a top-level window or a child window. In either case, the window can be a layered window, but in all cases the window must belong to the calling process. If the window belongs to a different process, this method returns DCOMPOSITION_ERROR_ACCESS_DENIED.

When DirectComposition content is composed to the window, the content is always composed on top of whatever is drawn directly to that window through the device context returned by the GetDC function, or by calls to DirectX Present methods. However, because window clipping rules apply to DirectComposition content, if the window has child windows, those child windows may clip the visual tree. The topmost parameter determines whether child windows clip the visual tree.

Conceptually, each window consists of four layers:

1. The contents drawn directly to the window handle (this is the bottommost layer).
2. An optional DirectComposition visual tree.
3. The contents of all child windows, if any.
4. Another optional DirectComposition visual tree (this is the topmost layer).

All four layers are clipped to the window?s visible region.

At most, only two composition targets can be created for each window in the system, one topmost and one not topmost. If a composition target is already bound to the specified window at the specified layer, this method fails. When a composition target object is destroyed, the layer it composed is available for use by a new composition target object.

You can use the surface reference in calls to the method to set the content of one or more visuals. After setting the content, the visuals compose the contents of the specified layered window as long as the window is layered. If the window is unlayered, the window content disappears from the output of the composition tree. If the window is later re-layered, the window content reappears as long as it is still associated with a visual. If the window is resized, the affected visuals are re-composed.

The contents of the window are not cached beyond the life of the window. That is, if the window is destroyed, the affected visuals stop composing the window.

If the window is moved off-screen or resized to zero, the system stops composing the content of those visuals. You should use the DwmSetWindowAttribute function with the DWMWA_CLOAK flag to "cloak" the layered child window when you need to hide the original window while allowing the system to continue to compose the content of the visuals.

Calls to DirectComposition methods are always batched and executed atomically as a single transaction. Calls take effect only when is called, at which time all pending method calls for a device are executed at once.

An application that uses multiple devices must call Commit for each device separately. However, because the composition engine processes the calls individually, the batch of commands might not take effect at the same time.

This method retrieves timing information about the composition engine that an application can use to synchronize the rasterization of bitmaps with independent animations.

A Microsoft DirectComposition visual tree must be bound to a window before anything can be displayed on screen. The window can be a top-level window or a child window. In either case, the window can be a layered window, but in all cases the window must belong to the calling process. If the window belongs to a different process, this method returns DCOMPOSITION_ERROR_ACCESS_DENIED.

When DirectComposition content is composed to the window, the content is always composed on top of whatever is drawn directly to that window through the device context () returned by the GetDC function, or by calls to Microsoft DirectX Present methods. However, because window clipping rules apply to DirectComposition content, if the window has child windows, those child windows may clip the visual tree. The topmost parameter determines whether child windows clip the visual tree.

Conceptually, each window consists of four layers:

1. The contents drawn directly to the window handle (this is the bottommost layer).
2. An optional DirectComposition visual tree.
3. The contents of all child windows, if any.
4. Another optional DirectComposition visual tree (this is the topmost layer).

All four layers are clipped to the window's visible region.

At most, only two composition targets can be created for each window in the system, one topmost and one not topmost. If a composition target is already bound to the specified window at the specified layer, this method fails. When a composition target object is destroyed, the layer it composed is available for use by a new composition target object.

A new visual object has a static value of zero for the OffsetX and OffsetY properties, and null for the Transform, Clip, and Content properties. Initially, the visual does not cause the contents of a window to change. The visual must be added as a child of another visual, or as the root of a composition target, before it can affect the appearance of a window.

A Microsoft DirectComposition surface is a rectangular array of pixels that can be associated with a visual for composition.

A newly created surface object is in an uninitialized state. While it is uninitialized, the surface has no effect on the composition of the visual tree. It behaves exactly like a surface that has 100% transparent pixels.

To initialize the surface with pixel data, use the method. The first call to this method must cover the entire surface area to provide an initial value for every pixel. Subsequent calls may specify smaller sub-rectangles of the surface to update.

DirectComposition surfaces support the following pixel formats:

A Microsoft DirectComposition sparse surface is a logical object that behaves like a rectangular array of pixels that can be associated with a visual for composition. The surface is not necessarily backed by any physical video or system memory for every one of its pixels. The application can realize or virtualize parts of the logical surface at different times.

A newly created surface object is in an uninitialized state. While it is uninitialized, the surface has no effect on the composition of the visual tree. It behaves exactly like a surface that is initialized with 100% transparent pixels.

To initialize the surface with pixel data, use the method. This method not only provides pixels for the surface, but it also allocates actual storage space for those pixels. The memory allocation persists until the application returns some of the memory to the system. The application can free part or all of the allocated memory by calling the IDComposition::VirtualSurfaceTrim method.

DirectComposition surfaces support the following pixel formats:

This method fails if initialWidth or initialHeight exceeds 16,777,216 pixels.

This method enables an application to use a shared composition surface in a composition tree.

You can use the surface reference in calls to the method to set the content of one or more visuals. After setting the content, the visuals compose the contents of the specified layered window as long as the window is layered. If the window is unlayered, the window content disappears from the output of the composition tree. If the window is later re-layered, the window content reappears as long as it is still associated with a visual. If the window is resized, the affected visuals are re-composed.

The contents of the window are not cached beyond the life of the window. That is, if the window is destroyed, the affected visuals stop composing the window.

If the window is moved off-screen or resized to zero, the system stops composing the content of visuals. You should use the DwmSetWindowAttribute function with the DWMWA_CLOAK flag to "cloak" the layered child window when you need to hide the original window while allowing the system to continue to compose the content of the visuals. For more information, see How to animate the bitmap of a layered child window and DirectComposition layered child window sample.

A new 2D translation transform object has a static value of zero for the OffsetX and OffsetY properties.

A new 2D scale transform object has a static value of zero for the ScaleX, ScaleY, CenterX, and CenterY properties.

A new 2D rotation transform object has a static value of zero for the Angle, CenterX, and CenterY properties.

A new 2D skew transform object has a static value of zero for the AngleX, AngleY, CenterX, and CenterY properties.

A new matrix transform object has the identity matrix as its initial value. The identity matrix is the 3x2 matrix with ones on the main diagonal and zeros elsewhere, as shown in the following illustration.

When an identity transform is applied to an object, it does not change the position, shape, or size of the object. It is similar to the way that multiplying a number by one does not change the number. Any transform other than the identity transform will modify the position, shape, and/or size of objects.

The array entries in a transform group cannot be changed. However, each transform in the array can be modified through its own property setting methods. If a transform in the array is modified, the change is reflected in the computed matrix of the transform group.

The array entries in a transform group cannot be changed. However, each transform in the array can be modified through its own property setting methods. If a transform in the array is modified, the change is reflected in the computed matrix of the transform group.

A newly created 3D translation transform has a static value of 0 for the OffsetX, OffsetY, and OffsetZ properties.

A new 3D scale transform object has a static value of 1.0 for the ScaleX, ScaleY, and ScaleZ properties.

A new 3D rotation transform object has a default static value of zero for the Angle, CenterX, CenterY, AxisX, and AxisY properties, and a default static value of 1.0 for the AxisZ property.

The new 3D matrix transform has the identity matrix as its value. The identity matrix is the 4-by-4 matrix with ones on the main diagonal and zeros elsewhere, as shown in the following illustration.

When an identity transform is applied to an object, it does not change the position, shape, or size of the object. It is similar to the way that multiplying a number by one does not change the number. Any transform other than the identity transform will modify the position, shape, and/or size of objects.

The array entries in a 3D transform group cannot be changed. However, each transform in the array can be modified through its own property setting methods. If a transform in the array is modified, the change is reflected in the computed matrix of the transform group.

The array entries in a 3D transform group cannot be changed. However, each transform in the array can be modified through its own property setting methods. If a transform in the array is modified, the change is reflected in the computed matrix of the transform group.

An effect group enables an application to apply multiple effects to a single visual subtree.

A new effect group has a default opacity value of 1.0 and no 3D transformations.

A newly created clip object has a static value of ?FLT_MAX for the left and top properties, and a static value of ?FLT_MAX for the right and bottom properties, effectively making it a no-op clip object.

A number of DirectComposition object properties can have an animation object as the value of the property. When a property has an animation object as its value, DirectComposition redraws the visual at the refresh rate to reflect the changing value of the property that is being animated.

A newly created animation object does not have any animation segments associated with it. An application must use the methods of the interface to build an animation function before setting the animation object as the property of another DirectComposition object.

If the Microsoft DirectX Graphics Infrastructure (DXGI) device is lost, the DirectComposition device associated with the DXGI device is also lost. When it detects a lost device, DirectComposition sends the WM_PAINT message to all windows that are composing DirectComposition content using the lost device. An application should call CheckDeviceState in response to each WM_PAINT message to ensure that the DirectComposition device object is still valid. The application must take steps to recover content if the device object becomes invalid. Steps include creating new DXGI and DirectComposition devices, and recreating all content. (It?s not possible to create just a new DXGI device and associate it with the existing DirectComposition device.) The system ensures that the device object remains valid between WM_PAINT messages.

This method retrieves timing information about the composition engine that an application can use to synchronize the rasterization of bitmaps with independent animations.

is an abstract interface that represents a bitmap effect. An effect applies to the entire visual subtree rooted at the visual that the effect is associated with. An effect object can be associated with multiple visuals. When an effect object is modified, all affected visuals are recomposed to reflect the change.

More than one effect can be simultaneously applied to a visual by using the interface.

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the Opacity property unless this method is called again. If the Opacity property was previously animated, calling this method replaces the previous animation with the new animation.

This method fails if animation is an invalid reference or if it was not created by the same interface as the affected compostion effect group. The interface cannot be a custom implementation; only interfaces created by Microsoft DirectComposition can be used with this method.

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the Opacity property unless this method is called again. If the Opacity property was previously animated, calling this method replaces the previous animation with the new animation.

This method fails if animation is an invalid reference or if it was not created by the same interface as the affected compostion effect group. The interface cannot be a custom implementation; only interfaces created by Microsoft DirectComposition can be used with this method.

This method fails if transform3D is an invalid reference, or if the reference was not created by the same interface as this effect group. The interface cannot be a custom implementation; only interfaces created by Microsoft DirectComposition can be used with this method.

If the transform3D parameter is null, the effect group does not apply any perspective transformations to the visuals. Setting the transform to null is equivalent to setting the transform to an object where the specified matrix is the identity matrix. However, an application should use a null transform whenever possible because it is slightly faster.

This method fails if transform3D is an invalid reference, or if the reference was not created by the same interface as this effect group. The interface cannot be a custom implementation; only interfaces created by Microsoft DirectComposition can be used with this method.

If the transform3D parameter is null, the effect group does not apply any perspective transformations to the visuals. Setting the transform to null is equivalent to setting the transform to an object where the specified matrix is the identity matrix. However, an application should use a null transform whenever possible because it is slightly faster.

The interface is an abstract interface that represents a 2D affine transformation. Transformations affect the entire visual subtree that is rooted at the visual that the transform is associated with. A transform object can be associated with multiple visuals. When a transform object is modified, all affected visuals are recomposed to reflect the change.

Transforms operate by modifying the coordinate system for all rendering operations on a visual. For example, ordinarily a bitmap that is associated with a visual draws at position (0,0) and extends the full width and height of the bitmap. If a translation transform is applied, the bitmap draws at a position that is offset by that transform. If a scale transform is applied, the extent covered by the bitmap is affected by the scale transform. More than one transform can be simultaneously applied to a visual by using the interface.

The interface is an abstract interface that represents a 3D perspective transformation effect. A 3D transform object can be associated with multiple visuals and multiple effect groups. When a 3D transform object is modified, all affected visuals are recomposed to reflect the change.

This method fails if any of the matrix values are NaN, positive infinity, or negative infinity.

If any of the matrix elements were previously animated, this method removes the animations and sets the elements to the specified static value.

A 3D matrix transform represents the following 4-by-4 matrix:

The application can set any of the values in the first three columns. Note that the fourth column is padded to allow for matrix concatenation.

This method fails if any of the matrix values are NaN, positive infinity, or negative infinity.

If any of the matrix elements were previously animated, this method removes the animations and sets the elements to the specified static value.

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the specified element unless this method is called again. If the specified element was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the specified element unless this method is called again. If the specified element was previously animated, calling this method replaces the previous animation with the new animation.

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

The default interpolation mode for a visual is . If all visuals in a visual tree specify this mode, the default for all visuals is nearest neighbor sampling, which is the fastest mode.

A single visual can have any combination of visual properties. However, if a visual has the following combination of properties, the borders of the visual will default to .

• SetCompositeMode()
• SetBorderMode()
• SetBitmapInterpolationMode()

If you want a visual to be drawn with antialiasing, use for the content of the visual, and for the edges.

The default border mode for any given visual is , which delegates the determination of the border mode to the parent visual. If all visuals in a visual tree specify this mode, the default for all visuals is aliased rendering, which is the fastest mode.

A single visual can have any combination of visual properties. However, if a visual has the following combination of properties, the borders of the visual will default to .

• SetCompositeMode()
• SetBorderMode()
• SetBitmapInterpolationMode()

If you want a visual to be drawn with antialiasing, use for the content of the visual, and for the edges.

A single visual can have any combination of visual properties. However, if a visual has the following combination of properties, the borders of the visual will default to .

• SetCompositeMode()
• SetBorderMode()
• SetBitmapInterpolationMode()

If you want a visual to be drawn with antialiasing, use for the content of the visual, and for the edges.

A device object serves as the factory for all other DirectComposition objects. It also controls transactional composition through the method.

The renderingDevice parameter may point to a DXGI, Direct3D, Direct2D device object, or it may be null. This parameter affects the behavior of the , and methods.

If the renderingDevice parameter is null then the returned DirectComposition device cannot directly create DirectComposition surface objects. In particular, and methods return E_INVALIDARG, regardless of the supplied parameters. However, such a DirectComposition device object can still be used to indirectly create surfaces if the application creates a surface factory object via the method.

If the renderingDevice parameter points to a DXGI device, that device is used to allocate all video memory needed by the and methods. Moreover, the method returns an interface reference to a DXGI surface that belongs to that same DXGI device.

If the renderingDevice parameter points to a Direct2D device object, DirectComposition extracts from it the underlying DXGI device object and uses it as if that DXGI device object had been passed in as the renderingDevice parameter. However, passing in a Direct2D object further causes to accept __uuidof() for its iid parameter for any objects created with the or methods. In that case, the Direct2D device context object returned by will belong to the same Direct2D device passed as the renderingDevice parameter.

If the iid parameter is __uuidof(), then the dcompositionDevice parameter receives a reference to a Version 1 interface, but the underlying object is a Version 2 desktop device object. The application can later obtain a reference to either the or interfaces by calling the QueryInterface method on that device. Similarly, all DirectComposition objects created from such a device are Version 2 objects under the covers. For example, the method will return an interface to the created visual, but the application can obtain a reference to the interface via the QueryInterface method. This behavior allows an application written to the DirectComposition V1 API to incrementally adopt DirectComposition V2 features by changing the device creation method from to , while still requesting the interface. This allows the rest of the code to remain unchanged, while allowing the application to use QueryInterface in just the places where new functionality is needed.

A device object serves as the factory for all other DirectComposition objects. It also controls transactional composition through the method.

The DXGI device specified by dxgiDevice is used to create all DirectComposition surface objects. In particular, the method returns an interface reference to a DXGI surface that belongs to the device specified by the dxgiDevice parameter.

When creating the DXGI device, developers must specify the D3D11_CREATE_DEVICE BGRA_SUPPORT or flag for Direct2D interoperability with Microsoft Direct3D resources.

The iid parameter must be __uuidof(), and the dcompositionDevice parameter receives a reference to an interface.

Performance counters are displayed on the top-right corner of the screen. From left to right, Microsoft DirectComposition displays the following information:

• The composition engine frame rate, in frames per second, averaged over the last 60 composition frames
• The overall CPU usage of the composition thread, in milliseconds

The DirectComposition composition engine operates on the entire desktop all at once, so the performance counters measure the total cost of desktop composition, not just the cost of any one particular application. If the application occupies the entire screen, however, it is reasonable to assume that all of the composition cost is due to that one application.

Microsoft DirectComposition keeps a count of how many DirectComposition devices have performance counters enabled, for the entire desktop session. If the count is non-zero, the performance counters are displayed. Therefore, disabling the counters may not make them go away if another device is also requesting display of the counters.

This method fails if the left parameter is NaN, positive infinity, or negative infinity.

If the Left property was previously animated, this method removes the animation and sets the Left property to the specified static value.

This method fails if the left parameter is NaN, positive infinity, or negative infinity.

If the Left property was previously animated, this method removes the animation and sets the Left property to the specified static value.

This method fails if the top parameter is NaN, positive infinity, or negative infinity.

If the Top property was previously animated, this method removes the animation and sets the Top property to the specified static value.

This method fails if the top parameter is NaN, positive infinity, or negative infinity.

If the Top property was previously animated, this method removes the animation and sets the Top property to the specified static value.

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the Right property unless this method is called again. If the Right property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the Right property unless this method is called again. If the Right property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method fails if the bottom parameter is NaN, positive infinity, or negative infinity.

If the Bottom property was previously animated, this method removes the animation and sets the Bottom property to the specified static value.

This method fails if the bottom parameter is NaN, positive infinity, or negative infinity.

If the Bottom property was previously animated, this method removes the animation and sets the Bottom property to the specified static value.

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the x radius unless this method is called again. If the x radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the x radius unless this method is called again. If the x radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the y radius unless this method is called again. If the y radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the y radius unless this method is called again. If the y radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the x radius unless this method is called again. If the x radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the x radius unless this method is called again. If the x radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the y radius unless this method is called again. If the y radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the y radius unless this method is called again. If the y radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the x radius unless this method is called again. If the x radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the x radius unless this method is called again. If the x radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the y radius unless this method is called again. If the y radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the y radius unless this method is called again. If the y radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the x radius unless this method is called again. If the x radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the x radius unless this method is called again. If the x radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the y radius unless this method is called again. If the y radius was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the y radius unless this method is called again. If the y radius was previously animated, calling this method replaces the previous animation with the new animation.

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

A rotate transform represents the following 3-by-3 matrix:

The effect is to rotate the coordinate system clockwise or counter-clockwise, and to apply the corresponding translation such that the center point does not move.

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the Angle property unless this method is called again. If the Angle property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the Angle property unless this method is called again. If the Angle property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method fails if the centerX parameter is NaN, positive infinity, or negative infinity.

If the CenterX property was previously animated, this method removes the animation and sets the CenterX property to the specified static value.

This method fails if the centerX parameter is NaN, positive infinity, or negative infinity.

If the CenterX property was previously animated, this method removes the animation and sets the CenterX property to the specified static value.

This method fails if the centerY parameter is NaN, positive infinity, or negative infinity.

If the CenterY property was previously animated, this method removes the animation and sets the CenterY property to the specified static value.

This method fails if the centerY parameter is NaN, positive infinity, or negative infinity.

If the CenterY property was previously animated, this method removes the animation and sets the CenterY property to the specified static value.

A 3D rotate transform represents the following 4-by-4 matrix:

where the offsetX, offsetY, and offsetZ values of the matrix are the following:

The effect is to rotate the coordinate system clockwise or counter-clockwise around the specified axis, and to apply the corresponding translation such that the center point does not move.

A new 3D rotation transform object has a default static value of zero for the Angle, CenterX, CenterY, AxisX, and AxisY properties, and a default static value of 1.0 for the AxisZ property.

When setting the axis to a non-default value, you should always set all three axis properties (AxisX, AxisY, and AxisZ).

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the Angle property unless this method is called again. If the Angle property was previously animated, calling this method replaces the previous animation with the new animation.

This method fails if animation is an invalid reference or if it was not created by the same interface as the affected 3D transform. The interface cannot be a custom implementation; only interfaces created by Microsoft DirectComposition can be used with this method.

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the Angle property unless this method is called again. If the Angle property was previously animated, calling this method replaces the previous animation with the new animation.

This method fails if animation is an invalid reference or if it was not created by the same interface as the affected 3D transform. The interface cannot be a custom implementation; only interfaces created by Microsoft DirectComposition can be used with this method.

When setting the axis to a non-default value, you should always set all three axis properties (AxisX, AxisY, and AxisZ).

This method fails if the axisX parameter is NaN, positive infinity, or negative infinity.

If the AxisX property was previously animated, this method removes the animation and sets the AxisX property to the specified static value.

When setting the axis to a non-default value, you should always set all three axis properties (AxisX, AxisY, and AxisZ).

This method fails if the axisX parameter is NaN, positive infinity, or negative infinity.

If the AxisX property was previously animated, this method removes the animation and sets the AxisX property to the specified static value.

When setting the axis to a non-default value, you should always set all three axis properties (AxisX, AxisY, and AxisZ).

This method fails if the axisY parameter is NaN, positive infinity, or negative infinity.

If the AxisY property was previously animated, this method removes the animation and sets the AxisY property to the specified static value.

When setting the axis to a non-default value, you should always set all three axis properties (AxisX, AxisY, and AxisZ).

This method fails if the axisY parameter is NaN, positive infinity, or negative infinity.

If the AxisY property was previously animated, this method removes the animation and sets the AxisY property to the specified static value.

When setting the axis to a non-default value, you should always set all three axis properties (AxisX, AxisY, and AxisZ).

This method fails if the axisZ parameter is NaN, positive infinity, or negative infinity.

If the AxisZ property was previously animated, this method removes the animation and sets the AxisX property to the specified static value.

When setting the axis to a non-default value, you should always set all three axis properties (AxisX, AxisY, and AxisZ).

This method fails if the axisZ parameter is NaN, positive infinity, or negative infinity.

If the AxisZ property was previously animated, this method removes the animation and sets the AxisX property to the specified static value.

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the CenterX property unless this method is called again. If the CenterX property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the CenterX property unless this method is called again. If the CenterX property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method fails if the centerY parameter is NaN, positive infinity, or negative infinity.

If the CenterY property was previously animated, this method removes the animation and sets the CenterY property to the specified static value.

This method fails if the centerY parameter is NaN, positive infinity, or negative infinity.

If the CenterY property was previously animated, this method removes the animation and sets the CenterY property to the specified static value.

This method fails if the centerZ parameter is NaN, positive infinity, or negative infinity.

If the CenterZ property was previously animated, this method removes the animation and sets the CenterZ property to the specified static value.

This method fails if the centerZ parameter is NaN, positive infinity, or negative infinity.

If the CenterZ property was previously animated, this method removes the animation and sets the CenterZ property to the specified static value.

A scale transform represents the following 3-by-3 matrix:

The effect is to scale the coordinate system up or down and apply the corresponding translation such that the center point does not move.

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the ScaleX property unless this method is called again. If the ScaleX property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the ScaleX property unless this method is called again. If the ScaleX property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method fails if the scaleY parameter is NaN, positive infinity, or negative infinity.

If the ScaleY property was previously animated, this method removes the animation and sets the ScaleY property to the specified static value.

This method fails if the scaleY parameter is NaN, positive infinity, or negative infinity.

If the ScaleY property was previously animated, this method removes the animation and sets the ScaleY property to the specified static value.

This method fails if the centerX parameter is NaN, positive infinity, or negative infinity.

If the CenterX property was previously animated, this method removes the animation and sets the CenterX property to the specified static value.

This method fails if the centerX parameter is NaN, positive infinity, or negative infinity.

If the CenterX property was previously animated, this method removes the animation and sets the CenterX property to the specified static value.

This method fails if the centerY parameter is NaN, positive infinity, or negative infinity.

If the CenterY property was previously animated, this method removes the animation and sets the CenterY property to the specified static value.

This method fails if the centerY parameter is NaN, positive infinity, or negative infinity.

If the CenterY property was previously animated, this method removes the animation and sets the CenterY property to the specified static value.

A 3D scale transform represents the following 4-by-4 matrix:

The effect is to scale the blending of the visual's subtree up or down, and apply the corresponding translation such that the center point does not move.

This method fails if the scaleX parameter is NaN, positive infinity, or negative infinity.

If the ScaleX property was previously animated, this method removes the animation and sets the ScaleX property to the specified static value.

This method fails if the scaleX parameter is NaN, positive infinity, or negative infinity.

If the ScaleX property was previously animated, this method removes the animation and sets the ScaleX property to the specified static value.

This method fails if the scaleY parameter is NaN, positive infinity, or negative infinity.

If the ScaleY property was previously animated, this method removes the animation and sets the ScaleY property to the specified static value.

This method fails if the scaleY parameter is NaN, positive infinity, or negative infinity.

If the ScaleY property was previously animated, this method removes the animation and sets the ScaleY property to the specified static value.

This method fails if the scaleZ parameter is NaN, positive infinity, or negative infinity.

If the ScaleZ property was previously animated, this method removes the animation and sets the ScaleZ property to the specified static value.

This method fails if the scaleZ parameter is NaN, positive infinity, or negative infinity.

If the ScaleZ property was previously animated, this method removes the animation and sets the ScaleZ property to the specified static value.

This method fails if the centerX parameter is NaN, positive infinity, or negative infinity.

If the CenterX property was previously animated, this method removes the animation and sets the CenterX property to the specified static value.

This method fails if the centerX parameter is NaN, positive infinity, or negative infinity.

If the CenterX property was previously animated, this method removes the animation and sets the CenterX property to the specified static value.

This method fails if the centerY parameter is NaN, positive infinity, or negative infinity.

If the CenterY property was previously animated, this method removes the animation and sets the CenterY property to the specified static value.

This method fails if the centerY parameter is NaN, positive infinity, or negative infinity.

If the CenterY property was previously animated, this method removes the animation and sets the CenterY property to the specified static value.

This method fails if the centerZ parameter is NaN, positive infinity, or negative infinity.

If the CenterZ property was previously animated, this method removes the animation and sets the CenterZ property to the specified static value.

This method fails if the centerZ parameter is NaN, positive infinity, or negative infinity.

If the CenterZ property was previously animated, this method removes the animation and sets the CenterZ property to the specified static value.

A skew transform represents the following 3-by-3 matrix:

The effect is to slant the coordinate system along the x-axis and y-axis such that a rectangle becomes a parallelogram, and to apply the corresponding translation such that the center point does not move.

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the AngleX property unless this method is called again. If the AngleX property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the AngleX property unless this method is called again. If the AngleX property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the AngleY property unless this method is called again. If the AngleY property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the AngleY property unless this method is called again. If the AngleY property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method fails if the centerX parameter is NaN, positive infinity, or negative infinity.

If the CenterX property was previously animated, this method removes the animation and sets the CenterX property to the specified static value.

This method fails if the centerX parameter is NaN, positive infinity, or negative infinity.

If the CenterX property was previously animated, this method removes the animation and sets the CenterX property to the specified static value.

This method fails if the centerY parameter is NaN, positive infinity, or negative infinity.

If the CenterY property was previously animated, this method removes the animation and sets the CenterY property to the specified static value.

This method fails if the centerY parameter is NaN, positive infinity, or negative infinity.

If the CenterY property was previously animated, this method removes the animation and sets the CenterY property to the specified static value.

This method enables an application to incrementally update the contents of a DirectComposition surface object. The application must use the following sequence:

1. Call BeginDraw to initiate the incremental update.
2. Use the retrieved surface as a render target and draw the updated contents at the retrieved offset.
3. Call the method to finish the update.

The update object returned by this method is either a Direct2D device context or a DXGI surface, depending on the value of the iid parameter and on how the DirectComposition surface object was created. If the iid parameter is __uuidof(), then the returned object is a Direct2D device context that already has the DirectComposition surface selected as a render target. Otherwise, it is a DXGI surface which the application may use as a render target. In either case, the returned object is associated with the Direct2D or DXGI device passed by the application to the function or the method.

The iid parameter may only be __uuidof() if the DirectComposition surface object was created from a DirectComposition device or surface factory that was, itself, created with an associated Direct2D device. In particular, the application must have called either the function or the method with a Direct2D device as the renderingDevice parameter. If the DirectComposition surface was created via a surface factory that was not associated with a Direct2D device, or if it was created directly via the interface and the device was not directly associated with a Direct2D device, then passing __uuidof() as the iid parameter causes this method to return E_INVALIDARG.

If the application successfully retrieves a Direct2D device context as the update object, then the application should not call either the ID2D1DeviceContext::BeginDraw or ID2D1DeviceContext::EndDraw methods on the returned Direct2D device context.

The retrieved offset is not necessarily the same as the top-left corner of the requested update rectangle. The application must transform its rendering primitives to draw within a rectangle of the same width and height as the input rectangle, but at the given offset. The application should not draw outside of this rectangle.

If the updateRectangle parameter is null, the entire surface is updated. In that case, because the retrieved offset still might not be (0,0), the application still needs to transform its rendering primitives accordingly.

If the surface is not a virtual surface, then the first time the application calls this method for a particular non-virtual surface, the update rectangle must cover the entire surface, either by specifying the full surface in the requested update rectangle, or by specifying null as the updateRectangle parameter. For virtual surfaces, the first call may be any sub-rectangle of the surface.

Because each call to this method might retrieve a different object in the updateObject surface, the application should not cache the retrieved surface reference. The application should release the retrieved reference as soon as it finishes drawing.

The retrieved surface rectangle does not contain the previous contents of the bitmap. The application must update every pixel in the update rectangle, either by first clearing the render target, or by issuing enough rendering primitives to fully cover the update rectangle. Because the initial contents of the update surface are undefined, failing to update every pixel leads to undefined behavior.

Only one DirectComposition surface can be updated at a time. An application must suspend drawing on one surface before beginning or resuming to draw on another surface. If the application calls BeginDraw twice, either for the same surface or for another surface belonging to the same DirectComposition device, without an intervening call to , the second call fails. If the application calls without calling EndDraw, the update remains pending. The update takes effect only after the application calls EndDraw and then calls the method.

This method completes an update that was begun by a previous call to the method. After this method returns, the application can start another update on the same surface object or on a different one.

If the application calls before calling for a surface with a pending update, that update is not processed by that Commit call. The update only takes effect on screen after the application calls followed by the method.

Because only one surface can be open for drawing at a time, calling SuspendDraw allows the user to call on a different surface. Drawing to this surface can be resumed by calling .

This method allows the surface update to continue unless there are other surfaces that have active, unsuspended draws.

This method allows an application to blt/copy a sub-rectangle of a DirectComposition surface object. This avoids re-rendering content that is already available.

The scrollRect rectangle must be contained in the boundaries of the surface. If the scrollRect rectangle goes outside the bounds of the surface, this method fails.

The bits copied by the scroll operation (source) are defined by the intersection of the scrollRect and clipRect rectangles.

The bits shown on the screen (destination) are defined by the intersection of the offset source rectangle and clipRect.

Scroll operations can only be called before calling BeginDraw or after calling EndDraw. Suspended or resumed surfaces are not candidates for scrolling because they are still being updated.

The application is responsible for ensuring that the scrollable area for an is limited to valid pixels. The behavior for invalid pixels in the scrollRect is undefined.

Virtual surface sub-rectangular areas that were discarded by a trim or a resize operation can't be scrolled even if the trim or resize is applied in the same batch. Trim and Resize are applied immediately.

A Microsoft DirectComposition surface is a rectangular array of pixels that can be associated with a visual for composition. A newly created surface object is in an uninitialized state. While it is uninitialized, the surface has no effect on the composition of the visual tree. It behaves exactly like a surface that has 100% transparent pixels.

To initialize the surface with pixel data, use the method. The first call to this method must cover the entire surface area to provide an initial value for every pixel. Subsequent calls may specify smaller sub-rectangles of the surface to update.

This method will fail if either the width or height exceed the max texture size. If your scenario requires dimensions beyond the max texture size, use CreateVirtualSurface method.

DirectComposition surfaces support the following pixel formats:

A newly created virtual surface object is in an uninitialized state. While it is uninitialized, the surface has no effect on the composition of the visual tree. It behaves exactly like a surface that is initialized with 100% transparent pixels.

To initialize the surface with pixel data, use the method. This method not only provides pixels for the surface, but it also allocates actual storage space for those pixels. The memory allocation persists until the application returns some of the memory to the system. The application can free part or all of the allocated memory by calling the or method.

Microsoft DirectComposition surfaces support the following pixel formats:

A visual can be either the root of a single visual tree, or a child of another visual, but it cannot be both at the same time. This method fails if the visual parameter is already the root of another visual tree, or is a child of another visual.

If visual is null, the visual tree is empty. If there was a previous non-null root visual, that visual becomes available for use as the root of another visual tree, or as a child of another visual.

A visual can be either the root of a single visual tree, or a child of another visual, but it cannot be both at the same time. This method fails if the visual parameter is already the root of another visual tree, or is a child of another visual.

If visual is null, the visual tree is empty. If there was a previous non-null root visual, that visual becomes available for use as the root of another visual tree, or as a child of another visual.

A translation transform represents the following 3-by-2 matrix:

The effect is simply to offset the coordinate system by x and y.

This method perfoms an affine transformation, which moves every point by a fixed distance in the same direction. It is similar to shifting the origin of the coordinate space.

This method fails if the offsetX parameter is NaN, positive infinity, or negative infinity.

If the OffsetX property was previously animated, this method removes the animation and sets the OffsetX property to the specified static value.

This method perfoms an affine transformation, which moves every point by a fixed distance in the same direction. It is similar to shifting the origin of the coordinate space.

This method fails if the offsetX parameter is NaN, positive infinity, or negative infinity.

If the OffsetX property was previously animated, this method removes the animation and sets the OffsetX property to the specified static value.

This method fails if the offsetY parameter is NaN, positive infinity, or negative infinity.

If the OffsetY property was previously animated, this method removes the animation and sets the OffsetY property to the specified static value.

This method fails if the offsetY parameter is NaN, positive infinity, or negative infinity.

If the OffsetY property was previously animated, this method removes the animation and sets the OffsetY property to the specified static value.

This method makes a copy of the specified animation. If the object referenced by the animation parameter is changed after calling this method, the change does not affect the OffsetZ property unless this method is called again. If the OffsetZ property was previously animated, calling this method replaces the previous animation with the new animation.

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

This method fails if the offsetX parameter is NaN, positive infinity, or negative infinity.

If the OffsetX property was previously animated, this method removes the animation and sets the OffsetX property to the specified static value.

This method fails if the offsetX parameter is NaN, positive infinity, or negative infinity.

If the OffsetX property was previously animated, this method removes the animation and sets the OffsetX property to the specified static value.

This method fails if the offsetY parameter is NaN, positive infinity, or negative infinity.

If the OffsetY property was previously animated, this method removes the animation and sets the OffsetY property to the specified static value.

This method fails if the offsetY parameter is NaN, positive infinity, or negative infinity.

If the OffsetY property was previously animated, this method removes the animation and sets the OffsetY property to the specified static value.

This method fails if the offsetZ parameter is NaN, positive infinity, or negative infinity.

If the OffsetZ property was previously animated, this method removes the animation and sets the OffsetZ property to the specified static value.

This method fails if the offsetZ parameter is NaN, positive infinity, or negative infinity.

If the OffsetZ property was previously animated, this method removes the animation and sets the OffsetZ property to the specified static value.

When a virtual surface is resized, its contents are preserved up to the new boundaries of the surface. If the surface is made smaller, any previously allocated pixels that fall outside of the new width or height are discarded.

This method fails if was called for this bitmap without a corresponding call to .

This method fails if width or height exceeds 16,777,216 pixels.

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 method, and to release memory for the surface by calling the 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 was called for this bitmap without a corresponding call to .

This method fails if the offsetX parameter is NaN, positive infinity, or negative infinity.

Changing the OffsetX property of a visual transforms the coordinate system of the entire visual subtree that is rooted at that visual. If the Clip property of this visual is specified, the clip rectangle is also transformed.

A transformation that is specified by the Transform property is applied after the OffsetX property. In other words, the effect of setting the Transform property and the OffsetX property is the same as setting only the Transform property on a transform group object where the first member of the group is an object that has the same OffsetX value as offsetX. However, you should use 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.

If the OffsetX property was previously animated, this method removes the animation and sets the property to the specified static value.

This method fails if the offsetX parameter is NaN, positive infinity, or negative infinity.

Changing the OffsetX property of a visual transforms the coordinate system of the entire visual subtree that is rooted at that visual. If the Clip property of this visual is specified, the clip rectangle is also transformed.

A transformation that is specified by the Transform property is applied after the OffsetX property. In other words, the effect of setting the Transform property and the OffsetX property is the same as setting only the Transform property on a transform group object where the first member of the group is an object that has the same OffsetX value as offsetX. However, you should use 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.

If the OffsetX property was previously animated, this method removes the animation and sets the property to the specified static value.

This method fails if the offsetY parameter is NaN, positive infinity, or negative infinity.

Changing the OffsetY 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.

A transformation that is specified by the Transform property is applied after the OffsetY property. In other words, the effect of setting the Transform property and the OffsetY property is the same as setting only the Transform property on a transform group object where the first member of the group is an object that has the same OffsetY value as offsetY. However, you should use 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.

If the OffsetY property was previously animated, this method removes the animation and sets the property to the specified static value.

This method fails if the offsetY parameter is NaN, positive infinity, or negative infinity.

Changing the OffsetY 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.

A transformation that is specified by the Transform property is applied after the OffsetY property. In other words, the effect of setting the Transform property and the OffsetY property is the same as setting only the Transform property on a transform group object where the first member of the group is an object that has the same OffsetY value as offsetY. However, you should use 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.

If the OffsetY property was previously animated, this method removes the animation and sets the property to the specified static value.

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 object that has those same OffsetX and OffsetY values. However, you should use the and SetOffsetY methods whenever possible because they are slightly faster.

This method fails if transform is an invalid reference or if it was not created by the same 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 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.

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 object that has those same OffsetX and OffsetY values. However, you should use the and SetOffsetY methods whenever possible because they are slightly faster.

This method fails if transform is an invalid reference or if it was not created by the same 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 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.

The coordinate system of a visual is modified by the OffsetX, OffsetY, and Transform properties. Normally, these properties define the coordinate system of a visual relative to its immediate parent. This method specifies the visual relative to which the coordinate system for this visual is based. The specified visual must be an ancestor of the current visual. If it is not an ancestor, the coordinate system is based on this visual's immediate parent, just as if the TransformParent property were set to null. Because visuals can be reparented, this property can take effect again if the specified visual becomes an ancestor of the target visual through a reparenting operation.

If the visual parameter is null, the coordinate system is always transformed relative to the visual's immediate parent. This is the default behavior if this method is not used.

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

This method creates an implicit off-screen surface to which the subtree that is rooted at this visual is composed. The surface is used as one of the inputs to the specified effect. The output of the effect is composed directly to the composition target. Some effects also use the composition target as another implicit input. This is typically the case for compositional or blend effects such as opacity, where the composition target is considered to be the "background." In that case, any visuals that are "behind" the current visual are included in the composition target when the current visual is rendered and are considered to be the "background" that this visual composes to.

If this visual is not the root of a visual tree and one of its ancestors also has an effect applied to it, the off-screen surface created by the closest ancestor is the composition target to which this visual's effect is composed. Otherwise, the composition target is the root composition target. As a consequence, the background for compositional and blend effects includes only the visuals up to the closest ancestor that itself has an effect. Conversely, any effects applied to visuals under the current visual use the newly created off-screen surface as the background, which may affect how those visuals ultimately compose on top of what the end user perceives as being "behind" those visuals.

If the effect parameter is null, no bitmap effect is applied to this visual. Any previous effects that were associated with this visual are removed. The off-screen surface is also removed and the visual subtree is composed directly to the parent composition target, which may also affect how compositional or blend effects under this visual are rendered.

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

The interpolation mode affects how a bitmap is composed when it is transformed such that there is no one-to-one correspondence between pixels in the bitmap and pixels on the screen.

By default, a visual inherits the interpolation mode of the parent visual, which may inherit the interpolation mode of its parent visual, and so on. A visual uses the default interpolation mode if this method is never called for the visual, or if this method is called with . If no visuals set the interpolation mode, the default for the entire visual tree is nearest neighbor interpolation, which offers the lowest visual quality but the highest performance.

If the interpolationMode parameter is anything other than , this visual's bitmap is composed with the specified interpolation mode, and this mode becomes the new default mode for the children of this visual. That is, if the interpolation mode of this visual's children is unchanged or explicitly set to , the bitmaps of the child visuals are composed using the interpolation mode of this visual.

The border mode affects how the edges of a bitmap are composed when the bitmap is transformed such that the edges are not exactly axis-aligned and at precise pixel boundaries. It also affects how content is clipped at the corners of a clip that has rounded corners, and at the edge of a clip that is transformed such that the edges are not exactly axis-aligned and at precise pixel boundaries.

By default, a visual inherits the border mode of its parent visual, which may inherit the border mode of its parent visual, and so on. A visual uses the default border mode if this method is never called for the visual, or if this method is called with . If no visuals set the border mode, the default for the entire visual tree is aliased rendering, which offers the lowest visual quality but the highest performance.

If the borderMode parameter is anything other than , this visual's bitmap and clip are composed with the specified border mode. In addition, this border mode becomes the new default for the children of the current visual. That is, if the border mode of this visual's children is unchanged or explicitly set to , the bitmaps and clips of the child visuals are composed using the border mode of this visual.

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 rectangle, the newly specified Clip object replaces the clip rectangle.

This method fails if clip is an invalid reference or if it was not created by the same 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 clip is null, the visual is not clipped relative to its parent. However, the visual is clipped by the clip object of the parent visual, or by the closest ancestor visual that has a clip object. Setting clip to null is similar to specifying a clip object whose clip rectangle has the left and top sides set to negative infinity, and the right and bottom sides set to positive infinity. Using a null clip object results in slightly better performance.

If clip specifies a clip object that has an empty rectangle, 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.

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 rectangle, the newly specified Clip object replaces the clip rectangle.

This method fails if clip is an invalid reference or if it was not created by the same 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 clip is null, the visual is not clipped relative to its parent. However, the visual is clipped by the clip object of the parent visual, or by the closest ancestor visual that has a clip object. Setting clip to null is similar to specifying a clip object whose clip rectangle has the left and top sides set to negative infinity, and the right and bottom sides set to positive infinity. Using a null clip object results in slightly better performance.

If clip specifies a clip object that has an empty rectangle, 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.

The content parameter must point to one of the following:

• An object that implements the interface.
• An object that implements the interface.
• A wrapper object that is returned by the CreateSurfaceFromHandle or CreateSurfaceFromHwnd method.

The new content replaces any content that was previously associated with the visual. If the content parameter is null, the visual has no associated content.

A visual can be associated with a bitmap object or a window wrapper. A bitmap is either a Microsoft DirectX swap chain or a Microsoft DirectComposition surface.

A window wrapper is created with the CreateSurfaceFromHwnd method and is a stand-in for the rasterization of another window, which must be a top-level window or a layered child window. A window wrapper is conceptually equivalent to a bitmap that is the size of the target window on which the contents of the window are drawn. The contents include the target window's child windows (layered or otherwise), and any DirectComposition content that is drawn in the child windows.

A DirectComposition surface wrapper is created with the CreateSurfaceFromHandle method and is a reference to a swap chain. An application might use a surface wrapper in a cross-process scenario where one process creates the swap chain and another process associates the bitmap with a visual.

The bitmap is always drawn at position (0,0) relative to the visual's coordinate system, although the coordinate system is directly affected by the OffsetX, OffsetY, and Transform properties, as well as indirectly by the transformations on ancestor visuals. The bitmap of a visual is always drawn behind the children of that visual.

Child visuals are arranged in an ordered list. The contents of a child visual are drawn in front of (or above) the contents of its parent visual, but behind (or below) the contents of its children.

The referenceVisual parameter must be an existing child of the parent visual, or it must be null. The insertAbove parameter indicates whether the new child should be rendered immediately above the reference visual in the Z order, or immediately below it.

If the referenceVisual parameter is null, the specified visual is rendered above or below all children of the parent visual, depending on the value of the insertAbove parameter. If insertAbove is TRUE, the new child visual is above no sibling, therefore it is rendered below all of its siblings. Conversely, if insertAbove is , the visual is below no sibling, therefore it is rendered above all of its siblings.

The visual specified by the visual parameter cannot be either a child of a single other visual, or the root of a visual tree that is associated with a composition target. If visual is already a child of another visual, AddVisual fails. The child visual must be removed from the children list of its previous parent before adding it to the children list of the new parent. If visual is the root of a visual tree, the visual must be dissociated from that visual tree before adding it to the children list of the new parent. To dissociate the visual from a visual tree, call the method and specify either a different visual or null as the visual parameter.

A child visual need not have been created by the same interface as its parent. When visuals from different devices are combined in the same visual tree, Microsoft DirectComposition composes the tree as it normally would, except that changes to a particular visual take effect only when is called on the device object that created the visual. The ability to combine visuals from different devices enables multiple threads to create and manipulate a single visual tree while maintaining independent devices that can be used to commit changes asynchronously

This method fails if visual or referenceVisual is an invalid reference, or if the visual referenced by the referenceVisual parameter is not a child of the parent visual. These interfaces cannot be custom implementations; only interfaces created by DirectComposition can be used with this method.

The child visual is removed from the list of children. The order of the remaining child visuals is not changed.

This method fails if visual is not a child of the parent visual.

This method can be called even if this visual has no children.

The composite mode determines how visual's bitmap is blended with the screen. By default, the visual is blended with "source over" semantics; that is, the colors are blended with per-pixel transparency.

This method creates an implicit off-screen surface to which the subtree that is rooted at this visual is composed. The surface is used as one of the inputs to the specified effect. The output of the effect is composed directly to the composition target. Some effects also use the composition target as another implicit input. This is typically the case for compositional or blend effects such as opacity, where the composition target is considered to be the "background." In that case, any visuals that are "behind" the current visual are included in the composition target when the current visual is rendered and are considered to be the "background" that this visual composes to.

If this visual is not the root of a visual tree and one of its ancestors also has an effect applied to it, the off-screen surface created by the closest ancestor is the composition target to which this visual's effect is composed. Otherwise, the composition target is the root composition target. As a consequence, the background for compositional and blend effects includes only the visuals up to the closest ancestor that itself has an effect. Conversely, any effects applied to visuals under the current visual use the newly created off-screen surface as the background, which may affect how those visuals ultimately compose on top of what the end user perceives as being "behind" those visuals.

If the effect parameter is null, no bitmap effect is applied to this visual. Any previous effects that were associated with this visual are removed. The off-screen surface is also removed and the visual subtree is composed directly to the parent composition target, which may also affect how compositional or blend effects under this visual are rendered.

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

The interpolation mode affects how a bitmap is composed when it is transformed such that there is no one-to-one correspondence between pixels in the bitmap and pixels on the screen.

By default, a visual inherits the interpolation mode of the parent visual, which may inherit the interpolation mode of its parent visual, and so on. A visual uses the default interpolation mode if this method is never called for the visual, or if this method is called with . If no visuals set the interpolation mode, the default for the entire visual tree is nearest neighbor interpolation, which offers the lowest visual quality but the highest performance.

If the interpolationMode parameter is anything other than , this visual's bitmap is composed with the specified interpolation mode, and this mode becomes the new default mode for the children of this visual. That is, if the interpolation mode of this visual's children is unchanged or explicitly set to , the bitmaps of the child visuals are composed using the interpolation mode of this visual.

The border mode affects how the edges of a bitmap are composed when the bitmap is transformed such that the edges are not exactly axis-aligned and at precise pixel boundaries. It also affects how content is clipped at the corners of a clip that has rounded corners, and at the edge of a clip that is transformed such that the edges are not exactly axis-aligned and at precise pixel boundaries.

By default, a visual inherits the border mode of its parent visual, which may inherit the border mode of its parent visual, and so on. A visual uses the default border mode if this method is never called for the visual, or if this method is called with . If no visuals set the border mode, the default for the entire visual tree is aliased rendering, which offers the lowest visual quality but the highest performance.

If the borderMode parameter is anything other than , this visual's bitmap and clip are composed with the specified border mode. In addition, this border mode becomes the new default for the children of the current visual. That is, if the border mode of this visual's children is unchanged or explicitly set to , the bitmaps and clips of the child visuals are composed using the border mode of this visual.

The content parameter must point to one of the following:

• An object that implements the interface.
• An object that implements the interface.
• A wrapper object that is returned by the CreateSurfaceFromHandle or CreateSurfaceFromHwnd method.

The new content replaces any content that was previously associated with the visual. If the content parameter is null, the visual has no associated content.

A visual can be associated with a bitmap object or a window wrapper. A bitmap is either a Microsoft DirectX swap chain or a Microsoft DirectComposition surface.

A window wrapper is created with the CreateSurfaceFromHwnd method and is a stand-in for the rasterization of another window, which must be a top-level window or a layered child window. A window wrapper is conceptually equivalent to a bitmap that is the size of the target window on which the contents of the window are drawn. The contents include the target window's child windows (layered or otherwise), and any DirectComposition content that is drawn in the child windows.

A DirectComposition surface wrapper is created with the CreateSurfaceFromHandle method and is a reference to a swap chain. An application might use a surface wrapper in a cross-process scenario where one process creates the swap chain and another process associates the bitmap with a visual.

The bitmap is always drawn at position (0,0) relative to the visual's coordinate system, although the coordinate system is directly affected by the OffsetX, OffsetY, and Transform properties, as well as indirectly by the transformations on ancestor visuals. The bitmap of a visual is always drawn behind the children of that visual.

The composite mode determines how visual's bitmap is blended with the screen. By default, the visual is blended with "source over" semantics; that is, the colors are blended with per-pixel transparency.

The opacity mode affects how the Opacity property of an effect group object affects the composition of a visual sub-tree. DirectComposition supports two opacity modes: Layer and Multiply. In Layer mode, each visual sub-tree can be logically viewed as a bitmap that contains the opaque rasterization of that entire sub-tree, to which the opacity value is then applied. In this manner, overlapping opaque surfaces blend with the sub-tree?s background, but not with each other. In contrast, in Multiply mode the opacity is applied individually to each surface as it is composed, so surfaces blend with each other. Multiply mode is faster than Layer mode and always preferred if the visual tree contains entirely non-overlapping contents. However, Multiply mode may produce undesired visual results for overlapping elements.

By default, a visual inherits the opacity mode of its parent visual, which may inherit the opacity mode of its parent visual, and so on. A visual uses the mode if this method is never called for the visual, or if this method is called with . If no visuals set the opacity mode, the default for the entire visual tree is .

If the opacityMode parameter is anything other than , this visual's surfaces are composed with the specified opacity mode. In addition, this opacity mode becomes the new default for the children of the current visual. That is, if the opacity mode of this visual's children is unchanged or explicitly set to , the surfaces the child visuals are composed using the opacity mode of this visual.

The back face visibility property affects how surfaces that have 3D transformations applied are rendered.

By default, a visual inherits the back face visibility property of its parent visual, which may inherit the back face visibility property of its parent visual, and so on. A visual uses the mode if this method is never called for the visual, or if this method is called with . If no visuals set the back face visibility property, the default for the entire visual tree is .

If the visibility parameter is anything other than , this visual's surfaces are composed with the specified visibility mode. In addition, this visibility mode becomes the new default for the children of the current visual. That is, if the visibility mode of this visual's children is unchanged or explicitly set to , the surfaces the child visuals are composed using the visibility mode of this visual.

The opacity mode affects how the Opacity property of an effect group object affects the composition of a visual sub-tree. DirectComposition supports two opacity modes: Layer and Multiply. In Layer mode, each visual sub-tree can be logically viewed as a bitmap that contains the opaque rasterization of that entire sub-tree, to which the opacity value is then applied. In this manner, overlapping opaque surfaces blend with the sub-tree?s background, but not with each other. In contrast, in Multiply mode the opacity is applied individually to each surface as it is composed, so surfaces blend with each other. Multiply mode is faster than Layer mode and always preferred if the visual tree contains entirely non-overlapping contents. However, Multiply mode may produce undesired visual results for overlapping elements.

By default, a visual inherits the opacity mode of its parent visual, which may inherit the opacity mode of its parent visual, and so on. A visual uses the mode if this method is never called for the visual, or if this method is called with . If no visuals set the opacity mode, the default for the entire visual tree is .

If the opacityMode parameter is anything other than , this visual's surfaces are composed with the specified opacity mode. In addition, this opacity mode becomes the new default for the children of the current visual. That is, if the opacity mode of this visual's children is unchanged or explicitly set to , the surfaces the child visuals are composed using the opacity mode of this visual.

The back face visibility property affects how surfaces that have 3D transformations applied are rendered.

By default, a visual inherits the back face visibility property of its parent visual, which may inherit the back face visibility property of its parent visual, and so on. A visual uses the mode if this method is never called for the visual, or if this method is called with . If no visuals set the back face visibility property, the default for the entire visual tree is .

If the visibility parameter is anything other than , this visual's surfaces are composed with the specified visibility mode. In addition, this visibility mode becomes the new default for the children of the current visual. That is, if the visibility mode of this visual's children is unchanged or explicitly set to , the surfaces the child visuals are composed using the visibility mode of this visual.

Heatmaps can be enabled by calling EnableHeatMap. The heatmaps are drawn on the source of the VisualDebug visual and child visuals. The heatmaps are represented in a specified color for all visual content. The heatmap color must have an transparency in order to see the overlaying overdraw regions. The colored surfaces are blended together to visually show all overdraw regions in a single view.

Highlighting redraw regions can be enabled by calling EnableRedrawRegions. With this function, redrawn client areas are visually highlighted every frame the visual is updated. Redraw regions are drawn on the source of the VisualDebug and child visuals. Redraw is triggered when properties of a visual are updated. The updated visusal does not neccessarly need to visually change to trigger a redraw. The highlighting will cycle through Blue, Yellow, Pink and Green to provide an order of which content is being updated. The redraw regions are only visible while the window of the VisualDebug is being updated.

The method fills this structure. An application can use the information in this structure to estimate the timestamp of the next few frames that will be started by the composition engine. Note that this is only an estimate because the composition engine may or may not compose the next frame, depending on whether any active animations or other work are pending for that frame. In addition, the composition engine may change frame rates according to the cost of composing individual frames.