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 可视化树中，但屏幕外的内容可以捕获，只要它不是 可见性 = 折叠。

构造函数

属性

方法

适用于

另请参阅

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