BitmapEncoder BitmapEncoder BitmapEncoder BitmapEncoder Class

Definition

Contains methods to create, edit and save images.

public : sealed class BitmapEncoder : IBitmapEncoder, IBitmapEncoderWithSoftwareBitmappublic sealed class BitmapEncoder : IBitmapEncoder, IBitmapEncoderWithSoftwareBitmapPublic NotInheritable Class BitmapEncoder Implements IBitmapEncoder, IBitmapEncoderWithSoftwareBitmap// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

Here's a partial example of creating an encoder object. This example assumes you selected a file with Windows.Storage.Pickers.FileSavePicker. For full instructions on selecting a file, creating an encoder, and encoding 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.
        }

Remarks

Image formats

BitmapEncoder can encode the following formats.

  • JPEG
  • PNG
  • GIF
  • TIFF
  • BMP
  • JPEG-XR For a list of decoding formats, see the BitmapDecoder topic.

BitmapEncoder behaves differently from BitmapDecoder in that it doesn't provide random access to the frames in an image. Instead, you need to perform actions on the encoder in a specific order.

When you create a BitmapEncoder, it provides access to data on the container and the first frame. When you are done setting data on the first frame and container, if you don't want to encode any additional frames, then call FlushAsync to complete the encoding operation.

If you want to encode an additional frame, call GoToNextFrameAsync. This commits the data in the container and the first frame so you can't edit them anymore. At this point any actions you perform on the encoder will affect the second frame. After you are done with each frame, you can call GoToNextFrameAsync to commit and append a new frame, or call FlushAsync to finish.Bitmap encoders may expose various encoding options that affect the quality, size and other properties of the encoded output file. For more info, see Imaging.

Properties

BitmapContainerProperties BitmapContainerProperties BitmapContainerProperties BitmapContainerProperties

The metadata for the container.

public : BitmapProperties BitmapContainerProperties { get; }public BitmapProperties BitmapContainerProperties { get; }Public ReadOnly Property BitmapContainerProperties As BitmapProperties// You can use this property in JavaScript.
Value
BitmapProperties BitmapProperties BitmapProperties BitmapProperties

A BitmapProperties object that provides both read and write access to the metadata for the container.

BitmapProperties BitmapProperties BitmapProperties BitmapProperties

The metadata for the selected frame.

public : BitmapProperties BitmapProperties { get; }public BitmapProperties BitmapProperties { get; }Public ReadOnly Property BitmapProperties As BitmapProperties// You can use this property in JavaScript.
Value
BitmapProperties BitmapProperties BitmapProperties BitmapProperties

A BitmapProperties object that provides both read and write access to the metadata for the selected frame.

BitmapTransform BitmapTransform BitmapTransform BitmapTransform

A BitmapTransform object that is used to specify how the frame bitmap is to be transformed.

public : BitmapTransform BitmapTransform { get; }public BitmapTransform BitmapTransform { get; }Public ReadOnly Property BitmapTransform As BitmapTransform// You can use this property in JavaScript.
Value
BitmapTransform BitmapTransform BitmapTransform BitmapTransform

A BitmapTransform object that is used to specify how the frame bitmap is to be transformed.

Remarks

If you try scale an image stored in an indexed pixel format using the BitmapTransform member, FlushAsync fails with HRESULT WINCODEC_ERR_INVALIDPARAMETER . Instead, you must use GetPixelDataAsync to obtain the scaled pixel data and then use SetPixelData to set it on the encoder.

BmpEncoderId BmpEncoderId BmpEncoderId BmpEncoderId

The unique identifier of the built-in BMP encoder.

public : static PlatForm::Guid BmpEncoderId { get; }public static Guid BmpEncoderId { get; }Public Static ReadOnly Property BmpEncoderId As Guid// You can use this property in JavaScript.
Value
PlatForm::Guid Guid Guid Guid

The unique identifier of the built-in BMP encoder.

EncoderInformation EncoderInformation EncoderInformation EncoderInformation

Information about the bitmap encoder.

