RenderTargetBitmap Class

Reference

Definition

Namespace:: Microsoft.UI.Xaml.Media.Imaging

Important

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

Edit

Represents an image source that can be populated with the combined contents of a XAML visual tree. See for some notable limitations on which XAML visuals can be captured in a RenderTargetBitmap.

public ref class RenderTargetBitmap sealed : ImageSource

/// [Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class RenderTargetBitmap final : ImageSource

[Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class RenderTargetBitmap : ImageSource

Public NotInheritable Class RenderTargetBitmap
Inherits ImageSource

Inheritance: Object Platform::Object IInspectable DependencyObject ImageSource RenderTargetBitmap

Attributes: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Examples

This basic code outline is adapted from the first scenario XAML and code of the XAML render to bitmap sample. Note how all the code, even the constructor, is within an async method. Here it's an event handler for a button that a user clicks to initiate the rendering request.

<StackPanel> 
  <Button Content="Save as image source" Click="SaveImageSource_Click"/> 
...
  <Grid x:Name="RenderedGrid" Height="500"/>
  <!--user adds child-item content to this Grid using other code, not shown-->
...
  <Image x:Name="RenderedImage" Stretch="None"/>
  <!-- this Image has no Source yet, will be set by a RenderTargetBitmap.RenderAsync call --> 
</StackPanel>

private async void SaveImageSource_Click(object sender, RoutedEventArgs e) 
{                        
...
    RenderTargetBitmap renderTargetBitmap = new RenderTargetBitmap(); 
    await renderTargetBitmap.RenderAsync(RenderedGrid, width, height); 
    RenderedImage.Source = renderTargetBitmap; 
}

Remarks

Using a RenderTargetBitmap, you can accomplish scenarios such as applying image effects to a visual that originally came from a XAML UI composition, generating thumbnail images of child pages for a navigation system, or enabling the user to save parts of the UI as an image source and then share that image with other apps.

Because RenderTargetBitmap is a subclass of ImageSource, it can be used as the image source for Image elements or an ImageBrush brush.

Calling RenderAsync provides a useful image source but the full buffer representation of rendering content is not copied out of video memory until the app calls GetPixelsAsync. It is faster to call RenderAsync only (without calling GetPixelsAsync) and use the RenderTargetBitmap as an Image or ImageBrush source if the app only intends to display the rendered content and does not need the pixel data. You probably do need the pixel data if you intend to capture the image for a DataTransferManager operation such as a Share contract exchange, or if you want to apply effects to the image or transcode it using the Windows.Graphics.ImagingAPI.

The RenderTargetBitmap API you'll use the most often is RenderAsync. There are two overloads of this method: RenderAsync(UIElement) and another overload where you can specify the desired dimensions of the image source to be different than the natural size of the source visual tree. RenderAsync is an async method by design, so there's no guarantee of exact frame synchronization with the UI source, but it's close enough timing-wise for most scenarios.

A RenderTargetBitmap object isn't typically declared in a XAML UI, because you need to call RenderAsync in code before you have a useful, image-populated instance of RenderTargetBitmap for UI display purposes.

For more code examples of using RenderTargetBitmap, see XAML render to bitmap sample.

The contents of a RenderTargetBitmap can be lost in rare cases because of interaction with other lower-level systems, for example if the video driver is reset as part of a recovery (see Timeout Detection and Recovery (TDR)). If that happens, the CompositionTarget.SurfaceContentsLost event will fire. To account for this case and similar info-loss cases, apps should listen for the CompositionTarget.SurfaceContentsLost event and re-render the contents of a RenderTargetBitmap by calling RenderAsync again.

The rendered bitmap contents of a RenderTargetBitmap do not automatically scale when the current DPI setting changes. Apps should re-render the contents of a RenderTargetBitmap when the current view's DPI setting changes in order to ensure that the rendered vector content remains crisp. For example, a resize can occur if the user moves an app between two monitors running at a different DPI setting. Consider listening for the DisplayInformation.DpiChanged event to detect these cases.

The maximum rendered size of a XAML visual tree is restricted by the maximum dimensions of a Microsoft DirectX texture; for more info see Resource Limits (Direct3D 11). This limit can vary depending on the hardware where the app runs. Very large content that exceeds this limit might be scaled to fit. If scaling limits are applied in this way, the rendered size after scaling can be queried using the PixelWidth and PixelHeight properties. For example, a 10000 by 10000 pixel XAML visual tree might be scaled to 4096 by 4096 pixels, an example of a particular limit as forced by the hardware where the app runs.

XAML visuals and RenderTargetBitmap capture capabilities

There are a few scenarios for XAML-composed visual content that you can't capture to a RenderTargetBitmap:

Content that's in the tree but with its Visibility set to Collapsed won't be captured.
Content that's not directly connected to the XAML visual tree and the content of the main window won't be captured. This includes Popup content, which is considered to be like a sub-window.
Content that can't be captured will appear as blank in the captured image, but other content in the same visual tree can still be captured and will render (the presence of content that can't be captured won't invalidate the entire capture of that XAML composition).
Content that's in the XAML visual tree but offscreen can be captured, so long as it's not Visibility = Collapsed.

Constructors

RenderTargetBitmap()

Initializes a new instance of the RenderTargetBitmap class.

Properties

Dispatcher	Always returns `null` in a Windows App SDK app. Use DispatcherQueue instead. (Inherited from DependencyObject)
DispatcherQueue	Gets the `DispatcherQueue` that this object is associated with. The `DispatcherQueue` represents a facility that can access the `DependencyObject` on the UI thread even if the code is initiated by a non-UI thread. (Inherited from DependencyObject)
PixelHeight	Gets the height of the rendered bitmap in pixels.
PixelHeightProperty	Identifies the PixelHeight dependency property.
PixelWidth	Gets the width of the rendered bitmap in pixels.
PixelWidthProperty	Identifies the PixelWidth dependency property.

Methods

ClearValue(DependencyProperty)	Clears the local value of a dependency property. (Inherited from DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetPixelsAsync()	Retrieves the previously rendered RenderTargetBitmap image as a buffered stream of bytes in BGRA8 format.
GetValue(DependencyProperty)	Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
ReadLocalValue(DependencyProperty)	Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance. (Inherited from DependencyObject)
RenderAsync(UIElement, Int32, Int32)	Renders a snapshot of a UIElement visual tree to an image source. Specify values for scaledWidth and scaledHeight to alter the original source's rendering dimension.
RenderAsync(UIElement)	Renders a snapshot of a UIElement visual tree to an image source.
SetValue(DependencyProperty, Object)	Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback. (Inherited from DependencyObject)

Applies to

Share via