RenderTargetBitmap 類別

定義

命名空間:

Windows.UI.Xaml.Media.Imaging

表示可以填入 XAML 視覺化樹狀結構合併內容的影像來源。 如需可在 RenderTargetBitmap 中擷取 XAML 視覺效果的一些值得注意的限制，請參閱 。

public ref class RenderTargetBitmap sealed : ImageSource

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

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

Public NotInheritable Class RenderTargetBitmap
Inherits ImageSource

繼承

Object Platform::Object IInspectable DependencyObject ImageSource RenderTargetBitmap

屬性

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows 需求

裝置系列	Windows 10 (已於 10.0.10240.0 引進)
API contract	Windows.Foundation.UniversalApiContract (已於 v1.0 引進)

範例

此基本程式碼大綱會從第一個案例 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 事件將會引發。 為了考慮此案例和類似的資訊遺失案例，應用程式應該再次呼叫RenderAsync來接聽CompositionTarget.SurfaceContentsLost事件，並重新轉譯 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 設定為 Collapsed 的內容。
• 未直接連接到 XAML 視覺化樹狀結構的內容，且不會擷取主視窗的內容。 這包括 快顯 內容，這被視為類似子視窗。
• 無法擷取的內容會在擷取的影像中顯示為空白，但相同視覺化樹狀結構中的其他內容仍可擷取，而且會轉譯 (無法擷取的內容是否存在，不會使該 XAML 組合的整個擷取失效) 。
• XAML 視覺化樹狀結構中但螢幕外的內容可以擷取，只要它不是Visibility = Collapsed即可。

建構函式

RenderTargetBitmap()

初始化 RenderTargetBitmap 類別的新實例。

屬性

Dispatcher	取得這個 物件相關聯的 CoreDispatcher 。 CoreDispatcher代表可在 UI 執行緒上存取DependencyObject的功能，即使程式碼是由非 UI 執行緒起始也一樣。 (繼承來源 DependencyObject)
PixelHeight	取得轉譯點陣圖的高度，以圖元為單位。
PixelHeightProperty	識別 PixelHeight 相依性屬性。
PixelWidth	取得轉譯點陣圖的寬度，以圖元為單位。
PixelWidthProperty	識別 PixelWidth 相依性屬性。

方法

ClearValue(DependencyProperty)	清除相依性屬性的本機值。 (繼承來源 DependencyObject)
GetAnimationBaseValue(DependencyProperty)	傳回為相依性屬性建立的任何基底值，如果動畫未使用中，則適用此屬性。 (繼承來源 DependencyObject)
GetPixelsAsync()	擷取先前轉譯的 RenderTargetBitmap 影像做為 BGRA8、 預乘 Alpha 格式的位元組 緩衝資料流程。
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