public : BitmapCodecInformation EncoderInformation { get; }public BitmapCodecInformation EncoderInformation { get; }Public ReadOnly Property EncoderInformation As BitmapCodecInformation// You can use this property in JavaScript.
Value
BitmapCodecInformation BitmapCodecInformation BitmapCodecInformation BitmapCodecInformation

An object containing information about the bitmap encoder.

GeneratedThumbnailHeight GeneratedThumbnailHeight GeneratedThumbnailHeight GeneratedThumbnailHeight

The height, in pixels, of any generated thumbnail.

public : unsigned int GeneratedThumbnailHeight { get; set; }public uint GeneratedThumbnailHeight { get; set; }Public ReadWrite Property GeneratedThumbnailHeight As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The height of the thumbnail, in pixels. The default value is 120 pixels.

GeneratedThumbnailWidth GeneratedThumbnailWidth GeneratedThumbnailWidth GeneratedThumbnailWidth

The width, in pixels, of any generated thumbnail.

public : unsigned int GeneratedThumbnailWidth { get; set; }public uint GeneratedThumbnailWidth { get; set; }Public ReadWrite Property GeneratedThumbnailWidth As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

The width of the thumbnail, in pixels. The default value is 160 pixels.

GifEncoderId GifEncoderId GifEncoderId GifEncoderId

The unique identifier of the built-in GIF encoder.

public : static PlatForm::Guid GifEncoderId { get; }public static Guid GifEncoderId { get; }Public Static ReadOnly Property GifEncoderId As Guid// You can use this property in JavaScript.
Value
PlatForm::Guid Guid Guid Guid

The unique identifier of the built-in GIF encoder.

IsThumbnailGenerated IsThumbnailGenerated IsThumbnailGenerated IsThumbnailGenerated

Indicates whether or not a new thumbnail is automatically generated.

public : PlatForm::Boolean IsThumbnailGenerated { get; set; }public bool IsThumbnailGenerated { get; set; }Public ReadWrite Property IsThumbnailGenerated As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

A value that indicates whether or not the bitmap encoder will automatically generate a new thumbnail. The default value is False.

Remarks

When this value is true, the bitmap encoder will generate a new thumbnail by downscaling the frame bitmap. The thumbnail size is determined by the GeneratedThumbnailWidth and GeneratedThumbnailHeight properties. When this value is false, no thumbnail is written to the file.

If the BitmapEncoder was created using the CreateForTranscodingAsync method and IsThumbnailGenerated is false, the bitmap encoder will leave any existing thumbnail data untouched. In this case, if the bitmap was modified before encoding, it's possible for the output file to have a thumbnail that does not match the new contents of the image.

Only JPEG, TIFF and JPEG-XR image types support encoding thumbnails. If the image format being encoded does not support thumbnails and you set IsThumbnailGenerated to true, then the call to FlushAsync will fail with HRESULT WINCODEC_ERR_UNSUPPORTEDOPERATION. You should catch this exception and retry encoding with thumbnail generation disabled. If your app only encodes image formats that support thumbnails, you can skip this step.


   try
    {
        await encoder.FlushAsync();
    }
    catch (Exception err)
    {
        switch (err.HResult)
        {
            case unchecked ((int) 0x88982F81): //WINCODEC_ERR_UNSUPPORTEDOPERATION
                // If the encoder does not support writing a thumbnail, then try again
                // but disable thumbnail generation.
                encoder.IsThumbnailGenerated = false;
                break;
            default:
                throw err;
        }
    }

    if (encoder.IsThumbnailGenerated == false)
    {
        await encoder.FlushAsync();
    }

JpegEncoderId JpegEncoderId JpegEncoderId JpegEncoderId

The unique identifier of the built-in JPEG encoder.

public : static PlatForm::Guid JpegEncoderId { get; }public static Guid JpegEncoderId { get; }Public Static ReadOnly Property JpegEncoderId As Guid// You can use this property in JavaScript.
Value
PlatForm::Guid Guid Guid Guid

The unique identifier of the built-in JPEG encoder.

JpegXREncoderId JpegXREncoderId JpegXREncoderId JpegXREncoderId

