RenderTargetBitmap 类

定义

命名空间:

Microsoft.UI.Xaml.Media.Imaging

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

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的子类，因此它可以用作图像 元素的图像 源或 ImageBrush 画笔。

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

最常使用的 RenderTargetBitmap API RenderAsync。 此方法有两个重载：RenderAsync（UIElement），另一个重载，可在其中指定图像源的所需尺寸与源可视化树的自然大小不同。 RenderAsync 是一种异步方法，因此不能保证与 UI 源的确切帧同步，但对于大多数方案而言，它足够接近计时。

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

有关使用 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 到 10000 像素的 XAML 可视化树可能会缩放到 4096 像素，这是应用运行的硬件强制的特定限制的示例。

XAML 视觉对象和 RenderTargetBitmap 捕获功能

对于 XAML 撰写的视觉内容，有几个方案无法捕获到 RenderTargetBitmap：

• 树中的内容，但其 可见性 设置为 折叠 不会被捕获。
• 不会直接连接到 XAML 可视化树的内容，并且不会捕获主窗口的内容。 这包括 弹出窗口 内容，该内容被视为类似于子窗口。
• 无法捕获的内容将在捕获的图像中显示为空白，但同一可视化树中的其他内容仍可捕获并呈现（无法捕获的内容的存在不会使该 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()	以 BGRA8 格式检索以前呈现 的 renderTargetBitmap 图像作为缓冲的字节流。
GetValue(DependencyProperty)	从 DependencyObject返回依赖属性的当前有效值。 (继承自 DependencyObject)
ReadLocalValue(DependencyProperty)	如果设置了本地值，则返回依赖属性的本地值。 (继承自 DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	注册一个通知函数，用于侦听此 DependencyObject 实例上特定 DependencyProperty 的更改。 (继承自 DependencyObject)
RenderAsync(UIElement, Int32, Int32)	将 UIElement 可视化树的快照呈现到图像源。 指定 scaledWidth 和 scaledHeight 的值以更改原始源的呈现维度。
RenderAsync(UIElement)	将 UIElement 可视化树的快照呈现到图像源。
SetValue(DependencyProperty, Object)	设置 DependencyObject上的依赖属性的本地值。 (继承自 DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	取消以前通过调用 RegisterPropertyChangedCallback注册的更改通知。 (继承自 DependencyObject)

另请参阅

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