RenderTargetBitmap 類別

定義

命名空間:: Microsoft.UI.Xaml.Media.Imaging

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

編輯

代表一個可填充 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 操作（例如 Share 合約交換）擷取影像，或是想對影像套用特效或用 Windows 轉碼，你大概還是需要這些像素資料。圖形。影像API。

你最常用的 RenderTargetBitmap API 是 RenderAsync。此方法有兩種超載： RenderAsync（UIElement）及另一種超載，後者可指定影像來源的尺寸與原始視覺樹的自然大小不同。 RenderAsync 本身就是非同步方法，所以無法保證與 UI 來源的幀完全同步，但在時間上對大多數情境來說已經足夠接近。

RenderTargetBitmap 物件通常不會在 XAML UI 中宣告，因為你需要在程式碼中呼叫 RenderAsync ，才能建立一個有用的、充滿圖片的 RenderTargetBitmap 實例來顯示 UI。

欲了解更多使用 RenderTargetBitmap 的程式碼範例，請參見 XAML 渲染至點陣範例。

在少數情況下，RenderTargetBitmap 的內容可能因與其他低階系統互動而遺失，例如視訊驅動程式在恢復過程中被重置（參見逾時偵測與恢復（TDR））。如果發生這種情況， CompositionTarget.SurfaceContentsLost 事件就會觸發。為了考慮這種情況及類似的資訊遺失情況，應用程式應監聽 CompositionTarget.SurfaceContentsLost 事件，並透過再次呼叫 RenderAsync 重新渲染 RenderTargetBitmap 的內容。

RenderTargetBitmap 的渲染點陣內容不會在當前 DPI 設定改變時自動縮放。當當前視圖的 DPI 設定改變時，應用程式應重新渲染 RenderTargetBitmap 的內容，以確保渲染的向量內容保持清晰。例如，如果使用者在兩個以不同 DPI 設定運行的螢幕間移動應用程式，就可能發生大小調整。考慮監聽 DisplayInformation.DpiChanged 事件以偵測這些案例。

XAML 視覺樹的最大渲染大小受限於 Microsoft DirectX 材質的最大尺寸;更多資訊請參見資源限制（Direct3D 11）。這個限制會依應用程式所運行的硬體而有所不同。超過這個限制的超大型內容可能會被調整以符合。若以此方式套用縮放限制，縮放後的渲染大小可利用 PixelWidth 與 PixelHeight 屬性查詢。例如，一個 10000 x 10000 像素的 XAML 視覺樹可能被縮放到 4096 x 4096 像素，這是應用程式執行硬體所強制的特定限制。

XAML 視覺化與 RenderTargetBitmap 擷取功能

有幾種 XAML 組成的視覺內容無法擷取到 RenderTargetBitmap 的情況：

在樹中但其可見性設為 「摺疊 」的內容不會被擷取。
沒有直接連接到 XAML 視覺樹且主視窗內容的內容不會被擷取。這包括彈出視窗內容，被視為類似子視窗。
無法擷取的內容會在擷取的影像中顯示為空白，但同一視覺樹中的其他內容仍可擷取並會被渲染（無法擷取的內容存在不會使該 XAML 組合的整個擷取失效）。
XAML 視覺樹中但螢幕外的內容可以被擷取，只要不是 Visibility = Collapsed。

建構函式

名稱	Description
RenderTargetBitmap()	初始化 RenderTargetBitmap 類別的新實例。

屬性

名稱	Description
Dispatcher	它總是在 Windows 應用程式 SDK 應用程式中回傳 `null` 。改用 DispatcherQueue 。 (繼承來源 DependencyObject)
DispatcherQueue	得到 `DispatcherQueue` 這個物件所關聯的那個。代表 `DispatcherQueue` 一個功能，即使程式碼是由非 UI 執行緒發起，也能存取 UI `DependencyObject` 執行緒。 (繼承來源 DependencyObject)
PixelHeight	取得渲染後點陣圖的高度（像素單位）。
PixelHeightProperty	識別 PixelHeight 依賴屬性。
PixelWidth	取得渲染後點陣圖的寬度（像素數）。
PixelWidthProperty	識別 PixelWidth 相依屬性。

方法

名稱	Description
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)

適用於

另請參閱

意見反應

此頁面對您有幫助嗎？