RenderTargetBitmap Classe
Definição
Importante
Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.
Representa uma fonte de imagem que pode ser preenchida com o conteúdo combinado de uma árvore visual XAML. Confira algumas limitações notáveis sobre quais visuais XAML podem ser capturados em um 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 : ImageSourcePublic NotInheritable Class RenderTargetBitmap
Inherits ImageSource- Herança
- Atributos
Exemplos
Essa 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, até mesmo o construtor, está dentro de um método assíncrono . Aqui é 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 de 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, em seguida, compartilhe essa imagem com outros aplicativos.
Como RenderTargetBitmap é uma subclasse de ImageSource, ele pode ser usado como a fonte de imagem para elementos Image ou um pincel ImageBrush .
Chamar RenderAsync fornece uma fonte de imagem útil, mas a representação de buffer completa 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 RenderTargetBitmap como uma fonte Image ou ImageBrush se o aplicativo pretende apenas exibir o conteúdo renderizado e não precisa 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 a API Windows.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 origem 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á próximo o suficiente 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 da interface do usuário.
Para obter mais exemplos de código de como usar RenderTargetBitmap, consulte Renderização XAML para amostra 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 poderá 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 do 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 4096 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á conectado diretamente à árvore visual XAML e o conteúdo da janela main não será capturado. 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 outros conteúdos na mesma árvore visual ainda poderão ser capturados e renderizados (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 Visibilidade = Recolhida.
Construtores
| RenderTargetBitmap() |
Inicializa uma nova instância da classe RenderTargetBitmap . |
Propriedades
| Dispatcher |
Sempre retorna |
| DispatcherQueue |
Obtém o ao |
| PixelHeight |
Obtém a altura do bitmap renderizado em pixels. |
| PixelHeightProperty |
Identifica a propriedade de dependência PixelHeight . |
| PixelWidth |
Obtém a largura do bitmap renderizado em pixels. |
| PixelWidthProperty |
Identifica a propriedade de dependência PixelWidth . |
Métodos
| ClearValue(DependencyProperty) |
Limpa o valor local de uma propriedade de dependência. (Herdado de DependencyObject) |
| GetAnimationBaseValue(DependencyProperty) |
Retorna qualquer valor base estabelecido para uma propriedade de dependência, que se aplicaria nos casos em que uma animação não está ativa. (Herdado de DependencyObject) |
| GetPixelsAsync() |
Recupera a imagem RenderTargetBitmap renderizada anteriormente como um fluxo em buffer de bytes no formato BGRA8 . |
| GetValue(DependencyProperty) |
Retorna o valor efetivo atual de uma propriedade de dependência de um DependencyObject. (Herdado de DependencyObject) |
| ReadLocalValue(DependencyProperty) |
Retorna o valor local de uma propriedade de dependência, se um valor local for definido. (Herdado de DependencyObject) |
| RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback) |
Registra uma função de notificação para escutar alterações em uma DependencyProperty específica nessa instância dependencyObject . (Herdado de DependencyObject) |
| RenderAsync(UIElement) |
Renderiza um instantâneo de uma árvore visual UIElement em uma fonte de imagem. |
| RenderAsync(UIElement, Int32, Int32) |
Renderiza um instantâneo de uma árvore visual UIElement em uma fonte de imagem. Especifique valores para scaledWidth e scaledHeight para alterar a dimensão de renderização da origem original. |
| SetValue(DependencyProperty, Object) |
Define o valor local de uma propriedade de dependência em um DependencyObject. (Herdado de DependencyObject) |
| UnregisterPropertyChangedCallback(DependencyProperty, Int64) |
Cancela uma notificação de alteração que foi registrada anteriormente chamando RegisterPropertyChangedCallback. (Herdado de DependencyObject) |