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 notables sobre qué objetos visuales XAML se pueden capturar en un objeto 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 de la representación XAML al 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 al usuario guardar partes de la interfaz de usuario como origen de imágenes y, a continuación, compartir esa imagen con otras aplicaciones.
Dado que RenderTargetBitmap es una subclase de ImageSource, se puede usar como origen de imagen para los elementos Image o un pincel imageBrush .
La llamada 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 solo a RenderAsync (sin llamar a GetPixelsAsync) y usar RenderTargetBitmap como origen Image o ImageBrush 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 piensa capturar la imagen para una operación dataTransferManager , como un intercambio de contratos de uso compartido, o si desea aplicar efectos a la imagen o transcodificarla mediante la API Windows.Graphics.Imaging.
La API RenderTargetBitmap que usarás con más frecuencia 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 para mostrar la interfaz de usuario.
Para obtener más ejemplos de código sobre el uso de RenderTargetBitmap, consulta Xaml render to bitmap sample (Representación XAML en un ejemplo de mapa de bits).
El contenido de un 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 (consulte 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 objeto 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, puede producirse 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 (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 escale para ajustarse. Si se aplican límites de escala de esta manera, el tamaño representado después del escalado se puede consultar mediante las propiedades PixelWidth y PixelHeight . Por ejemplo, un árbol visual XAML de 10000 píxeles de 10000 píxeles podría escalarse a 4096 en 4096 píxeles, un ejemplo de un límite determinado forzado por el hardware donde se ejecuta la aplicación.
Funcionalidades de captura de objetos visuales XAML y RenderTargetBitmap
Hay algunos escenarios para el contenido visual compuesto por XAML que no se puede capturar en renderTargetBitmap:
- El contenido que se encuentra en el árbol, pero con su visibilidad establecido en Collapsed 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 emergente , que se considera como una sub-ventana.
- 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 fuera de la pantalla se puede capturar, siempre y cuando no secontraigala visibilidad = .
Constructores
| RenderTargetBitmap() |
Inicializa una nueva instancia de la clase RenderTargetBitmap . |
Propiedades
| Dispatcher |
Siempre devuelve |
| DispatcherQueue |
Obtiene el objeto |
| PixelHeight |
Obtiene el alto del mapa de bits representado en píxeles. |
| PixelHeightProperty |
Identifica la propiedad de dependencia PixelHeight . |
| PixelWidth |
Obtiene el ancho del mapa de bits representado en píxeles. |
| PixelWidthProperty |
Identifica la propiedad de dependencia 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 RenderTargetBitmap representada previamente como una secuencia almacenada en búfer de bytes en formato BGRA8 . |
| GetValue(DependencyProperty) |
Devuelve el valor efectivo actual de una propiedad de dependencia de 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 dependencyProperty específica en esta instancia de DependencyObject . (Heredado de DependencyObject) |
| RenderAsync(UIElement) |
Representa una instantánea de un árbol visual UIElement en un origen de imagen. |
| RenderAsync(UIElement, Int32, Int32) |
Representa una instantánea de un árbol visual UIElement en un origen de imagen. Especifique los valores de scaledWidth y scaledHeight para modificar la dimensión de representación del origen original. |
| SetValue(DependencyProperty, Object) |
Establece el valor local de una propiedad de dependencia en dependencyObject. (Heredado de DependencyObject) |
| UnregisterPropertyChangedCallback(DependencyProperty, Int64) |
Cancela una notificación de cambio registrada anteriormente llamando a RegisterPropertyChangedCallback. (Heredado de DependencyObject) |