RenderTargetBitmap 클래스

정의

네임스페이스:

Windows.UI.Xaml.Media.Imaging

XAML 시각적 트리의 결합된 콘텐츠로 채울 수 있는 이미지 원본을 나타냅니다. RenderTargetBitmap에서 XAML 시각적 개체를 캡처할 수 있는 몇 가지 주목할 만한 제한 사항을 참조하세요.

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

상속

Object Platform::Object IInspectable DependencyObject ImageSource RenderTargetBitmap

특성

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows 요구 사항

디바이스 패밀리	Windows 10 (10.0.10240.0에서 도입되었습니다.)
API contract	Windows.Foundation.UniversalApiContract (v1.0에서 도입되었습니다.)

예제

이 기본 코드 개요는 첫 번째 시나리오 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 UI 컴퍼지션에서 제공된 시각적 개체에 이미지 효과를 적용하거나, 탐색 시스템에 대한 자식 페이지의 썸네일 이미지를 생성하거나, 사용자가 UI의 일부를 이미지 원본으로 저장한 다음 해당 이미지를 다른 앱과 공유할 수 있는 시나리오를 수행할 수 있습니다.

RenderTargetBitmap은 ImageSource의 하위 클래스이므로 Image 요소 또는 ImageBrush 브러시의 이미지 원본으로 사용할 수 있습니다.

RenderAsync를 호출하면 유용한 이미지 원본이 제공되지만 앱이 GetPixelsAsync를 호출할 때까지 렌더링 콘텐츠의 전체 버퍼 표현이 비디오 메모리에서 복사되지 않습니다. 앱이 렌더링된 콘텐츠만 표시하려고 하고 픽셀 데이터가 필요하지 않은 경우 RenderAsync 만 호출하고( GetPixelsAsync를 호출하지 않고) RenderTargetBitmap을 Image 또는 ImageBrush 원본으로 사용하는 것이 더 빠릅니다. Share 계약 교환과 같은 DataTransferManager 작업에 대한 이미지를 캡처하거나 이미지에 효과를 적용하거나 Windows.Graphics.ImagingAPI를 사용하여 변환하려는 경우 픽셀 데이터가 필요할 수 있습니다.

가장 자주 사용할 RenderTargetBitmap API는 RenderAsync입니다. 이 메서드에는 RenderAsync(UIElement) 와 이미지 원본의 원하는 차원을 원본 시각적 트리의 자연 크기와 다르게 지정할 수 있는 또 다른 오버로드 의 두 가지 오버로드가 있습니다. RenderAsync 는 기본적으로 비동기 메서드이므로 UI 원본과의 정확한 프레임 동기화를 보장하지는 않지만 대부분의 시나리오에서 타이밍에 충분히 가깝습니다.

RenderTargetBitmap 개체는 일반적으로 XAML UI에서 선언되지 않습니다. UI 표시를 위해 RenderTargetBitmap의 유용한 이미지 채우기 instance 전에 코드에서 RenderAsync를 호출해야 하기 때문입니다.

RenderTargetBitmap 사용에 대한 자세한 코드 예제는 비트맵 샘플에 XAML 렌더링을 참조하세요.

비디오 드라이버가 복구의 일부로 다시 설정되는 경우와 같이 다른 하위 수준 시스템과의 상호 작용으로 인해 드물게 RenderTargetBitmap의 콘텐츠가 손실될 수 있습니다( TDR(시간 제한 검색 및 복구) 참조). 이 경우 CompositionTarget.SurfaceContentsLost 이벤트가 발생합니다. 이 사례 및 유사한 정보 손실 사례를 설명하기 위해 앱은 CompositionTarget.SurfaceContentsLost 이벤트를 수신 대기하고 RenderAsync 를 다시 호출하여 RenderTargetBitmap의 콘텐츠를 다시 렌더링해야 합니다.

