RenderTargetBitmap Classe

Riferimento

Definizione

Spazio dei nomi:: Microsoft.UI.Xaml.Media.Imaging

Importante

Alcune informazioni sono relative alla release non definitiva del prodotto, che potrebbe subire modifiche significative prima della release definitiva. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Modifica

Rappresenta un'origine immagine che può essere popolata con il contenuto combinato di una struttura ad albero visuale XAML. Vedi per alcune limitazioni rilevanti per cui gli oggetti visivi XAML possono essere acquisiti in renderTargetBitmap.

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

Ereditarietà: Object Platform::Object IInspectable DependencyObject ImageSource RenderTargetBitmap

Attributi: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Esempio

Questa struttura del codice di base è adattata dal primo scenario XAML e dal codice del rendering XAML all'esempio bitmap. Si noti che tutto il codice, anche il costruttore, si trova all'interno di un metodo asincrono. Ecco un gestore eventi per un pulsante che un utente fa clic per avviare la richiesta di rendering.

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

Commenti

Usando renderTargetBitmap, puoi eseguire scenari come l'applicazione di effetti immagine a un oggetto visivo originariamente proveniente da una composizione dell'interfaccia utente XAML, la generazione di immagini di anteprima di pagine figlio per un sistema di spostamento o l'abilitazione dell'utente a salvare parti dell'interfaccia utente come origine immagine e quindi condividere l'immagine con altre app.

Poiché RenderTargetBitmap è una sottoclasse di ImageSource, può essere usata come origine dell'immagine per elementi Image o un pennello ImageBrush .

La chiamata RenderAsync fornisce un'origine immagine utile, ma la rappresentazione full buffer del contenuto di rendering non viene copiata dalla memoria video finché l'app non chiama GetPixelsAsync. È più veloce chiamare solo RenderAsync (senza chiamare GetPixelsAsync) e usare RenderTargetBitmap come Image o 'origine ImageBru sh se l'app intende visualizzare solo il contenuto sottoposto a rendering e non richiede i dati pixel. È probabile che siano necessari i dati pixel se si intende acquisire l'immagine per un'operazione di DataTransferManager, ad esempio uno scambio di contratti di condivisione o se si desidera applicare effetti all'immagine o transcodificarla usando l'API Windows.Graphics.Imaging.

L'API RenderTargetBitmap che verrà usata più spesso è RenderAsync. Esistono due overload di questo metodo: RenderAsync(UIElement) e un altro overload in cui è possibile specificare le dimensioni desiderate dell'origine immagine in modo che siano diverse dalle dimensioni naturali dell'albero visivo di origine. RenderAsync è un metodo asincrono per progettazione, quindi non esiste alcuna garanzia di sincronizzazione esatta dei fotogrammi con l'origine dell'interfaccia utente, ma è abbastanza breve per la maggior parte degli scenari.

Un oggetto RenderTargetBitmap non viene in genere dichiarato in un'interfaccia utente XAML, perché è necessario chiamare RenderAsync nel codice prima di avere un'istanza utile popolata dall'immagine di RenderTargetBitmap per scopi di visualizzazione dell'interfaccia utente.

Per altri esempi di codice sull'uso di RenderTargetBitmap, vedi rendering XAML nell'esempio bitmap.

Il contenuto di renderTargetBitmap può essere perso in rari casi a causa dell'interazione con altri sistemi di livello inferiore, ad esempio se il driver video viene reimpostato come parte di un ripristino (vedere Timeout Detection and Recovery (TDR)). In tal caso, verrà generato l'evento CompositionTarget.SurfaceContentsLost . Per tenere conto di questo caso e di casi di perdita di informazioni simili, le app devono restare in ascolto dell'evento CompositionTarget.SurfaceContentsLost ed eseguire di nuovo il rendering del contenuto di un Oggetto RenderTargetBitmap chiamando di nuovo RenderAsync.

Il contenuto bitmap sottoposto a rendering di un Oggetto RenderTargetBitmap non viene ridimensionato automaticamente quando cambia l'impostazione DPI corrente. Le app devono eseguire nuovamente il rendering del contenuto di un Oggetto RenderTargetBitmap quando cambia l'impostazione DPI della visualizzazione corrente per garantire che il contenuto del vettore sottoposto a rendering rimanga nitido. Ad esempio, un ridimensionamento può verificarsi se l'utente sposta un'app tra due monitor in esecuzione con un'impostazione DPI diversa. Prendere in considerazione l'ascolto dell'evento DisplayInformation.DpiChanged per rilevare questi casi.

