RenderTargetBitmap Class

Representa un origen de imagen que se puede rellenar con el contenido combinado de un árbol visual XAML. Vea las notas sobre algunas limitaciones notables en los que las representaciones visuales de XAML se pueden capturar en RenderTargetBitmap.

Herencia

Object
  DependencyObject
    ImageSource
      RenderTargetBitmap

Sintaxis


public sealed class RenderTargetBitmap : ImageSource

Atributos

[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06030000)]
[WebHostHidden()]

Members

A continuación se indican los tipos de miembros de RenderTargetBitmap (Clase):

Constructores

A continuación se indican los constructores de RenderTargetBitmap (Clase).

ConstructorDescripción
RenderTargetBitmap Initializes a new instance of the RenderTargetBitmap class.

 

Métodos

The RenderTargetBitmap Clase tiene estos métodos. También hereda métodos de Object Clase.

MétodoDescripción
ClearValue Clears the local value of a dependency property. (Se hereda de DependencyObject)
GetAnimationBaseValue Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Se hereda de DependencyObject)
GetPixelsAsync Retrieves the previously rendered RenderTargetBitmap image as a buffered stream of bytes in BGRA8 format.
GetValue Returns the current effective value of a dependency property from a DependencyObject. (Se hereda de DependencyObject)
ReadLocalValue Returns the local value of a dependency property, if a local value is set. (Se hereda de DependencyObject)
RenderAsync(UIElement) Renders a snapshot of a UIElement visual tree to an image source.
RenderAsync(UIElement, Int32, Int32) Renders a snapshot of a UIElement visual tree to an image source. Specify values for scaledWidth and scaledHeight to alter the original source's rendering dimension.
SetValue Sets the local value of a dependency property on a DependencyObject. (Se hereda de DependencyObject)

 

Propiedades

RenderTargetBitmapClase tiene estas propiedades.

PropiedadTipo de accesoDescripción

Dispatcher

De sólo lecturaGets the CoreDispatcher that this object is associated with. (Se hereda de DependencyObject)

PixelHeight

De sólo lecturaGets the height of the rendered bitmap in pixels.

PixelHeightProperty

De sólo lecturaIdentifies the PixelHeight dependency property.

PixelWidth

De sólo lecturaGets the width of the rendered bitmap in pixels.

PixelWidthProperty

De sólo lecturaIdentifies the PixelWidth dependency property.

 

Comentarios

Mediante RenderTargetBitmap, puede conseguir escenarios como aplicar efectos de imagen a una representación visual que provenía originalmente de una composición de IU 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 comparta después dicha imagen con otras aplicaciones.

Como la clase RenderTargetBitmap es una subclase de ImageSource, esta puede usarse como origen de la imagen para los elementos Image o como pincel ImageBrush.

La llamada al método RenderAsync proporciona un origen de imagen útil pero la representación completa del búfer de contenido de representación no se copiará fuera de la memoria de vídeo hasta que la aplicación llame al método GetPixelsAsync. Es más rápido llamar solo a RenderAsync (sin llamar a GetPixelsAsync) y utilizar RenderTargetBitmap como origen Image o ImageBrush si la aplicación solo intenta mostrar el contenido presentado 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 para contenido compartido, o si desea aplicar efectos a la imagen o transcodificarla mediante la API Windows.Graphics.Imaging.

La API de RenderTargetBitmap que usará con mayor frecuencia es RenderAsync. Existen dos sobrecargas de este método: RenderAsync(UIElement) y another overload donde puede especificar que las dimensiones deseadas de origen de la imagen sean diferentes al 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 del fotograma con el origen de la interfaz de usuario, pero es suficiente para la mayoría de los escenarios.

Un objeto RenderTargetBitmap no se declara normalmente en una interfaz de usuario XAML, porque necesita llamar a RenderAsync en el código antes de tener una instancia útil, rellenada por imagen, de RenderTargetBitmap para fines de presentación de interfaz de usuario.

Para obtener más ejemplos de código del uso de RenderTargetBitmap, vea Representación XAML para ejemplo de mapa de bits.

El contenido de un objeto 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 ocurre, el evento CompositionTarget.SurfaceContentsLost se desencadenará. Para tener en cuenta este caso y otros similares de pérdida de información, las aplicaciones deben escuchar el evento CompositionTarget.SurfaceContentsLost y volver a presentar el contenido de RenderTargetBitmap llamando a RenderAsync de nuevo.

El tamaño del contenido del mapa de bits representado de un objeto RenderTargetBitmap no se ajusta automáticamente cuando cambia la configuración de PPP actual. Las aplicaciones deben volver a presentar el contenido de la clase RenderTargetBitmap cuando el valor de PPP de la vista actual cambia para garantizar que el contenido del vector mostrado permanece nítido. Por ejemplo, un cambio de tamaño puede producirse si el usuario mueve una aplicación entre dos monitores que se ejecutan con distinta configuración de PPP. Considere la posibilidad de escuchar al evento DisplayInformation.DpiChanged para detectar estos casos.

El tamaño máximo de representación de un árbol visual XAML está limitado por las dimensiones máximas de una textura de Microsoft DirectX; para obtener más información, vea Límites de recursos (Direct3D). Este límite puede variar según el hardware donde se ejecuta la aplicación. Se puede ajustar la escala del contenido muy grande que supera este límite. Si se aplican los límites de escala de esta manera, se podrá consultar el tamaño representado tras escalar utilizando las propiedades PixelWidth y PixelHeight. Por ejemplo, un árbol visual XAML de 10.000 por 10.000 píxeles XAML se podría escalar hasta 4096 por 4096 píxeles como ejemplo de límite establecido por el hardware que se aplica cuando se ejecuta la aplicación.

Los efectos visuales de XAML y capacidades de captura de RenderTargetBitmap

Hay algunos escenarios de contenido visual compuesto por XAML que no se pueden capturar para RenderTargetBitmap:

  • El contenido de vídeo de MediaElement o CaptureElement no se puede capturar mediante RenderTargetBitmap. Eso incluye capturar fotogramas desde dentro del contenido de vídeo.
  • No se puede capturar el contenido personalizado de DirectX (su propia cadena de intercambio) dentro de las clases SwapChainBackgroundPanel o SwapChainPanel mediante RenderTargetBitmap.
  • No se capturará el contenido que se encuentre en el árbol visual de XAML pero que se encuentre fuera de la pantalla. No se capturará el contenido que se encuentre en el árbol pero que tenga la propiedad Visibility establecida en Collapsed.
  • No se capturará el contenido que no esté directamente conectado al árbol visual XAML ni 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 espacio en blanco en la imagen capturada; sin embargo, el resto del contenido del mismo árbol visual todavía se capturará y se presentará (la presencia de contenido que no puede capturarse no invalidará la captura completa de la composición XAML).

Ejemplos

Este esquema de código básico se ha adaptado del primer escenario XAML y del código de la Ejemplo de representación XAML en mapa de bits. Observe como todo el código, incluso el constructor, está dentro de un método async. 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; 
}

Requisitos

Cliente mínimo admitido

Windows 8.1 [Solo aplicaciones de la Tienda Windows]

Servidor mínimo admitido

Windows Server 2012 R2 [Solo aplicaciones de la Tienda Windows]

Espacio de nombres

Windows.UI.Xaml.Media.Imaging
Windows::UI::Xaml::Media::Imaging [C++]

Metadatos

Windows.winmd

Vea también

ImageSource
Ejemplo de representación XAML en mapa de bits
Inicio rápido: Image e ImageBrush
RenderAsync(UIElement)

 

 

Mostrar:
© 2014 Microsoft