IWICFormatConverter::Initialize-Methode (wincodec.h)

Artikel
08/27/2023

Initialisiert den Formatkonverter.

Syntax

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

Parameter

[in] pISource

Typ: IWICBitmapSource*

Die zu konvertierende Eingabebitbitbit

[in] dstFormat

Typ: REFWICPixelFormatGUID

Die Zielpixelformat-GUID.

[in] dither

Typ: WICBitmapDitherType

Der wicBitmapDitherType, der für die Konvertierung verwendet wird.

[in] pIPalette

Typ: IWICPalette*

Die Palette, die für die Konvertierung verwendet werden soll.

[in] alphaThresholdPercent

Typ: double

Der Alphaschwellenwert, der für die Konvertierung verwendet werden soll.

[in] paletteTranslate

Typ: WICBitmapPaletteType

Der Für die Konvertierung zu verwendende Palettenübersetzungstyp.

Rückgabewert

Typ: HRESULT

Wenn diese Methode erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Wenn Sie nicht über eine vordefinierte Palette verfügen, müssen Sie zuerst eine erstellen. Verwenden Sie InitializeFromBitmap , um das Palettenobjekt zu erstellen, und übergeben Sie es dann zusammen mit Ihren anderen Parametern.

dither, pIPalette, alphaThresholdPercent und paletteTranslate werden verwendet, um Farbverluste bei der Konvertierung in ein Format mit geringerer Bittiefe zu minimieren. Für Konvertierungen, die diese Einstellungen nicht benötigen, sollten die folgenden Parameterwerte verwendet werden: dither auf WICBitmapDitherTypeNone, pIPalette auf NULL, alphaThresholdPercent auf 0,0f und paletteTranslate auf WICBitmapPaletteTypeCustom festgelegt.

Der grundlegende Algorithmus, der bei der Verwendung eines geordneten Dithers verwendet wird, erfordert eine feste Palette, die in der WICBitmapPaletteType-Enumeration in einer bestimmten Reihenfolge zu finden ist.

Häufig kann die tatsächliche Palette, die für die Ausgabe bereitgestellt wird, eine andere Reihenfolge oder eine geringfügige Variation der tatsächlichen Farben aufweisen. Dies ist der Fall, wenn Sie die Microsoft Windows-Palette verwenden, die geringfügige Unterschiede zwischen den Versionen von Windows.To dafür bietet, dass dem Formatkonverter eine Palette und eine Palettenübersetzung zugewiesen werden. Die pIPalette ist die tatsächliche Zielpalette, die verwendet werden soll, und die paletteTranslate ist eine feste Palette. Sobald die Konvertierung abgeschlossen ist, werden die Farben von der festen Palette den tatsächlichen Farben in pIPalette mithilfe eines Farbabgleichsalgorithmus am nächsten zugeordnet.

Wenn Farben in pIPalette nicht genau mit denen in paletteTranslate übereinstimmen, kann die Zuordnung zu unerwünschten Ergebnissen führen.

WICBitmapDitherTypeOrdered4x4x4 kann bei Formatkonvertierungen von 8-Bit-Formaten in 5- oder 6-Bit-Formate nützlich sein, da es keine Möglichkeit gibt, Farbdaten genau zu konvertieren.

WICBitmapDitherTypeErrorDiffusion wählt den Fehlerdiffusion-Algorithmus aus und kann mit jeder Palette verwendet werden. Wenn eine beliebige Palette bereitgestellt wird, sollte WICBitmapPaletteCustom als paletteTranslate übergeben werden. Fehlerdiffusion liefert häufig überlegene Ergebnisse im Vergleich zu den geordneten Ditheringalgorithmen, insbesondere in Kombination mit der optimierten Palettengenerierungsfunktion der IWICPalette.

Beim Konvertieren einer Bitmap mit einem Alphakanal, z. B. png (Portable Network Graphics), in 8bpp wird der Alphakanal normalerweise ignoriert. Alle Pixel, die in der ursprünglichen Bitmap transparent waren, werden in der endgültigen Ausgabe als schwarz angezeigt, da sowohl transparent als auch schwarz pixelige Werte von 0 (null) in den jeweiligen Formaten aufweisen.

Einige 8bpp-Inhalte können eine Alphafarbe enthalten; für instance ermöglicht das GIF-Format (Graphics Interchange Format) die Verwendung eines einzelnen Paletteneintrags als transparente Farbe. Für diesen Inhaltstyp gibt alphaThresholdPercent an, welcher Prozentsatz der Transparenz der transparenten Farbe zugeordnet werden soll. Da der Alphawert direkt proportional zur Deckkraft (nicht zur Transparenz) eines Pixels ist, gibt alphaThresholdPercent an, welcher Deckkraftgrad der vollständig transparenten Farbe zugeordnet ist.

Für instance bedeutet 9,8 %, dass jedes Pixel mit einem Alphawert von weniger als 25 der transparenten Farbe zugeordnet wird. Der Wert 100 % ordnet alle Pixel, die nicht vollständig undurchsichtig sind, der transparenten Farbe zu. Beachten Sie, dass die Palette eine transparente Farbe bereitstellen sollte. Wenn dies nicht der Fall ist, ist die Farbe "transparent" die am nächsten 0 (oft schwarz).

Beispiele

Im folgenden Beispiel wird ein Bildrahmen ohne Dithering- oder Alphaschwellenwert in ein 32bppPBGRA-Format konvertiert. Direct2D erfordert, dass Bitmapquellen das 32bppPBGRA-Format für das Rendern aufweisen. Ein vollständiges Beispiel zur Veranschaulichung der Verwendung von IWICFormatConverter finden Sie im WIC-Bildanzeigebeispiel mit Direct2D.

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

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP mit SP2, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	wincodec.h
Bibliothek	Windowscodecs.lib
DLL	Windowscodecs.dll