RenderTargetBitmap 类

定义

命名空间:

Microsoft.UI.Xaml.Media.Imaging

表示可以使用 XAML 可视化树的组合内容填充的图像源。 有关哪些 XAML 视觉对象可以在 RenderTargetBitmap 中捕获的一些显著限制，请参阅 。

public ref class RenderTargetBitmap sealed : ImageSource

/// [Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class RenderTargetBitmap final : ImageSource

[Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class RenderTargetBitmap : ImageSource

Public NotInheritable Class RenderTargetBitmap
Inherits ImageSource

继承

Object Platform::Object IInspectable DependencyObject ImageSource RenderTargetBitmap

属性

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

示例

此基本代码大纲改编自第一个方案 XAML 和 XAML 呈现到位图示例的代码。 请注意，所有代码（甚至构造函数）如何位于 异步 方法中。 此处，它是用户单击以启动呈现请求的按钮的事件处理程序。

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

注解

使用 RenderTargetBitmap，可以完成一些方案，例如将图像效果应用于最初来自 XAML UI 组合的视觉对象、为导航系统生成子页面的缩略图图像，或者使用户能够将 UI 的某些部分保存为图像源，然后与其他应用共享该图像。

由于 RenderTargetBitmap 是 ImageSource 的子类，因此它可用作 Image 元素或 ImageBrush 画笔的图像源。

调用 RenderAsync 可提供有用的图像源，但在应用调用 GetPixelsAsync 之前，呈现内容的完整缓冲区表示形式不会从视频内存中复制。 如果应用只打算显示 呈现 的内容而不需要像素数据，则只需 (调用 RenderAsync 而不调用 GetPixelsAsync) 并使用 RenderTargetBitmap 作为 Image 或 ImageBrush 源会更快。 如果想要为 DataTransferManager 操作（例如共享合约交换）捕获图像，或者想要对图像应用效果或使用 Windows.Graphics.ImagingAPI 进行转码，则可能需要像素数据。

最常使用的 RenderTargetBitmap API 是 RenderAsync。 此方法有两个重载： RenderAsync (UIElement) 和另一个重载 ，可在其中将图像源的所需尺寸指定为不同于源可视化树的自然大小。 RenderAsync 在设计上是一种异步方法，因此不能保证与 UI 源的帧完全同步，但在大多数情况下，它足够接近计时。

RenderTargetBitmap 对象通常不会在 XAML UI 中声明，因为需要先在代码中调用 RenderAsync ，然后才能获得一个有用的、图像填充的 RenderTargetBitmap 实例以进行 UI 显示。

有关使用 RenderTargetBitmap 的更多代码示例，请参阅 XAML 呈现到位图示例。

RenderTargetBitmap 的内容在极少数情况下可能会丢失，因为与其他较低级别的系统交互，例如，在恢复过程中重置视频驱动程序 (请参阅 超时检测和恢复 (TDR) ) 。 如果发生这种情况，将触发 CompositionTarget.SurfaceContentsLost 事件。 若要考虑这种情况和类似的信息丢失情况，应用应侦听 CompositionTarget.SurfaceContentsLost 事件，并通过再次调用 RenderAsync 来重新呈现 RenderTargetBitmap 的内容。

当当前 DPI 设置更改时，RenderTargetBitmap 的呈现位图内容不会自动缩放。 当当前视图的 DPI 设置发生更改时，应用应重新呈现 RenderTargetBitmap 的内容，以确保呈现的矢量内容保持清晰。 例如，如果用户在以不同 DPI 设置运行的两个监视器之间移动应用，则可能会发生重设大小。 考虑侦听 DisplayInformation.DpiChanged 事件以检测这些情况。

XAML 可视化树的最大呈现大小受 Microsoft DirectX 纹理的最大尺寸限制;有关详细信息 ，请参阅 Direct3D 11) (资源限制 。 此限制可能因运行应用的硬件而异。 超出此限制的非常大的内容可能会进行缩放以适应。 如果以这种方式应用缩放限制，则可以使用 PixelWidth 和 PixelHeight 属性查询缩放后呈现的大小。 例如，10000 x 10000 像素的 XAML 可视化树可能会缩放为 4096 x 4096 像素，这是运行应用的硬件强制设置的特定限制的示例。

XAML 视觉对象和 RenderTargetBitmap 捕获功能

对于 XAML 组合的视觉内容，有一些方案无法捕获到 RenderTargetBitmap：

• 不会捕获树中其 可见性 设置为 “折叠 ”的内容。
• 不会捕获未直接连接到 XAML 可视化树的内容和main窗口的内容。 这包括 弹出窗口 内容，该内容被视为类似于子窗口。
• 无法捕获的内容将在捕获的图像中显示为空白，但同一可视化树中的其他内容仍可捕获，并且将呈现 (存在无法捕获的内容不会使该 XAML 合成) 的整个捕获失效。
• 在 XAML 可视化树中，但屏幕外的内容可以捕获，只要它不是 可见性 = 折叠。

构造函数

RenderTargetBitmap()

初始化 RenderTargetBitmap 类的新实例。

属性

Dispatcher	始终在Windows 应用 SDK应用中返回 null 。 请改用 DispatcherQueue 。 (继承自 DependencyObject)
DispatcherQueue	DispatcherQueue获取与此对象关联的 。 表示 DispatcherQueue 一个可以在 UI 线程上访问 DependencyObject 的设施，即使代码是由非 UI 线程启动的。 (继承自 DependencyObject)
PixelHeight	获取呈现的位图的高度（以像素为单位）。
PixelHeightProperty	标识 PixelHeight 依赖属性。
PixelWidth	获取呈现的位图的宽度（以像素为单位）。
PixelWidthProperty	标识 PixelWidth 依赖属性。

方法

ClearValue(DependencyProperty)	清除依赖属性的本地值。 (继承自 DependencyObject)
GetAnimationBaseValue(DependencyProperty)	返回为依赖属性建立的任何基值，该基值适用于动画未处于活动状态的情况。 (继承自 DependencyObject)
GetPixelsAsync()	检索以前呈现的 RenderTargetBitmap 图像作为 BGRA8 格式的缓冲字节流。
GetValue(DependencyProperty)	从 DependencyObject 返回依赖属性的当前有效值。 (继承自 DependencyObject)
ReadLocalValue(DependencyProperty)	如果设置了本地值，则返回依赖属性的本地值。 (继承自 DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	注册通知函数，用于侦听此 DependencyObject 实例上对特定 DependencyProperty 的更改。 (继承自 DependencyObject)
RenderAsync(UIElement)	将 UIElement 可视化树的快照呈现给图像源。
RenderAsync(UIElement, Int32, Int32)	将 UIElement 可视化树的快照呈现给图像源。 指定 scaledWidth 和 scaledHeight 的值以更改原始源的呈现维度。
SetValue(DependencyProperty, Object)	设置 DependencyObject 上依赖属性的本地值。 (继承自 DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	取消以前通过调用 RegisterPropertyChangedCallback 注册的更改通知。 (继承自 DependencyObject)

另请参阅

• ImageSource
• RenderAsync(UIElement)
• XAML 呈现到位图示例
• Image 和 ImageBrush