BitmapEncoder BitmapEncoder BitmapEncoder BitmapEncoder Class

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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<IKeyValuePair<String, BitmapTypedValue>>)CreateAsync(Guid, IRandomAccessStream, IIterable<IKeyValuePair<String, BitmapTypedValue>>)CreateAsync(Guid, IRandomAccessStream, IIterable<IKeyValuePair<String, BitmapTypedValue>>)CreateAsync(Guid, IRandomAccessStream, IIterable<IKeyValuePair<String, BitmapTypedValue>>)

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.

See Also

Imaging

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

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.

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:
  • BitmapEncoder::BitmapProperties::GetPropertiesAsync
  • BitmapEncoder::BitmapProperties::SetPropertiesAsync
  • BitmapEncoder::FlushAsync Any other methods will fail if you call them.
• 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 format	JPEG metadata query	TIFF, 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

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.

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

Imaging

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.

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.

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.

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.

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<IKeyValuePair<String, BitmapTypedValue>>)GoToNextFrameAsync(IIterable<IKeyValuePair<String, BitmapTypedValue>>)GoToNextFrameAsync(IIterable<IKeyValuePair<String, BitmapTypedValue>>)GoToNextFrameAsync(IIterable<IKeyValuePair<String, BitmapTypedValue>>)

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.

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

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

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.

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.

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.

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.