RenderTargetBitmap Класс

Определение

Пространство имен:

Microsoft.UI.Xaml.Media.Imaging

Представляет источник изображения, который можно заполнить объединенным содержимым визуального дерева XAML. Сведения о некоторых важных ограничениях, в которых визуальные элементы XAML можно записать в 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 : ImageSource

Public NotInheritable Class RenderTargetBitmap
Inherits ImageSource

Наследование

Object Platform::Object IInspectable DependencyObject ImageSource RenderTargetBitmap

Атрибуты

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Примеры

Эта базовая структура кода адаптирована из первого сценария XAML и кода отрисовки XAML для примера растрового изображения. Обратите внимание, что весь код, даже конструктор, находится в асинхронном методе. Здесь это обработчик событий для кнопки, которую пользователь щелкает, чтобы инициировать запрос на отрисовку.

<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; 
}

Комментарии

С помощью RenderTargetBitmap можно выполнить такие сценарии, как применение эффектов изображения к визуальному элементу, который изначально был получен из композиции пользовательского интерфейса XAML, создания эскизов дочерних страниц для системы навигации или сохранения частей пользовательского интерфейса в качестве источника изображения, а затем совместного использования этого изображения с другими приложениями.

Так как RenderTargetBitmap является подклассом ImageSource, его можно использовать в качестве источника изображения для элементов Image или кисти ImageBrush.

Вызов RenderAsync предоставляет полезный источник изображения, но полное представление содержимого отрисовки не копируется из памяти видео, пока приложение не вызывает GetPixelsAsync. Быстрее вызывать только RenderAsync (без вызова GetPixelsAsync) и использовать RenderTargetBitmap в качестве изображения или ImageBrush, если приложение намерено отображать отрисованное содержимое и не нуждается в пиксельных данных. Возможно, вам потребуется пиксельные данные, если вы планируете записать изображение для операции DataTransferManager, например обмена контрактами share, или если вы хотите применить эффекты к изображению или перекодировать его с помощью API Windows.Graphics.Imaging.

API RenderTargetBitmap, который используется чаще всего, — RenderAsync. Существует две перегрузки этого метода: RenderAsync(UIElement) и другую перегрузку, где можно указать требуемые размеры источника изображения, отличаемые от естественного размера исходного визуального дерева. RenderAsync является асинхронным методом по проектированию, поэтому для большинства сценариев нет никаких гарантий точной синхронизации кадров с источником пользовательского интерфейса.

Объект RenderTargetBitmap обычно не объявлен в пользовательском интерфейсе XAML, так как необходимо вызывать RenderAsync в коде, прежде чем иметь полезный, заполненный изображением экземпляр RenderTargetBitmap для отображения пользовательского интерфейса.

Дополнительные примеры кода использования RenderTargetBitmap см. в отрисовке XAML для примера растрового изображения.

Содержимое RenderTargetBitmap может быть потеряно в редких случаях из-за взаимодействия с другими системами нижнего уровня, например, если драйвер видео сбрасывается в рамках восстановления (см. обнаружение времени ожидания и восстановление (TDR)). В этом случае событие CompositionTarget.SurfaceContentsLost будет срабатывает. Чтобы учитывать этот случай и аналогичные случаи потери информации, приложения должны прослушивать событие CompositionTarget.SurfaceContentsLost и повторно отображать содержимое RenderTargetBitmap, вызвав RenderAsync еще раз.

Отрисованное растровое содержимое объекта RenderTargetBitmap не масштабируется автоматически при изменении текущего параметра DPI. Приложения должны повторно отрисовывать содержимое объекта RenderTargetBitmap при изменении параметров DPI текущего представления, чтобы убедиться, что отрисованное векторное содержимое остается четким. Например, изменение размера может произойти, если пользователь перемещает приложение между двумя мониторами, работающими в другом параметре DPI. Рассмотрите возможность прослушивания события DisplayInformation.DpiChanged для обнаружения этих случаев.

