IWICLeadBitmapEncoder::GetProgressiveOptions Method

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 usingWICLeadEnumName.

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.

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

IWICLeadBitmapEncoder::GetProgressiveOptions Method

Syntax

Parameters

Return Values

Remarks

Example

See Also

Reference