RenderTargetBitmap Classe

Definizione

Spazio dei nomi:

Windows.UI.Xaml.Media.Imaging

Rappresenta un'origine immagine che può essere popolata con il contenuto combinato di una struttura ad albero visuale XAML. Vedi per alcune limitazioni rilevanti sulle quali è possibile acquisire oggetti visivi XAML in un Oggetto RenderTargetBitmap.

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

Ereditarietà

Object Platform::Object IInspectable DependencyObject ImageSource RenderTargetBitmap

Attributi

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Requisiti Windows

Famiglia di dispositivi	Windows 10 (è stato introdotto in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (è stato introdotto in v1.0)

Esempio

Questa struttura del codice di base viene adattata dal primo codice XAML dello scenario 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 di salvare parti dell'interfaccia utente come origine immagine e quindi condividere tale immagine con altre app.

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

La chiamata a 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 origine Image o ImageBrush 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 DataTransferManager , ad esempio uno scambio di contratti di condivisione, oppure 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 della struttura ad albero visuale di origine. RenderAsync è un metodo asincrono per impostazione predefinita, quindi non esiste alcuna garanzia di sincronizzazione esatta dei fotogrammi con l'origine dell'interfaccia utente, ma è abbastanza temporizzazione 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 Esempio di rendering XAML in bitmap.

Il contenuto di un Oggetto 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 Rilevamento timeout e ripristino (TDR). In tal caso, verrà generato l'evento CompositionTarget.SurfaceContentsLost . Per tenere conto di questo caso e di casi simili di perdita di informazioni, le app devono restare in ascolto dell'evento CompositionTarget.SurfaceContentsLost ed eseguire nuovamente il rendering del contenuto di un RenderTargetBitmap chiamando di nuovo RenderAsync .

Il contenuto bitmap di cui è stato eseguito il rendering di un Oggetto RenderTargetBitmap non viene ridimensionato automaticamente quando viene modificata 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 di cui è stato eseguito il rendering di una struttura ad albero visuale 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 sottoposte a rendering dopo il ridimensionamento usando le proprietà PixelWidth e PixelHeight . Ad esempio, una struttura ad albero visuale XAML di 10000 pixel di 10000 pixel può essere ridimensionata a 4096 di 4096 pixel, un esempio di un limite specifico forzato dall'hardware in cui viene eseguita l'app.

Oggetti visivi XAML e funzionalità di acquisizione RenderTargetBitmap

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

• Il contenuto presente nell'albero, ma con il relativo valore Visibility impostato su Collapsed non verrà acquisito.
• Il contenuto non connesso direttamente alla struttura ad albero visuale XAML e il contenuto della finestra principale non verrà acquisito. Ciò include il contenuto popup , che viene considerato come una finestra secondaria.
• Il contenuto che non può essere acquisito verrà visualizzato come vuoto nell'immagine acquisita, ma altri contenuti nella stessa struttura ad albero visuale possono comunque essere acquisiti e verranno visualizzati (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	Ottiene coreDispatcher a cui è associato questo oggetto. CoreDispatcher rappresenta una funzionalità che può accedere a 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 RenderTargetBitmap sottoposta a rendering precedentemente come flusso memorizzato nel buffer di byte in formato BGRA8, alfa premoltiplicato .
GetValue(DependencyProperty)	Restituisce il valore effettivo corrente di una proprietà di dipendenza da 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 dipendenza specifica in questa istanza di DependencyObject . (Ereditato da DependencyObject)
RenderAsync(UIElement)	Esegue il rendering di uno snapshot di una struttura ad albero visuale UIElement in un'origine immagine.
RenderAsync(UIElement, Int32, Int32)	Esegue il rendering di uno snapshot di una struttura ad albero visuale UIElement in un'origine immagine. Specificare i valori per scaledWidth e scaledHeight per modificare la dimensione di rendering dell'origine originale.
SetValue(DependencyProperty, Object)	Imposta il valore locale di una proprietà di dipendenza su dependencyObject. (Ereditato da DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Annulla una notifica di modifica registrata in precedenza chiamando RegisterPropertyChangedCallback. (Ereditato da DependencyObject)

Vedi anche

• ImageSource
• RenderAsync(UIElement)
• Esempio di rendering XAML in bitmap
• Image e ImageBrush