CompositionTarget CompositionTarget CompositionTarget CompositionTarget Class

Definition

Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Prerelease APIs are identified by a Prerelease label.

[Contains prerelease APIs.]
Represents the composited display surface for an app. This class is mainly for Microsoft DirectX content interop scenarios.

public : sealed class CompositionTarget : ICompositionTarget
struct winrt::Windows::UI::Xaml::Media::CompositionTarget : ICompositionTarget
public sealed class CompositionTarget : ICompositionTarget
Public NotInheritable Class CompositionTarget Implements ICompositionTarget
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

CompositionTarget has one member, Rendering. Rendering is a static event that is fired by the XAML rendering system overall, not by the Application, Window, Page or any other specific object part of an app. CompositionTarget 's sole purpose is to provide this hook into the rendering process. That's mainly relevant only to Microsoft DirectX content interop scenarios where you want to know when the XAML rendering happens, so that you can execute some Microsoft DirectX code in response. For scenarios that don't involve Microsoft DirectX content you probably won't need Rendering and can just rely on the XAML rendering system running and performing all your composition and layout.

Events

Rendered Rendered Rendered Rendered

Prerelease. Occurs immediately after the core rendering process renders a frame. This event lets you determine how long each frame takes to render.

public : event EventHandler Rendered<RenderedEventArgs>
// Register
event_token Rendered(EventHandler<RenderedEventArgs> const& handler) const;

// Revoke with event_token
void Rendered(event_token const& cookie) const;

// Revoke with event_revoker
Rendered_revoker Rendered(auto_revoker_t, EventHandler<RenderedEventArgs> const& handler) const;
public event EventHandler Rendered<RenderedEventArgs>
Public Event EventHandler Rendered( Of ( Of RenderedEventArgs ))
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.17095.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v6)

Remarks

Tip

We recommend that you use the Visual Studio Application Timeline profiler when developing and testing your application. It gives more detailed information on your application's resource consumption, including time spent preparing UI frames.

You can use the Rendered event to measure frame duration and application responsiveness at runtime without Visual Studio or a debugger attached. For example, this could be used to generate telemetry for apps after they are deployed, or to adjust the amount of custom DirectX rendering work an application is doing each frame.

A longer frame duration means your app had to perform more work before a frame could be rendered. Frame durations longer than approximately 16 milliseconds mean that your application is not able to update at the recommended frequency of 60 frames per second, and so the user might experience a noticeable delay in UI responsiveness.

If you do see long frame durations then consider profiling your application using the Visual Studio Application Timeline and implementing the recommended Performance best practices.

Handlers for Rendered run on the UI thread even though they're not tied to any specific UI element. It's a good idea to remove any Rendered handlers when you no longer need them, and add them only when you do need them.

Rendering Rendering Rendering Rendering

Occurs when the core rendering process renders a frame.

public : event EventHandler Rendering<Platform::Object>
// Register
event_token Rendering(EventHandler<Platform::Object> const& handler) const;

// Revoke with event_token
void Rendering(event_token const& cookie) const;

// Revoke with event_revoker
Rendering_revoker Rendering(auto_revoker_t, EventHandler<Platform::Object> const& handler) const;
public event EventHandler Rendering<object>
Public Event EventHandler Rendering( Of ( Of object ))

Remarks

Handling Rendering is mainly interesting if you have interop scenarios with Microsoft DirectX content. For example you might want to know when the XAML system is rendering and synchronize that with your Microsoft DirectX generated content and when your SwapChainPanel draws. For more info, see DirectX and XAML interop.

Because this event is for an interop scenario, it's rare that you would handle Rendering in C# or Microsoft Visual Basic code. You'd usually only handle it in the Visual C++ component extensions (C++/CX) code that supports the XAML portion of your UI, as part of an interop/hybrid app that also has a Microsoft DirectX component.

To satisfy the compiler, the second e/args parameter of your handler for a Rendering event must be Object. Don't use EventArgs. However, within the handler, you can cast the e/args reference as RenderingEventArgs. RenderingEventArgs has one property, RenderingTime, that might be useful in your rendering scenario, but not all handlers would need this info. It may be enough just to know that the event fires and handle every occurrence.

Handlers for Rendering run on the UI thread even though they're not tied to any specific UI element. It's a good idea to remove any Rendering handlers when you no longer need them, and add them only when you do need them. For example add the handler only when specific pages with interop content are loaded, and then remove the handler as part of page cleanup (OnNavigatedFrom ).

For example code of handling Rendering, see shooting game sample. The App::OnRendering method in this sample is the handler. This handler is noteworthy because it has code in it that checks its own UI state (such as checking for whether the control has focus). For certain states the handler acts as its own one-time cleanup by calling ::remove with an app-level stored event token from the initial ::add.

See Also

SurfaceContentsLost SurfaceContentsLost SurfaceContentsLost SurfaceContentsLost

Occurs when an underlying major change occurs, such as a DirectX device change. Typically the application must regenerate its surface contents when notified of this event.

public : event EventHandler SurfaceContentsLost<Platform::Object>
// Register
event_token SurfaceContentsLost(EventHandler<Platform::Object> const& handler) const;

// Revoke with event_token
void SurfaceContentsLost(event_token const& cookie) const;

// Revoke with event_revoker
SurfaceContentsLost_revoker SurfaceContentsLost(auto_revoker_t, EventHandler<Platform::Object> const& handler) const;
public event EventHandler SurfaceContentsLost<object>
Public Event EventHandler SurfaceContentsLost( Of ( Of object ))

See Also