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

Gets a list of the valid predefined quality factors for a LEAD Bitmap encoder.

Syntax

 
HRESULT GetQualityFactorPredefined(      
    WICPixelFormatGUID guidPixelFormat,
    UINT uSubFormatIndex,
    UINT cbSizePredefinedQualityFactors,
    INT *pPredefinedQualityFactors,
    UINT *pcPredefinedQualityFactors
);

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.
cbSizePredefinedQualityFactors
[in] The size of the pPredefinedQualityFactors buffer.
pPredefinedQualityFactors
[in,out] A pointer that receives a list of predefined quality factors supported by the encoder.
pcPredefinedQualityFactors
[in,out] A pointer that receives the number of predefined quality factors the encoder supports.

Return Values

Returns S_OK if successful, or an error value otherwise.

Remarks

Use this method to get a list of the valid predefined quality factors for a LEAD Bitmap Encoder sub-format index. First, call GetSubFormats to get an array of valid sub-formats for the particular LEAD bitmap encoder.  When calling the GetQualityFactorPredefined method, pass the index of the sub-format array for the uSubFormatIndex argument.

Call GetQualityFactorPredefined once to get the number of supported predefined quality factors. Allocate the appropriately sized array.  Then call GetQualityFactorPredefined again, passing the allocated array as an argument. The example illustrates this technique.

LEAD Bitmap Encoders that have a QualityFactor property bag item use this number to specify the degree of loss in the compression process for lossy formats.  In addition to the typical values of 0 through 255 for quality factor, some LEAD Bitmap Encoders support other values know as Predefined Quality Factors.  Currently, the CLSID_WICLeadCmpEncoder and CLSID_WICLeadAbcEncoder LEAD Bitmap Encoders support a predefined quality factor.

For more information, see QualityFactor, WICLeadAbcQualityFactorPredefined, and WICLeadCmpQualityFactorPredefined.

See Also

Example

// ******************************************************************************************************************
// This example lists the predefined quality factors for one of the LEAD Cmp Encoder (subformat,guidPixelFormat) pairs
// that supports predefined quality factors
// 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 the 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;
}
CString MyGetQualityFactorPredefinedFriendlyName(IWICLeadBitmapEncoder *piLeadBitmapEncoder, INT nQualityFactor)
{
   CString csRet;
   HRESULT hr = S_OK;
   UINT uActual = 0;
   WCHAR *pwzFriendlyName = NULL; 

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

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

   // Create a LEAD TIFF 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, get the sub formats for the LEAD Jpeg Encoder with 24 bits per pixel
   // **************************************************************************
   // 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));
      }
   }

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

   // **************************************************************************
   // If we found a subformat that supports WICLeadFlagCmpQualityFactorPredefined,
   // * print the the friendly name for the subformat
   // * get the progressive options
   // * print the friendly name for the progressive options
   // **************************************************************************
   UINT uPredefinedQualityFactors = 0;
   INT *pPredefinedQualityFactors = NULL;
   if (nIndex >= 0)
   {
      csMsg = csMsg + L"LEAD Cmp Encoder sub-format: " + MyGetSubFormatFriendlyName(piLeadBitmapEncoder, guidPixelFormat, nIndex) + L"\n\n";
      IFS(piLeadBitmapEncoder->GetQualityFactorPredefined(guidPixelFormat, nIndex, 0, NULL, &uPredefinedQualityFactors));
      if (SUCCEEDED(hr))
      {
         pPredefinedQualityFactors = new INT[uPredefinedQualityFactors];
         if (pPredefinedQualityFactors)
         {
            csMsg = csMsg + L"QualityFactorPredefined\n";
            IFS(piLeadBitmapEncoder->GetQualityFactorPredefined(guidPixelFormat, nIndex, uPredefinedQualityFactors, pPredefinedQualityFactors, &uPredefinedQualityFactors));
            for (UINT i=0; i < uPredefinedQualityFactors; i++)
            {
               csMsg = csMsg + MyGetQualityFactorPredefinedFriendlyName(piLeadBitmapEncoder, pPredefinedQualityFactors[i]) + L"\n";
            }
         }  
      }
   }
   RELEASE_INTERFACE(piLeadBitmapEncoder);
   RELEASE_INTERFACE(piBitmapEncoder);
   RELEASE_INTERFACE(piImagingFactory);
   DELETE_POINTER(pPredefinedQualityFactors);

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