IWICFormatConverter：：Initialize 方法 (wincodec.h)

初始化格式转换器。

语法

HRESULT Initialize(
  [in] IWICBitmapSource      *pISource,
  [in] REFWICPixelFormatGUID dstFormat,
  [in] WICBitmapDitherType   dither,
  [in] IWICPalette           *pIPalette,
  [in] double                alphaThresholdPercent,
  [in] WICBitmapPaletteType  paletteTranslate
);

参数

[in] pISource

类型： IWICBitmapSource*

要转换的输入位图

[in] dstFormat

类型： REFWICPixelFormatGUID

目标像素格式 GUID。

[in] dither

类型： WICBitmapDitherType

用于转换的 WICBitmapDitherType 。

[in] pIPalette

类型： IWICPalette*

用于转换的调色板。

[in] alphaThresholdPercent

类型： double

用于转换的 alpha 阈值。

[in] paletteTranslate

类型： WICBitmapPaletteType

用于转换的调色板转换类型。

返回值

类型： HRESULT

如果该方法成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。

注解

如果没有预定义的调色板，必须先创建一个。 使用 InitializeFromBitmap 创建调色板对象，然后将其与其他参数一起传入。

dither、 pIPalette、 alphaThresholdPercent 和 paletteTranslate 用于在转换为减小位深度格式时减少颜色损失。 对于不需要这些设置的转换，应使用以下参数值： dither 设置为 WICBitmapDitherTypeNone， pIPalette 设置为 NULL， alphaThresholdPercent 设置为 0.0f， paletteTranslate 设置为 WICBitmapPaletteTypeCustom。

使用有序抖动时涉及的基本算法需要固定调色板（在 WICBitmapPaletteType 枚举中按特定顺序找到）。

通常，为输出提供的实际调色板可能具有不同的顺序或实际颜色的一些轻微变化。 使用 Microsoft Windows 调色板时就是这种情况，该调色板在 Windows.To 提供的版本之间略有差异，因此会向格式转换器提供调色板和调色板转换。 pIPalette 是要使用的实际目标调色板，调色板Translate 是固定的调色板。 转换完成后，使用最接近的颜色匹配算法将颜色从固定调色板映射到 pIPalette 中的实际颜色。

如果 pIPalette 中的颜色与 paletteTranslate 中的颜色不匹配，则映射可能会产生不良结果。

WICBitmapDitherTypeOrdered4x4 可用于从 8 位格式到 5 位或 6 位格式的格式转换，因为无法准确转换颜色数据。

WICBitmapDitherTypeErrorDiffusion 选择误差扩散算法，可与任何调色板一起使用。 如果提供了任意调色板，则应将 WICBitmapPaletteCustom 作为 paletteTranslate 传入。 与有序抖动算法相比，误差扩散通常提供优越的结果，尤其是在与 IWICPalette 上优化的调色板生成功能结合使用时。

将具有 alpha 通道的位图（例如可移植网络图形 (PNG) ）转换为 8bpp 时，通常忽略 alpha 通道。 原始位图中透明的任何像素在最终输出中显示为黑色，因为透明和黑色的像素值在各自的格式中均为零。

某些 8bpp 内容可以包含 alpha 颜色;例如，图形交换格式 (GIF) 格式允许将单个调色板条目用作透明颜色。 对于此类内容， alphaThresholdPercent 指定应映射到透明颜色的透明度百分比。 由于 alpha 值与像素的不透明度 (透明度) 成正比， 因此 alphaThresholdPercent 指示映射到完全透明颜色的不透明度级别。

例如，9.8% 表示 alpha 值小于 25 的任何像素都将映射到透明颜色。 值 100% 将所有不完全不透明的像素映射到透明颜色。 请注意，调色板应提供透明颜色。 否则，“透明”颜色将是最接近零的颜色-通常是黑色。

示例

以下示例将图像帧转换为没有抖变或 alpha 阈值的 32bppPBGRA 格式。 Direct2D 要求位图源采用 32bppPBGRA 格式进行呈现。 有关演示如何使用 IWICFormatConverter 的完整示例，请参阅 使用 Direct2D 的 WIC 图像查看器示例。

HRESULT hr = S_OK;

IWICBitmapDecoder *pIDecoder = NULL;
IWICBitmapFrameDecode *pIDecoderFrame  = NULL;
IWICFormatConverter *pIFormatConverter = NULL;

// Create the decoder.
hr = m_pIWICFactory->CreateDecoderFromFilename(
   L"turtle.jpg",                  // Image to be decoded
   NULL,                           // Do not prefer a particular vendor
   GENERIC_READ,                   // Desired read access to the file
   WICDecodeMetadataCacheOnDemand, // Cache metadata when needed
   &pIDecoder                      // Pointer to the decoder
   );

// Retrieve the first bitmap frame.
if (SUCCEEDED(hr))
{
   hr = pIDecoder->GetFrame(0, &pIDecoderFrame);
}


// Create the flip/rotator.
if (SUCCEEDED(hr))
{
   hr = m_pIWICFactory->CreateFormatConverter(&pIFormatConverter);
}

// Initialize the format converter.
if (SUCCEEDED(hr))
{
   hr = pIFormatConverter->Initialize(
       pIDecoderFrame,                  // Input source to convert
       GUID_WICPixelFormat32bppPBGRA,   // Destination pixel format
       WICBitmapDitherTypeNone,         // Specified dither pattern
       NULL,                            // Specify a particular palette 
       0.f,                             // Alpha threshold
       WICBitmapPaletteTypeCustom       // Palette translation type
       );
}
//Create render target and D2D bitmap from IWICBitmapSource
if (SUCCEEDED(hr))
{
   hr = CreateDeviceResources(hWnd);
}

if (SUCCEEDED(hr))
{
   // Need to release the previous D2DBitmap if there is one
   SafeRelease(&m_pD2DBitmap);
   hr = m_pRT->CreateBitmapFromWicBitmap(pIFormatConverter, NULL, &m_pD2DBitmap);
}

SafeRelease(&pIFormatConverter);
SafeRelease(&pIDecoderFrame);
SafeRelease(&pIDecoder);

要求

最低受支持的客户端	Windows XP SP2，Windows Vista [桌面应用 |UWP 应用]
最低受支持的服务器	Windows Server 2008 [桌面应用 | UWP 应用]
目标平台	Windows
标头	wincodec.h
Library	Windowscodecs.lib
DLL	Windowscodecs.dll