BitmapImage 클래스

참조

정의

네임스페이스:: Windows.UI.Xaml.Media.Imaging

중요

일부 정보는 릴리스되기 전에 상당 부분 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적이거나 묵시적인 보증도 하지 않습니다.

편집

Image.Source 및 ImageBrush.ImageSource 속성에 대한 실제 개체 원본 형식을 제공합니다. 이미지 원본 파일을 참조하는 URI(Uniform Resource Identifier)를 사용하거나 SetSourceAsync 를 호출하고 스트림을 제공하여 BitmapImage를 정의할 수 있습니다.

public ref class BitmapImage sealed : BitmapSource

/// [Windows.Foundation.Metadata.Activatable(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [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)]
class BitmapImage final : BitmapSource

/// [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(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class BitmapImage final : BitmapSource

[Windows.Foundation.Metadata.Activatable(typeof(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[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)]
public sealed class BitmapImage : BitmapSource

[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(typeof(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BitmapImage : BitmapSource

Public NotInheritable Class BitmapImage
Inherits BitmapSource

<BitmapImage .../>

상속: Object Platform::Object IInspectable DependencyObject ImageSource BitmapSource BitmapImage

특성: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows 요구 사항

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

예제

다음은 BitmapImage 개체를 사용하여 C#에서 Image.Source 를 설정하는 예제입니다. 이 예제에서는 Image 개체가 XAML에서 만들어졌지만 원본 또는 다른 속성 값이 없습니다. 대신 XAML에서 이미지를 로드할 때 런타임에 이러한 값이 제공됩니다.

<Image Loaded="Image_Loaded"/>

void Image_Loaded(object sender, RoutedEventArgs e)
{
    Image img = sender as Image; 
    BitmapImage bitmapImage = new BitmapImage();
    img.Width = bitmapImage.DecodePixelWidth = 80; 
    // Natural px width of image source.
    // You don't need to set Height; the system maintains aspect ratio, and calculates the other
    // dimension, as long as one dimension measurement is provided.
    bitmapImage.UriSource = new Uri(img.BaseUri,"Assets/StoreLogo.png");
    img.Source = bitmapImage;
}

설명

BitmapImage는 다음 이미지 파일 형식에서 공급할 수 있습니다.

JPEG(Joint Photographic Experts Group)
PNG(이동식 네트워크 그래픽)
비트맵(BMP)
GIF(Graphics Interchange Format)
TIFF(Tagged Image File Format)
JPEG XR
아이콘(ICO)

이미지 원본이 스트림인 경우 해당 스트림은 이러한 형식 중 하나로 이미지 파일을 포함해야 합니다.

BitmapImage 클래스는 이미지 원본을 비동기적으로 설정할 수 있지만 XAML 태그에서 속성 값으로 또는 코드에서 대기 가능한 구문을 사용하지 않는 개체로 참조할 수 있도록 추상화 를 나타냅니다. 코드에서 BitmapImage 개체를 만들 때 처음에는 유효한 원본이 없습니다. 그런 다음, 다음 기술 중 하나를 사용하여 원본을 설정해야 합니다.

기본 생성자 대신 BitmapImage(Uri) 생성자를 사용합니다. 생성자이지만 암시적 비동기 동작이 있다고 생각할 수 있습니다. BitmapImage는 성공적인 비동기 소스 집합 작업을 나타내는 ImageOpened 이벤트를 발생할 때까지 사용할 준비가 되지 않습니다.
UriSource 속성을 설정합니다. Uri 생성자를 사용하는 것과 마찬가지로 이 작업은 암시적으로 비동기적이며, ImageOpened 이벤트가 발생할 때까지 BitmapImage를 사용할 준비가 되지 않습니다.
SetSourceAsync를 사용합니다. 이 메서드는 명시적으로 비동기입니다. Image.Source와 같은 BitmapImage를 사용할 수 있는 속성은 이 비동기 동작을 위해 설계되었으며, 아직 전체 원본이 없는 BitmapImage를 사용하여 설정된 경우 예외를 throw하지 않습니다. 예외를 처리하는 대신 BitmapImage에서 직접 또는 원본을 사용하는 컨트롤(컨트롤 클래스에서 해당 이벤트를 사용할 수 있는 경우)에서 ImageOpened 또는 ImageFailed 이벤트를 처리해야 합니다.

ImageFailed 및 ImageOpened 은 상호 배타적입니다. BitmapImage 개체에 원본 값이 설정되거나 다시 설정될 때마다 한 이벤트 또는 다른 이벤트가 항상 발생합니다.

BitmapImage 및 인코딩

이미지 파일에 대한 기본 코덱 지원은 Windows의 WIC(Windows 이미징 구성 요소) API에서 제공합니다. 코덱에 대해 설명된 특정 이미지 형식에 대한 자세한 내용은 네이티브 WIC 코덱을 참조하세요. 형식 및 URI(Uniform Resource Identifier)를 사용하여 앱 리소스에서 제공되는 이미지 원본 파일에 액세스하는 방법에 대한 자세한 내용은 Image 및 ImageBrush를 참조하세요.

이미지, BitmapImage 및 BitmapSource용 API에는 미디어 형식의 인코딩 및 디코딩을 위한 전용 메서드가 포함되어 있지 않습니다. 모든 인코드 및 디코드 작업이 기본 제공되며 인코드 또는 디코드의 측면을 로드 이벤트에 대한 이벤트 데이터의 일부로 표시할 뿐입니다. 앱이 이미지 변환 또는 조작을 수행하는 경우 사용할 수 있는 이미지 인코딩 또는 디코딩을 사용하여 특별한 작업을 수행하려면 Windows.Graphics.Imaging 네임스페이스에서 사용할 수 있는 API를 사용해야 합니다. 이러한 이미징 API는 JavaScript를 사용하는 C++, C#또는 Visual Basic 또는 Windows 앱을 사용하는 UWP 앱에서 사용할 수 있습니다. 이러한 API는 Windows 8의 WIC(Windows 이미징 구성 요소) 구성 요소에서도 지원됩니다.

애니메이션 이미지

Windows 10 버전 1607부터 XAML Image 요소는 애니메이션 GIF 이미지를 지원합니다. BitmapImage를 이미지 원본으로 사용하는 경우 BitmapImage API에 액세스하여 애니메이션 GIF 이미지의 재생을 제어할 수 있습니다.

기본값인 자동 실행 속성을 사용하여 애니메이션 비트맵이 로드되는 즉시 재생되는지 여부를 지정합니다.
IsAnimatedBitmap 속성을 사용하여 비트맵에 애니메이션 효과를 적용할지 여부를 검사.
애니메이션 비트맵의 재생을 제어하려면 Play 및 Stop 메서드와 함께 IsPlaying 속성을 사용합니다.

참고

대부분의 앱에서는 사용자의 접근성 요구를 지원하기 위해 UISettings.AnimationsEnabled가 false인 경우 자동 실행을false로 설정하는 것이 좋습니다. 애니메이션 GIF의 콘텐츠가 앱의 유용성에 중요한 경우 이 작업을 수행하지 마세요.

앱이 버전 1607 이전의 Windows 10 릴리스에서 실행되는 경우 해당 멤버를 사용하기 전에 ApiInformation 클래스를 사용하여 이러한 멤버가 있는지 검사 합니다. 자세한 내용은 버전 적응 코드: 이전 버전과의 호환성을 유지하면서 새 API 사용을 참조하세요.

이 예제에서는 애니메이션 GIF를 사용하는 방법을 보여줍니다. 단추를 사용하면 사용자가 애니메이션을 시작하거나 중지할 수 있습니다. 이 예제에서는 버전 적응 코드를 사용하여 모든 버전의 Windows 10 실행할 수 있습니다. 버전 1607 이전 버전에서는 GIF의 첫 번째 프레임이 표시되지만 애니메이션이 적용되지는 않습니다.

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <Image Loaded="Image_Loaded">
        <Image.Source>
            <BitmapImage x:Name="imageSource"
                         UriSource="Assets/example.gif"
                         ImageOpened="imageSource_ImageOpened"/>
        </Image.Source>
    </Image>

    <AppBarButton x:Name="playButton"
              Icon="Play"
              Visibility="Collapsed"
              Click="playButton_Click"/>
</Grid>

// Set the AutoPlay property.
private void Image_Loaded(object sender, RoutedEventArgs e)
{
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "AutoPlay") == true)
    {
        imageSource.AutoPlay = false;
    }
}

// Show the play/stop button if the image is animated.
private void imageSource_ImageOpened(object sender, RoutedEventArgs e)
{
    var bitmapImage = (BitmapImage)sender;
    // At this point you can query whether the image is animated or not.
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsAnimatedBitmap") 
        && bitmapImage.IsAnimatedBitmap == true)
    {
        // Enable the play button
        playButton.Visibility = Visibility.Visible;
    }
}

// Play or stop the animated bitmap.
void playButton_Click(object sender, RoutedEventArgs e)
{
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsPlaying"))
    {
        // You can call the Play and Stop methods safely because is the IsPlaying property is
        // present, these methods are also present.
        if (imageSource.IsPlaying == true)
        {
            playButton.Icon = new SymbolIcon(Symbol.Play);
            imageSource.Stop();
        }
        else
        {
            playButton.Icon = new SymbolIcon(Symbol.Stop);
            imageSource.Play();
        }
    }
}

자세한 예제는 애니메이션 GIF 재생 샘플을 참조하세요.

버전 기록

Windows 버전	SDK 버전	추가된 값
1607	14393	자동 실행
1607	14393	IsAnimatedBitmap
1607	14393	IsPlaying
1607	14393	재생
1607	14393	Stop

생성자

BitmapImage()	BitmapImage 클래스의 새 instance 초기화합니다.
BitmapImage(Uri)	제공된 URI(Uniform Resource Identifier)를 사용하여 BitmapImage 클래스의 새 instance 초기화합니다.

속성

AutoPlay	애니메이션 이미지가 로드되는 즉시 재생되어야 하는지 여부를 나타내는 값을 가져오거나 설정합니다.
AutoPlayProperty	자동 실행 종속성 속성을 식별합니다.
CreateOptions	BitmapImage에 대한 BitmapCreateOptions를 가져오거나 설정합니다.
CreateOptionsProperty	CreateOptions 종속성 속성을 식별합니다.
DecodePixelHeight	이미지 디코딩 작업에 사용할 높이를 가져오거나 설정합니다.
DecodePixelHeightProperty	DecodePixelHeight 종속성 속성을 식별합니다.
DecodePixelType	디코딩 작업에 대해 DecodePixelWidth 및 DecodePixelHeight 값을 해석하는 방법을 결정하는 값을 가져오거나 설정합니다.
DecodePixelTypeProperty	DecodePixelType 종속성 속성을 식별합니다.
DecodePixelWidth	이미지 디코딩 작업에 사용할 너비를 가져오거나 설정합니다.
DecodePixelWidthProperty	DecodePixelWidth 종속성 속성을 식별합니다.
Dispatcher	이 개체가 연결된 CoreDispatcher 를 가져옵니다. CoreDispatcher는 코드가 비 UI 스레드에서 시작된 경우에도 UI 스레드에서 DependencyObject에 액세스할 수 있는 기능을 나타냅니다. (다음에서 상속됨 DependencyObject)
IsAnimatedBitmap	이미지에 애니메이션 효과를 적용할지 여부를 나타내는 값을 가져옵니다.
IsAnimatedBitmapProperty	IsAnimatedBitmap 종속성 속성을 식별합니다.
IsPlaying	애니메이션 이미지가 재생되고 있는지 여부를 나타내는 값을 가져옵니다.
IsPlayingProperty	IsPlaying 종속성 속성을 식별합니다.
PixelHeight	비트맵의 높이를 픽셀 단위로 가져옵니다. (다음에서 상속됨 BitmapSource)
PixelWidth	비트맵의 너비를 픽셀 단위로 가져옵니다. (다음에서 상속됨 BitmapSource)
UriSource	이 BitmapImage를 생성한 그래픽 원본 파일의 URI(Uniform Resource Identifier)를 가져오거나 설정합니다.
UriSourceProperty	UriSource 종속성 속성을 식별합니다.

메서드

ClearValue(DependencyProperty)	종속성 속성의 로컬 값을 지웁니다. (다음에서 상속됨 DependencyObject)
GetAnimationBaseValue(DependencyProperty)	애니메이션이 활성화되지 않은 경우 적용되는 종속성 속성에 대해 설정된 모든 기본 값을 반환합니다. (다음에서 상속됨 DependencyObject)
GetValue(DependencyProperty)	DependencyObject에서 종속성 속성의 현재 유효 값을 반환합니다. (다음에서 상속됨 DependencyObject)
Play()	애니메이션 이미지의 애니메이션을 시작합니다.
ReadLocalValue(DependencyProperty)	로컬 값이 설정된 경우 종속성 속성의 로컬 값을 반환합니다. (다음에서 상속됨 DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	이 DependencyObject instance 특정 DependencyProperty의 변경 내용을 수신 대기하기 위한 알림 함수를 등록합니다. (다음에서 상속됨 DependencyObject)
SetSource(IRandomAccessStream)	스트림에 액세스하여 BitmapSource 의 원본 이미지를 설정합니다. 대부분의 호출자는 대신 SetSourceAsync를 사용해야 합니다. (다음에서 상속됨 BitmapSource)
SetSourceAsync(IRandomAccessStream)	스트림에 액세스하고 결과를 비동기적으로 처리하여 BitmapSource 의 원본 이미지를 설정합니다. (다음에서 상속됨 BitmapSource)
SetValue(DependencyProperty, Object)	DependencyObject에서 종속성 속성의 로컬 값을 설정합니다. (다음에서 상속됨 DependencyObject)
Stop()	애니메이션 이미지의 애니메이션을 종료합니다.
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	RegisterPropertyChangedCallback을 호출하여 이전에 등록된 변경 알림을 취소합니다. (다음에서 상속됨 DependencyObject)

이벤트

DownloadProgress	BitmapImage 콘텐츠의 다운로드 진행률에서 상당한 변경이 발생한 경우에 발생합니다.
ImageFailed	이미지 검색 또는 형식과 관련된 오류가 있을 때 발생합니다.
ImageOpened	이미지 원본을 다운로드하고 오류 없이 디코딩할 때 발생합니다. 이 이벤트를 사용하여 렌더링하기 전에 이미지의 크기를 확인할 수 있습니다.

적용 대상

다음을 통해 공유