La dimensione massima sottoposta a rendering di un albero visivo XAML è limitata dalle dimensioni massime di una trama Microsoft DirectX; per altre info, vedi limiti delle risorse (Direct3D 11). Questo limite può variare a seconda dell'hardware in cui viene eseguita l'app. Contenuto molto grande che supera questo limite potrebbe essere ridimensionato per adattarsi. Se i limiti di ridimensionamento vengono applicati in questo modo, è possibile eseguire query sulle dimensioni di cui è stato eseguito il rendering dopo il ridimensionamento usando le proprietà PixelWidth PixelHeight e PixelHeight. Ad esempio, un albero visivo XAML di 10000 pixel di 10000 pixel potrebbe essere ridimensionato a 4096 di 4096 pixel, un esempio di un limite specifico come forzato dall'hardware in cui viene eseguita l'app.

Oggetti visivi XAML e funzionalità di acquisizione di RenderTargetBitmap

Esistono alcuni scenari per il contenuto visivo composto da XAML che non è possibile acquisire in renderTargetBitmap:

Il contenuto presente nell'albero, ma con il relativo Visibility impostato su compresso non verrà acquisito.
Il contenuto non connesso direttamente alla struttura ad albero visuale XAML e il contenuto della finestra principale non verrà acquisito. Sono inclusi contenuto popup, considerato come una sotto-finestra.
Il contenuto che non può essere acquisito verrà visualizzato come vuoto nell'immagine acquisita, ma è comunque possibile acquisire altri contenuti nella stessa struttura ad albero visuale e verrà eseguito il rendering (la presenza di contenuto che non può essere acquisito non invaliderà l'intera acquisizione di tale composizione XAML).
Il contenuto che si trova nella struttura ad albero visuale XAML, ma può essere acquisito, purché non sia Visibility = Collapsed.

Costruttori

RenderTargetBitmap()

Inizializza una nuova istanza della classe RenderTargetBitmap .

Proprietà

Dispatcher	Restituisce sempre `null` in un'app di Windows App SDK. In alternativa, usare DispatcherQueue. (Ereditato da DependencyObject)
DispatcherQueue	Ottiene il `DispatcherQueue` a cui è associato questo oggetto. Il `DispatcherQueue` rappresenta una funzionalità che può accedere al `DependencyObject` nel thread dell'interfaccia utente anche se il codice viene avviato da un thread non dell'interfaccia utente. (Ereditato da DependencyObject)
PixelHeight	Ottiene l'altezza della bitmap sottoposta a rendering in pixel.
PixelHeightProperty	Identifica la proprietà di dipendenza PixelHeight.
PixelWidth	Ottiene la larghezza della bitmap sottoposta a rendering in pixel.
PixelWidthProperty	Identifica la proprietà di dipendenza PixelWidth.

Metodi

ClearValue(DependencyProperty)	Cancella il valore locale di una proprietà di dipendenza. (Ereditato da DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Restituisce qualsiasi valore di base stabilito per una proprietà di dipendenza, che si applica nei casi in cui un'animazione non è attiva. (Ereditato da DependencyObject)
GetPixelsAsync()	Recupera l'immagine di RenderTargetBit map precedentemente sottoposta a rendering come flusso memorizzato nel buffer di byte nel formato BGRA8.
GetValue(DependencyProperty)	Restituisce il valore effettivo corrente di una proprietà di dipendenza da un DependencyObject. (Ereditato da DependencyObject)
ReadLocalValue(DependencyProperty)	Restituisce il valore locale di una proprietà di dipendenza, se è impostato un valore locale. (Ereditato da DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registra una funzione di notifica per l'ascolto delle modifiche apportate a una specifica DependencyProperty in questa istanza DependencyObject. (Ereditato da DependencyObject)
RenderAsync(UIElement, Int32, Int32)	Esegue il rendering di uno snapshot di un UIElement struttura ad albero visuale in un'origine immagine. Specificare i valori per scaledWidth e scaledHeight per modificare la dimensione di rendering dell'origine originale.
RenderAsync(UIElement)	Esegue il rendering di uno snapshot di un UIElement struttura ad albero visuale in un'origine immagine.
SetValue(DependencyProperty, Object)	Imposta il valore locale di una proprietà di dipendenza in un DependencyObject. (Ereditato da DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Annulla una notifica di modifica registrata in precedenza chiamando RegisterPropertyChangedCallback. (Ereditato da DependencyObject)

Si applica a

Condividi tramite