RenderTargetBitmap RenderTargetBitmap RenderTargetBitmap RenderTargetBitmap Class

Definition

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 : sealed class RenderTargetBitmap : ImageSource, IRenderTargetBitmappublic sealed class RenderTargetBitmap : ImageSource, IRenderTargetBitmapPublic NotInheritable Class RenderTargetBitmap Inherits ImageSource Implements IRenderTargetBitmap// This API is not available in Javascript.
Inheritance
RenderTargetBitmapRenderTargetBitmapRenderTargetBitmapRenderTargetBitmap
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited methods

Inherited properties

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.Imaging API.

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 (). 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 capabilities

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.

Constructors

RenderTargetBitmap() RenderTargetBitmap() RenderTargetBitmap() RenderTargetBitmap()

Initializes a new instance of the RenderTargetBitmap class.

public : RenderTargetBitmap()public RenderTargetBitmap()Public Sub New()// This API is not available in Javascript.

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// This API is not available in Javascript.
Value
int int int int

The height of the rendered bitmap in pixels.

Remarks

Don't rely on this value prior to RenderAsync 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// This API is not available in Javascript.
Value
DependencyProperty DependencyProperty DependencyProperty DependencyProperty

The identifier for the PixelHeight dependency property.

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// This API is not available in Javascript.
Value
int int int int

The width of the rendered bitmap in pixels.

Remarks

Don't rely on this value prior to RenderAsync 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// This API is not available in Javascript.
Value
DependencyProperty DependencyProperty DependencyProperty DependencyProperty

The identifier for the PixelWidth dependency property.

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 )// This API is not available in Javascript.
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 method to help with the conversion.

Through the IAsyncOperation intermediate value, this method returns the pixels of the image source that was produced by the most recent call to RenderAsync.

Always call RenderAsync before calling GetPixelsAsync. If you call GetPixelsAsync and never called RenderAsync 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).

See Also

RenderAsync(UIElement) RenderAsync(UIElement) RenderAsync(UIElement) RenderAsync(UIElement)

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

public : IAsyncAction RenderAsync(UIElement element)public IAsyncAction RenderAsync(UIElement element)Public Function RenderAsync(element As UIElement) As IAsyncAction// This API is not available in Javascript.
Parameters
element
UIElement UIElement UIElement UIElement

A UIElement that represents the visual tree fragment to render.

Returns

When this method returns, an IAsyncAction object that can be used to control the asynchronous operation.

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.

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 capabilities

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).
See Also

RenderAsync(UIElement, Int32, Int32) RenderAsync(UIElement, Int32, Int32) RenderAsync(UIElement, Int32, Int32) 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.

public : IAsyncAction RenderAsync(UIElement element, int scaledWidth, int scaledHeight)public IAsyncAction RenderAsync(UIElement element, Int32 scaledWidth, Int32 scaledHeight)Public Function RenderAsync(element As UIElement, scaledWidth As Int32, scaledHeight As Int32) As IAsyncAction// This API is not available in Javascript.
Parameters
element
UIElement UIElement UIElement UIElement

A UIElement that represents the visual tree fragment to render.

scaledWidth
int Int32 Int32 Int32

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

scaledHeight
int Int32 Int32 Int32

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

Returns

When this method returns, an IAsyncAction object that can be used to control the asynchronous operation.

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.

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 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(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 capabilities

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).
See Also

See Also