Send comments on this topic. | Back to Introduction - All Topics | Help Version 17.0.8.10
IWICLeadBitmapEncoder::GetSubFormats Method
See Also
Gets the valid list of encoder sub-formats for a particular pixel format.

Syntax

 
HRESULT GetSubFormats(      
    WICPixelFormatGUID guidPixelFormat,     UINT cbSizeSubFormats,     WICLeadSubFormat *pSubFormats, UINT *pcSubFormats );

Parameters

 
guidPixelFormat
[in] The pixel format GUID that the encoder is using.
cbSizeSubFormats
[in] The array size of the pSubFormats array.
pSubFormats
[in,out] A pointer that receives a list of sub-formats supported by the encoder.
pcSubFormats
[in,out] A pointer that receives the number of sub-formats the encoder supports.

Return Values

Returns S_OK if successful, or an error value otherwise.

Remarks

This method fills an array with the valid sub-formats for particular LEAD bitmap encoder.  Call GetSubFormats once to get the number of sub-formats.  Allocate the appropriate sized array.  Then call GetSubFormats again passing the allocated array as an argument.

Calling the GetSubFormatFlags method on each of the sub-formats returns flags that specify the supported options for the sub-format . The (sub-format)/(sub-format flag) pair is unique .  The friendly-name for the (sub-format)/sub-format flag) pair can be obtained by calling the GetSubFormatFriendlyName method.  Since it is the (sub-format)/(sub-format flag) pair that is unique, the array of sub-formats can contain duplicate values. 

Example1:
A LEAD object implementing the  IWICLeadBitmapEncoder interface is created using the class id CLSID_WICLeadCmpEncoder.  For a pixel format of GUID_WICPixelFormat24bppBGR, the GetSubFormats method will return an array of two values (shown in the first column below).  Calling the GetSubFormatFlags method on each of the sub-formats returns the flags that specify options for the sub-format (shown in second column).  Finally, the friendly name is obtained by calling GetSubFormatFriendlyName.
WICLeadSubFormat WICLeadSubFormatFlags Friendly Name
WICLeadSubFormatCmp WICLeadFlagStamp
WICLeadFlagQualityFactor
WICLeadFlagCmpQualityFactorPredefined
Progressive
WICLeadSubFormatCmp Stamp
WICLeadFlagQualityFactor
WICLeadFlagCmpQualityFactorPredefined
Progressive
Progressive

 

Example 2:
The IWICLeadBitmapEncoder object is created using with CLSID_WICLeadJpegEncoder using GUID_WICPixelFormat24bppBGR. The GetSubFormats method will return an array of ten values.  The results are shown in the following table.
WICLeadBitmapEncoderSubFormat WICLeadBitmapEncoderSubFormatFlags Friendly Name
WICLeadSubFormatJpeg WICLeadFlagQualityFactor 
WICLeadFlagStamp
Yuv 4:4:4
WICLeadSubFormatJpeg422 WICLeadFlagQualityFactor 
WICLeadFlagStamp
Yuv 4:2:2
WICLeadSubFormatJpeg411 WICLeadFlagQualityFactor
WICLeadFlagStamp
Yuv 4:1:1
WICLeadSubFormatJpeg WICLeadFlagProgressive 
WICLeadFlagQualityFactor
WICLeadFlagStamp
Progressive 444
WICLeadSubFormatJpeg422 WICLeadFlagProgressive
WICLeadFlagQualityFactor
WICLeadFlagWICLeadFlagStamp
Progressive 422
WICLeadSubFormatJpeg411 WICLeadFlagProgressive
WICLeadFlagQualityFactor
WICLeadFlagStamp
Progressive 411
WICLeadSubFormatJpeg WICLeadFlagStamp
WICLeadFlagLosslessJpeg
Lossless
WICLeadSubFormatJpegLab WICLeadFlagQualityFactor
WICLeadFlagStamp
Lab 4:4:4
WICLeadSubFormatJpegLab422 WICLeadFlagQualityFactor
WICLeadFlagStamp
Lab 4:2:2
WICLeadSubFormatJpegLab411 WICLeadFlagQualityFactor
WICLeadFlagStamp
Lab 4:1:1

See Also

Example

// This example displays all the subformats and flags for the LEAD Jpeg Encoder
// Refer to the Example Requirements for help in running this sample

// MyGetSubFormatFriendlyName gets the friendly name of the subformat
CString MyGetSubFormatFriendlyName(IWICLeadBitmapEncoder *piLeadBitmapEncoder, WICPixelFormatGUID guidPixelFormat, UINT uSubformatIndex)
{
   CString csRet;
   HRESULT hr = S_OK;
   UINT uActual = 0;
   WCHAR *pwzFriendlyName = NULL; 

   if (piLeadBitmapEncoder)
   {
      IWICBitmapEncoder *piBitmapEncoder = NULL;

      // Get subformat friendly name
      IFS(piLeadBitmapEncoder->GetSubFormatFriendlyName(guidPixelFormat, uSubformatIndex, 0, NULL, &uActual));
      if (uActual > 0)
      {
         pwzFriendlyName = new WCHAR[uActual];
         if (pwzFriendlyName)
         {
            IFS(piLeadBitmapEncoder->GetSubFormatFriendlyName(guidPixelFormat, uSubformatIndex, uActual, pwzFriendlyName, &uActual));
            if (SUCCEEDED(hr))
               csRet = pwzFriendlyName;
         }
      }
   }
   DELETE_POINTER(pwzFriendlyName);
   return csRet;
}

