RenderTargetBitmap Klasse

Referenz

Definition

Namespace:: Microsoft.UI.Xaml.Media.Imaging

Wichtig

Einige Informationen beziehen sich auf Vorabversionen, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Bearbeiten

Stellt eine Bildquelle dar, die mit dem kombinierten Inhalt einer visuellen XAML-Struktur aufgefüllt werden kann. Beachten Sie einige wichtige Einschränkungen, bei denen XAML-Visuals in einer RenderTargetBitmap erfasst werden können.

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

Vererbung: Object Platform::Object IInspectable DependencyObject ImageSource RenderTargetBitmap

Attribute: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Beispiele

Diese grundlegende Codegliederung wird aus dem xaml-Code des ersten Szenarios und dem Code des XAML-Render-in-Bitmap-Beispiels angepasst. Beachten Sie, dass sich der gesamte Code, auch der Konstruktor, in einer asynchronen Methode befindet. Hier handelt es sich um einen Ereignishandler für eine Schaltfläche, auf die ein Benutzer klickt, um die Renderinganforderung zu initiieren.

<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; 
}

Hinweise

Mithilfe einer RenderTargetBitmap können Sie z. B. Bildeffekte auf ein Visual anwenden, das ursprünglich aus einer XAML-UI-Komposition stammt, Miniaturansichten von untergeordneten Seiten für ein Navigationssystem generieren oder es dem Benutzer ermöglichen, Teile der Benutzeroberfläche als Bildquelle zu speichern und dieses Bild dann mit anderen Apps zu teilen.

Da RenderTargetBitmap eine Unterklasse von ImageSource ist, kann sie als Bildquelle für Image-Elemente oder einen ImageBrush-Pinsel verwendet werden.

Der Aufruf von RenderAsync bietet eine nützliche Bildquelle, aber die vollständige Pufferdarstellung des Renderinginhalts wird erst aus dem Videospeicher kopiert, wenn die App GetPixelsAsync aufruft. Es ist schneller, nur RenderAsync aufzurufen (ohne GetPixelsAsync aufzurufen) und renderTargetBitmap als Bild - oder ImageBrush-Quelle zu verwenden, wenn die App nur den gerenderten Inhalt anzeigen möchte und die Pixeldaten nicht benötigt. Sie benötigen die Pixeldaten wahrscheinlich, wenn Sie beabsichtigen, das Bild für einen DataTransferManager-Vorgang wie einen Austausch von Freigabeverträgen zu erfassen, oder wenn Sie Effekte auf das Bild anwenden oder es mithilfe der Windows.Graphics.Imaging-APItranscodieren möchten.

Die RenderTargetBitmap-API, die Sie am häufigsten verwenden, ist RenderAsync. Es gibt zwei Überladungen dieser Methode: RenderAsync(UIElement) und eine weitere Überladung , bei der Sie angeben können, dass sich die gewünschten Dimensionen der Bildquelle von der natürlichen Größe der visuellen Quellstruktur unterscheiden. RenderAsync ist standardmäßig eine asynchrone Methode, sodass es keine Garantie für eine exakte Framesynchronisierung mit der UI-Quelle gibt, aber sie ist zeitlich für die meisten Szenarien nah genug.

Ein RenderTargetBitmap-Objekt wird in der Regel nicht in einer XAML-Benutzeroberfläche deklariert, da Sie RenderAsync im Code aufrufen müssen, bevor Sie über eine nützliche, bildfüllte instance von RenderTargetBitmap für die Anzeige der Benutzeroberfläche verfügen.

Weitere Codebeispiele für die Verwendung von RenderTargetBitmap finden Sie unter XAML-Beispiel zum Rendern in Bitmap.

Der Inhalt einer RenderTargetBitmap kann in seltenen Fällen aufgrund einer Interaktion mit anderen Systemen auf niedrigerer Ebene verloren gehen, z. B. wenn der Videotreiber im Rahmen einer Wiederherstellung zurückgesetzt wird (siehe Timeouterkennung und -wiederherstellung (TDR)). In diesem Fall wird das CompositionTarget.SurfaceContentsLost-Ereignis ausgelöst. Um diesen Fall und ähnliche Informationsverlustfälle zu berücksichtigen, sollten Apps auf das CompositionTarget.SurfaceContentsLost-Ereignis lauschen und den Inhalt einer RenderTargetBitmap erneut rendern, indem RenderAsync erneut aufgerufen wird.

Die gerenderten Bitmapinhalte einer RenderTargetBitmap werden nicht automatisch skaliert, wenn sich die aktuelle DPI-Einstellung ändert. Apps sollten den Inhalt einer RenderTargetBitmap neu rendern, wenn sich die DPI-Einstellung der aktuellen Ansicht ändert, um sicherzustellen, dass der gerenderte Vektorinhalt schärfer bleibt. Beispielsweise kann eine Größenänderung auftreten, wenn der Benutzer eine App zwischen zwei Monitoren verschiebt, die mit einer anderen DPI-Einstellung ausgeführt werden. Erwägen Sie, auf das DisplayInformation.DpiChanged-Ereignis zu lauschen, um diese Fälle zu erkennen.

