BitmapEncoder.CreateForInPlacePropertyEncodingAsync(BitmapDecoder) Method

Definition

Namespace:

Windows.Graphics.Imaging

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

/// [Windows.Foundation.Metadata.RemoteAsync]
 static IAsyncOperation<BitmapEncoder> CreateForInPlacePropertyEncodingAsync(BitmapDecoder const& bitmapDecoder);

[Windows.Foundation.Metadata.RemoteAsync]
public static IAsyncOperation<BitmapEncoder> CreateForInPlacePropertyEncodingAsync(BitmapDecoder bitmapDecoder);

function createForInPlacePropertyEncodingAsync(bitmapDecoder)

Public Shared Function CreateForInPlacePropertyEncodingAsync (bitmapDecoder As BitmapDecoder) As IAsyncOperation(Of BitmapEncoder)

Parameters

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

IAsyncOperation<BitmapEncoder>

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

Attributes

RemoteAsyncAttribute

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