IWICBitmapEncoder implementeren
IWICBitmapEncoder
Deze interface is de tegenhanger van de IWICBitmapDecoder interface en is het startpunt voor het coderen van een afbeeldingsbestand. Net zoals IWICBitmapDecoder- wordt gebruikt voor het ophalen van eigenschappen op containerniveau en afzonderlijke afbeeldingsframes uit de afbeeldingscontainer, wordt IWICBitmapEncoder- gebruikt voor het instellen van eigenschappen op containerniveau en het serialiseren van afzonderlijke afbeeldingsframes in de container. U implementeert deze interface in de coderingsklasse op containerniveau.
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);
};
Zoals besproken in IWICBitmapDecoder implementeren, hebben sommige afbeeldingsindelingen globale miniaturen, kleurcontexten of metagegevens, terwijl veel afbeeldingsindelingen deze alleen per frame bieden. Daarom zijn de methoden voor het instellen van deze optioneel op IWICBitmapEncoder, maar zijn vereist voor IWICBitmapFrameEncode. We bespreken de methoden die optioneel zijn op IWICBitmapEncoder in de sectie over IWICBitmapFrameEncode, waar ze het meest worden geïmplementeerd.
Als u geen ondersteuning biedt voor globale miniaturen, retourneert u WINCODEC_ERR_CODECNOTHUMBNAIL uit de methode SetThumbnail op IWICBitmapEncoder. Als u geen palet op containerniveau ondersteunt of als de afbeelding die u codeert geen geïndexeerde indeling heeft, retourneer WINCODEC_ERR_PALETTEUNAVAILABLE vanuit de SetPalette-methode. Voor andere niet-ondersteunde methoden, geef WINCODEC_ERR_UNSUPPORTEDOPERATION terug.
Initialiseren
initialiseer is de eerste methode die wordt aangeroepen op een IWICBitmapEncoder nadat deze is geïnstantieerd. Een afbeeldingsstroom wordt doorgegeven aan de encoder en een aanroeper kan eventueel een cacheoptie opgeven. In het geval van de decoder is de stream alleen-lezen, maar de stroom die aan een encoder wordt doorgegeven, is een beschrijfbare stroom waarin de encoder alle afbeeldingsgegevens en metagegevens serialiseert. De cacheopties voor de encoder verschillen ook.
enum WICBitmapEncoderCacheOption
{
WICBitmapEncoderCacheInMemory,
WICBitmapEncoderCacheTempFile,
WICBitmapEncoderNoCache
}
De toepassing heeft de keuze om de encoder aan te vragen om de afbeeldingsgegevens in het geheugen op te slaan in de cache, deze in een tijdelijk bestand op te slaan of om deze rechtstreeks in het schijfbestand te schrijven zonder caching. Wanneer u wordt gevraagd om de gegevens in een tijdelijk bestand in de cache op te slaan, moet de encoder een tijdelijk bestand op schijf maken en rechtstreeks naar dat bestand schrijven zonder in cache op te slaan in het geheugen. Wanneer de aanroeper de optie geen cache selecteert, moet elk frame op volgorde worden doorgevoerd voordat het volgende frame kan worden gemaakt.
GetContainerFormat
GetContainerFormat wordt op dezelfde manier geïmplementeerd als de GetContainerFormat methode in Het implementeren van IWICBitmapDecoder.
GetEncoderInfo
GetEncoderInfo- retourneert een IWICBitmapEncoderInfo-object. Als u het object IWICBitmapEncoderInfo wilt ophalen, geeft u de GUID van uw encoder door aan de methode CreateComponentInfo op IWICImagingFactory-en vraagt u vervolgens de IWICBitmapEncoderInfo interface aan.
Zie het voorbeeld in IWICBitmapDecoder- implementeren onder GetDecoderInfo-.
CreateNewFrame
CreateNewFrame is de encoder-tegenhanger van GetFrame- op IWICBitmapDecoder-. Met deze methode wordt een IWICBitmapFrameEncode object geretourneerd. Dit is het object dat de afbeeldingsgegevens daadwerkelijk serialiseert voor een specifiek frame in de container.
Een van de voordelen van Windows Imaging Component (WIC) is dat het een abstractielaag biedt voor toepassingen waarmee ze op dezelfde manier met alle afbeeldingsindelingen kunnen werken. Niet alle afbeeldingsindelingen zijn echter precies hetzelfde. Sommige afbeeldingsindelingen hebben mogelijkheden die anderen niet hebben. Voor toepassingen die kunnen profiteren van deze unieke mogelijkheden, is het nodig om een manier te bieden voor de codec om ze beschikbaar te maken. Dit is het doel van encoderopties. Als uw codec coderingsopties ondersteunt, moet u een IPropertyBag2-object maken dat de coderingsopties weergeeft die u ondersteunt en deze retourneren in de ppIEncoderOptions-parameter van deze methode. De beller kan dit IPropertyBag2-object vervolgens gebruiken om te bepalen welke encoderopties uw codec ondersteunt. Als de aanroeper waarden wil opgeven voor een van de ondersteunde encoderopties, wijst deze de waarde toe aan de relevante eigenschap in het object IPropertyBag2 en geeft deze door aan het zojuist gemaakte IWICBitmapFrameEncode object in de initialize-methode.
Als u een IPropertyBag2--object wilt instantiëren, moet u eerst een PROPBAG2-struct maken om elke encoderoptie op te geven die uw encoder ondersteunt en het bijbehorende gegevenstype voor elke eigenschap. Vervolgens moet u een IPropertyBag2-object implementeren dat de waardebereiken afdwingt voor elke eigenschap bij schrijven en eventuele conflicterende of overlappende waarden afstemmen. Voor eenvoudige sets met niet-conflicterende coderingsprogramma's kunt u de methode CreateEncoderPropertyBag aanroepen. Hiermee maakt u een eenvoudig IPropertyBag2-object met behulp van de eigenschappen die u opgeeft in uw PROPBAG2 struct. U moet de waardebereiken nog steeds afdwingen. Voor geavanceerdere encoderopties of als u conflicterende waarden wilt afstemmen, moet u uw eigen IPropertyBag2-implementatie schrijven.
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 biedt een kleine set canonieke encoderopties die worden gebruikt door een aantal algemene afbeeldingsindelingen. Alle canonieke encoderopties zijn optioneel en codecs zijn niet vereist om ze te ondersteunen. De reden waarom ze worden geleverd als canonieke opties is omdat veel toepassingen de gebruikersinterface beschikbaar maken voor gebruikers om deze opties op te geven bij het opslaan van een afbeeldingsbestand in een indeling die hen ondersteunt. Door een canonieke manier op te geven om deze opties op te geven, is het voor toepassingen eenvoudig om ze op een consistente manier te communiceren met encoders. De canonieke encoderopties worden weergegeven in de volgende tabel.
| Encoderoptie | VARTYPE | Waardebereik |
|---|---|---|
| Verliesloos | VT_BOOL | Waar/onwaar |
| ImageQuality | VT_R4 | 0.0-1.0 |
| Compressiekwaliteit | VT_R4 | 0.0-1.0 |
| BitmapTransform | VT_UI1 | WICBitmapTransformOptions |
Als uw codec ondersteuning biedt voor lossless codering, moet u de optie Lossless encoder beschikbaar maken als een manier voor toepassingen om aan te vragen dat een afbeelding zonder verlies wordt gecodeerd. Als een beller deze eigenschap instelt op True, moet u de optie ImageQuality negeren en de afbeelding zonder verlies coderen.
Met de optie ImageQuality kan een toepassing de kwaliteit opgeven waarmee de afbeelding moet worden gecodeerd. Met deze optie kan een gebruiker een afweging maken tussen afbeeldingskwaliteit versus snelheid en/of bestandsgrootte. JPEG is een voorbeeld van een afbeeldingsindeling die deze afweging ondersteunt. Een waarde van 0,0 geeft aan dat betrouwbaarheid van laag belang is en dat de encoder het meest lossy-algoritme moet gebruiken. Een waarde van 1,0 geeft aan dat betrouwbaarheid het belangrijkste is en dat de encoder de hoogst mogelijke betrouwbaarheid moet behouden. (Afhankelijk van uw codec is dit mogelijk synoniem voor de optie Verliesloos. Als uw codec echter ondersteuning biedt voor lossless codering en als de optie Lossless is ingesteld op True, moet de optie ImageQuality worden genegeerd.)
Met de optie CompressionQuality kan een toepassing de efficiëntie van compressie opgeven die moet worden gebruikt bij het coderen van de afbeelding. Een zeer efficiënt algoritme kan een kleiner afbeeldingsbestand met dezelfde kwaliteit produceren als een minder efficiënt compressie-algoritme, maar het kan langer duren om te coderen. Met deze optie kan een gebruiker een compromis opgeven tussen de bestandsgrootte en de snelheid van codering, terwijl hetzelfde kwaliteitsniveau behouden blijft. TIFF is een voorbeeld van een beeldformaat dat deze afweging ondersteunt. (Houd er rekening mee dat een indeling zoals JPEG verschillende compressieniveaus ondersteunt, maar een hogere compressiesnelheid resulteert in een lagere beeldkwaliteit. Daarom zou een JPEG-afbeeldingsindeling de optie ImageQuality weergeven in plaats van de optie CompressionQuality.) Een waarde van 0,0 voor deze optie geeft aan dat u de afbeelding zo snel mogelijk moet comprimeren, zonder de betrouwbaarheid te verminderen, ten koste van een grotere bestandsgrootte. Een waarde van 1.0 geeft aan dat u de kleinste bestandsgrootte (op hetzelfde niveau van kwaliteit) moet maken, ongeacht hoe lang het kan duren om het te coderen. Een codec kan zowel de optie ImageQuality als de Optie CompressionQuality ondersteunen, waarbij de optie ImageQuality de acceptabele mate van verlies aangeeft en de optie CompressionQuality een compromis tussen grootte en snelheid biedt op het opgegeven kwaliteitsniveau.
De optie BitmapTransform biedt een manier voor de aanroeper om een draaihoek of verticale of horizontale spiegelstand op te geven bij het coderen. De WICBitmapTransformOptions-enum die wordt gebruikt om de aangevraagde transformatie op te geven, is hetzelfde enum dat wordt gebruikt bij het aanvragen van een transformatie tijdens het decoderen via de interface IWICBitmapSourceTransform.
Houd er rekening mee dat coderingsprogramma's niet beperkt zijn tot de canonieke encoderopties. Het doel van encoderopties is om encoders in staat te stellen hun mogelijkheden beschikbaar te maken en er is geen limiet voor de typen mogelijkheden die u beschikbaar kunt maken. Zorg ervoor dat de coderingsopties goed zijn gedocumenteerd. Hoewel een toepassing de eigenschapsverzameling kan gebruiken die u vanuit deze methode retourneert om de namen, typen en waardebereiken te ontdekken voor de opties die u ondersteunt, is de enige manier om hun betekenissen te achterhalen, of om ze beschikbaar te maken in de gebruikersinterface, afkomstig uit uw documentatie.
Plegen
Commit is de methode die u aanroept nadat alle afbeeldingsgegevens en metagegevens in de stroom zijn geserialiseerd. U moet deze methode gebruiken om de gegevens van de voorbeeldafbeelding in de stroom te serialiseren, evenals enige globale miniaturen, metagegevens, het palet of andere items, indien van toepassing. Deze methode mag de bestandsstroom niet sluiten, omdat de toepassing die de stream heeft geopend, naar verwachting wordt gesloten.
De sectie over de methode IWICBitmapFrameEncode:Commit bevat details over hoe de IWICBitmapEncoderCacheOptions van invloed is op het gedrag van deze methode.
VoorbeeldInstellen
SetPreview- wordt gebruikt om een voorbeeld van de afbeelding te maken. Hoewel het niet strikt vereist is dat elke afbeelding een voorbeeld heeft, wordt het ten zeerste aanbevolen. Moderne digitale camera's en scanners genereren zeer hoge resolutie beelden, die meestal erg groot zijn en dus aanzienlijke verwerkingstijd in beslag nemen om te decoderen. Afbeeldingen van de volgende generatie camera's zijn nog groter. Het is een goed idee om een kleinere, lagere resolutieversie van een afbeelding te bieden, meestal in JPEG-indeling, die snel kan worden gedecodeerd en 'onmiddellijk' kan worden weergegeven wanneer een gebruiker deze aanvraagt. Een toepassing kan een voorbeeld aanvragen voordat de daadwerkelijke afbeelding wordt gedecodeerd om gebruikers een betere ervaring te bieden en een schermgrootte van de afbeelding weer te geven terwijl ze wachten om de werkelijke afbeelding te decoderen. Hoewel codecs previews moeten bieden, moeten codecs die geen ondersteuning bieden voor IWICBitmapSourceTransform dit zeker moeten doen.
Als u een JPEG-voorbeeld opgeeft, hoeft u geen JPEG-encoder te schrijven om deze te coderen. U moet delegeren aan de JPEG-encoder die wordt geleverd met het WIC-platform voor het coderen van zowel previews als miniaturen.
Verwante onderwerpen
-
Referentie
-
conceptuele
-
Een WIC-Enabled CODEC- schrijven
-
Overzicht van Windows Imaging-onderdelen