Максимальный размер визуального дерева XAML ограничен максимальными размерами текстуры Microsoft DirectX; Дополнительные сведения см. вограничения ресурсов (Direct3D 11). Это ограничение может отличаться в зависимости от оборудования, в котором выполняется приложение. Очень большое содержимое, превышающее это ограничение, может быть масштабировано для соответствия. Если ограничения масштабирования применяются таким образом, отображаемый размер после масштабирования можно запросить с помощью свойств PixelWidth и PixelHeight. Например, визуальное дерево XAML на 10000 пикселей может быть масштабировано до 4096 пикселей на 4096 пикселей, пример определенного ограничения, как принудительное оборудование, на котором выполняется приложение.

Визуальные элементы XAML и возможности записи RenderTargetBitmap

Существует несколько сценариев для визуального содержимого, состоящего в XAML, которое невозможно записать в RenderTargetBitmap:

• Содержимое, которое находится в дереве, но с видимости установлено значение Свернутый не будет захвачено.
• Содержимое, которое не подключено непосредственно к визуальному дереву XAML, и содержимое главного окна не будет записано. Это включает в себя содержимое всплывающего окна, которое считается таким, как вложенное окно.
• Содержимое, которое не может быть записано, будет отображаться как пустое на захваченном изображении, но другое содержимое в том же визуальном дереве по-прежнему может быть записано и отрисовывается (наличие содержимого, которое не может быть записано, не приведет ко всей записи этой композиции XAML).
• Содержимое, которое находится в визуальном дереве XAML, но экран можно записать, пока он не видимости = свернутые.

Конструкторы

RenderTargetBitmap()

Инициализирует новый экземпляр класса RenderTargetBitmap.

Свойства

Dispatcher	Всегда возвращает null в приложении пакета SDK для приложений windows. Вместо этого используйте DispatcherQueue. (Унаследовано от DependencyObject)
DispatcherQueue	Возвращает DispatcherQueue, с которым связан этот объект. DispatcherQueue представляет собой объект, который может получить доступ к DependencyObject в потоке пользовательского интерфейса, даже если код инициируется потоком, отличным от пользовательского интерфейса. (Унаследовано от DependencyObject)
PixelHeight	Возвращает высоту отрисованного растрового изображения в пикселях.
PixelHeightProperty	Определяет свойство зависимостей PixelHeight.
PixelWidth	Возвращает ширину отрисованного растрового изображения в пикселях.
PixelWidthProperty	Определяет свойство зависимости PixelWidth.

Методы

ClearValue(DependencyProperty)	Очищает локальное значение свойства зависимостей. (Унаследовано от DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Возвращает любое базовое значение, установленное для свойства зависимостей, которое будет применяться в случаях, когда анимация не активна. (Унаследовано от DependencyObject)
GetPixelsAsync()	Извлекает ранее отрисованное renderTargetBitmap изображение в виде буферизованного потока байтов в формате BGRA8.
GetValue(DependencyProperty)	Возвращает текущее эффективное значение свойства зависимостей из DependencyObject. (Унаследовано от DependencyObject)
ReadLocalValue(DependencyProperty)	Возвращает локальное значение свойства зависимостей, если задано локальное значение. (Унаследовано от DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Регистрирует функцию уведомлений для прослушивания изменений в определенном экземпляре DependencyProperty в этом экземпляре DependencyObj ect. (Унаследовано от DependencyObject)
RenderAsync(UIElement, Int32, Int32)	Отрисовывает моментальный снимок UIElement визуального дерева в источник изображения. Укажите значения для scaledWidth и scaledHeight для изменения измерения отрисовки исходного источника.
RenderAsync(UIElement)	Отрисовывает моментальный снимок UIElement визуального дерева в источник изображения.
SetValue(DependencyProperty, Object)	Задает локальное значение свойства зависимостей в DependencyObject. (Унаследовано от DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Отменяет уведомление об изменении, которое было зарегистрировано ранее путем вызова RegisterPropertyChangedCallback. (Унаследовано от DependencyObject)

См. также раздел

• ImageSource
• RenderAsync(UIElement)
• отрисовке XAML в образец растрового изображения
• Image и ImageBrush