The unique identifier of the built-in JPEG-XR encoder.

public : static PlatForm::Guid JpegXREncoderId { get; }public static Guid JpegXREncoderId { get; }Public Static ReadOnly Property JpegXREncoderId As Guid// You can use this property in JavaScript.
Value
PlatForm::Guid Guid Guid Guid

The unique identifier of the built-in JPEG-XR encoder.

PngEncoderId PngEncoderId PngEncoderId PngEncoderId

The unique identifier of the built-in PNG encoder.

public : static PlatForm::Guid PngEncoderId { get; }public static Guid PngEncoderId { get; }Public Static ReadOnly Property PngEncoderId As Guid// You can use this property in JavaScript.
Value
PlatForm::Guid Guid Guid Guid

The unique identifier of the built-in PNG encoder.

TiffEncoderId TiffEncoderId TiffEncoderId TiffEncoderId

The unique identifier of the built-in TIFF encoder.

public : static PlatForm::Guid TiffEncoderId { get; }public static Guid TiffEncoderId { get; }Public Static ReadOnly Property TiffEncoderId As Guid// You can use this property in JavaScript.
Value
PlatForm::Guid Guid Guid Guid

The unique identifier of the built-in TIFF encoder.

Methods

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

Asynchronously creates a new BitmapEncoder.

public : static IAsyncOperation<BitmapEncoder> CreateAsync(PlatForm::Guid encoderId, IRandomAccessStream stream)public static IAsyncOperation<BitmapEncoder> CreateAsync(Guid encoderId, IRandomAccessStream stream)Public Static Function CreateAsync(encoderId As Guid, stream As IRandomAccessStream) As IAsyncOperation( Of BitmapEncoder )// You can use this method in JavaScript.
Parameters
encoderId
PlatForm::Guid Guid Guid Guid

The unique identifier of the specified encoder.

Returns

Remarks

An application must always specify the encoderId in order to create a BitmapEncoder. The unique identifiers of the built-in encoders are available as properties on BitmapEncoder. In addition, the unique identifier of any installed encoder can be obtained by using the GetEncoderInformationEnumerator method.

BitmapEncoder expects that the output stream is empty. You can ensure that the stream is empty by setting its Size property to 0.

See Also

CreateAsync(Guid, IRandomAccessStream, IIterable<>>) CreateAsync(Guid, IRandomAccessStream, IIterable<>>) CreateAsync(Guid, IRandomAccessStream, IIterable<>>) CreateAsync(Guid, IRandomAccessStream, IIterable<>>)

Asynchronously creates a new BitmapEncoder for the specified codec with the specified encoding options and initializes it on a stream.

public : static IAsyncOperation<BitmapEncoder> CreateAsync(PlatForm::Guid encoderId, IRandomAccessStream stream, IIterable<IKeyValuePair<PlatForm::String, BitmapTypedValue>> encodingOptions)public static IAsyncOperation<BitmapEncoder> CreateAsync(Guid encoderId, IRandomAccessStream stream, IEnumerable<KeyValuePair<String, BitmapTypedValue>> encodingOptions)Public Static Function CreateAsync(encoderId As Guid, stream As IRandomAccessStream, encodingOptions As IEnumerable<KeyValuePair<String, BitmapTypedValue>>) As IAsyncOperation( Of BitmapEncoder )// You can use this method in JavaScript.
Parameters
encoderId
PlatForm::Guid Guid Guid Guid

The unique identifier of the specified encoder.

stream
IRandomAccessStream IRandomAccessStream IRandomAccessStream IRandomAccessStream

A stream representing where the image file is to be written.

encodingOptions
IIterable<IKeyValuePair<PlatForm::String, BitmapTypedValue>> IEnumerable<KeyValuePair<String, BitmapTypedValue>> IEnumerable<KeyValuePair<String, BitmapTypedValue>> IEnumerable<KeyValuePair<String, BitmapTypedValue>>

A collection of key-value pairs containing one or more codec-specific encoding options and the desired values.

Returns
See Also

