RenderTargetBitmap Klasse

Definition

Namespace:

Windows.UI.Xaml.Media.Imaging

Stellt eine Bildquelle dar, die mit dem kombinierten Inhalt einer visuellen XAML-Struktur aufgefüllt werden kann. Einige wichtige Einschränkungen, für die XAML-Visuals in einer RenderTargetBitmap erfasst werden können, finden Sie unter.

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

Vererbung

Object Platform::Object IInspectable DependencyObject ImageSource RenderTargetBitmap

Attribute

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows-Anforderungen

Gerätefamilie	Windows 10 (eingeführt in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (eingeführt in v1.0)

Beispiele

Diese grundlegende Codegliederung wird vom ersten XAML-Szenario und dem Code des XAML-Renderns auf das Bitmapbeispiel angepasst. Beachten Sie, dass sich der gesamte Code, auch der Konstruktor, innerhalb 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

Mit einer RenderTargetBitmap können Sie Szenarien ausführen, z. B. das Anwenden von Bildeffekten auf ein Visual, das ursprünglich aus einer XAML-UI-Komposition stammt, das Generieren von Miniaturansichten untergeordneter Seiten für ein Navigationssystem oder das Speichern von Teilen der Benutzeroberfläche als Bildquelle und das Freigeben dieses Bilds für andere Apps.

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

Das Aufrufen 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 die RenderTargetBitmap als Image- 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 das Image für einen DataTransferManager-Vorgang wie einen Austausch von Freigabeverträgen erfassen möchten, oder wenn Sie Effekte auf das Image 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 eine asynchrone Methode, sodass es keine Garantie für eine exakte Framesynchronisierung mit der UI-Quelle gibt, aber für die meisten Szenarien ist sie zeitlich eng 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, mit Bildern gefüllte instance von RenderTargetBitmap für Benutzeroberflächenanzeigezwecke verfügen.

Weitere Codebeispiele zur 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 Infoverlustfä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 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 Dimensionen einer Microsoft DirectX-Textur eingeschränkt. Weitere Informationen finden Sie unter Ressourcengrenzwerte (Direct3D 11). Dieses Limit 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 Skalierungsgrenzwerte auf diese Weise angewendet werden, kann die gerenderte Größe nach der Skalierung mithilfe der PixelWidth - und PixelHeight-Eigenschaften abgefragt werden. Beispielsweise kann eine visuelle XAML-Struktur von 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 XAML-zusammengestellte visuelle Inhalte, die Sie nicht in einer RenderTargetBitmap erfassen können:

• Inhalte, die sich in der Struktur befindet, aber die Sichtbarkeit auf Reduziert festgelegt ist, werden nicht erfasst.
• Inhalte, die nicht direkt mit der visuellen XAML-Struktur verbunden sind, und der Inhalt des Standard Fensters werden 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, ungültig macht nicht die gesamte Erfassung dieser XAML-Komposition).
• Inhalte, die sich in der visuellen XAML-Struktur befinden, aber außerhalb des Bildschirms sind, können erfasst werden, solange die Sichtbarkeit = nichtreduziert ist.

Konstruktoren

RenderTargetBitmap()

Initialisiert eine neue instance der RenderTargetBitmap-Klasse.

Eigenschaften

Dispatcher	Ruft den CoreDispatcher ab, dem dieses Objekt zugeordnet ist. CoreDispatcher stellt eine Funktion dar, die auf das 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	Gibt die PixelHeight-Abhängigkeitseigenschaft an.
PixelWidth	Ruft die Breite der gerenderten Bitmap in Pixel ab.
PixelWidthProperty	Gibt die PixelWidth-Abhängigkeitseigenschaft an.

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 festgelegt wurde, was in Fällen gilt, in denen eine Animation nicht aktiv ist. (Geerbt von DependencyObject)
GetPixelsAsync()	Ruft das zuvor gerenderte RenderTargetBitmap-Bild als gepufferten Bytesstrom im vormultiplizierten AlphaformatBGRA8 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 registriert wurde, indem RegisterPropertyChangedCallback aufgerufen wurde. (Geerbt von DependencyObject)

Weitere Informationen

• ImageSource
• RenderAsync(UIElement)
• XAML-Beispiel für das Rendern in Bitmap
• Image und ImageBrush