RenderTargetBitmap Clase
Definición
Importante
Parte de la información hace referencia a la versión preliminar del producto, que puede haberse modificado sustancialmente antes de lanzar la versión definitiva. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.
Representa un origen de imagen que se puede rellenar con el contenido combinado de un árbol visual XAML. Consulta algunas limitaciones importantes sobre qué objetos visuales XAML se pueden capturar en un 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- Herencia
- Atributos
Ejemplos
Este esquema de código básico se adapta desde el primer escenario XAML y el código del representación XAML en el ejemplo de mapa de bits. Observe cómo todo el código, incluso el constructor, está dentro de un método asincrónico. Aquí es un controlador de eventos para un botón en el que un usuario hace clic para iniciar la solicitud de representación.
<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;
}
Comentarios
Con renderTargetBitmap, puedes realizar escenarios como aplicar efectos de imagen a un objeto visual que originalmente provenía de una composición de interfaz de usuario XAML, generar imágenes en miniatura de páginas secundarias para un sistema de navegación o permitir que el usuario guarde partes de la interfaz de usuario como origen de imágenes y luego comparta esa imagen con otras aplicaciones.
Dado que RenderTargetBitmap es una subclase de ImageSource, se puede usar como origen de imagen para elementos image o un pincel de ImageBrush.
Llamar a renderAsync proporciona un origen de imagen útil, pero la representación de búfer completa del contenido de representación no se copia de la memoria de vídeo hasta que la aplicación llama a GetPixelsAsync. Es más rápido llamar a RenderAsync solo (sin llamar a GetPixelsAsync) y usar RenderTargetBitmap como Image o ImageBrush origen si la aplicación solo pretende mostrar el contenido representado y no necesita los datos de píxeles. Probablemente necesite los datos de píxeles si tiene previsto capturar la imagen para una operación de DataTransferManager, como un intercambio de contratos de uso compartido, o si desea aplicar efectos a la imagen o transcodificarla mediante la API de Windows.Graphics.Imaging.
La API RenderTargetBitmap que usará más a menudo es RenderAsync. Hay dos sobrecargas de este método: renderAsync(UIElement) y otra sobrecarga donde puede especificar las dimensiones deseadas del origen de la imagen para que sean diferentes del tamaño natural del árbol visual de origen. renderAsync es un método asincrónico por diseño, por lo que no hay ninguna garantía de sincronización exacta de fotogramas con el origen de la interfaz de usuario, pero es lo suficientemente cercano como para la mayoría de los escenarios.
Un objeto RenderTargetBitmap no se declara normalmente en una interfaz de usuario XAML, ya que debes llamar a RenderAsync en el código antes de tener una instancia útil rellenada por imágenes de RenderTargetBitmap con fines de visualización de la interfaz de usuario.
Para obtener más ejemplos de código de uso de RenderTargetBitmap, consulta representación XAML en el ejemplo de mapa de bits.
El contenido de renderTargetBitmap se puede perder en raras ocasiones debido a la interacción con otros sistemas de nivel inferior, por ejemplo, si el controlador de vídeo se restablece como parte de una recuperación (vea detección y recuperación de tiempo de espera (TDR)). Si esto sucede, se desencadenará el evento CompositionTarget.SurfaceContentsLost. Para tener en cuenta este caso y casos de pérdida de información similares, las aplicaciones deben escuchar el evento CompositionTarget.SurfaceContentsLost y volver a representar el contenido de un renderTargetBitmap llamando a RenderAsync de nuevo.
El contenido del mapa de bits representado de renderTargetBitmap no se escala automáticamente cuando cambia la configuración actual de PPP. Las aplicaciones deben volver a representar el contenido de un renderTargetBitmap cuando cambia la configuración de PPP de la vista actual para asegurarse de que el contenido vectorial representado permanece nítido. Por ejemplo, se puede producir un cambio de tamaño si el usuario mueve una aplicación entre dos monitores que se ejecutan en una configuración de PPP diferente. Considere la posibilidad de escuchar el evento DisplayInformation.DpiChanged para detectar estos casos.
El tamaño máximo representado de un árbol visual XAML está restringido por las dimensiones máximas de una textura de Microsoft DirectX; para obtener más información, consulta límites de recursos de (Direct3D 11). Este límite puede variar en función del hardware en el que se ejecuta la aplicación. Es posible que el contenido muy grande que supere este límite se ajuste. Si se aplican límites de escalado de esta manera, se puede consultar el tamaño representado después del escalado mediante las propiedades PixelWidth y PixelHeight. Por ejemplo, un árbol visual XAML de 10000 píxeles por 10000 píxeles podría escalarse a 4096 en 4096 píxeles, un ejemplo de un límite determinado, tal como lo fuerza el hardware donde se ejecuta la aplicación.
Objetos visuales XAML y funcionalidades de captura de RenderTargetBitmap
Hay algunos escenarios para el contenido visual compuesto por XAML que no se puede capturar en un renderTargetBitmap:
- El contenido que se encuentra en el árbol, pero con su Visibility establecido en contraído no se capturará.
- El contenido que no está conectado directamente al árbol visual XAML y no se capturará el contenido de la ventana principal. Esto incluye contenido popup, que se considera como una ventana secundaria.
- El contenido que no se puede capturar aparecerá como en blanco en la imagen capturada, pero otro contenido del mismo árbol visual se puede capturar y se representará (la presencia de contenido que no se puede capturar no invalidará toda la captura de esa composición XAML).
- El contenido que se encuentra en el árbol visual XAML pero que está fuera de pantalla se puede capturar, siempre y cuando no se Visibilidad = contraído.
Constructores
| RenderTargetBitmap() |
Inicializa una nueva instancia de la clase RenderTargetBitmap. |
Propiedades
| Dispatcher |
Siempre devuelve |
| DispatcherQueue |
Obtiene el |
| PixelHeight |
Obtiene el alto del mapa de bits representado en píxeles. |
| PixelHeightProperty |
Identifica la propiedad de dependencia de PixelHeight. |
| PixelWidth |
Obtiene el ancho del mapa de bits representado en píxeles. |
| PixelWidthProperty |
Identifica la propiedad de dependencia de PixelWidth. |
Métodos
| ClearValue(DependencyProperty) |
Borra el valor local de una propiedad de dependencia. (Heredado de DependencyObject) |
| GetAnimationBaseValue(DependencyProperty) |
Devuelve cualquier valor base establecido para una propiedad de dependencia, que se aplicaría en los casos en los que una animación no está activa. (Heredado de DependencyObject) |
| GetPixelsAsync() |
Recupera la imagen representada anteriormente |
| GetValue(DependencyProperty) |
Devuelve el valor efectivo actual de una propiedad de dependencia de un DependencyObject. (Heredado de DependencyObject) |
| ReadLocalValue(DependencyProperty) |
Devuelve el valor local de una propiedad de dependencia, si se establece un valor local. (Heredado de DependencyObject) |
| RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback) |
Registra una función de notificación para escuchar los cambios en una |
| RenderAsync(UIElement, Int32, Int32) |
Representa una instantánea de un UIElement árbol visual en un origen de imagen. Especifique los valores de scaledWidth y scaledHeight para modificar la dimensión de representación del origen original. |
| RenderAsync(UIElement) |
Representa una instantánea de un UIElement árbol visual en un origen de imagen. |
| SetValue(DependencyProperty, Object) |
Establece el valor local de una propiedad de dependencia en un DependencyObject. (Heredado de DependencyObject) |
| UnregisterPropertyChangedCallback(DependencyProperty, Int64) |
Cancela una notificación de cambio registrada anteriormente llamando a RegisterPropertyChangedCallback. (Heredado de DependencyObject) |
Se aplica a
Consulte también
- ImageSource
- RenderAsync(UIElement)
- representación XAML en de ejemplo de mapa de bits
- Image e ImageBrush