Send comments on this topic. | Back to Introduction - All Topics | Help Version 15.03.27
IWICLeadBitmapEncoder::GetProgressiveOptions Method
See Also

Gets a list of the valid progressive options for a LEAD Bitmap encoder.

Syntax

 
    
HRESULT GetProgressiveOptions(      
    WICPixelFormatGUID guidPixelFormat,
    UINT uSubFormatIndex,
    UINT cbSizeProgressiveOptions,
    INT *pProgressiveOptions,
    UINT *pcProgessiveOptions
);

Parameters

 
guidPixelFormat
[in] The pixel format GUID that the encoder is using.
uSubFormatIndex
[in] The index of the sub-format array returned by the GetSubFormats method.
cbSizeProgressiveOptions
[in] The size of the pProgessiveOptions buffer.
pProgressiveOptions
[in,out] A pointer that receives a list of progressive options supported by the encoder.
pcProgressiveOptions
[in,out] A pointer that receives the number of progressive options the encoder supports.

Return Values

Returns S_OK if successful, or an error value otherwise.

Remarks

Some image formats can be compressed with progressive passes. This means that the image data is stored with a succession of image scans that are derived from approximations of the original image. The first image scan is typically of low accuracy. Additional scans are used to gradually refine the image. The WIC-Enabled LEAD Bitmap Encoders that support progressive scans include Cmp, Jpeg, Mng, and Jbig. Set the passes property bag item with a valid value to save these image formats with progressive passes. 
Use the GetProgressiveOptions method to get a list of the valid progressive options for a LEAD Bitmap Encoder. First call GetSubFormats to get an array of valid sub-formats for the particular LEAD bitmap encoder.  When calling the GetProgressiveOptions method, pass the index of the sub-format array for the uSubFormatIndex argument.
 
Call GetProgressiveOptions once to get number of supported predefined quality factors. Allocate the appropriately sized array.  Then call GetProgressiveOptions again, passing the allocated array as an argument. The example illustrates this technique.
To get a printable name for any of the progressive options, call the IWICLeadBitmapEncoder_GetProgressiveOptionsFriendlyName method.

See Also

Example

// This example gets the progressive options for the LEAD JPEG encoder.
// Then it displays the friendly names.
// See the following 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 friendly name for the subformat
      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;
}

// Gets the friendly name for a progressive option (nProgressiveOption)
CString MyGetProgressiveOptionsFriendlyName(IWICLeadBitmapEncoder *piLeadBitmapEncoder, INT nProgressiveOption)
{
   CString csRet;
   HRESULT hr = S_OK;
   UINT uActual = 0;
   WCHAR *pwzFriendlyName = NULL; 

   if (piLeadBitmapEncoder)
   {
      IFS(piLeadBitmapEncoder->GetProgressiveOptionsFriendlyName (nProgressiveOption, 0, NULL, &uActual));
      if (uActual > 0)
      {
         pwzFriendlyName = new WCHAR[uActual];
         if (pwzFriendlyName)
         {
            IFS(piLeadBitmapEncoder->GetProgressiveOptionsFriendlyName (nProgressiveOption, uActual, pwzFriendlyName, &uActual));
            if (SUCCEEDED(hr))
               csRet = pwzFriendlyName;
         }
      }
   }
   DELETE_POINTER(pwzFriendlyName);
   return csRet;
}



HRESULT IWICLeadBitmapEncoder_GetProgressiveOptions(HWND hWnd)
{
   HRESULT hr = S_OK;
   IWICImagingFactory *piImagingFactory = NULL;
   IWICBitmapEncoder *piBitmapEncoder = NULL;
   IWICLeadBitmapEncoder *piLeadBitmapEncoder = NULL;
   CString csExampleName = L"IWICLeadBitmapEncoder_GetProgressiveOptions";
   CString csMsg = csExampleName + "\n\n";

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

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

   // **************************************************************************
   // First get the sub formats for the LEAD Jpeg Encoder with 24 bits per pixel
   // **************************************************************************
   WICPixelFormatGUID guidPixelFormat = GUID_WICPixelFormat24bppBGR;
   UINT uSubFormats = 0;
   WICLeadSubFormat *pSubFormats = NULL;
   WICLeadSubFormatFlags uFlags = WICLeadFlagNone;
   INT nIndexProgressive = -1;

   // first call, to get number of subformats
   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));
      }
   }

   // **************************************************************************
   // Next, get the sub formats flags for the sub-formats.  
   // Continue this until we find a subformat that supports WICLeadFlagProgressive
   // **************************************************************************
   for (UINT i=0; i < uSubFormats; i++)
   {
      IFS(piLeadBitmapEncoder->GetSubFormatFlags(guidPixelFormat, i, &uFlags));
      if (uFlags & WICLeadFlagProgressive)
         nIndexProgressive = i;
   }

   // **************************************************************************
   // If we found a subformat that supports WICLeadFlagProgressive,
   // * print the the friendly name for the subformat
   // * get the progressive options
   // * print the friendly name for the progressive option
   // **************************************************************************
   UINT uProgressiveOptions = 0;
   INT *pProgressiveOptions = NULL;
   if (nIndexProgressive >= 0)
   {
      csMsg = csMsg + L"LEAD Jpeg Encoder sub-format: " + MyGetSubFormatFriendlyName(piLeadBitmapEncoder, guidPixelFormat, nIndexProgressive) + L"\n";
      IFS(piLeadBitmapEncoder->GetProgressiveOptions(guidPixelFormat, nIndexProgressive, 0, NULL, &uProgressiveOptions));
      if (SUCCEEDED(hr))
      {
         pProgressiveOptions = new INT[uProgressiveOptions];
         if (pProgressiveOptions)
         {
            csMsg = csMsg + L"ProgressiveOptions\n";
            IFS(piLeadBitmapEncoder->GetProgressiveOptions(guidPixelFormat, nIndexProgressive, uProgressiveOptions, pProgressiveOptions, &uProgressiveOptions));
            for (UINT i=0; i < uProgressiveOptions; i++)
            {
               csMsg = csMsg + MyGetProgressiveOptionsFriendlyName(piLeadBitmapEncoder, pProgressiveOptions[i]) + L"\n";
            }
         }  
      }
   }
   // Cleanup
   RELEASE_INTERFACE(piLeadBitmapEncoder);
   RELEASE_INTERFACE(piBitmapEncoder);
   RELEASE_INTERFACE(piImagingFactory);
   DELETE_POINTER(pProgressiveOptions);
   DELETE_POINTER(pSubFormats);

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