How to use encoding options (XAML)
[ 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
- We assume you know how to create a basic Windows Runtime app using C++, C#, or Visual Basic. For more info, see Create a "Hello, world" app (XAML).
- You should know how to encode an image using BitmapEncoder. For more info, see How to encode a new image.
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.