RenderTargetBitmap class

Applies to Windows and Windows Phone

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

Inheritance

Object
  DependencyObject
    ImageSource
      RenderTargetBitmap

Syntax


public sealed class RenderTargetBitmap : ImageSource

Attributes

[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06030000)]
[WebHostHidden()]

Members

The RenderTargetBitmap class has these types of members:

Constructors

The RenderTargetBitmap class has these constructors.

ConstructorDescription
RenderTargetBitmap Initializes a new instance of the RenderTargetBitmap class.

 

Methods

The RenderTargetBitmap class has these methods. It also inherits methods from the Object class.

MethodDescription
ClearValue Clears the local value of a dependency property. (Inherited from DependencyObject)
GetAnimationBaseValue 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 Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
ReadLocalValue Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
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.
SetValue Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)

 

Properties

The RenderTargetBitmap class has these properties.

PropertyAccess typeDescription

Dispatcher

Read-onlyGets the CoreDispatcher that this object is associated with. (Inherited from DependencyObject)

PixelHeight

Read-onlyGets the height of the rendered bitmap in pixels.

PixelHeightProperty

Read-onlyIdentifies the PixelHeight dependency property.

PixelWidth

Read-onlyGets the width of the rendered bitmap in pixels.

PixelWidthProperty

Read-onlyIdentifies the PixelWidth dependency property.

 

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). 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 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.
    • Applies to Windows Phone

    Note  Windows Phone: 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; 
}

Requirements

Minimum supported client

Windows 8.1 [Windows Store apps only]

Minimum supported server

Windows Server 2012 R2 [Windows Store apps only]

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

ImageSource
XAML render to bitmap sample
Quickstart: Image and ImageBrush
RenderAsync(UIElement)

 

 

Show:
© 2014 Microsoft