How to use encoding options (XAML)

  • Article

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

We show you how to set encoding options on a BitmapEncoder. Encoding options allow you to fine tune the behavior and parameters of an encoder. Like, you can set the ImageQuality option on the JPEG encoder to control the tradeoff between image quality and file size. Typically, you don't need to use encoding options as the encoder will automatically select appropriate default values.

Encoding options are only exposed by the CreateAsync and GoToNextFrameAsync methods of BitmapEncoder. This is because you must specify the encoding option when you initialize the encoder or frame.

What you need to know

Technologies

Prerequisites

Encoding options reference

You can use the encoding options here with BitmapEncoder. An encoding option is defined by its name, which is a string, and a value in a particular data type (Windows.Foundation.PropertyType).

Name PropertyType Usage notes Valid formats
ImageQuality single Valid values from 0 to 1.0. Higher values indicate higher quality. JPEG, JPEG-XR
CompressionQuality single Valid values from 0 to 1.0. Higher values indicate a more efficient and slower compression scheme. TIFF
Lossless boolean If this is set to true, the ImageQuality option is ignored. JPEG-XR
InterlaceOption boolean Whether to interlace the image. PNG
FilterOption uint8 Use the PngFilterMode enumeration. PNG
TiffCompressionMethod uint8 Use the TiffCompressionMode enumeration. TIFF
Luminance uint32Array An array of 64 elements containing luminance quantization constants. JPEG
Chrominance uint32Array An array of 64 elements containing chrominance quantization constants. JPEG
JpegYCrCbSubsampling uint8 Use the JpegSubsamplingMode enumeration. JPEG
SuppressApp0 boolean Whether to suppress the creation of an App0 metadata block. JPEG
EnableV5Header32bppBGRA boolean Whether to encode to a version 5 BMP which supports alpha. BMP

 

Instructions

Step 1: Get an output stream

Write the beginning of a function that receives an IRandomAccessStream opened from the file to which you are encoding. You must be using a stream that was opened using ReadWrite privileges.

async void CreateEncoderWithEncodingOptions(
    Windows.Storage.Streams.IRandomAccessStream stream
    )
{

Note  This example assumes that you are encoding to a JPEG image. Encoding options are specific to the image format.

 

To learn how to obtain an output stream, see How to encode a new image.

Step 2: Create a collection of encoding options

You use a BitmapPropertySet object to store one or more encoding options. Each encoding option is a key-value pair. The key is a string set to the encoding option’s name, like ImageQuality. The value is a BitmapTypedValue object which lets you to associate the actual encoding option value with an explicit data type (Windows.Foundation.PropertyType).

This example shows you how to set the JPEG encoder to use the maximum available quality. To set the quality, create an encoding option with the key ImageQuality and set the value to a single precision number, 1.0 (the highest valid value).

     var propertySet = new Windows.Graphics.Imaging.BitmapPropertySet();
    var qualityValue = new Windows.Graphics.Imaging.BitmapTypedValue(
        1.0, // Maximum quality
        Windows.Foundation.PropertyType.Single
        );

    propertySet.Add("ImageQuality", qualityValue);

Step 3: Initialize the encoder with the encoding options

Use the CreateAsync method with the encoding options as the last parameter.

    await Windows.Graphics.Imaging.BitmapEncoder.CreateAsync(
        Windows.Graphics.Imaging.BitmapEncoder.JpegEncoderId,
        stream,
        propertySet
        );

    // Encoder is initialized with encoding options.
}

You now have an encoder that you can use as normal.

Windows.Graphics.Imaging

BitmapPropertySet

BitmapTypedValue

CreateAsync

How to encode a new image