Windows Dev Center

RenderTargetBitmap.RenderAsync(UIElement, Int32, Int32) method

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.

Syntax


Public Function RenderAsync(
  element As UIElement,  
  scaledWidth As Integer,  
  scaledHeight As Integer 
) As IAsyncAction

Parameters

element

Type: UIElement

A UIElement that represents the visual tree fragment to render.

scaledWidth

Type: System.Int32 [.NET] | int32 [C++]

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

scaledHeight

Type: System.Int32 [.NET] | int32 [C++]

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

Return value

Type: IAsyncAction

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

Requirements (Windows 10 device family)

Device family

Universal

API contract

Windows.Foundation.UniversalApiContract, introduced version 1.0

Namespace

Windows.UI.Xaml.Media.Imaging
Windows::UI::Xaml::Media::Imaging [C++]

Metadata

Windows.Foundation.UniversalApiContract.winmd

Requirements (Windows 8.x and Windows Phone 8.x)

Minimum supported client

Windows 8.1

Minimum supported server

Windows Server 2012 R2

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml.Media.Imaging
Windows::UI::Xaml::Media::Imaging [C++]

Metadata

Windows.winmd

See also

RenderTargetBitmap
RenderAsync(UIElement)
XAML render to bitmap sample

 

 

Show:
© 2015 Microsoft