Sdílet prostřednictvím

Implementace IWICBitmapEncoder

  • Článek

IWICBitmapEncoder

Toto rozhraní je protějškem IWICBitmapDecoder rozhraní a je výchozím bodem pro kódování souboru obrázku. Stejně jako IWICBitmapDecoder slouží k načítání vlastností na úrovni kontejneru a jednotlivých rámců z kontejneru imagí, IWICBitmapEncoder slouží k nastavení vlastností na úrovni kontejneru a serializaci jednotlivých snímků imagí do kontejneru. Toto rozhraní implementujete ve třídě kodéru na úrovni kontejneru.

interface IWICBitmapEncoder : public IUnknown
{
   // Required methods
   HRESULT Initialize ( IStream *pIStream,
              WICBitmapEncoderCacheOption cacheOption );
   HRESULT GetContainerFormat ( GUID *pguidContainerFormat );
   HRESULT GetEncoderInfo ( IWICBitmapEncoderInfo **pIEncoderInfo );
   HRESULT CreateNewFrame ( IWICBitmapFrameEncode **ppIFrameEncode,
              IPropertyBag2 **ppIEncoderOptions );
   HRESULT Commit ( void );

   // Optional methods
   HRESULT SetPreview ( IWICBitmapSource *pIPreview );
   HRESULT SetThumbnail ( IWICBitmapSource *pIThumbnail );
   HRESULT SetColorContexts ( UINT cCount,
              IWICColorContext **ppIColorContext );
   HRESULT GetMetadataQueryWriter ( IWICMetadataQueryWriter 
              **ppIMetadataQueryWriter );
   HRESULT SetPalette ( IWICPalette *pIPalette);
};

Jak je popsáno v Implementace IWICBitmapDecoder, některé formáty obrázků mají globální miniatury, barevné kontexty nebo metadata, zatímco mnoho formátů obrázků je poskytuje pouze pro jednotlivé snímky. Proto jsou metody pro nastavení volitelné pro IWICBitmapEncoder, ale jsou vyžadovány v IWICBitmapFrameEncode. Probereme metody, které jsou volitelné v IWICBitmapEncoder v části o IWICBitmapFrameEncode, kde se nejčastěji implementují.

Pokud nepodporujete globální miniatury, vraťte WINCODEC_ERR_CODECNOTHUMBNAIL z metody SetThumbnail na IWICBitmapEncoder. Pokud paletu na úrovni kontejneru nepodporujete nebo pokud obrázek, který kódujete, nemá indexovaný formát, vraťte WINCODEC_ERR_PALETTEUNAVAILABLE z metody SetPalette. Pro jakékoli jiné metody, které nejsou podporovány, vraťte WINCODEC_ERR_UNSUPPORTEDOPERATION.

Inicializovat

Initialize je první metoda vyvolaná na IWICBitmapEncoder po vytvoření instance. Stream obrázku se předá kodéru a volající může volitelně zadat možnost mezipaměti. V případě dekodéru je stream jen pro čtení, ale stream předaný kodéru je zapisovatelný datový proud, do kterého kodér serializuje všechna data a metadata obrázku. Možnosti mezipaměti v kodéru se také liší.

enum WICBitmapEncoderCacheOption
{
   WICBitmapEncoderCacheInMemory,
   WICBitmapEncoderCacheTempFile,
   WICBitmapEncoderNoCache
}

Aplikace může požádat kodér, aby ukládal data obrázků do mezipaměti v paměti, v dočasném souboru, nebo aby zapsal data přímo na disk bez ukládání do mezipaměti. Když se zobrazí výzva k uložení dat do mezipaměti v dočasném souboru, kodér by měl vytvořit dočasný soubor na disku a zapisovat přímo do souboru bez ukládání do mezipaměti v paměti. Když volající vybere možnost bez mezipaměti, musí být každý snímek zaznamenán v přesném pořadí před vytvořením dalšího snímku.

GetContainerFormat

GetContainerFormat je implementován stejným způsobem jako metoda GetContainerFormat v části Implementace IWICBitmapDecoder.

GetEncoderInfo

GetEncoderInfo vrátí objekt IWICBitmapEncoderInfo. Pokud chcete získat objekt IWICBitmapEncoderInfo, stačí předat identifikátor GUID kodéru do metody CreateComponentInfo na IWICImagingFactorya poté na něm požádat o rozhraní IWICBitmapEncoderInfo.

Podívejte se na příklad v Implementace IWICBitmapDecoder v části GetDecoderInfo.

CreateNewFrame

CreateNewFrame je kodérovým protějškem GetFrame u IWICBitmapDecoder. Tato metoda vrátí IWICBitmapFrameEncode objektu, což je objekt, který ve skutečnosti serializuje data obrázku pro konkrétní rámec v rámci kontejneru.

