RenderTargetBitmap RenderTargetBitmap RenderTargetBitmap Class

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.

Syntax

Declaration

public sealed class RenderTargetBitmappublic sealed class RenderTargetBitmapPublic NotInheritable Class RenderTargetBitmap

Inheritance Hierarchy

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(Windows.UI.Xaml.UIElement) 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(Windows.UI.Xaml.UIElement) 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.Imaging API.

The RenderTargetBitmap API you'll use the most often is RenderAsync(Windows.UI.Xaml.UIElement). There are two overloads of this method: RenderAsync(Windows.UI.Xaml.UIElement) and RenderAsync(Windows.UI.Xaml.UIElement,System.Int32,System.Int32) where you can specify the desired dimensions of the image source to be different than the natural size of the source visual tree. RenderAsync(Windows.UI.Xaml.UIElement) 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(Windows.UI.Xaml.UIElement) 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 SurfaceContentsLost event will fire. To account for this case and similar info-loss cases, apps should listen for the SurfaceContentsLost event and re-render the contents of a RenderTargetBitmap by calling RenderAsync(Windows.UI.Xaml.UIElement) 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 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 (). This limit can vary depending on the hardware whre 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 capabilitie

s

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

  • Video content in a MediaElement or CaptureElement can't be captured using RenderTargetBitmap. That includes capturing frames from within video content.
  • Custom Microsoft DirectX content (your own swap chain) inside a SwapChainBackgroundPanel or SwapChainPanel can't be captured using 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.
  • For Windows Phone Store app: the contents of a WebView control can't be rendered into a RenderTargetBitmap.
  • 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 or in the other restricted cases.

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; 
}

Constructors summary

Initializes a new instance of the RenderTargetBitmap class.

Properties summary

Gets the height of the rendered bitmap in pixels.

Identifies the PixelHeight dependency property.

Gets the width of the rendered bitmap in pixels.

Identifies the PixelWidth dependency property.

Methods summary

Retrieves the previously rendered RenderTargetBitmap image as a buffered stream of bytes in BGRA8 format.

Renders a snapshot of a UIElement visual tree to an image source.

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.

Constructors

  • RenderTargetBitmap()
    RenderTargetBitmap()
    RenderTargetBitmap()
    RenderTargetBitmap()

    Initializes a new instance of the RenderTargetBitmap class.

    public RenderTargetBitmap()public RenderTargetBitmap()Public Function RenderTargetBitmap() As

Properties

  • PixelHeight
    PixelHeight
    PixelHeight
    PixelHeight

    Gets the height of the rendered bitmap in pixels.

    public int PixelHeight { get; }public int PixelHeight { get; }Public ReadOnly Property PixelHeight As int

    Property Value

    • int
      int
      int

      The height of the rendered bitmap in pixels.

    Remarks

    Don't rely on this value prior to RenderAsync(Windows.UI.Xaml.UIElement) being called.

    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 (). This resource 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 resource limit on 2D textures being applied.

  • PixelHeightProperty
    PixelHeightProperty
    PixelHeightProperty
    PixelHeightProperty

    Identifies the PixelHeight dependency property.

    public static DependencyProperty PixelHeightProperty { get; }public static DependencyProperty PixelHeightProperty { get; }Public Static ReadOnly Property PixelHeightProperty As DependencyProperty

    Property Value

  • PixelWidth
    PixelWidth
    PixelWidth
    PixelWidth

    Gets the width of the rendered bitmap in pixels.

    public int PixelWidth { get; }public int PixelWidth { get; }Public ReadOnly Property PixelWidth As int

    Property Value

    • int
      int
      int

      The width of the rendered bitmap in pixels.

    Remarks

    Don't rely on this value prior to RenderAsync(Windows.UI.Xaml.UIElement) being called.

    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 (). This resource 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 resource limit on 2D textures being applied.

  • PixelWidthProperty
    PixelWidthProperty
    PixelWidthProperty
    PixelWidthProperty

    Identifies the PixelWidth dependency property.

    public static DependencyProperty PixelWidthProperty { get; }public static DependencyProperty PixelWidthProperty { get; }Public Static ReadOnly Property PixelWidthProperty As DependencyProperty

    Property Value