Die maximale gerenderte Größe einer visuellen XAML-Struktur wird durch die maximalen Abmessungen einer Microsoft DirectX-Textur eingeschränkt. weitere Informationen finden Sie unter Ressourcenlimits (Direct3D 11). Dieser Grenzwert kann abhängig von der Hardware variieren, auf der die App ausgeführt wird. Sehr große Inhalte, die diesen Grenzwert überschreiten, können entsprechend skaliert werden. Wenn Skalierungslimits auf diese Weise angewendet werden, kann die gerenderte Größe nach der Skalierung mit den Eigenschaften PixelWidth und PixelHeight abgefragt werden. Beispielsweise kann eine visuelle XAML-Struktur mit 10000 x 10000 Pixeln auf 4096 x 4096 Pixel skaliert werden, ein Beispiel für einen bestimmten Grenzwert, der von der Hardware erzwungen wird, auf der die App ausgeführt wird.

XAML-Visuals und RenderTargetBitmap-Erfassungsfunktionen

Es gibt einige Szenarien für xamlkomponierte visuelle Inhalte, die Sie nicht in einer RenderTargetBitmap erfassen können:

Inhalt, der sich in der Struktur befindet, aber dessen Sichtbarkeit auf Reduziert festgelegt ist, wird nicht erfasst.
Inhalte, die nicht direkt mit der visuellen XAML-Struktur verbunden sind, und der Inhalt des Standard-Fensters wird nicht erfasst. Dies schließt Popupinhalte ein, die wie ein Unterfenster gelten.
Inhalte, die nicht erfasst werden können, werden im erfassten Bild als leer angezeigt, aber andere Inhalte in derselben visuellen Struktur können weiterhin erfasst und gerendert werden (das Vorhandensein von Inhalten, die nicht erfasst werden können, führt nicht dazu, dass die gesamte Erfassung dieser XAML-Komposition ungültig wird).
Inhalte, die sich in der visuellen XAML-Struktur befinden, aber außerhalb des Bildschirms erfasst werden können, solange die Sichtbarkeit = nichtreduziert ist.

Konstruktoren

RenderTargetBitmap()

Initialisiert eine neue instance der RenderTargetBitmap-Klasse.

Eigenschaften

Dispatcher	Gibt immer in einer Windows App SDK-App zurück`null`. Verwenden Sie stattdessen DispatcherQueue . (Geerbt von DependencyObject)
DispatcherQueue	Ruft den `DispatcherQueue` ab, dem dieses Objekt zugeordnet ist. Stellt `DispatcherQueue` eine Funktion dar, die auf den `DependencyObject` im UI-Thread zugreifen kann, auch wenn der Code von einem Nicht-UI-Thread initiiert wird. (Geerbt von DependencyObject)
PixelHeight	Ruft die Höhe der gerenderten Bitmap in Pixel ab.
PixelHeightProperty	Identifiziert die PixelHeight-Abhängigkeitseigenschaft .
PixelWidth	Ruft die Breite der gerenderten Bitmap in Pixel ab.
PixelWidthProperty	Identifiziert die PixelWidth-Abhängigkeitseigenschaft .

Methoden

ClearValue(DependencyProperty)	Löscht den lokalen Wert einer Abhängigkeitseigenschaft. (Geerbt von DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Gibt einen beliebigen Basiswert zurück, der für eine Abhängigkeitseigenschaft eingerichtet wurde, der in Fällen gilt, in denen eine Animation nicht aktiv ist. (Geerbt von DependencyObject)
GetPixelsAsync()	Ruft das zuvor gerenderte RenderTargetBitmap-Bild als gepufferten Bytestrom im BGRA8-Format ab.
GetValue(DependencyProperty)	Gibt den aktuellen effektiven Wert einer Abhängigkeitseigenschaft aus einem DependencyObject zurück. (Geerbt von DependencyObject)
ReadLocalValue(DependencyProperty)	Gibt den lokalen Wert einer Abhängigkeitseigenschaft zurück, wenn ein lokaler Wert festgelegt ist. (Geerbt von DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registriert eine Benachrichtigungsfunktion zum Lauschen auf Änderungen an einer bestimmten DependencyProperty für dieses DependencyObject-instance. (Geerbt von DependencyObject)
RenderAsync(UIElement)	Rendert eine Momentaufnahme einer visuellen UIElement-Struktur in einer Bildquelle.
RenderAsync(UIElement, Int32, Int32)	Rendert eine Momentaufnahme einer visuellen UIElement-Struktur in einer Bildquelle. Geben Sie Werte für scaledWidth und scaledHeight an, um die Renderingdimension der ursprünglichen Quelle zu ändern.
SetValue(DependencyProperty, Object)	Legt den lokalen Wert einer Abhängigkeitseigenschaft für ein DependencyObject fest. (Geerbt von DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Bricht eine Änderungsbenachrichtigung ab, die zuvor durch Aufrufen von RegisterPropertyChangedCallback registriert wurde. (Geerbt von DependencyObject)

Gilt für:

Freigeben über