IWICBitmapEncoder::CreateNewFrame method (wincodec.h)

Article
10/13/2021

Creates a new IWICBitmapFrameEncode instance.

Syntax

HRESULT CreateNewFrame(
  [out]     IWICBitmapFrameEncode **ppIFrameEncode,
  [in, out] IPropertyBag2         **ppIEncoderOptions
);

Parameters

[out] ppIFrameEncode

Type: IWICBitmapFrameEncode**

A pointer that receives a pointer to the new instance of an IWICBitmapFrameEncode.

[in, out] ppIEncoderOptions

Type: IPropertyBag2**

Optional. Receives the named properties to use for subsequent frame initialization. See Remarks.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The parameter ppIEncoderOptions can be used to receive an IPropertyBag2 that can then be used to specify encoder options. This is done by passing a pointer to a NULL IPropertyBag2 pointer in ppIEncoderOptions. The returned IPropertyBag2 is initialized with all encoder options that are available for the given format, at their default values. To specify non-default encoding behavior, set the needed encoder options on the IPropertyBag2 and pass it to IWICBitmapFrameEncode::Initialize.

Note Do not pass in a pointer to an initialized IPropertyBag2. The pointer will be overwritten, and the original IPropertyBag2 will not be freed.

Otherwise, you can pass NULL in ppIEncoderOptions if you do not intend to specify encoder options.

See Encoding Overview for an example of how to set encoder options.

For formats that support encoding multiple frames (for example, TIFF, JPEG-XR), you can work on only one frame at a time. This means that you must call IWICBitmapFrameEncode::Commit before you call CreateNewFrame again.

Requirements

Requirement	Value
Minimum supported client	Windows XP with SP2, Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	wincodec.h
Library	Windowscodecs.lib
DLL	Windowscodecs.dll