RenderTargetBitmap.RenderAsync Method
Definition
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.
Overloads
| RenderAsync(UIElement) |
Renders a snapshot of a UIElement visual tree to an image source. |
| 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)
public:
virtual IAsyncAction ^ RenderAsync(UIElement ^ element) = RenderAsync;/// [Windows.Foundation.Metadata.Overload("RenderAsync")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncAction RenderAsync(UIElement const& element);[Windows.Foundation.Metadata.Overload("RenderAsync")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncAction RenderAsync(UIElement element);function renderAsync(element)Public Function RenderAsync (element As UIElement) As IAsyncActionParameters
Returns
An IAsyncAction object that you can use to control the asynchronous operation.
- Attributes
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 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 8.x 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.
See also
Applies to
RenderAsync(UIElement, Int32, Int32)
public:
virtual IAsyncAction ^ RenderAsync(UIElement ^ element, int scaledWidth, int scaledHeight) = RenderAsync;/// [Windows.Foundation.Metadata.Overload("RenderToSizeAsync")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncAction RenderAsync(UIElement const& element, int const& scaledWidth, int const& scaledHeight);[Windows.Foundation.Metadata.Overload("RenderToSizeAsync")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncAction RenderAsync(UIElement element, int scaledWidth, int scaledHeight);function renderAsync(element, scaledWidth, scaledHeight)Public Function RenderAsync (element As UIElement, scaledWidth As Integer, scaledHeight As Integer) As IAsyncActionParameters
- scaledWidth
-
Int32
int
Specifies the target width at which to render. The default is 0. scaledWidth and/or scaledHeight can be optional; see Remarks.
- scaledHeight
-
Int32
int
Specifies the target height at which to render. The default is 0. scaledWidth and/or scaledHeight can be optional; see Remarks.
Returns
An IAsyncAction object that you can use to control the asynchronous operation.
- Attributes
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 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 8.x 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.