CreateForInPlacePropertyEncodingAsync(BitmapDecoder) CreateForInPlacePropertyEncodingAsync(BitmapDecoder) CreateForInPlacePropertyEncodingAsync(BitmapDecoder) CreateForInPlacePropertyEncodingAsync(BitmapDecoder)

Asynchronously creates a new BitmapEncoder for in-place property and metadata editing. The new encoder can only edit bitmap properties in-place and will fail for any other uses.

public : static IAsyncOperation<BitmapEncoder> CreateForInPlacePropertyEncodingAsync(BitmapDecoder bitmapDecoder)public static IAsyncOperation<BitmapEncoder> CreateForInPlacePropertyEncodingAsync(BitmapDecoder bitmapDecoder)Public Static Function CreateForInPlacePropertyEncodingAsync(bitmapDecoder As BitmapDecoder) As IAsyncOperation( Of BitmapEncoder )// You can use this method in JavaScript.
Parameters
bitmapDecoder
BitmapDecoder BitmapDecoder BitmapDecoder BitmapDecoder

A BitmapDecoder containing the image data to be edited. This parameter must be created on a stream with an access mode of ReadWrite.

Note

The encoder writes to the stream that the original BitmapDecoder was created on. You can't specify an output stream.

Returns

An object that manages the asynchronous initialization of a new BitmapEncoder using data from an existing BitmapDecoder.

Remarks

Use this method to retrieve an encoder when you are only going to use it to edit or write a limited amount of properties to the image. An encoder retrieved this way can provide a performance advantage over an encoder returned by CreateForTranscodingAsync because it writes the new properties to empty padding space instead of encoding the entire image again.

Here are several limitations to an encoder retrieved this way:

  • You can only use these methods on the encoder:
  • The input BitmapDecoder must be an encoder created on a stream with ReadWrite access.
  • Not all metadata formats support fast metadata encoding. The native metadata handlers that support metadata are IFD, Exif, XMP, and GPS.
  • The metadata block must have enough padding to store the properties that you are trying to edit. If an encoding operation fails for any reason, you will have to use CreateForTranscodingAsync to edit the metadata and re-encode the image. When you re-encode, you can also add new or additional padding to enable in-place property encoding in the future. To do this, create a new BitmapTypedValue with Type set to UInt32 and Value set to the number of bytes of padding you wish to add. A typical value is 4096 bytes. Set this metadata item on one or more of the metadata query locations in this table.
    Metadata formatJPEG metadata queryTIFF, JPEG-XR metadata query
    IFD/app1/ifd/PaddingSchema:Padding/ifd/PaddingSchema:Padding
    EXIF/app1/ifd/exif/PaddingSchema:Padding/ifd/exif/PaddingSchema:Padding
    XMP/xmp/PaddingSchema:Padding/ifd/xmp/PaddingSchema:Padding
    GPS/app1/ifd/gps/PaddingSchema:Padding/ifd/gps/PaddingSchema:Padding

CreateForTranscodingAsync(IRandomAccessStream, BitmapDecoder) CreateForTranscodingAsync(IRandomAccessStream, BitmapDecoder) CreateForTranscodingAsync(IRandomAccessStream, BitmapDecoder) CreateForTranscodingAsync(IRandomAccessStream, BitmapDecoder)

Asynchronously creates a new BitmapEncoder and initializes it using data from an existing BitmapDecoder.

public : static IAsyncOperation<BitmapEncoder> CreateForTranscodingAsync(IRandomAccessStream stream, BitmapDecoder bitmapDecoder)public static IAsyncOperation<BitmapEncoder> CreateForTranscodingAsync(IRandomAccessStream stream, BitmapDecoder bitmapDecoder)Public Static Function CreateForTranscodingAsync(stream As IRandomAccessStream, bitmapDecoder As BitmapDecoder) As IAsyncOperation( Of BitmapEncoder )// You can use this method in JavaScript.
Parameters
bitmapDecoder
BitmapDecoder BitmapDecoder BitmapDecoder BitmapDecoder

A BitmapDecoder containing the image data to be copied.

Returns

Remarks

