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. Sehen Sie sich einige wichtige Einschränkungen an, mit denen XAML-Visuelle Elemente 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 ersten Szenario-XAML und Code des XAML-Renderns an Bitmapbeispielangepasst. Beachten Sie, dass sich der gesamte Code, auch der Konstruktor, in einer asynchronen-Methode befindet. Hier ist es ein 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 Szenarien wie das Anwenden von Bildeffekten auf ein visuelles Element ausführen, das ursprünglich aus einer XAML-UI-Komposition stammt, Miniaturansichten untergeordneter Seiten für ein Navigationssystem generieren oder es dem Benutzer ermöglichen, Teile der Benutzeroberfläche als Bildquelle zu speichern und dieses Bild dann für andere Apps freizugeben.

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

Das Aufrufen 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, RenderAsync- nur aufzurufen (ohne GetPixelsAsync-) aufzurufen und renderTargetBitmap als Image oder ImageBrush Quelle zu verwenden, wenn die App nur die gerenderten Inhalte anzeigt und die Pixeldaten nicht benötigt. Sie benötigen wahrscheinlich die Pixeldaten, wenn Sie das Bild für einen DataTransferManager- Vorgang wie einen Austausch von Freigabe-Verträgen erfassen oder Effekte auf das Bild anwenden oder es mithilfe der Windows.Graphics.Imaging-API transcodieren möchten.

Die RenderTargetBitmap-API, die Sie am häufigsten verwenden, ist RenderAsync-. Es gibt zwei Überladungen dieser Methode: RenderAsync(UIElement) und eine andere Überladung, in der Sie die gewünschten Dimensionen der Bildquelle angeben können, die von der natürlichen Größe der visuellen Quellstruktur abweichen soll. RenderAsync- ist eine asynchrone Methode nach Design, daher gibt es keine Garantie für die genaue Framesynchronisierung mit der UI-Quelle, aber es ist nah genug Timing für die meisten Szenarien.

Ein RenderTargetBitmap-Objekt wird in der Regel nicht in einer XAML-Benutzeroberfläche deklariert, da Sie RenderAsync- im Code aufrufen müssen, bevor Sie eine nützliche, bildgefüllte Instanz von RenderTargetBitmap für Ui-Anzeigezwecke haben.

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

Der Inhalt einer RenderTargetBitmap kann in seltenen Fällen aufgrund der Interaktion mit anderen Systemen auf niedrigerer Ebene verloren gehen, z. B. wenn der Videotreiber als Teil einer Wiederherstellung zurückgesetzt wird (siehe Timeout Detection and Recovery (TDR)). In diesem Fall wird das CompositionTarget.SurfaceContentsLost Ereignis ausgelöst. Um diesen Fall und ähnliche Info-Verlustfä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 erneut rendern, wenn sich die DPI-Einstellung der aktuellen Ansicht ändert, um sicherzustellen, dass der gerenderte Vektorinhalt scharf bleibt. Beispielsweise kann eine Größenänderung auftreten, wenn der Benutzer eine App zwischen zwei Monitoren verschiebt, die bei einer anderen DPI-Einstellung ausgeführt werden. Erwägen Sie, auf das DisplayInformation.DpiChanged Ereignis zu achten, um diese Fälle zu erkennen.

Die maximale gerenderte Größe einer visuellen XAML-Struktur wird durch die maximalen Dimensionen einer Microsoft DirectX-Textur eingeschränkt. weitere Informationen finden Sie unter Resource Limits (Direct3D 11). Dieser Grenzwert kann je nach Hardware variieren, auf der die App ausgeführt wird. Sehr große Inhalte, die diesen Grenzwert überschreiten, können entsprechend skaliert werden. Wenn Skalierungsgrenzwerte auf diese Weise angewendet werden, kann die gerenderte Größe nach der Skalierung mithilfe der eigenschaften PixelWidth und PixelHeight abgefragt werden. Beispielsweise kann eine visuelle XAML-Struktur von 10000 x 1000 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.

VISUELLE XAML-Elemente und RenderTargetBitmap Aufnahmefunktionen

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

Inhalte, die sich in der Struktur befinden, aber mit der Sichtbarkeit auf Reduzierten festgelegt sind, werden nicht erfasst.
Inhalte, die nicht direkt mit der visuellen XAML-Struktur verbunden sind, und der Inhalt des Hauptfensters wird nicht erfasst. Dies umfasst Popup- Inhalt, der als "Unterfenster" angesehen wird.
Inhalte, die nicht erfasst werden können, werden im aufgenommenen 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 zur Ungültigkeit der gesamten Aufnahme dieser XAML-Komposition).
Inhalte, die sich in der visuellen XAML-Struktur befinden, aber der Offscreen kann erfasst werden, solange sie nicht Sichtbarkeit = reduziertenist.

Konstruktoren

RenderTargetBitmap()

Initialisiert eine neue Instanz der RenderTargetBitmap Klasse.

Eigenschaften

Dispatcher	Gibt immer `null` in einer Windows App SDK-App zurück. Verwenden Sie stattdessen DispatcherQueue. (Geerbt von DependencyObject)
DispatcherQueue	Ruft den `DispatcherQueue` ab, dem dieses Objekt zugeordnet ist. Die `DispatcherQueue` stellt eine Einrichtung dar, die auf die `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 Pixeln ab.
PixelHeightProperty	Identifies the PixelHeight dependency property.
PixelWidth	Ruft die Breite der gerenderten Bitmap in Pixeln ab.
PixelWidthProperty	Identifies the PixelWidth dependency property.

Methoden

ClearValue(DependencyProperty)	Löscht den lokalen Wert einer Abhängigkeitseigenschaft. (Geerbt von DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Gibt einen Basiswert zurück, der für eine Abhängigkeitseigenschaft eingerichtet wurde, was in Fällen angewendet wird, 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 wird. (Geerbt von DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registriert eine Benachrichtigungsfunktion, um Änderungen an einer bestimmten DependencyProperty- für diese DependencyObject-Instanz zu überwachen. (Geerbt von DependencyObject)
RenderAsync(UIElement, Int32, Int32)	Rendert eine Momentaufnahme einer UIElement- visuellen Struktur in einer Bildquelle. Geben Sie Werte für scaledWidth und scaledHeight- an, um die Renderingdimension der ursprünglichen Quelle zu ändern.
RenderAsync(UIElement)	Rendert eine Momentaufnahme einer UIElement- visuellen Struktur in einer Bildquelle.
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 RegisterPropertyChangedCallback-registriert wurde. (Geerbt von DependencyObject)

Gilt für:

Freigeben über