Jednou z výhod technologie Windows Imaging Component (WIC) je, že poskytuje vrstvu abstrakce pro aplikace, které jim umožňují pracovat se všemi formáty obrázků stejným způsobem. Ne všechny formáty obrázků jsou ale úplně stejné. Některé formáty obrázků mají možnosti, které jiné nemají. Aby aplikace mohly využívat tyto jedinečné funkce, je nutné poskytnout způsob, jak je kodek zveřejnit. Jedná se o účel možností kodéru. Pokud váš kodek podporuje jakékoli možnosti kodéru, měli byste vytvořit IPropertyBag2 objekt, který zveřejňuje možnosti kodéru, které podporujete, a vrátit ho v ppIEncoderOptions parametru této metody. Volající pak může pomocí tohoto objektu IPropertyBag2 určit, jaké možnosti kodéru váš kodek podporuje. Pokud volající chce zadat hodnoty pro některou z podporovaných možností kodéru, přiřadí hodnotu k příslušné vlastnosti v objektu IPropertyBag2 a předá ji nově vytvořenému objektu IWICBitmapFrameEncode v její metodě Initialize.

Pokud chcete vytvořit instanci objektu IPropertyBag2, musíte nejprve vytvořit strukturu PROPBAG2, která určuje každou možnost kodéru, kterou kodér podporuje, a jeho datový typ pro každou vlastnost. Pak musíte implementovat IPropertyBag2 objekt, který vynucuje rozsahy hodnot pro každou vlastnost při zápisu a odsouhlasí všechny konfliktní nebo překrývající se hodnoty. U jednoduchých sad nekonfliktních možností kodéru můžete vyvolat CreateEncoderPropertyBag metoda, která vytvoří jednoduchý objekt IPropertyBag2 pomocí vlastností, které zadáte ve struktuře PROPBAG2. Stále musíte vynucovat rozsahy hodnot. Pro pokročilejší možnosti kodéru nebo pokud potřebujete odsouhlasit konfliktní hodnoty, měli byste napsat vlastní implementaci IPropertyBag2.

UINT cuiPropertyCount = 0;
IPropertyBag2* pPropertyBag = NULL;
PROPBAG2* pPropBagOptions;
HRESULT hr;

// Insert code here to initialize piPropertyBag with the 
// supported options for your encoder, and to initialize 
// cuiPropertyCount to the number of encoder option properties
// you are exposing.
...

hr = pComponentFactory->CreateEncoderPropertyBag( 
   pPropBagOptions, cuiPropertyCount, &pPropertyBag);

WIC poskytuje malou sadu možností kanonického kodéru, které používají některé běžné formáty obrázků. Všechny možnosti kanonického kodéru jsou volitelné a kodeky nejsou nutné k jejich podpoře. Důvodem, proč jsou kanonické možnosti, je, že mnoho aplikací zveřejňuje uživatelské rozhraní pro uživatele, aby tyto možnosti určili při ukládání souboru obrázku ve formátu, který je podporuje. Poskytnutí kanonického způsobu, jak tyto možnosti určit, usnadňuje aplikacím jejich komunikaci s kodéry konzistentním způsobem. Možnosti kanonického kodéru jsou uvedeny v následující tabulce.

Možnost kodéru VARTYPE Rozsah hodnot
Bezeztrátový VT_BOOL Pravda nebo nepravda
ImageQuality VT_R4 0.0-1.0
KvalitaKomprese VT_R4 0.0-1.0
BitmapTransform VT_UI1 Možnosti Transformace Bitové Mapy WIC

 

Pokud váš kodek podporuje bezeztrátové kódování, měli byste zveřejnit možnost kodéru bezeztrátového kódování jako způsob, jak aplikace požádat o bezeztrátové kódování obrázku. Pokud volající nastaví tuto vlastnost na True, měli byste ignorovat možnost ImageQuality a zakódovat obrázek bezeztrát.

Možnost ImageQuality umožňuje aplikaci určit stupeň přesnosti, se kterou se má obrázek kódovat. Tato možnost umožňuje uživateli nastavit kompromis mezi kvalitou obrázku a rychlostí a/nebo velikostí souboru. JPEG je příkladem formátu obrázku, který podporuje tento kompromis. Hodnota 0,0 označuje, že věrnost je nízká důležitost a kodér by měl používat svůj nejvíce ztrátový algoritmus. Hodnota 1,0 označuje, že věrnost je nejdůležitější a kodér by měl zachovat nejvyšší možnou věrnost. (V závislosti na vašem kodeku to může být synonymum bezeztrátové možnosti. Pokud však váš kodek podporuje bezeztrátové kódování a pokud je možnost Bezeztrátová nastavená na Hodnotu True, měla by být možnost ImageQuality ignorována.)

