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子類別，所以它可以做為 image Image 元素或 ImageBrush 筆刷的影像來源。

呼叫 RenderAsync 提供有用的影像來源，但除非應用程式 呼叫 getPixelsAsync，否則轉譯內容的完整緩衝區表示不會複製到視訊記憶體中。 僅呼叫 RenderAsync 會更快速（沒有呼叫 getPixelsAsync），並使用 RenderTargetBitmap 作為 Image 或 ImageBrush 來源，如果應用程式只想要顯示轉譯的內容，而且不需要像素數據。 如果您想要擷取 DataTransferManager 作業，例如共用合約交換，或想要將效果套用至影像，或使用 Windows.Graphics.ImagingAPI 來轉碼，您可能需要圖元數據。

您最常使用的 RenderTargetBitmap API RenderAsync。 這個方法有兩個多載：RenderAsync（UIElement），另一個多載，您可以在其中指定影像來源所需的維度，使其與來源可視化樹狀結構的自然大小不同。 RenderAsync 是設計方式的異步方法，因此無法保證與 UI 來源的確切畫面同步處理，但對於大多數案例而言，其時間不夠接近。

RenderTargetBitmap 物件通常不會在 XAML UI 中宣告，因為您必須先在程式碼中呼叫 RenderAsync，然後才有針對 UI 顯示用途而填入 RenderTargetBitmap 的實用影像填入實例。

如需使用 RenderTargetBitmap 的更多程式碼範例，請參閱 XAML 轉譯至位圖範例。

轉譯TargetBitmap 的內容可能會因為與其他較低層級系統的互動而遺失，例如，如果視訊驅動程式重設為復原的一部分（請參閱 逾時偵測和復原（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：

• 樹狀結構中的內容，但其 Visibility 設定為 [折疊 將不會擷取。
• 不會直接連線到 XAML 可視化樹狀結構的內容，而且不會擷取主視窗的內容。 這包括 快顯 內容，這被視為像是子視窗。
• 無法擷取的內容會在擷取的影像中顯示為空白，但相同可視化樹狀結構中的其他內容仍可擷取並轉譯（無法擷取的內容不會使該 XAML 組合的整個擷取失效）。
• XAML 視覺化樹狀結構中但螢幕外的內容可以擷取，只要它不會 Visibility = Collapsed。

建構函式

RenderTargetBitmap()

初始化 RenderTargetBitmap 類別的新實例。

屬性

Dispatcher	一律會在 Windows App 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, Int32, Int32)	將 UIElement 的快照集 可視化樹狀結構轉譯為影像來源。 指定 scaledWidth 和 scaledHeight 的值，以改變原始來源的轉譯維度。
RenderAsync(UIElement)	將 UIElement 的快照集 可視化樹狀結構轉譯為影像來源。
SetValue(DependencyProperty, Object)	在 DependencyObject上設定相依性屬性的本機值。 (繼承來源 DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	取消先前透過呼叫 registerPropertyChangedCallback 註冊的變更通知。 (繼承來源 DependencyObject)

另請參閱

• ImageSource
• RenderAsync(UIElement)
• XAML 轉譯至位圖範例
• Image 和 ImageBrush