Methods

  • GetPixelsAsync()
    GetPixelsAsync()
    GetPixelsAsync()
    GetPixelsAsync()

    Retrieves the previously rendered RenderTargetBitmap image as a buffered stream of bytes in BGRA8 format.

    public IAsyncOperation<IBuffer> GetPixelsAsync()public IAsyncOperation<IBuffer> GetPixelsAsync()Public Function GetPixelsAsync() As IAsyncOperation( Of IBuffer )

    Returns

    • When this method returns, an IBuffer stream that contains bytes. This is the binary data for the image and can be converted to a byte array in BGRA8 format

    Remarks

    The IBuffer return value enables passing the result to a WriteableBitmap and its PixelBuffer. Another alternative is passing the buffer to a BitmapEncoder. If you want an array of bytes, use a DataReader and the FromBuffer(Windows.Storage.Streams.IBuffer) method to help with the conversion.

    Through the IAsyncOperation<TResult> intermediate value, this method returns the pixels of the image source that was produced by the most recent call to RenderAsync(Windows.UI.Xaml.UIElement).

    Always call RenderAsync(Windows.UI.Xaml.UIElement) before calling GetPixelsAsync(). If you call GetPixelsAsync() and never called RenderAsync(Windows.UI.Xaml.UIElement) previously on that RenderTargetBitmap instance, GetPixelsAsync() will return an empty buffer stream, and no error will occur (async Status is Completed, so you can't use that as an indicator).

  • RenderAsync(Windows.UI.Xaml.UIElement)
    RenderAsync(Windows.UI.Xaml.UIElement)
    RenderAsync(Windows.UI.Xaml.UIElement)
    RenderAsync(Windows.UI.Xaml.UIElement)

    Renders a snapshot of a UIElement visual tree to an image source.

    public IAsyncAction RenderAsync(Windows.UI.Xaml.UIElement element)public IAsyncAction RenderAsync(Windows.UI.Xaml.UIElement element)Public Function RenderAsync(element As Windows.UI.Xaml.UIElement) As IAsyncAction

    Parameters

    Returns

    Remarks

    The rendered image isn't returned by this method. But after it returns, so long as the async Status value doesn't indicate an error, the RenderTargetBitmap that called it will have valid image info. The RenderTargetBitmap can then be assigned in code as an image source for an Image control or ImageBrush instance.

    If you need a pixel buffer representation of the rendered content and not just an image source, use GetPixelsAsync() after calling RenderAsync(Windows.UI.Xaml.UIElement).

    This is an async method, so there's no guarantee of exact frame synchronization with the UI source. See Remarks in RenderTargetBitmap for info on some other limitations.

    You can pass null for the element parameter, and that renders the root visual tree of the app.

    XAML visuals and RenderTargetBitmap capture capabilitie

    s

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

    • Video content in a MediaElement or CaptureElement can't be captured using RenderTargetBitmap. That includes capturing frames from within video content.
    • Custom Microsoft DirectX content (your own swap chain) inside a SwapChainBackgroundPanel or SwapChainPanel can't be captured using RenderTargetBitmap.
    • Content that's in the XAML visual tree but offscreen won't be captured. 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).
  • RenderAsync(Windows.UI.Xaml.UIElement,System.Int32,System.Int32)
    RenderAsync(Windows.UI.Xaml.UIElement,System.Int32,System.Int32)
    RenderAsync(Windows.UI.Xaml.UIElement,System.Int32,System.Int32)
    RenderAsync(Windows.UI.Xaml.UIElement,System.Int32,System.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.

    public IAsyncAction RenderAsync(Windows.UI.Xaml.UIElement element,System.Int32 scaledWidth,System.Int32 scaledHeight)public IAsyncAction RenderAsync(Windows.UI.Xaml.UIElement element,System.Int32 scaledWidth,System.Int32 scaledHeight)Public Function RenderAsync(element As Windows.UI.Xaml.UIElement,scaledWidth As System.Int32,scaledHeight As System.Int32) As IAsyncAction

    Parameters

    • element

      A UIElement that represents the visual tree fragment to render.

    • scaledWidth
      System.Int32
      System.Int32
      System.Int32

      Specifies the target width at which to render. The default is 0. scaledWidth and/or scaledHeight can be optional; see Remarks.

    • scaledHeight
      System.Int32
      System.Int32
      System.Int32

      Specifies the target height at which to render. The default is 0. scaledWidth and/or scaledHeight can be optional; see Remarks.

    Returns

    Remarks

    The rendered image isn't returned by this method. But after it returns, so long as the async Status value doesn't indicate an error, the RenderTargetBitmap that called it will have valid image info. The RenderTargetBitmap can then be assigned in code as an image source for an Image control or ImageBrush instance.

    If you need a pixel buffer representation of the rendered content and not just an image source, use GetPixelsAsync() after calling RenderAsync(Windows.UI.Xaml.UIElement).

    This is an async method, so there's no guarantee of exact frame synchronization with the UI source. See Remarks in RenderTargetBitmap for info on some other limitations.

    Calling RenderAsync(Windows.UI.Xaml.UIElement) will fail if the scaled height or width of the UIElement visual tree are larger than the amount of video memory the system is able to allocate internally.

    You can pass null for the element parameter, and that renders the root visual tree of the app.

    scaledWidth and scaledHeight values

    If scaledWidth and scaledHeight are both set, the aspect ratio of the original bitmap is ignored, and your values can alter the aspect ratio.

    If either scaledWidth or scaledHeight but not both is specified, the value you provide controls that dimension but the aspect ratio is preserved (the other dimension is calculated based on factoring the original bitmap's aspect ratio).

    You can call this method and leave the scaledWidth and scaledHeight values both as 0. In this case the UIElement tree will be rendered at its native size. This is the same behavior as the RenderAsync(Windows.UI.Xaml.UIElement) overload.

    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 (). This resource 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 resource limit on 2D textures being applied.

    XAML visuals and RenderTargetBitmap capture capabilitie

    s

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

    • Video content in a MediaElement or CaptureElement can't be captured using RenderTargetBitmap. That includes capturing frames from within video content.
    • Custom Microsoft DirectX content (your own swap chain) inside a SwapChainBackgroundPanel or SwapChainPanel can't be captured using RenderTargetBitmap.
    • Content that's in the XAML visual tree but offscreen won't be captured. 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).

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.StaticAttribute

Details

Assembly

Windows.UI.Xaml.Media.Imaging.dll