IWICBitmapDecoder implementeren

IWICBitmapDecoder

Wanneer een toepassing een decoder aanvraagt, is het eerste interactiepunt met de codec via de IWICBitmapDecoder interface. Dit is de interface op containerniveau die toegang biedt tot de eigenschappen op het hoogste niveau van de container en, vooral, de frames die deze bevat. Dit is de primaire interface van uw decoderklasse op containerniveau.

interface IWICBitmapDecoder : IUnknown
{
// Required methods
   HRESULT QueryCapability (IStream *pIStream, 
      DWORD *pdwCapabilities );
   HRESULT Initialize ( IStream *pIStream,
      WICDecodeOptions cacheOptions );
   HRESULT GetContainerFormat ( GUID *pguidContainerFormat );
   HRESULT GetDecoderInfo ( IWICBitmapDecoderInfo **pIDecoderInfo );
   HRESULT GetFrameCount ( UINT *pCount );
   HRESULT GetFrame ( UINT index, 
      IWICBitmapFrameDecode **ppIBitmapFrame );

// Optional methods
   HRESULT GetPreview ( IWICBitmapSource **ppIPreview );
   HRESULT GetThumbnail ( IWICBitmapSource **ppIThumbnail );
   HRESULT GetColorContexts ( UINT cCount, 
      IWICColorContext **ppIColorContexts, 
      UINT *pcActualCount );
   HRESULT GetMetadataQueryReader ( IWICMetadataQueryReader **ppIMetadataQueryReader);
   HRESULT CopyPalette ( IWICPalette *pIPalette );
}

Sommige afbeeldingsindelingen hebben globale miniaturen, kleurcontexten of metagegevens, terwijl veel afbeeldingsindelingen deze alleen per frame bieden. De methoden voor toegang tot deze items zijn optioneel op IWICBitmapDecoder, maar zijn vereist voor IWICBitmapFrameDecode. Op dezelfde manier gebruiken sommige codecs geen geïndexeerde pixelindelingen en hoeven ze de CopyPalette-methoden niet te implementeren voor beide interfaces. Zie voor meer informatie over de optionele IWICBitmapDecoder methoden IWICBitmapFrameDecode implementeren, waar ze het meest worden geïmplementeerd.

QueryCapability

QueryCapability is de methode die wordt gebruikt voor codec-arbitrage. (Zie Ontdekking en Arbitrage in de Hoe De Windows Imaging-component Werkt sectie). Als twee codecs in staat zijn om dezelfde afbeeldingsindeling te decoderen of als er een patroonconflict optreedt waarin twee codecs hetzelfde identificatiepatroon gebruiken, kunt u met deze methode de codec selecteren die het beste elke specifieke afbeelding kan verwerken.

Wanneer u deze methode aanroept, geeft Windows Imaging Component (WIC) u de werkelijke stroom door die de afbeelding bevat. U moet controleren of u elk frame in de afbeelding kunt decoderen en de metagegevensblokken kunt opsommen om nauwkeurig te declareren welke mogelijkheden deze decoder heeft met betrekking tot de specifieke bestandsstroom die eraan wordt doorgegeven. Dit is belangrijk voor alle decoders, maar vooral belangrijk voor afbeeldingsindelingen op basis van TIFF-containers (Tagged Image File Format). Het ontdekkingsproces werkt door patronen te matchen die geassocieerd zijn met decoders in de registers aan patronen in het daadwerkelijke beeldbestand. Het opnemen van uw herkenningspatroon in het registerbestand garandeert dat uw decoder altijd wordt herkend voor beelden in uw beeldformaat. Uw decoder kan echter nog steeds worden gedetecteerd voor afbeeldingen in andere indelingen. Alle TIFF-containers bevatten bijvoorbeeld het TIFF-patroon. Dit is een geldig identificatiepatroon voor de TIFF-afbeeldingsindeling. Dit betekent dat tijdens de detectie ten minste twee identificatiepatronen worden gevonden in afbeeldingsbestanden voor elke afbeeldingsindeling die is gebaseerd op een TIFF-stijlcontainer. De ene is het TIFF-patroon en de andere is het werkelijke patroon voor de afbeeldingsopmaak. Hoewel de kans kleiner is, kunnen er ook patroonconflicten zijn tussen andere ongelijksoortige afbeeldingsindelingen. Daarom is detectie en arbitrage een proces in twee fasen. Controleer altijd of de afbeeldingsstroom die is doorgegeven aan QueryCapability een geldig exemplaar van uw eigen afbeeldingsindeling is. Als uw codec een afbeeldingsindeling ontsleutelt waarvoor u niet de eigenaar bent van de specificatie, moet uw QueryCapability implementatie controleren op de aanwezigheid van een functie die mogelijk geldig is in de specificatie van de afbeeldingsindeling die uw codec niet implementeert. Dit zorgt ervoor dat gebruikers geen onnodige decoderingsfouten ervaren of onverwachte resultaten krijgen met uw codec.