RenderTargetBitmap의 렌더링된 비트맵 콘텐츠는 현재 DPI 설정이 변경될 때 자동으로 크기 조정되지 않습니다. 렌더링된 벡터 콘텐츠가 선명하게 유지되도록 현재 보기의 DPI 설정이 변경될 때 앱은 RenderTargetBitmap의 콘텐츠를 다시 렌더링해야 합니다. 예를 들어 사용자가 다른 DPI 설정에서 실행되는 두 모니터 간에 앱을 이동하는 경우 크기 조정이 발생할 수 있습니다. 이러한 경우를 감지하려면 DisplayInformation.DpiChanged 이벤트를 수신 대기하는 것이 좋습니다.

XAML 시각적 트리의 렌더링된 최대 크기는 Microsoft DirectX 텍스처의 최대 크기에 의해 제한됩니다. 자세한 내용은 리소스 제한(Direct3D 11)을 참조하세요. 이 제한은 앱이 실행되는 하드웨어에 따라 달라질 수 있습니다. 이 제한을 초과하는 매우 큰 콘텐츠는 맞게 크기가 조정될 수 있습니다. 이러한 방식으로 크기 조정 제한을 적용하는 경우 PixelWidth 및 PixelHeight 속성을 사용하여 크기 조정 후 렌더링된 크기를 쿼리할 수 있습니다. 예를 들어 10000 x 10000픽셀 XAML 시각적 트리는 4096 x 4096픽셀로 스케일링될 수 있습니다. 앱이 실행되는 하드웨어에 의해 강제로 적용되는 특정 제한의 예입니다.

XAML 시각적 개체 및 RenderTargetBitmap 캡처 기능

RenderTargetBitmap에 캡처할 수 없는 XAML로 구성된 시각적 콘텐츠에 대한 몇 가지 시나리오가 있습니다.

• 트리에 있지만 표시 유형 이 Collapsed 로 설정된 콘텐츠는 캡처되지 않습니다.
• XAML 시각적 트리에 직접 연결되지 않은 콘텐츠와 기본 창의 콘텐츠는 캡처되지 않습니다. 여기에는 하위 창과 같은 것으로 간주되는 팝업 콘텐츠가 포함됩니다.
• 캡처할 수 없는 콘텐츠는 캡처된 이미지에 비어 있는 것으로 표시되지만 동일한 시각적 트리의 다른 콘텐츠는 여전히 캡처되고 렌더링됩니다(캡처할 수 없는 콘텐츠의 존재는 해당 XAML 컴퍼지션의 전체 캡처를 무효화하지 않음).
• XAML 시각적 트리에 있지만 오프스크린에 있는 콘텐츠는 표시 유형 = 축소가 아닌 한 캡처할 수 있습니다.

생성자

RenderTargetBitmap()

RenderTargetBitmap 클래스의 새 instance 초기화합니다.

속성

Dispatcher	이 개체가 연결된 CoreDispatcher 를 가져옵니다. CoreDispatcher는 코드가 비 UI 스레드에서 시작되더라도 UI 스레드에서 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)	이 DependencyObject instance 특정 DependencyProperty에 대한 변경 내용을 수신 대기하기 위한 알림 함수를 등록합니다. (다음에서 상속됨 DependencyObject)
RenderAsync(UIElement)	UIElement 시각적 트리의 스냅샷 이미지 원본에 렌더링합니다.
RenderAsync(UIElement, Int32, Int32)	UIElement 시각적 트리의 스냅샷 이미지 원본에 렌더링합니다. scaledWidth 및 scaledHeight 값을 지정하여 원래 소스의 렌더링 차원을 변경합니다.
SetValue(DependencyProperty, Object)	DependencyObject에 대한 종속성 속성의 로컬 값을 설정합니다. (다음에서 상속됨 DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	RegisterPropertyChangedCallback을 호출하여 이전에 등록된 변경 알림을 취소합니다. (다음에서 상속됨 DependencyObject)

추가 정보

• ImageSource
• RenderAsync(UIElement)
• 비트맵 샘플에 XAML 렌더링
• Image 및 ImageBrush