RenderTargetBitmap Clase

Definición

Espacio de nombres:

Windows.UI.Xaml.Media.Imaging

Representa un origen de imagen que se puede rellenar con el contenido combinado de un árbol visual XAML. Consulta para conocer algunas limitaciones importantes sobre qué objetos visuales XAML se pueden capturar en un 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

Herencia

Object Platform::Object IInspectable DependencyObject ImageSource RenderTargetBitmap

Atributos

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Requisitos de Windows

Familia de dispositivos	Windows 10 (se introdujo en la versión 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (se introdujo en la versión v1.0)

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 . Este 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 provenía originalmente 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 un origen de imagen y luego comparta 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 .

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 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 contrato de recurso 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 para la mayoría de los escenarios.

Un objeto RenderTargetBitmap no suele declararse 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 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 de nuevo a RenderAsync .

El contenido del mapa de bits representado de renderTargetBitmap no se escala automáticamente cuando cambia la configuración de PPP actual. 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, 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 (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 por 10000 píxeles se puede escalar a 4096 por 4096 píxeles, un ejemplo de un límite determinado forzado por el hardware en el que se ejecuta la aplicación.

Objetos visuales XAML y funcionalidades de captura 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 el 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 secontraigavisibilidad = .

Constructores

RenderTargetBitmap()

Inicializa una nueva instancia de la clase RenderTargetBitmap .

Propiedades

Dispatcher	Obtiene el CoreDispatcher al que está asociado este objeto. CoreDispatcher representa una instalación que puede acceder a DependencyObject en el subproceso de la interfaz de usuario, incluso si un subproceso que no es de interfaz de usuario inicia el código. (Heredado de DependencyObject)
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 anteriormente como una secuencia almacenada en búfer de bytes en formato alfa premultiplicadoBGRA8.
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 mediante una llamada a RegisterPropertyChangedCallback. (Heredado de DependencyObject)

Consulte también

• ImageSource
• RenderAsync(UIElement)
• Representación XAML en un ejemplo de mapa de bits
• Image e ImageBrush