Voordat u een bewerking op de afbeelding uitvoert, moet u de huidige positie van de stream opslaan, zodat u deze kunt herstellen naar de oorspronkelijke positie voordat u terugkeert van de methode. De WICBitmapDecoderCapabilities opsomming die de mogelijkheden aangeeft, wordt als volgt gedefinieerd:

enum WICBitmapDecoderCapabilities
{   
   WICBitmapDecoderCapabilitySameEncoder,
   WICBitmapDecoderCapabilityCanDecodeAllImages,
   WICBitmapDecoderCapabilityCanDecodeSomeImages,
   WICBitmapDecoderCapabilityCanEnumerateMetadata,
   WICBitmapDecoderCapabilityCanDecodeThumbnail
}

U moet WICBitmapDecoderCapabilitySameEncoder alleen declareren als uw encoder degene is die de afbeelding gecodeerd heeft. Nadat u hebt gecontroleerd of u elk frame in de container kunt decoderen, declareert u WICBitmapDecoderCapabilityCanDecodeSomeImages als u sommige maar niet alle frames kunt decoderen, WICBitmapDecoderCapabilityCanDecodeAllImages als u alle frames kunt decoderen of niet als u geen van deze frames kunt decoderen. (Deze twee opsommingen sluiten elkaar wederzijds uit; als u WICBitmapDecoderCapabilityCanDecodeAllImagesretourneert, wordt WICBitmapDecoderCapabilityCanDecodeSomeImages genegeerd.) Declareer WICBitmapDecoderCapabilityCanEnumerateMetadata nadat u hebt gecontroleerd of u de metagegevensblokken in de beeldcontainer kunt inventariseren. U hoeft niet te controleren op een miniatuur in elk frame. Als er een globale miniatuur is en u deze kunt ontcijferen, kunt u WICBitmapDecoderCapabilityCanDecodeThumbnaildeclareren. Als er geen globale miniatuur is, probeert u de miniatuur voor Frame 0 te decoderen. Als er geen thumbnail op een van deze plaatsen is, geef deze mogelijkheid dan niet aan.

Nadat u de mogelijkheden van de decoder hebt bepaald met betrekking tot de afbeeldingsstroom die aan deze methode is doorgegeven, voert u een OR-bewerking uit met de WICBitmapDecoderCapabilities u hebt geverifieerd dat deze decoder op deze afbeelding kan worden uitgevoerd en retourneert u het resultaat. Vergeet niet om de stream te herstellen naar de oorspronkelijke positie voordat u terugkeert.

Initialiseren

initialiseer wordt aangeroepen door een toepassing nadat een decoder is geselecteerd om een specifieke afbeelding te decoderen. De afbeeldingsstroom wordt doorgegeven aan de decoder en een aanroeper kan eventueel de WICDecodeOptions cacheoptie opgeven voor het omgaan met de metagegevens in het bestand.

enum WICDecodeOptions
{
   WICDecodeMetadataCacheOnDemand,
   WICDecodeMetadataCacheOnLoad
}

