RenderTargetBitmap Classe

Definição

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

Herança

Object Platform::Object IInspectable DependencyObject ImageSource RenderTargetBitmap

Atributos

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Exemplos

Esta estrutura de tópicos de código básica é adaptada do primeiro cenário XAML e do código da renderização XAML para o exemplo de bitmap. Observe como todo o código, mesmo o construtor, está dentro de um método assíncrono . Aqui está um manipulador de eventos para um botão que um usuário clica para iniciar a solicitação de renderização.

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

Comentários

Usando um RenderTargetBitmap, você pode realizar cenários como aplicar efeitos de imagem a um visual que originalmente veio de uma composição da interface do usuário XAML, gerar imagens em miniatura de páginas filho para um sistema de navegação ou permitir que o usuário salve partes da interface do usuário como uma fonte de imagem e compartilhe essa imagem com outros aplicativos.

Como RenderTargetBitmap é uma subclasse do ImageSource, ele pode ser usado como a fonte de imagem para elementos de imagem ou um pincel ImageBrush .

Chamar RenderAsync fornece uma fonte de imagem útil, mas a representação de buffer completo do conteúdo de renderização não é copiada da memória de vídeo até que o aplicativo chame GetPixelsAsync. É mais rápido chamar RenderAsync somente (sem chamar GetPixelsAsync) e usar o RenderTargetBitmap como uma fonte Image ou ImageBrush se o aplicativo pretende exibir apenas o conteúdo renderizado e não precisar dos dados de pixel. Você provavelmente precisará dos dados de pixel se pretende capturar a imagem para uma operação DataTransferManager, como uma troca de contrato de compartilhamento, ou se quiser aplicar efeitos à imagem ou transcodificá-la usando o Windows. API Graphics.Imaging.

A API RenderTargetBitmap que você usará com mais frequência é RenderAsync. Há duas sobrecargas desse método: RenderAsync(UIElement) e outra sobrecarga em que você pode especificar as dimensões desejadas da fonte da imagem para serem diferentes do tamanho natural da árvore visual de origem. RenderAsync é um método assíncrono por design, portanto, não há garantia de sincronização exata de quadros com a origem da interface do usuário, mas está perto o suficiente em termos de tempo para a maioria dos cenários.

Um objeto RenderTargetBitmap normalmente não é declarado em uma interface do usuário XAML, pois você precisa chamar RenderAsync no código antes de ter uma instância útil e preenchida por imagem de RenderTargetBitmap para fins de exibição de interface do usuário.

Para obter mais exemplos de código do uso de RenderTargetBitmap, consulte a renderização XAML para o exemplo de bitmap.

O conteúdo de um RenderTargetBitmap pode ser perdido em casos raros devido à interação com outros sistemas de nível inferior, por exemplo, se o driver de vídeo for redefinido como parte de uma recuperação (consulte TDR (Detecção e Recuperação de Tempo Limite)). Se isso acontecer, o evento CompositionTarget.SurfaceContentsLost será acionado. Para considerar esse caso e casos semelhantes de perda de informações, os aplicativos devem escutar o evento CompositionTarget.SurfaceContentsLost e renderizar novamente o conteúdo de um RenderTargetBitmap chamando RenderAsync novamente.

O conteúdo de bitmap renderizado de um RenderTargetBitmap não é dimensionado automaticamente quando a configuração de DPI atual é alterada. Os aplicativos devem renderizar novamente o conteúdo de um RenderTargetBitmap quando a configuração de DPI do modo de exibição atual for alterada para garantir que o conteúdo do vetor renderizado permaneça nítido. Por exemplo, um redimensionamento pode ocorrer se o usuário mover um aplicativo entre dois monitores em execução em uma configuração de DPI diferente. Considere escutar o evento DisplayInformation.DpiChanged para detectar esses casos.

O tamanho máximo renderizado de uma árvore visual XAML é restrito pelas dimensões máximas de uma textura Microsoft DirectX; para obter mais informações, consulte Limites de Recursos (Direct3D 11). Esse limite pode variar dependendo do hardware em que o aplicativo é executado. Conteúdo muito grande que excede esse limite pode ser dimensionado para caber. Se os limites de dimensionamento forem aplicados dessa forma, o tamanho renderizado após o dimensionamento poderá ser consultado usando as propriedades PixelWidth e PixelHeight . Por exemplo, uma árvore visual XAML de 10000 por 10000 pixels pode ser dimensionada para 4096 por 4.096 pixels, um exemplo de um limite específico, conforme forçado pelo hardware em que o aplicativo é executado.

Visuais XAML e recursos de captura RenderTargetBitmap

Há alguns cenários para conteúdo visual composto por XAML que você não pode capturar em um RenderTargetBitmap:

• O conteúdo que está na árvore, mas com sua Visibilidade definida como Recolhido , não será capturado.
• O conteúdo que não está diretamente conectado à árvore visual XAML e o conteúdo da janela principal não serão capturados. Isso inclui o conteúdo pop-up , que é considerado como uma sub-janela.
• O conteúdo que não pode ser capturado aparecerá como em branco na imagem capturada, mas outro conteúdo na mesma árvore visual ainda pode ser capturado e será renderizado (a presença de conteúdo que não pode ser capturado não invalidará toda a captura dessa composição XAML).
• O conteúdo que está na árvore visual XAML, mas fora da tela, pode ser capturado, desde que não seja a Visibilidade = Recolhida.

Confira também

• ImageSource
• RenderAsync(UIElement)
• Exemplo de renderização XAML para bitmap
• Imagem e ImageBrush