Call this method when you want to edit some elements in an image but want to preserve the rest of the data intact. For example, if you want to write some metadata or properties but don't want to touch the image itself. When you create a BitmapEncoder using this method, it is initialized using data from the bitmapDecoder argument. Any data that you set on the encoder will overwrite the existing data, and all other data is preserved unchanged.

This method only allows you to create an encoder of the same image format as the decoder.

See Also

FlushAsync() FlushAsync() FlushAsync() FlushAsync()

Asynchronously commits and flushes all of the image data.

public : IAsyncAction FlushAsync()public IAsyncAction FlushAsync()Public Function FlushAsync() As IAsyncAction// You can use this method in JavaScript.
Returns

An object that manages the asynchronous flush operation.

Remarks

Call this method when you are done encoding and before you close the output stream. The minimum data you need to set on a new image before calling FlushAsync is the pixel data (SetPixelData ). After this method is called, any subsequent calls to BitmapEncoder methods will fail.

If, after encoding is complete, you want to reuse the IRandomAccessStream from which the BitmapEncoder was created, such as passing it to the Windows.Storage.Compression APIs, you must first reset the stream's seek position to 0, the start of the stream, by calling IRandomAccessStream::Seek.

GetEncoderInformationEnumerator() GetEncoderInformationEnumerator() GetEncoderInformationEnumerator() GetEncoderInformationEnumerator()

A list of the bitmap encoders installed on the system and information about them.

public : static IVectorView<BitmapCodecInformation> GetEncoderInformationEnumerator()public static IReadOnlyList<BitmapCodecInformation> GetEncoderInformationEnumerator()Public Static Function GetEncoderInformationEnumerator() As IReadOnlyList( Of BitmapCodecInformation )// You can use this method in JavaScript.
Returns
IVectorView<BitmapCodecInformation> IReadOnlyList<BitmapCodecInformation> IReadOnlyList<BitmapCodecInformation> IReadOnlyList<BitmapCodecInformation>

A list of BitmapCodecInformation objects containing information about each encoder.

GoToNextFrameAsync() GoToNextFrameAsync() GoToNextFrameAsync() GoToNextFrameAsync()

Asynchronously commits the current frame data and appends a new empty frame to be edited.

public : IAsyncAction GoToNextFrameAsync()public IAsyncAction GoToNextFrameAsync()Public Function GoToNextFrameAsync() As IAsyncAction// You can use this method in JavaScript.
Returns

An object that manages the asynchronous operation of committing the current frame data and appending a new empty frame to be edited.

Remarks

After this method is called, data on the just-committed frame is no longer accessible. Instead, a new, empty frame is appended to the image and subsequent reads and writes on the BitmapEncoder will access this frame. You can't "rewind" to a previously committed frame.

Don't call this method if the current frame is intended to be the last frame in the image, as this will result in a superfluous, empty frame at the end of the image. Instead, call FlushAsync which will commit the frame and close the entire BitmapEncoder. For example, in most scenarios the application only needs to save a single-frame image. In these cases GoToNextFrameAsync should never be called.

The first time this method is called, all container level data as well as the first frame data is committed. Afterwards, any attempts to access container level data will fail.

See Also

GoToNextFrameAsync(IIterable<>>) GoToNextFrameAsync(IIterable<>>) GoToNextFrameAsync(IIterable<>>) GoToNextFrameAsync(IIterable<>>)

Asynchronously commits the current frame data and appends a new empty frame, with the specified encoding options, to be edited.

public : IAsyncAction GoToNextFrameAsync(IIterable<IKeyValuePair<PlatForm::String, BitmapTypedValue>> encodingOptions)public IAsyncAction GoToNextFrameAsync(IEnumerable<KeyValuePair<String, BitmapTypedValue>> encodingOptions)Public Function GoToNextFrameAsync(encodingOptions As IEnumerable<KeyValuePair<String, BitmapTypedValue>>) As IAsyncAction// You can use this method in JavaScript.
Parameters
encodingOptions
IIterable<IKeyValuePair<PlatForm::String, BitmapTypedValue>> IEnumerable<KeyValuePair<String, BitmapTypedValue>> IEnumerable<KeyValuePair<String, BitmapTypedValue>> IEnumerable<KeyValuePair<String, BitmapTypedValue>>

