Implementazione di IWICBitmapDecoder
IWICBitmapDecoder
Quando un'applicazione richiede un decodificatore, il primo punto di interazione con il codec è tramite l'interfaccia IWICBitmapDecoder . Si tratta dell'interfaccia a livello di contenitore che fornisce l'accesso alle proprietà di primo livello del contenitore e, soprattutto, i frame contenuti. Si tratta dell'interfaccia primaria nella classe decodificatore a livello di contenitore.
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 );
}
Alcuni formati di immagine hanno anteprime globali, contesti di colore o metadati, mentre molti formati di immagine forniscono questi solo per fotogramma. I metodi per l'accesso a questi elementi sono facoltativi in IWICBitmapDecoder, ma sono necessari in IWICBitmapFrameDecode. Analogamente, alcuni codec non usano formati pixel indicizzati e quindi non devono implementare i metodi CopyPalette in entrambe le interfacce. Per altre informazioni sui metodi IWICBitmapDecoder facoltativi, vedere Implementazione di IWICBitmapFrameDecode, in cui vengono implementati più comunemente.
QueryCapability
QueryCapability è il metodo usato per l'arbitrato codec. (Vedere Individuazione e arbitratonell'argomento How The Windows Imaging Component Works ). Se due codec sono in grado di decodificare lo stesso formato di immagine o se si verifica una collisione di modello in cui due codec usano lo stesso modello di identificazione, questo metodo consente di selezionare il codec che può gestire meglio qualsiasi immagine specifica.
Quando si richiama questo metodo, Windows Imaging Component (WIC) passa il flusso effettivo contenente l'immagine. È necessario verificare se è possibile decodificare ogni frame all'interno dell'immagine ed enumerare tramite i blocchi di metadati, per dichiarare con precisione le funzionalità di questo decodificatore rispetto al flusso di file specifico passato. Questo è importante per tutti i decodificatori, ma particolarmente importante per i formati di immagine basati sui contenitori TIFF (Tag Image File Format). Il processo di individuazione funziona in base ai modelli associati ai decodificatori nel Registro di sistema per i modelli nel file di immagine effettivo. Dichiarando il modello di identificazione nel Registro di sistema garantisce che il decodificatore venga sempre rilevato per le immagini nel formato immagine. Tuttavia, il decodificatore potrebbe comunque essere rilevato per le immagini in altri formati. Ad esempio, tutti i contenitori TIFF includono il modello TIFF, che è un modello di identificazione valido per il formato di immagine TIFF. Ciò significa che, durante l'individuazione, almeno due modelli di identificazione verranno trovati nei file di immagine per qualsiasi formato di immagine basato su un contenitore in stile TIFF. Uno sarà il modello TIFF e l'altro sarà il modello di formato immagine effettivo. Anche se meno probabile, potrebbero verificarsi collisioni tra altri formati di immagine non correlati. Questo è il motivo per cui l'individuazione e l'arbitrato sono un processo a due fasi. Verificare sempre che il flusso di immagini passato a QueryCapability sia effettivamente un'istanza valida del proprio formato di immagine. Inoltre, se il codec decodifica un formato di immagine per il quale non si possiede la specifica, l'implementazione queryCapability deve verificare la presenza di qualsiasi funzionalità che potrebbe essere valida nella specifica del formato di immagine che il codec non implementa. In questo modo, gli utenti non riscontrano errori di decodifica non necessari o ottengono risultati imprevisti con il codec.
Prima di eseguire qualsiasi operazione sull'immagine, è necessario salvare la posizione corrente del flusso, in modo da poterla ripristinare nella posizione originale prima di restituire dal metodo. L'enumerazione WICBitmapDecoderCapabilities che specifica le funzionalità è definita come segue:
enum WICBitmapDecoderCapabilities
{
WICBitmapDecoderCapabilitySameEncoder,
WICBitmapDecoderCapabilityCanDecodeAllImages,
WICBitmapDecoderCapabilityCanDecodeSomeImages,
WICBitmapDecoderCapabilityCanEnumerateMetadata,
WICBitmapDecoderCapabilityCanDecodeThumbnail
}
È necessario dichiarare WICBitmapDecoderCapabilitySameEncoder solo se il codificatore era quello che codificava l'immagine. Dopo aver verificato se è possibile decodificare ogni frame nel contenitore, dichiarare WICBitmapDecoderCapabilityCanDecodeSomeImages se è possibile decodificare alcuni fotogrammi ma non tutti i fotogrammi, WICBitmapDecoderCapabilityCapabilityCanDecodeAllImages se è possibile decodificare tutti i fotogrammi o nessuno dei due se non è possibile decodificare nessuno di essi. Queste due enumerazioni si escludono reciprocamente. Se si restituisce WICBitmapDecoderCapabilityCanDecodeAllImages, WICBitmapDecoderCapabilityCanDecodeSomeImages verrà ignorato. DichiaraRE WICBitmapDecoderCapabilityCanEnumerateMetadata dopo aver verificato che è possibile enumerare i blocchi di metadati nel contenitore di immagini. Non è necessario controllare la presenza di un'anteprima in ogni cornice. Se è presente un'anteprima globale ed è possibile decodificarla, è possibile dichiarare WICBitmapDecoderCapabilityCanDecodeThumbnail. Se non è presente alcuna anteprima globale, provare a decodificare l'anteprima per Frame 0. Se non sono presenti anteprime in una di queste posizioni, non dichiarare questa funzionalità.
Dopo aver determinato le funzionalità del decodificatore rispetto al flusso di immagini passato a questo metodo, eseguire un'operazione OR con WICBitmapDecoderCapabilities che questo decodificatore può eseguire su questa immagine e restituire il risultato. Ricordarsi di ripristinare il flusso nella posizione originale prima di restituire.
Initialize
L'inizializzazione viene richiamata da un'applicazione dopo che è stato selezionato un decodificatore per decodificare un'immagine specifica. Il flusso di immagini viene passato al decodificatore e un chiamante può facoltativamente specificare l'opzione cache WICDecodeOptions per la gestione dei metadati nel file.
enum WICDecodeOptions
{
WICDecodeMetadataCacheOnDemand,
WICDecodeMetadataCacheOnLoad
}
Alcune applicazioni usano i metadati più di altri. La maggior parte delle applicazioni non deve accedere a tutti i metadati in un file di immagine e richiederà metadati specifici in base alle esigenze. Altre applicazioni invece di memorizzare nella cache tutti i metadati in primo piano rispetto a mantenere aperto il flusso di file ed eseguire l'I/O del disco ogni volta che devono accedere ai metadati. Se il chiamante non specifica un'opzione cache dei metadati, il comportamento di memorizzazione nella cache predefinito deve essere memorizzato nella cache su richiesta. Ciò significa che non devono essere caricati metadati in memoria fino a quando l'applicazione effettua una richiesta specifica per tali metadati. Se l'applicazione specifica WICDecodeMetadataCacheOnLoad, i metadati devono essere caricati in memoria immediatamente e memorizzati nella cache. Quando i metadati vengono memorizzati nella cache sul carico, il flusso di file può essere rilasciato dopo che i metadati sono stati memorizzati nella cache.
GetContainerFormat
Per implementare GetContainerFormat, è sufficiente restituire il GUID del formato immagine dell'immagine per cui viene creata un'istanza del decodificatore. Questo metodo viene implementato anche in IWICMetadataBlockReader e IWICBitmapEncoder.
GetDecoderInfo
GetDecoderInfo restituisce un oggetto IWICBitmapDecoderInfo . Per ottenere l'oggetto IWICBitmapDecoderInfo , passare il GUID del decodificatore al metodo CreateComponentInfo in IWICImagingFactory e quindi richiedere l'interfaccia IWICBitmapDecoderInfo , come illustrato nell'esempio seguente.
IWICComponentInfo* pComponentInfo = NULL;
HRESULT hr;
hr = m_pImagingFactory->CreateComponentInfo(CLSID_This, &pComponentInfo);
hr = pComponentInfo->QueryInterface(IID_IWICBitmapDecoderInfo, (void**)ppIDecoderInfo);
GetFrameCount
GetFrameCount restituisce solo il numero di fotogrammi nel contenitore. Alcuni formati di contenitore supportano più frame e altri supportano solo un frame per contenitore.
GetFrame
GetFrame è un metodo importante nell'interfaccia IWICBitmapDecoder perché il frame contiene i bit di immagine effettivi e l'oggetto decodificatore frame restituito da questo metodo è l'oggetto che esegue la decodifica effettiva dell'immagine richiesta. Questo è l'altro oggetto che è necessario implementare quando si scrive un decodificatore. Per altre informazioni sui decodificatori frame, vedere Implementazione di IWICBitmapFrameDecode.
GetPreview
GetPreview restituisce un'anteprima dell'immagine. Per una discussione dettagliata sulle anteprime, vedere il metodo Implementa IWICBitmapEncoder nell'interfaccia Implementa IWICBitmapEncoder.
Se il formato immagine contiene un'anteprima JPEG incorporata, è consigliabile che, anziché scrivere un decodificatore JPEG per decodificarlo, si delega al decodificatore JPEG fornito con la piattaforma WIC per decodificare le anteprime e le anteprime. A tale scopo, cercare l'inizio dei dati dell'immagine di anteprima nel flusso e richiamare il metodo CreateDecoderFromStream nella 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);
Argomenti correlati
-
Riferimento
-
Informazioni concettuali
-
Implementazione di IWICBitmapCodecProgressNotification (decodificatore)