Az IWICBitmapEncoder implementálása
IWICBitmapEncoder
Ez a felület a IWICBitmapDecoder felület megfelelője, és a képfájl kódolásának kiindulópontja. Ahogyan IWICBitmapDecoder tárolószintű tulajdonságok és egyéni keretek lekérésére szolgál a lemezképtárolóból, IWICBitmapEncoder tárolószintű tulajdonságok beállítására és az egyes képkeretek tárolóba való szerializálására szolgál. Ezt a felületet a tárolószintű kódoló osztályban implementálhatja.
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);
};
Ahogyan az Implementing IWICBitmapDecodercímű cikk ismerteti, egyes képformátumok globális miniatűrökkel, színkörnyezetekkel vagy metaadatokkal rendelkeznek, míg számos képformátum csak keretenként biztosítja ezeket. Ezért ezek beállításának módszerei nem kötelezőek IWICBitmapEncoder, de kötelezőek IWICBitmapFrameEncode. A IWICBitmapEncoder nem kötelező metódusokat a IWICBitmapFrameEncodeszakaszában ismertetjük, ahol a leggyakrabban implementálva vannak.
Ha nem támogatja a globális miniatűröket, a SetThumbnail metódusnak vissza kell adnia a WINCODEC_ERR_CODECNOTHUMBNAIL hibakódot IWICBitmapEncoderesetén. Ha nem támogatja a tárolószintű palettát, vagy ha a kódoláskor használt kép nem rendelkezik indexelt formátummal, a SetPalette metódusból adja vissza a WINCODEC_ERR_PALETTEUNAVAILABLE. Egyéb nem támogatott metódusok esetén adja vissza a WINCODEC_ERR_UNSUPPORTEDOPERATION.
Inicializál
inicializálása az első metódus, amelyet egy IWICBitmapEncoder példányosítása után hívnak meg. A rendszer képstreamet ad át a kódolónak, és a hívó opcionálisan megadhat egy gyorsítótár-beállítást. A dekóder esetében a stream írásvédett, de a kódolónak átadott stream egy írható stream, amelybe a kódoló szerializálja az összes képadatot és metaadatot. A kódoló gyorsítótár-beállításai is eltérőek.
enum WICBitmapEncoderCacheOption
{
WICBitmapEncoderCacheInMemory,
WICBitmapEncoderCacheTempFile,
WICBitmapEncoderNoCache
}
Az alkalmazásnak lehetősége van arra, hogy kérje a kódolót, hogy gyorsítótárazza a képadatokat a memóriában, gyorsítótárazza őket egy ideiglenes fájlban, vagy hogy közvetlenül a lemezfájlba írja őket gyorsítótárazás nélkül. Amikor az adatok ideiglenes fájlban való gyorsítótárazására kérik, a kódolónak létre kell hoznia egy ideiglenes fájlt a lemezen, és közvetlenül a fájlba kell írnia anélkül, hogy gyorsítótáraznia kellene a memóriát. Amikor a hívó kiválasztja a gyorsítótár nélküli beállítást, minden keretet le kell véglegesíteni a következő keret létrehozása előtt.
GetContainerFormat (Kontejnerformátum lekérése)
GetContainerFormat ugyanúgy implementáljuk, mint a GetContainerFormat metódust Implementing IWICBitmapDecoder.
KódolóInformációLekérése
GetEncoderInfo egy IWICBitmapEncoderInfo objektumot ad vissza. Az IWICBitmapEncoderInfo objektum lekéréséhez egyszerűen adja át a kódoló GUID azonosítóját a CreateComponentInfo metódusnak IWICImagingFactory, majd kérje meg a IWICBitmapEncoderInfo felületét.
Lásd a példát az IWICBitmapDecoder megvalósításában a GetDecoderInfokeretein belül.
CreateNewFrame
CreateNewFrame az GetFrame kódolási megfelelője az IWICBitmapDecoderesetén. Ez a metódus egy IWICBitmapFrameEncode objektumot ad vissza, amely valójában szerializálja a tárolóban lévő adott keret képadatait.
A Windows Képalkotó összetevő (WIC) egyik előnye, hogy absztrakciós réteget biztosít az alkalmazások számára, amelyek lehetővé teszik számukra, hogy az összes képformátumot ugyanúgy használják. Azonban nem minden képformátum azonos. Egyes képformátumok olyan képességekkel rendelkeznek, amelyekkel mások nem rendelkeznek. Ahhoz, hogy az alkalmazások kihasználhassák ezeket az egyedi képességeket, módot kell biztosítani a kodek számára, hogy elérhetővé tegyék őket. Ez a kódoló beállításainak célja. Ha a kodek bármilyen kódolóbeállítást támogat, hozzon létre egy IPropertyBag2 objektumot, amely elérhetővé teszi a támogatott kódolóbeállításokat, és adja vissza a metódus ppIEncoderOptions paraméterében. A hívó ezután ezt az IPropertyBag2 objektumot használhatja annak meghatározásához, hogy a kódoló milyen kódolóbeállításokat támogat. Ha a hívó bármilyen támogatott kódolóbeállításhoz meg szeretne adni értékeket, hozzárendeli az értéket az IPropertyBag2 objektum megfelelő tulajdonságához, és átadja azt az újonnan létrehozott IWICBitmapFrameEncode objektumnak az Inicializálási metódusában.
Egy IPropertyBag2 objektum példányosításához először létre kell hoznia egy PROPBAG2 szerkezetet, amely megadja a kódoló által támogatott kódoló-beállításokat és azok adattípusát az egyes tulajdonságokhoz. Ezután implementálnia kell egy IPropertyBag2 objektumot, amely az egyes tulajdonságok értéktartományait kényszeríti ki íráskor, és egyezteti az ütköző vagy átfedésben lévő értékeket. A nem ütköző kódolók egyszerű készleteihez meghívhatja a CreateEncoderPropertyBag metódust, amely létrehoz egy egyszerű IPropertyBag2 objektumot a PROPBAG2 szerkezetben megadott tulajdonságok használatával. Továbbra is kikényszerítenie kell az értékhatárokat. Ha fejlettebb kódolóbeállításokat szeretne, vagy ha ütköző értékeket szeretne összeegyeztetni, akkor saját IPropertyBag2-implementációt kell írnia.
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);
A WIC a gyakran használt képformátumok némelyike által használt canonical encoder-beállítások kis halmazát biztosítja. Az összes canonical encoder beállítás nem kötelező, és a kodekek nem szükségesek egyikük támogatásához sem. Az ok, amiért kanonikus lehetőségként biztosítják őket, az az, hogy sok alkalmazás a felhasználói felületen tesz elérhetővé lehetőségeket a felhasználók számára, hogy megadják ezeket a beállításokat, amikor olyan formátumban mentenek egy képfájlt, amely támogatja ezeket. Ezeknek a beállításoknak a megadásával az alkalmazások egyszerűen kommunikálhatnak a kódolókkal egységes módon. A kanonikus kódoló beállítások a következő táblázatban vannak felsorolva.
| Kódoló beállítás | VARTYPE | Értéktartomány |
|---|---|---|
| Veszteségmentes | VT_BOOL | Igaz/Hamis |
| ImageQuality | VT_R4 | 0.0-1.0 |
| Tömörítési minőség | VT_R4 | 0.0-1.0 |
| BitmapTransform | VT_UI1 | WICBitmapTransformOptions |
Ha a kodek támogatja a veszteségmentes kódolást, tegye közzé a Veszteségmentes kódoló lehetőséget, amely lehetővé teszi az alkalmazások számára, hogy a rendszerképek veszteségmentes kódolását kérjék. Ha egy hívó igaz értékre állítja ezt a tulajdonságot, figyelmen kívül kell hagynia az ImageQuality beállítást, és veszteségmentesen kell kódolnia a képet.
Az ImageQuality beállítás lehetővé teszi, hogy az alkalmazások megadják a kép kódolásának mértékét. Ez a beállítás lehetővé teszi, hogy a felhasználó kompromisszumot hozzon létre a képminőség és a sebesség és/vagy a fájlméret között. A JPEG egy példa egy képformátumra, amely támogatja ezt a kompromisszumot. A 0,0 érték azt jelzi, hogy a hűség alacsony fontosságú, és a kódolónak a legveszteségesebb algoritmust kell használnia. Az 1,0 érték azt jelzi, hogy a hűség a legfontosabb, és a kódolónak a lehető legmagasabb hűséget kell megőriznie. (A kodektől függően ez a Veszteségmentes beállítás szinonimája lehet. Ha azonban a kodek támogatja a veszteségmentes kódolást, és a Veszteségmentes beállítás értéke Igaz, akkor az ImageQuality beállítást figyelmen kívül kell hagyni.)
A CompressionQuality beállítás lehetővé teszi, hogy az alkalmazások megadják a kép kódolása során használandó tömörítés hatékonyságát. A nagyon hatékony algoritmusok kisebb képfájlokat hozhatnak létre, ugyanolyan minőségben, mint egy kevésbé hatékony tömörítési algoritmus, de a kódolás hosszabb időt vehet igénybe. Ez a beállítás lehetővé teszi, hogy a felhasználó kompromisszumot adjon meg a fájlméret és a kódolás sebessége között, miközben megőrzi ugyanazt a minőséget. A TIFF egy példa egy képformátumra, amely támogatja ezt a kompromisszumot. (Vegye figyelembe, hogy a JPEG formátumok különböző tömörítési szinteket támogatnak, de a nagyobb tömörítési sebesség alacsonyabb képminőséget eredményez. Ezért a JPEG-képformátum a CompressionQuality beállítás helyett az ImageQuality beállítást teszi elérhetővé.) Ehhez a beállításhoz a 0,0 érték azt jelzi, hogy a rendszerképet a lehető leggyorsabban, a hűség csökkentése nélkül, a nagyobb fájlméret rovására kell tömöríteni. Az 1.0-s érték azt jelzi, hogy a lehető legkisebb fájlméretet kell létrehoznia (azonos minőségi szinten), függetlenül attól, hogy mennyi ideig tarthat a kódolása. A kodekek támogathatják az ImageQuality és a CompressionQuality beállítást is, ahol az ImageQuality beállítás határozza meg a veszteség elfogadható mértékét, a CompressionQuality beállítás pedig a méret/sebesség kompromisszumot kínál a megadott minőségi szinten.
A BitmapTransform beállítással a hívó megadhatja a forgatási szöget, illetve a függőleges vagy vízszintes tükrözés tájolását kódoláskor. A kért átalakítás megadásához használt WICBitmapTransformOptions szám ugyanaz a szám, amelyet az átalakítás kérésekor használnak az IWICBitmapSourceTransform interfészen keresztüli dekódolás során.
Vegye figyelembe, hogy a kódolók nem korlátozódnak a canonical encoder beállításokra. A kódoló beállításainak célja, hogy a kódolók elérhetővé tegyék képességeiket, és nincs korlátozva az elérhető képességek típusaira. Ellenőrizze, hogy a kódoló beállításai megfelelően vannak-e dokumentálva. Annak ellenére, hogy egy alkalmazás használhatja az ebből a módszerből visszaadott tulajdonságcsomagot a támogatott beállítások neveinek, típusainak és értéktartományainak felderítéséhez, az egyetlen módja annak, hogy kiderítsék a jelentésüket, vagy hogy hogyan tegye közzé őket a felhasználói felületen, a dokumentációból származik.
Elkötelez
Commit az a módszer, amelyet a képadatok és metaadatok streambe való szerializálása után hív. Ezzel a módszerrel szerializálhatja az előnézeti képadatokat a streambe, és adott esetben a globális miniatűröket, metaadatokat, palettát vagy egyéb elemeket. Ez a módszer nem zárja be a fájlstreamet, mert a streamet megnyitó alkalmazás várhatóan bezárja azt.
Az IWICBitmapFrameEncode:Commit metódusról szóló szakasz részletesen ismerteti, hogy az IWICBitmapEncoderCacheOptions hogyan befolyásolja a metódus viselkedését.
Előnézet Beállítása
SetPreview a rendszerkép előnézetének létrehozásához használható. Bár nem feltétlenül szükséges, hogy minden kép rendelkezik előzetes verzióval, erősen ajánlott. A modern digitális fényképezőgépek és szkennerek nagyon nagy felbontású képeket hoznak létre, amelyek általában nagyon nagyok, ezért jelentős feldolgozási időt vesznek igénybe a dekódoláshoz. A kamerák következő generációjának képei még nagyobbak lesznek. Érdemes egy kép kisebb, kisebb felbontású verzióját biztosítani, általában JPEG formátumban, amely gyorsan dekódolható, és "azonnal" megjeleníthető, amikor egy felhasználó kéri. Az alkalmazások előzetes verziót kérhetnek, mielőtt a tényleges kép dekódolását kérték, hogy jobb élményt nyújtsanak a felhasználóknak, és megjeleníthetik a kép képernyőméretű ábrázolását, miközben arra várnak, hogy dekódolják a tényleges képet. Bár a kodekeknek előzetes verziókat kell biztosítaniuk, az IWICBitmapSourceTransformnem támogató kodekeknek feltétlenül ezt kell tenni.
Ha JPEG-előnézetet ad meg, nem kell JPEG-kódolót írnia a kódoláshoz. Ajánlott, hogy a JPEG kódolásra az előnézetek és a miniatűrök esetében használja a WIC platform által rendelkezésre bocsátott kódolót.
Kapcsolódó témakörök
-
referencia
-
fogalmi
-
IWICBitmapCodecProgressNotification (Encoder) implementálása