IWICLeadBitmapEncoder::GetQualityFactorPredefined Method

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

Syntax


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

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.

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

References

LEAD WIC-Enabled Codecs Overview
Registering a LEAD WIC-Enabled Codec
WICLeadEnumName
QualityFactor property bag
WICLeadSubFormatFlags
IWICLeadBitmapEncoder::GetQualityFactorRange
IWICLeadBitmapEncode::GetQualityFactorPredefinedFriendlyName
WICLeadAbcQualityFactorPredefined
WICLeadCmpQualityFactorPredefined

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.

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.

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