The specified encoding options. A collection of key-value pairs containing one or more codec-specific encoding options and the desired values.

Returns

An object that manages the asynchronous operation of committing the current frame data and appending a new empty frame to be edited.

Remarks

You can obtain a collection of key-value pairs that you can pass to the encodingOptions parameter by creating a new BitmapPropertySet.

See CreateAsync(Guid, IRandomAccessStream, IIterable(IKeyValuePair)) for more information about using encoding options.

See Also

SetPixelData(BitmapPixelFormat, BitmapAlphaMode, UInt32, UInt32, Double, Double, Byte[]) SetPixelData(BitmapPixelFormat, BitmapAlphaMode, UInt32, UInt32, Double, Double, Byte[]) SetPixelData(BitmapPixelFormat, BitmapAlphaMode, UInt32, UInt32, Double, Double, Byte[]) SetPixelData(BitmapPixelFormat, BitmapAlphaMode, UInt32, UInt32, Double, Double, Byte[])

Sets pixel data on the frame.

public : void SetPixelData(BitmapPixelFormat pixelFormat, BitmapAlphaMode alphaMode, unsigned int width, unsigned int height, double dpiX, double dpiY, Byte[] pixels)public void SetPixelData(BitmapPixelFormat pixelFormat, BitmapAlphaMode alphaMode, UInt32 width, UInt32 height, Double dpiX, Double dpiY, Byte[] pixels)Public Function SetPixelData(pixelFormat As BitmapPixelFormat, alphaMode As BitmapAlphaMode, width As UInt32, height As UInt32, dpiX As Double, dpiY As Double, pixels As Byte[]) As void// You can use this method in JavaScript.
Parameters
pixelFormat
BitmapPixelFormat BitmapPixelFormat BitmapPixelFormat BitmapPixelFormat

The pixel format of the pixel data.

alphaMode
BitmapAlphaMode BitmapAlphaMode BitmapAlphaMode BitmapAlphaMode

The alpha mode of the pixel data.

width
unsigned int UInt32 UInt32 UInt32

The width, in pixels, of the pixel data.

height
unsigned int UInt32 UInt32 UInt32

The height, in pixels, of the pixel data.

dpiX
double Double Double Double

The horizontal resolution, in dots per inch, of the pixel data.

dpiY
double Double Double Double

The vertical resolution, in dots per inch, of the pixel data.

pixels
Byte[] Byte[] Byte[] Byte[]

The pixel data.

Remarks

This method is synchronous because data is not committed until FlushAsync, GoToNextFrameAsync or GoToNextFrameAsync(IIterable(IKeyValuePair)) is called.

Setting a pixel format of Unknown will result in failure.

This method treats all pixel data as being in the sRGB color space. When you call this method it automatically clears any existing color space information from the frame, including embedded color profiles.

When you are encoding a new image, before you call FlushAsync at the minimum you must set pixel data using this method.

SetSoftwareBitmap(SoftwareBitmap) SetSoftwareBitmap(SoftwareBitmap) SetSoftwareBitmap(SoftwareBitmap) SetSoftwareBitmap(SoftwareBitmap)

Sets the image data of the current frame using the specified SoftwareBitmap.

public : void SetSoftwareBitmap(SoftwareBitmap bitmap)public void SetSoftwareBitmap(SoftwareBitmap bitmap)Public Function SetSoftwareBitmap(bitmap As SoftwareBitmap) As void// You can use this method in JavaScript.
Parameters
bitmap
SoftwareBitmap SoftwareBitmap SoftwareBitmap SoftwareBitmap

The software bitmap containing the image data.

Remarks

BitmapEncoder only supports software bitmaps that have a BitmapPixelFormat of Rgba16, Rgba8, or Bgra8. Attempting to call SetSoftwareBitmap with a software bitmap that has a different pixel format results in a format unsupported error. Use the SoftwareBitmap.Convert method to create a copy of an existing software bitmap with a different pixel format.

See Also