Možnost CompressionQuality umožňuje aplikaci určit efektivitu komprese, která se má použít při kódování obrázku. Velmi efektivní algoritmus může vytvořit menší soubor obrázku se stejnou kvalitou jako méně efektivní komprimační algoritmus, ale kódování může trvat déle. Tato možnost umožňuje uživateli určit kompromis mezi velikostí souboru a rychlostí kódování a současně zachovat stejnou úroveň kvality. TIFF je příkladem formátu obrázku, který podporuje tento kompromis. (Všimněte si, že formát, jako je JPEG, podporuje různé úrovně komprese, ale vyšší míra komprese má za následek nižší kvalitu obrázku. Formát obrázku JPEG by proto místo možnosti CompressionQuality zpřístupnil možnost ImageQuality.) Hodnota 0,0 pro tuto možnost značí, že byste měli obrázek co nejrychleji zkomprimovat, aniž byste snížili přesnost, na úkor větší velikosti souboru. Hodnota 1,0 označuje, že byste měli vytvořit nejmenší možnou velikost souboru (na stejné úrovni kvality), bez ohledu na to, jak dlouho může trvat jeho kódování. Kodek může podporovat možnost ImageQuality i možnost CompressionQuality, kde možnost ImageQuality určuje přijatelný stupeň ztráty a možnost CompressionQuality nabízí kompromis velikosti a rychlosti na zadané úrovni kvality.

Možnost BitmapTransform poskytuje volajícímu způsob, jak určit úhel otočení nebo svislou nebo vodorovnou orientaci překlopení při kódování. WICBitmapTransformOptions je výčet, který určuje požadovanou transformaci a stejný výčet se používá při dekódování prostřednictvím rozhraní IWICBitmapSourceTransform.

Mějte na paměti, že kodéry nejsou omezeny na možnosti kanonického kodéru. Účelem možností kodéru je umožnit kodérům zpřístupnit jejich možnosti a neexistuje žádné omezení pro typy funkcí, které můžete zveřejnit. Ujistěte se, že jsou možnosti kodéru dobře zdokumentované. I když aplikace může pomocí tašky vlastností, kterou z této metody vrátíte, zjistit názvy, typy a rozsahy hodnot pro možnosti, které podporujete, jediný způsob, jak zjistit jejich významy nebo jak je vystavit v uživatelském rozhraní, je z vaší dokumentace.

Zavázat se

Commit je metoda, kterou voláte po serializaci všech dat a metadat obrázku do datového proudu. Tuto metodu byste měli použít k serializaci dat náhledu obrázku do datového proudu a všech globálních miniatur, metadat, palety nebo jiných položek, pokud je to možné. Tato metoda by neměla zavřít datový proud souboru, protože aplikace, která otevřela datový proud, je očekáváno, že jej zavře.

Část o metodě IWICBitmapFrameEncode:Commit obsahuje podrobnosti o tom, jak IWICBitmapEncoderCacheOptions ovlivňují chování této metody.

SetPreview

SetPreview slouží k vytvoření náhledu obrázku. I když není nezbytně nutné, aby každý obrázek měl náhled, důrazně se doporučuje. Moderní digitální fotoaparáty a skenery generují obrázky s velmi vysokým rozlišením, které bývají velmi velké, a v důsledku toho vyžadují značnou dobu zpracování k dekódování. Obrázky z nové generace fotoaparátů budou ještě větší. Je vhodné poskytnout menší verzi obrázku s nižším rozlišením, obvykle ve formátu JPEG, která se dá rychle dekódovat a zobrazit "okamžitě", když si ji uživatel vyžádá. Aplikace může před požadavkem na dekódování skutečného obrázku požádat o náhled, aby uživatelům poskytla lepší prostředí a zobrazila jim reprezentaci obrázku ve velikosti obrazovky, zatímco čekají na dekódování skutečného obrázku. I když kodeky by měly poskytovat náhledy, kodeky, které nepodporují IWICBitmapSourceTransform by to určitě měly udělat.

Pokud zadáte náhled JPEG, nemusíte psát kodér JPEG, který ho zakóduje. Měli byste delegovat na kodér JPEG, který je dodáván s platformou WIC pro kódování náhledů i miniatur.

Referenční

IWICBitmapEncoder

IWICBitmapFrameEncode

koncepční

Rozhraní kodérů

implementace IWICBitmapCodecProgressNotification (Encoder)

Jak napsat WIC-Enabled kodek

Přehled komponent Windows Imaging