CString MyGetSubFormatFlagString(WICLeadSubFormatFlags uFlags)
{
   CString csRet;

   if (uFlags == 0)
      csRet = L"WICLeadFlagNone";

   if (uFlags & WICLeadFlagProgressive)
      csRet = csRet + L"\nWICLeadFlagProgressive";

   if (uFlags & WICLeadFlagCmpQualityFactorPredefined)
      csRet = csRet + L"\nWICLeadFlagCmpQualityFactorPredefined";

	if (uFlags & WICLeadFlagQualityFactor)
      csRet = csRet + L"\nWICLeadFlagQualityFactor";

	if (uFlags & WICLeadFlagMultiPage)
      csRet = csRet + L"\nWICLeadFlagMultiPage";

	if (uFlags & WICLeadFlagStamp)
      csRet = csRet + L"\nWICLeadFlagStamp";

	if (uFlags & WICLeadFlagLosslessJpeg)
      csRet = csRet + L"\nWICLeadFlagLosslessJpeg";

	if (uFlags & WICLeadFlagJpeg2000Basic)
      csRet = csRet + L"\nWICLeadFlagJpeg2000Basic";

	if (uFlags & WICLeadFlagJpeg2000Advanced)
      csRet = csRet + L"\nWICLeadFlagJpeg2000Advanced";

	if (uFlags & WICLeadFlagPngQualityFactor)
      csRet = csRet + L"\nWICLeadFlagPngQualityFactor";

	if (uFlags & WICLeadFlagAbcQualityFactor)
      csRet = csRet + L"\nWICLeadFlagAbcQualityFactor";

	if (uFlags & WICLeadFlagEcwQualityFactor)
      csRet = csRet + L"\nWICLeadFlagEcwQualityFactor";

	if (uFlags & WICLeadFlagJpeg2000AlphaChannel)
      csRet = csRet + L"\nWICLeadFlagJpeg2000AlphaChannel";

	if (uFlags & WICLeadFlagJbig2Support)
      csRet = csRet + L"\nWICLeadFlagJbig2Support";

	if (uFlags & WICLeadFlagXpsPngQualityFactor)
      csRet = csRet + L"\nWICLeadFlagXpsPngQualityFactor";

	if (uFlags & WICLeadFlagXpsJpegQualityFactor)
      csRet = csRet + L"\nWICLeadFlagXpsJpegQualityFactor";

	if (uFlags & WICLeadFlagJpeg2000QualityFactor)
      csRet = csRet + L"\nWICLeadFlagJpeg2000QualityFactor";

	if (uFlags & WICLeadFlagHdpQualityFactor)
      csRet = csRet + L"\nWICLeadFlagHdpQualityFactor";

	if (uFlags & WICLeadFlagInterlaced)
      csRet = csRet + L"\nWICLeadFlagInterlaced";

	if (uFlags & WICLeadFlagDither)
      csRet = csRet + L"\nWICLeadFlagDither";

   return csRet;
}

HRESULT IWICLeadBitmapEncoder_GetSubFormats(HWND hWnd)
{
   HRESULT hr = S_OK;
   IWICImagingFactory *piImagingFactory = NULL;
   IWICBitmapEncoder *piBitmapEncoder = NULL;
   IWICLeadBitmapEncoder *piLeadBitmapEncoder = NULL;
   CString csExampleName = L"IWICLeadBitmapEncoder_GetSubFormats";
   CString csMsg = csExampleName + "\n\n";
   GUID guidContainerFormat = GUID_ContainerFormatLeadJpeg;
   WICPixelFormatGUID guidPixelFormat = GUID_WICPixelFormat24bppBGR;

   // Create a LEAD Jpeg Bitmap Encoder
   IFS(CoCreateInstance(CLSID_WICImagingFactory, NULL, CLSCTX_INPROC_SERVER, IID_IWICImagingFactory, (LPVOID*) &piImagingFactory));
   IFS(piImagingFactory->CreateEncoder(guidContainerFormat, NULL, &piBitmapEncoder));

   // QueryInterface on the encoder to get the IWICLeadBitmapEncoder interface
   IFS(piBitmapEncoder->QueryInterface(IID_WICLeadBitmapEncoder, reinterpret_cast<void**>(&piLeadBitmapEncoder)));

   // first call to get number of subformats
   UINT uSubFormats = 0;
   WICLeadSubFormat *pSubFormats = NULL;
   IFS(piLeadBitmapEncoder->GetSubFormats(guidPixelFormat, 0, NULL, &uSubFormats));
   if (SUCCEEDED(hr))
   {
      pSubFormats = new WICLeadSubFormat[uSubFormats];
      if (pSubFormats)
      {
         // second call to get the subformats
         IFS(piLeadBitmapEncoder->GetSubFormats(guidPixelFormat, uSubFormats, pSubFormats, &uSubFormats));
      }
   }

   // Display the subformat friendly name, and flags
   for (UINT i = 0; i < uSubFormats; i++)
   {
      CString csSubFormat =  MyGetSubFormatFriendlyName(piLeadBitmapEncoder, guidPixelFormat, i);
      WICLeadSubFormatFlags uFlags = WICLeadFlagNone;

      IFS(piLeadBitmapEncoder->GetSubFormatFlags(guidPixelFormat, i, &uFlags));
      CString csFlag = MyGetSubFormatFlagString(uFlags);
      CString csOut;
      csOut = csSubFormat + csFlag + L"\n\n";
      csMsg = csMsg + csOut;
   }

   RELEASE_INTERFACE(piLeadBitmapEncoder);
   RELEASE_INTERFACE(piBitmapEncoder);
   RELEASE_INTERFACE(piImagingFactory);

   DELETE_POINTER(pSubFormats);

   MessageBox(hWnd, csMsg, csExampleName, MB_OK);
   return hr;
}