Bitmap​Decoder Bitmap​Decoder Bitmap​Decoder Class

Definition

Provides read access to bitmap container data as well as data from the first frame.

public sealed class BitmapDecoder : IBitmapDecoder, IBitmapFrame, IBitmapFrameWithSoftwareBitmappublic sealed class BitmapDecoder : IBitmapDecoder, IBitmapFrame, IBitmapFrameWithSoftwareBitmapPublic NotInheritable Class BitmapDecoder Implements IBitmapDecoder, IBitmapFrame, IBitmapFrameWithSoftwareBitmap
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Image formats

BitmapDecoder can decode the following formats.

  • JPEG
  • PNG
  • GIF
  • TIFF
  • BMP
  • ICO
  • JPEG-XR
  • Any installed Camera raw formats by using the Microsoft Camera Codec Pack. For a list of decoding formats, see the BitmapEncoder topic.

The BitmapDecoder class implements IBitmapFrame. It provides access to container data as well as data from the first frame. This allows applications to accomplish most common scenarios without needing to retrieve a separate BitmapFrame.

Examples

Here's a partial example of creating a decoder object. This example assumes you selected a file with Windows.Storage.Pickers.FileOpenPicker. For full instructions on selecting a file, creating an decoder, and decoding an image see Imaging

file.openAsync(Windows.Storage.FileAccessMode.readWrite).then(function (_stream) {
        stream = _stream;

        var encoderId;
        switch (fileType) {
            case ".jpg":
                encoderId = Windows.Graphics.Imaging.BitmapEncoder.jpegEncoderId;
                break;
        }
        return Windows.Graphics.Imaging.BitmapEncoder.createAsync(encoderId, stream);
        }).then(function (encoder) {

              // Your code here.
        }

Properties

BitmapAlphaMode BitmapAlphaMode BitmapAlphaMode

The default alpha mode of the first frame.

public BitmapAlphaMode BitmapAlphaMode { get; }public BitmapAlphaMode BitmapAlphaMode { get; }Public ReadOnly Property BitmapAlphaMode As BitmapAlphaMode
Value
BitmapAlphaMode BitmapAlphaMode BitmapAlphaMode

The default alpha mode of the first frame.

Attributes

Remarks

This is the alpha mode used when calling the GetPixelDataAsync method.

BitmapContainerProperties BitmapContainerProperties BitmapContainerProperties

Provides access to the container bitmap properties.

public BitmapPropertiesView BitmapContainerProperties { get; }public BitmapPropertiesView BitmapContainerProperties { get; }Public ReadOnly Property BitmapContainerProperties As BitmapPropertiesView
Value
BitmapPropertiesView BitmapPropertiesView BitmapPropertiesView

The container bitmap properties.

Attributes

Remarks

Many image file formats do not have container level metadata.

BitmapPixelFormat BitmapPixelFormat BitmapPixelFormat

The pixel format that best fits the first frame.

public BitmapPixelFormat BitmapPixelFormat { get; }public BitmapPixelFormat BitmapPixelFormat { get; }Public ReadOnly Property BitmapPixelFormat As BitmapPixelFormat
Value
BitmapPixelFormat BitmapPixelFormat BitmapPixelFormat

The pixel format that best fits the first frame.

Attributes

Remarks

This is the pixel format used when calling the GetPixelDataAsync method.

BitmapProperties BitmapProperties BitmapProperties

A read-only view of the metadata within the first frame.

public BitmapPropertiesView BitmapProperties { get; }public BitmapPropertiesView BitmapProperties { get; }Public ReadOnly Property BitmapProperties As BitmapPropertiesView
Value
BitmapPropertiesView BitmapPropertiesView BitmapPropertiesView

A read-only view of the metadata within the first frame.

Attributes

BmpDecoderId BmpDecoderId BmpDecoderId

The unique identifier of the BMP decoder.

public static PlatForm::Guid BmpDecoderId { get; }public static Guid BmpDecoderId { get; }Public Static ReadOnly Property BmpDecoderId As Guid
Value
System.Guid System.Guid System.Guid

The unique identifier of the BMP decoder.

Attributes

DecoderInformation DecoderInformation DecoderInformation

Information about the bitmap decoder.

public BitmapCodecInformation DecoderInformation { get; }public BitmapCodecInformation DecoderInformation { get; }Public ReadOnly Property DecoderInformation As BitmapCodecInformation
Attributes

DpiX DpiX DpiX

The horizontal resolution of the first frame in dots per inch.

public double DpiX { get; }public double DpiX { get; }Public ReadOnly Property DpiX As double
Value
double double double

The horizontal resolution of the first frame in dots per inch.

Attributes

DpiY DpiY DpiY

The vertical resolution of the first frame in dots per inch.

public double DpiY { get; }public double DpiY { get; }Public ReadOnly Property DpiY As double
Value
double double double

The vertical resolution of the first frame in dots per inch.

Attributes

FrameCount FrameCount FrameCount

The number of frames within the image file.

public unsigned short FrameCount { get; }public uint FrameCount { get; }Public ReadOnly Property FrameCount As uint
Value
uint uint uint

The number of frames.

Attributes

GifDecoderId GifDecoderId GifDecoderId

The unique identifier of the GIF decoder.

public static PlatForm::Guid GifDecoderId { get; }public static Guid GifDecoderId { get; }Public Static ReadOnly Property GifDecoderId As Guid
Value
System.Guid System.Guid System.Guid

The unique identifier of the GIF decoder.

Attributes

IcoDecoderId IcoDecoderId IcoDecoderId

The unique identifier of the ICO decoder.

public static PlatForm::Guid IcoDecoderId { get; }public static Guid IcoDecoderId { get; }Public Static ReadOnly Property IcoDecoderId As Guid
Value
System.Guid System.Guid System.Guid

The unique identifier of the ICO decoder.

Attributes

JpegDecoderId JpegDecoderId JpegDecoderId

The unique identifier of the JPEG decoder.

public static PlatForm::Guid JpegDecoderId { get; }public static Guid JpegDecoderId { get; }Public Static ReadOnly Property JpegDecoderId As Guid
Value
System.Guid System.Guid System.Guid

The unique identifier of the JPEG decoder.

Attributes

JpegXRDecoderId JpegXRDecoderId JpegXRDecoderId

The unique identifier of the JPEG-XR decoder.

public static PlatForm::Guid JpegXRDecoderId { get; }public static Guid JpegXRDecoderId { get; }Public Static ReadOnly Property JpegXRDecoderId As Guid
Value
System.Guid System.Guid System.Guid

The unique identifier of the JPEG-XR decoder.

Attributes

OrientedPixelHeight OrientedPixelHeight OrientedPixelHeight

The height of the first frame in pixels, after any EXIF orientation has been applied to the bitmap.

public unsigned short OrientedPixelHeight { get; }public uint OrientedPixelHeight { get; }Public ReadOnly Property OrientedPixelHeight As uint
Value
uint uint uint

The height of the first frame in pixels, after any EXIF orientation has been applied.

Attributes

Remarks

Use this property if you need to know the height of an image or of pixel data that has EXIF orientation applied, for example, if you call GetPixelDataAsync and specify RespectExifOrientation. Also, the HTML img element in Windows app using JavaScript, and Windows.UI.Xaml.Controls.Image respect EXIF orientation.

If you need pixel dimensions of the image as it is natively stored, use the PixelHeight property.

OrientedPixelWidth OrientedPixelWidth OrientedPixelWidth

The width of the first frame in pixels, after any EXIF orientation has been applied to the bitmap.

public unsigned short OrientedPixelWidth { get; }public uint OrientedPixelWidth { get; }Public ReadOnly Property OrientedPixelWidth As uint
Value
uint uint uint

The width of the first frame in pixels, after any EXIF orientation has been applied.

Attributes

Remarks

Use this property in the same way as OrientedPixelHeight is used if you need to know the width of an image or of pixel data.

PixelHeight PixelHeight PixelHeight

The height of the first frame in pixels.

public unsigned short PixelHeight { get; }public uint PixelHeight { get; }Public ReadOnly Property PixelHeight As uint
Value
uint uint uint

The height of the first frame in pixels.

Attributes

Remarks

Use PixelHeight for pixel dimensions of the image as it is natively stored.

PixelWidth PixelWidth PixelWidth

The width of the first frame in pixels.

public unsigned short PixelWidth { get; }public uint PixelWidth { get; }Public ReadOnly Property PixelWidth As uint
Value
uint uint uint

The width of the first frame in pixels.

Attributes

Remarks

Use PixelWidth for pixel dimensions of the image as it is natively stored.

PngDecoderId PngDecoderId PngDecoderId

The unique identifier of the PNG decoder.

public static PlatForm::Guid PngDecoderId { get; }public static Guid PngDecoderId { get; }Public Static ReadOnly Property PngDecoderId As Guid
Value
System.Guid System.Guid System.Guid

The unique identifier of the PNG decoder.

Attributes

TiffDecoderId TiffDecoderId TiffDecoderId

The unique identifier of the TIFF decoder.

public static PlatForm::Guid TiffDecoderId { get; }public static Guid TiffDecoderId { get; }Public Static ReadOnly Property TiffDecoderId As Guid
Value
System.Guid System.Guid System.Guid

The unique identifier of the TIFF decoder.

Attributes

Methods

CreateAsync(Guid, IRandomAccessStream) CreateAsync(Guid, IRandomAccessStream) CreateAsync(Guid, IRandomAccessStream)

Asynchronously creates a new BitmapDecoder using a specific bitmap codec and initializes it using a stream.

public static IAsyncOperation<BitmapDecoder> CreateAsync(Guid decoderId, IRandomAccessStream stream)public static IAsyncOperation<BitmapDecoder> CreateAsync(Guid decoderId, IRandomAccessStream stream)Public Static Function CreateAsync(decoderId As Guid, stream As IRandomAccessStream) As IAsyncOperation( Of BitmapDecoder )
Parameters
decoderId
System.Guid System.Guid System.Guid

The unique identifier of the specified bitmap codec.

stream
IRandomAccessStream IRandomAccessStream IRandomAccessStream

The stream containing the image file to be decoded.

Returns

An object that manages the asynchronous creation of a new BitmapDecoder.

Attributes

Remarks

This method allows the application to explicitly select the bitmap decoder to be used and bypass any automatic codec arbitration. The unique identifiers of the built-in decoders are available as properties on BitmapDecoder. In addition, the unique identifier of any installed decoder can be obtained using the GetDecoderInformationEnumerator method.

CreateAsync(IRandomAccessStream) CreateAsync(IRandomAccessStream) CreateAsync(IRandomAccessStream)

Asynchronously creates a new BitmapDecoder and initializes it using a stream.

public static IAsyncOperation<BitmapDecoder> CreateAsync(IRandomAccessStream stream)public static IAsyncOperation<BitmapDecoder> CreateAsync(IRandomAccessStream stream)Public Static Function CreateAsync(stream As IRandomAccessStream) As IAsyncOperation( Of BitmapDecoder )
Parameters
stream
IRandomAccessStream IRandomAccessStream IRandomAccessStream

The stream containing the image file to be decoded.

Returns

An object that manages the asynchronous creation of a new BitmapDecoder.

Attributes

Remarks

Windows.Graphics.Imaging automatically determines the correct bitmap decoder to decode the stream.

GetDecoderInformationEnumerator() GetDecoderInformationEnumerator() GetDecoderInformationEnumerator()

The bitmap decoders installed on the system and information about them.

public static IVectorView<BitmapCodecInformation> GetDecoderInformationEnumerator()public static IVectorView<BitmapCodecInformation> GetDecoderInformationEnumerator()Public Static Function GetDecoderInformationEnumerator() As IVectorView( Of BitmapCodecInformation )
Returns

A list of BitmapCodecInformation objects containing information about each decoder.

Attributes

GetFrameAsync(UInt32) GetFrameAsync(UInt32) GetFrameAsync(UInt32)

Asynchronously retrieves a frame from the image file.

public IAsyncOperation<BitmapFrame> GetFrameAsync(UInt32 frameIndex)public IAsyncOperation<BitmapFrame> GetFrameAsync(UInt32 frameIndex)Public Function GetFrameAsync(frameIndex As UInt32) As IAsyncOperation( Of BitmapFrame )
Parameters
frameIndex
System.UInt32 System.UInt32 System.UInt32

The zero-based index of the frame to be retrieved.

Returns

Object that manages the asynchronous retrieval of the frame.

Attributes

Remarks

You don't need to use this method to access data from the first frame in an image file. BitmapDecoder already provides a method to access the first frame.

You can get the total number of frames on the image using the FrameCount property.

GetPixelDataAsync() GetPixelDataAsync() GetPixelDataAsync()

Asynchronously requests the pixel data for the frame.

public IAsyncOperation<PixelDataProvider> GetPixelDataAsync()public IAsyncOperation<PixelDataProvider> GetPixelDataAsync()Public Function GetPixelDataAsync() As IAsyncOperation( Of PixelDataProvider )
Returns

Object that manages the asynchronous retrieval of the pixel data.

Attributes

Remarks

The pixel data array will use the bitmap pixel format and alpha mode specified in the BitmapPixelFormat and BitmapAlphaMode properties. It will also have color management and EXIF orientation applied.

An application should not assume that pixel data returned by this method uses any particular pixel format or alpha mode (like Rgba8 with premultiplied alpha). Instead, it should always check the BitmapPixelFormat and BitmapAlphaMode properties and handle the data accordingly.

As a convenience, this method performs color management from the frame’s embedded color space (if it exists) to the sRGB color space. If there is no embedded color profile data, then no color management is performed. This method also attempts to read the EXIF orientation flag on the frame, and if it exists, will perform the necessary transformation to correctly orient the pixel data.

In order to retrieve the correct bitmap pixel width and height, the application should read the OrientedPixelWidth and OrientedPixelHeight properties, instead of the PixelWidth and PixelHeight properties.

This method is equivalent to calling the GetPixelDataAsync(BitmapPixelFormat, BitmapAlphaMode, BitmapTransform, ExifOrientationMode, ColorManagementMode) method with the following arguments:

ArgumentValue
pixelFormatThe value of the BitmapPixelFormat property.
alphaModeThe value of the BitmapAlphaMode property
transformA new BitmapTransform.
exifOrientationModeThe ExifOrientationMode value RespectExifOrientation.
colorManagementModeThe ColorManagementMode value ColorManageToSRgb.

GetPixelDataAsync(BitmapPixelFormat, BitmapAlphaMode, BitmapTransform, ExifOrientationMode, ColorManagementMode) GetPixelDataAsync(BitmapPixelFormat, BitmapAlphaMode, BitmapTransform, ExifOrientationMode, ColorManagementMode) GetPixelDataAsync(BitmapPixelFormat, BitmapAlphaMode, BitmapTransform, ExifOrientationMode, ColorManagementMode)

Asynchronously requests the pixel data for the frame using the specified parameters.

public IAsyncOperation<PixelDataProvider> GetPixelDataAsync(BitmapPixelFormat pixelFormat, BitmapAlphaMode alphaMode, BitmapTransform transform, ExifOrientationMode exifOrientationMode, ColorManagementMode colorManagementMode)public IAsyncOperation<PixelDataProvider> GetPixelDataAsync(BitmapPixelFormat pixelFormat, BitmapAlphaMode alphaMode, BitmapTransform transform, ExifOrientationMode exifOrientationMode, ColorManagementMode colorManagementMode)Public Function GetPixelDataAsync(pixelFormat As BitmapPixelFormat, alphaMode As BitmapAlphaMode, transform As BitmapTransform, exifOrientationMode As ExifOrientationMode, colorManagementMode As ColorManagementMode) As IAsyncOperation( Of PixelDataProvider )
Parameters
pixelFormat
BitmapPixelFormat BitmapPixelFormat BitmapPixelFormat

The specified pixel format.

alphaMode
BitmapAlphaMode BitmapAlphaMode BitmapAlphaMode

The specified alpha mode.

transform
BitmapTransform BitmapTransform BitmapTransform

The set of transformations to be applied to the frame.

exifOrientationMode
ExifOrientationMode ExifOrientationMode ExifOrientationMode

Indicates whether the EXIF orientation flag should be ignored or respected.

colorManagementMode
ColorManagementMode ColorManagementMode ColorManagementMode

Indicates whether the pixel data should be color managed to the sRGB color space.

Returns

Object that manages the asynchronous retrieval of the pixel data.

Attributes

Remarks

This method should be used instead of GetPixelDataAsync if the application needs finer grained control over the pixel data array.

See Also

GetPreviewAsync() GetPreviewAsync() GetPreviewAsync()

Asynchronously returns a stream containing the preview image.

public IAsyncOperation<ImageStream> GetPreviewAsync()public IAsyncOperation<ImageStream> GetPreviewAsync()Public Function GetPreviewAsync() As IAsyncOperation( Of ImageStream )
Returns

Object that manages the asynchronous retrieval of the bitmap preview data.

The preview data is returned in the form of an image stream. You can display it using an image control, or read and edit it using BitmapDecoder and BitmapEncoder.

Attributes

Remarks

Some image formats, like JPEG-XR and camera RAW formats, contain an image preview. The preview is generally higher resolution than a thumbnail. This is an advantage because decoding the preview can be faster than decoding the full RAW image, but provides comparable fidelity when displaying images

If the image does not contain a preview, this operation fails with HRESULT WINCODEC_ERR_UNSUPPORTEDOPERATION.

GetSoftwareBitmapAsync() GetSoftwareBitmapAsync() GetSoftwareBitmapAsync()

Asynchronously gets a SoftwareBitmap representation of the decoded bitmap.

public IAsyncOperation<SoftwareBitmap> GetSoftwareBitmapAsync()public IAsyncOperation<SoftwareBitmap> GetSoftwareBitmapAsync()Public Function GetSoftwareBitmapAsync() As IAsyncOperation( Of SoftwareBitmap )
Returns

An asynchronous operation that returns a SoftwareBitmap on successful completion.

Attributes

GetSoftwareBitmapAsync(BitmapPixelFormat, BitmapAlphaMode) GetSoftwareBitmapAsync(BitmapPixelFormat, BitmapAlphaMode) GetSoftwareBitmapAsync(BitmapPixelFormat, BitmapAlphaMode)

Asynchronously gets a SoftwareBitmap representation of the decoded bitmap.

public IAsyncOperation<SoftwareBitmap> GetSoftwareBitmapAsync(BitmapPixelFormat pixelFormat, BitmapAlphaMode alphaMode)public IAsyncOperation<SoftwareBitmap> GetSoftwareBitmapAsync(BitmapPixelFormat pixelFormat, BitmapAlphaMode alphaMode)Public Function GetSoftwareBitmapAsync(pixelFormat As BitmapPixelFormat, alphaMode As BitmapAlphaMode) As IAsyncOperation( Of SoftwareBitmap )
Parameters
pixelFormat
BitmapPixelFormat BitmapPixelFormat BitmapPixelFormat

The pixel format of the software bitmap.

alphaMode
BitmapAlphaMode BitmapAlphaMode BitmapAlphaMode

The alpha mode of the software bitmap.

Returns

An asynchronous operation that returns a SoftwareBitmap on successful completion.

Attributes

GetSoftwareBitmapAsync(BitmapPixelFormat, BitmapAlphaMode, BitmapTransform, ExifOrientationMode, ColorManagementMode) GetSoftwareBitmapAsync(BitmapPixelFormat, BitmapAlphaMode, BitmapTransform, ExifOrientationMode, ColorManagementMode) GetSoftwareBitmapAsync(BitmapPixelFormat, BitmapAlphaMode, BitmapTransform, ExifOrientationMode, ColorManagementMode)

Asynchronously gets a SoftwareBitmap representation of the decoded bitmap.

public IAsyncOperation<SoftwareBitmap> GetSoftwareBitmapAsync(BitmapPixelFormat pixelFormat, BitmapAlphaMode alphaMode, BitmapTransform transform, ExifOrientationMode exifOrientationMode, ColorManagementMode colorManagementMode)public IAsyncOperation<SoftwareBitmap> GetSoftwareBitmapAsync(BitmapPixelFormat pixelFormat, BitmapAlphaMode alphaMode, BitmapTransform transform, ExifOrientationMode exifOrientationMode, ColorManagementMode colorManagementMode)Public Function GetSoftwareBitmapAsync(pixelFormat As BitmapPixelFormat, alphaMode As BitmapAlphaMode, transform As BitmapTransform, exifOrientationMode As ExifOrientationMode, colorManagementMode As ColorManagementMode) As IAsyncOperation( Of SoftwareBitmap )
Parameters
pixelFormat
BitmapPixelFormat BitmapPixelFormat BitmapPixelFormat

The pixel format of the software bitmap.

alphaMode
BitmapAlphaMode BitmapAlphaMode BitmapAlphaMode

The alpha mode of the software bitmap.

transform
BitmapTransform BitmapTransform BitmapTransform

The transform of the software bitmap.

exifOrientationMode
ExifOrientationMode ExifOrientationMode ExifOrientationMode

The EXIF orientation mode of the software bitmap.

colorManagementMode
ColorManagementMode ColorManagementMode ColorManagementMode

The color management mode of the software bitmap.

Returns

An asynchronous operation that returns a SoftwareBitmap on successful completion.

Attributes

GetThumbnailAsync() GetThumbnailAsync() GetThumbnailAsync()

Asynchronously returns a stream containing the thumbnail image.

public IAsyncOperation<ImageStream> GetThumbnailAsync()public IAsyncOperation<ImageStream> GetThumbnailAsync()Public Function GetThumbnailAsync() As IAsyncOperation( Of ImageStream )
Returns

Object that manages the asynchronous retrieval of the thumbnail stream.

The thumbnail data is returned in the form of an image stream. You can display it using an image control, or read and edit it using BitmapDecoder and BitmapEncoder

Attributes

Remarks

Many image formats, like JPEG and TIFF, allow a small sized thumbnail of the full image to be embedded within a frame. If the image does not contain a thumbnail, then this operation will fail with HRESULT WINCODEC_ERR_CODECNOTHUMBNAIL. If it exists, the EXIF orientation flag on the frame is automatically applied to the thumbnail before it is returned.

See Also