IWICLeadBitmapEncoder::GetQualityFactorRange Method

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

Syntax


HRESULT GetQualityFactorRange( WICPixelFormatGUID guidPixelFormat, UINT uSubFormatIndex, BOOL pbQualityFactorRangeSupported, INT pnMinQualityFactor, INT *pnMaxQualityFactor );

Parameters


guidPixelFormat [in] The pixel format GUID that the encoder is using WICLeadEnumName. uSubFormatIndex [in] The index of the sub-format array returned by the GetSubFormats method. pbQualityFactorRangeSupported [out] Pointer that receives TRUE if a quality factor range is supported; otherwise, FALSE. pnMinQualityFactor [out] Pointer that receives the minimum quality factor value supported. pnMaxQualityFactor [out] Pointer that receives the maximum quality factor value supported.

guidPixelFormat

[in] The pixel format GUID that the encoder is using WICLeadEnumName.

uSubFormatIndex

[in] The index of the sub-format array returned by the GetSubFormats method.

pbQualityFactorRangeSupported

[out] Pointer that receives TRUE if a quality factor range is supported; otherwise, FALSE.

pnMinQualityFactor

[out] Pointer that receives the minimum quality factor value supported.

pnMaxQualityFactor

[out] Pointer that receives the maximum quality factor value supported.

Return Values

Returns S_OK if successful, or an error value otherwise.

Remarks

Use this method to get the quality factor range that is valid 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 GetQualityFactorRange method, pass the index of the sub-format array for the uSubFormatIndex argument.

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. Typical values of the quality factor range are 0 through 255, but this varies depending on the LEAD Bitmap Encoder. For a list of LEAD Bitmap Encoders that use a quality factor, and a list of the corresponding quality factor ranges, see Quality Factor Property Bag Item.

Example

            // ******************************************************************************************************************
            // This example lists the quality factor range for one of the LEAD Png Encoder (subformat,guidPixelFormat) pairs
            // that support predefined quality factors
            // See 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;
            }
            
            HRESULT IWICLeadBitmapEncoder_GetQualityFactorRange(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_ContainerFormatLeadPng;
               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 Png Encoder with 24 bits per pixel
               // **************************************************************************
               // first call is 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 is to get the subformats
                     IFS(piLeadBitmapEncoder->GetSubFormats(guidPixelFormat, uSubFormats, pSubFormats, &uSubFormats));
                  }
               }
            
               // **************************************************************************
               // Next, get the sub format flags for the sub-formats.  
               // Continue this until we find a subformat that supports WICLeadFlagQualityFactor
               // **************************************************************************
               INT nIndex = -1;
               WICLeadSubFormatFlags uFlags = WICLeadFlagNone;
               for (UINT i=0; i < uSubFormats; i++)
               {
                  IFS(piLeadBitmapEncoder->GetSubFormatFlags(guidPixelFormat, i, &uFlags));
                  if (uFlags & WICLeadFlagQualityFactor)
                     nIndex = i;
               }
            
               // **************************************************************************
               // If we found a subformat that supports WICLeadFlagQualityFactor,
               // * print the the friendly name for the subformat
               // * print the quality factor range
               // **************************************************************************
                BOOL bQualityFactorRangeSupported = FALSE;
                INT nMinQualityFactor = 0;
                INT nMaxQualityFactor = 0;
            
               if (nIndex >= 0)
               {
                  csMsg = csMsg + L"LEAD Png Encoder sub-format: " + MyGetSubFormatFriendlyName(piLeadBitmapEncoder, guidPixelFormat, nIndex) + L"\n\n";
                  IFS(piLeadBitmapEncoder->GetQualityFactorRange(guidPixelFormat, nIndex, &bQualityFactorRangeSupported, &nMinQualityFactor, &nMaxQualityFactor));  
                  if (SUCCEEDED(hr) && bQualityFactorRangeSupported)
                  {
                     CString csTemp;
                     csTemp.Format(L"Quality Factor Range:  %d to %d\n", nMinQualityFactor, nMaxQualityFactor);
                        csMsg = csMsg + csTemp;
                  }
               }
               RELEASE_INTERFACE(piLeadBitmapEncoder);
               RELEASE_INTERFACE(piBitmapEncoder);
               RELEASE_INTERFACE(piImagingFactory);
            
               MessageBox(hWnd, csMsg, csExampleName, MB_OK);
               return hr;
            }

IWICLeadBitmapEncoder::GetQualityFactorRange Method

Syntax

Parameters

Return Values

Remarks

Example

See Also

Reference