Sommige toepassingen gebruiken meer metagegevens dan andere. De meeste toepassingen hoeven niet toegang te krijgen tot alle metagegevens in een afbeeldingsbestand en vragen specifieke metagegevens aan wanneer ze deze nodig hebben. Andere toepassingen slaan liever alle metagegevens vooraf in de cache op dan de bestandsstroom open te houden en schijf-I/O uit te voeren telkens wanneer ze toegang nodig hebben tot metagegevens. Als de aanroeper geen optie voor metagegevenscache opgeeft, moet het standaardgedrag voor opslaan in cache op aanvraag zijn. Dit betekent dat er geen metagegevens in het geheugen moeten worden geladen totdat de toepassing een specifieke aanvraag voor die metagegevens indient. Als de toepassing WICDecodeMetadataCacheOnLoad-opgeeft, moeten de metagegevens onmiddellijk in het geheugen worden geladen en in de cache worden opgeslagen. Wanneer metagegevens tijdens het laden in de cache worden opgeslagen, kan de bestandsstroom worden vrijgegeven nadat de metagegevens in de cache zijn opgeslagen.

VerkrijgContainerFormaat

Als u GetContainerFormatwilt implementeren, retourneert u de GUID van de afbeeldingsindeling van de afbeelding waarvoor de decoder wordt geïnstantieerd. Deze methode wordt ook geïmplementeerd op IWICMetadataBlockReader en IWICBitmapEncoder.

GetDecoderInfo

GetDecoderInfo retourneert een IWICBitmapDecoderInfo-object . Als u het IWICBitmapDecoderInfo object wilt ophalen, geeft u de GUID van de decoder door aan de CreateComponentInfo methode op IWICImagingFactoryen vraagt u vervolgens de IWICBitmapDecoderInfo interface op, zoals wordt weergegeven in het volgende voorbeeld.

IWICComponentInfo* pComponentInfo = NULL;
HRESULT hr;
 
hr = m_pImagingFactory->CreateComponentInfo(CLSID_This, &pComponentInfo);

hr = pComponentInfo->QueryInterface(IID_IWICBitmapDecoderInfo, (void**)ppIDecoderInfo);

GetFrameCount

GetFrameCount- retourneert alleen het aantal frames in de container. Sommige containerindelingen ondersteunen meerdere frames en andere ondersteunen slechts één frame per container.

GetFrame

GetFrame is een belangrijke methode op de IWICBitmapDecoder interface omdat het frame de werkelijke afbeeldingsbits bevat en het framedecodeerobject dat door deze methode wordt geretourneerd, het object is dat de daadwerkelijke decodering van de aangevraagde afbeelding doet. Dat is het andere object dat u moet implementeren bij het schrijven van een decoder. Zie IWICBitmapFrameDecode implementerenvoor meer informatie over frame decoders.

VoorbeeldOphalen

GetPreview- retourneert een voorbeeld van de afbeelding. Voor een gedetailleerde bespreking van previews, zie de Implementeren van IWICBitmapEncoder methode op de Implementeren van IWICBitmapEncoder interface.

Als uw afbeeldingsindeling een ingesloten JPEG-voorbeeld bevat, wordt het ten zeerste aanbevolen om in plaats van zelf een JPEG-decoder te schrijven, gebruik te maken van de JPEG-decoder die wordt geleverd met het WIC-platform voor het decoderen van voorbeelden en miniaturen. Als u dit wilt doen, zoekt u naar het begin van de voorbeeldafbeeldingsgegevens in de stream en roept u de methode CreateDecoderFromStream aan op de IWICImagingFactory.

IWICBitmapDecoder* pPreviewDecoder = NULL;
IWICBitmapFrameDecode* pPreviewFrame = NULL;
IWICBitmapSource* pPreview = NULL;
HRESULT hr;

hr = m_pImagingFactory->CreateDecoderFromStream(
                               m_pStream, NULL, 
                               WICDecodeMetadataCacheOnDemand, &pPreviewDecoder);
hr = pPreviewDecoder->GetFrame(0, pPreviewFrame);
hr = pPreviewFrame->QueryInterface(IID_IWICBitmapSource, (void**)&pPreview);

Verwante onderwerpen

Referentie

IWICBitmapDecoder

IWICBitmapFrameDecode

conceptuele

Decoder interfaces

IWICBitmapCodecProgressNotification (Decoder) implementeren

Hoe een WIC-Enabled CODEC te schrijven

Overzicht van Windows Imaging-onderdelen