Implementazione di IWICBitmapFrameEncode

  • Articolo

IWICBitmapFrameEncode

IWICBitmapFrameEncode è la controparte del codificatore all'interfaccia IWICBitmapFrameDecode . È possibile implementare questa interfaccia nella classe di codifica a livello di frame, ovvero la classe che esegue la codifica effettiva dei bit di immagine per ogni frame.

interface IWICBitmapFrameEncode : public IUnknown
{
   // Required methods
   HRESULT Initialize ( IPropertyBag2 *pIEncoderOptions );
   HRESULT SetSize ( UINT width,
               UINT height );
   HRESULT SetResolution ( double dpiX,
               double dpiY );
   HRESULT SetPixelFormat (WICPixelFormatGUID *pPixelFormat);
   HRESULT SetColorContexts ( UINT cCount,
               IWICColorContext **ppIColorContext );
   HRESULT GetMetadataQueryWriter ( IWICMetadataQueryWriter 
               **ppIMetadataQueryWriter );
   HRESULT SetThumbnail ( IWICBitmapSource *pIThumbnail );
   HRESULT WritePixels ( UINT lineCount,
               UINT cbStride,
               UINT cbBufferSize,
               BYTE *pbPixels );
   HRESULT WriteSource ( IWICBitmapSource *pIWICBitmapSource,
               WICRect *prc );
   HRESULT Commit ( void );

// Optional method
   HRESULT SetPalette ( IWICPalette *pIPalette );
};

Initialize

Initialize è il primo metodo richiamato su un oggetto IWICBitmapFrameEncode dopo che è stata creata un'istanza. Questo metodo ha un parametro, che può essere impostato su NULL. Questo parametro rappresenta le opzioni del codificatore ed è la stessa istanza IPropertyBag2 creata nel metodo CreateNewFrame nel decodificatore a livello di contenitore e passata al chiamante nel parametro pIEncoderOptions di tale metodo. In quel momento, è stato popolato lo struct IPropertyBag2 con proprietà che rappresentano le opzioni di codifica supportate dal codificatore a livello di frame. Il chiamante ha ora fornito valori per tali proprietà per indicare determinati parametri di opzione di codifica e passa di nuovo lo stesso oggetto per inizializzare l'oggetto IWICBitmapFrameEncode . È necessario applicare le opzioni specificate durante la codifica dei bit dell'immagine.

SetSize e SetResolution

SetSize e SetResolution sono autoesplicativi. Il chiamante usa questi metodi per specificare le dimensioni e la risoluzione per l'immagine codificata.

SetPixelFormat

SetPixelFormat viene usato per richiedere un formato pixel in cui codificare l'immagine. Se il formato pixel richiesto non è supportato, è necessario restituire il GUID del formato pixel più vicino supportato in pPixelFormat, ovvero un parametro in/out.

SetColorContexts

SetColorContexts viene usato per specificare uno o più contesti di colore validi (noti anche come profili di colore) per questa immagine. È importante specificare i contesti di colore, quindi un'applicazione che decodifica l'immagine in un secondo momento può eseguire la conversione dal profilo colore di origine al profilo di destinazione del dispositivo usato per visualizzare o stampare l'immagine. Senza un profilo di colore, non è possibile ottenere colori coerenti tra dispositivi diversi. Questo può essere frustrante per gli utenti finali quando le loro foto appaiono diverse su monitor diversi e non possono ottenere le stampe in modo che corrispondano a ciò che vedono sullo schermo.

GetMetadataQueryWriter

GetMetadataQueryWriter restituisce un oggetto IWICMetadataQueryWriter che un'applicazione può usare per inserire o modificare proprietà di metadati specifiche in un blocco di metadati nel frame dell'immagine.

È possibile creare un'istanza di IWICMetadataQueryWriter da IWICComponentFactory in diversi modi. È possibile crearlo da IWICMetadataBlockWriter, allo stesso modo in cui IWICMetadataQueryReader è stato creato da un oggetto IWICMetadataBlockReader nel metodo GetMetadataQueryReader nell'interfaccia IWICBitmapFrameDecode .

IWICMetadataQueryWriter* piMetadataQueryWriter = NULL;
HRESULT hr;

hr = m_piComponentFactory->CreateQueryWriterFromBlockWriter( 
      static_cast<IWICMetadataBlockWriter*>(this), 
      &piMetadataQueryWriter);

È anche possibile crearlo da un IWICMetadataQueryReader esistente, ad esempio quello ottenuto usando il metodo precedente.

hr = m_piComponentFactory->CreateQueryWriterFromReader( 
      piMetadataQueryReader, pguidVendor, &piMetadataQueryWriter);

Il parametro pguidVendor consente di specificare un determinato fornitore da usare per il writer di query durante la creazione di un'istanza di un writer di metadati. Ad esempio, se si specificano i propri writer di metadati, è possibile specificare il GUID del fornitore. È possibile passare NULL a questo parametro se non si ha una preferenza.

SetThumbnail

SetThumbnail viene usato per fornire un'anteprima. Tutte le immagini devono fornire un'anteprima a livello globale, in ogni fotogramma o in entrambi. I metodi GetThumbnail e SetThumbnail sono facoltativi a livello di contenitore, ma se un codec restituisce WINCODEC_ERR_CODECNOTHUMBNAIL dal metodo GetThumbnail , Windows Imaging Component (WIC) richiamerà il metodo GetThumbnail per Frame 0. Se non viene trovata alcuna anteprima in entrambe le posizioni, WIC deve decodificare l'immagine completa e ridimensionarla fino alle dimensioni dell'anteprima, il che potrebbe comportare una notevole riduzione delle prestazioni per le immagini di dimensioni maggiori.

L'anteprima deve essere di dimensioni e risoluzione che rende più veloce decodificare e visualizzare. Per questo motivo, le anteprime sono più comunemente immagini JPEG. Si noti che, se si usa JPEG per le anteprime, non è necessario scrivere un codificatore JPEG per codificarli o un decodificatore JPEG per decodificarli. Devi sempre delegare al codec JPEG fornito con la piattaforma WIC per la codifica e la decodifica delle anteprime.

WritePixels

WritePixels è il metodo usato per passare righe di analisi da una bitmap in memoria per la codifica. Il metodo verrà chiamato ripetutamente fino a quando non vengono passate tutte le righe di analisi. Il parametro lineCount indica il numero di righe di analisi da scrivere in questa chiamata. Il parametro cbStride indica il numero di byte per riga di analisi. cbBufferSize indica le dimensioni del buffer passato nel parametro pbPixels, che contiene i bit di immagine effettivi da codificare. Se l'altezza combinata delle righe di analisi dalle chiamate cumulative è maggiore dell'altezza specificata nel metodo SetSize , restituire WINCODEC_ERR_TOOMANYSCANLINES.

Quando WICBitmapEncoderCacheOption è WICBitmapEncoderCacheInMemory, le righe di analisi devono essere memorizzate nella cache in memoria finché non vengono passate tutte le righe di analisi. Se l'opzione cache del codificatore è WICBitmapEncoderCacheTempFile, le righe di analisi devono essere memorizzate nella cache in un file temporaneo, create durante l'inizializzazione dell'oggetto. In uno di questi casi, l'immagine non deve essere codificata fino a quando il chiamante chiama Commit. Nel caso in cui l'opzione cache sia WICBitmapEncoderNoCache, il codificatore deve codificare le righe di analisi quando vengono ricevute, se possibile. In alcuni formati non è possibile e le righe di analisi devono essere memorizzate nella cache fino a quando non viene chiamato commit.

La maggior parte dei codec non elaborati non implementerà WritePixels, perché non supportano la modifica dei bit di immagine nel file non elaborato. I codec non elaborati devono comunque implementare WritePixels, tuttavia, perché quando vengono aggiunti metadati, può aumentare le dimensioni del file, richiedendo che il file venga riscritto sul disco. In questo caso, è necessario essere in grado di copiare i bit di immagine esistenti, ovvero ciò che fa il metodo WritePixels .

WriteSource

WriteSource viene usato per codificare un oggetto IWICBitmapSource . Il primo parametro è un puntatore a un oggetto IWICBitmapSource . Il secondo parametro è un oggetto WICRect che specifica l'area di interesse da codificare. Questo metodo può essere chiamato più volte in successione, purché la larghezza di ogni rettangolo sia la stessa larghezza dell'immagine finale da codificare. Se la larghezza del rettangolo passato nel parametro prc è diversa dalla larghezza specificata nel metodo SetSize, restituire WINCODEC_ERR_SOURCERECTDOESNOTMATCHDIMENSIONS. Se l'altezza combinata delle righe di analisi dalle chiamate cumulative è maggiore dell'altezza specificata nel metodo SetSize, restituire WINCODEC_ERR_TOOMANYSCANLINES.

Le opzioni della cache funzionano allo stesso modo con questo metodo come con il metodo WritePixels descritto in precedenza.

Commit

Commit è il metodo che serializza i bit dell'immagine codificata nel flusso di file e scorre tutti i writer di metadati per il frame che richiede di serializzare i metadati nel flusso. Nel caso in cui l'opzione della cache del codificatore sia WICBitmapEncoderCacheInMemory o WICBitmapEncoderCacheTempFile, questo metodo è anche responsabile della codifica dell'immagine e quando l'opzione della cache è WICBitmapEncoderCacheTempFile, il metodo Commit deve eliminare anche il file temporaneo usato per memorizzare nella cache i dati dell'immagine prima della codifica.

Questo metodo viene sempre richiamato dopo che tutte le righe o i rettangoli di analisi che costituiscono l'immagine sono stati passati usando il metodo Commit o WriteSource . Le dimensioni del rettangolo finale composto tramite le chiamate accumulate a WritePixels o WriteSource devono essere le stesse dimensioni specificate nel metodo SetSize. Se le dimensioni non corrispondono alle dimensioni previste, questo metodo deve restituire WINCODECERROR_UNEXPECTEDSIZE.

Per scorrere i writer di metadati e indicare a ogni writer di metadati di serializzare i metadati, richiamare GetWriterByIndex per scorrere i writer per ogni blocco e richiamare IWICPersistStream.Save in ogni writer di metadati.

IWICMetadataWriter* piMetadataWRiter = NULL;
IWICPersistStream* piPersistStream = NULL;
HRESULT hr;

for (UINT x=0; x < m_blockCount; x++) 
{
    hr = GetWriterByIndex(x, & piMetadataWriter);
hr = piMetadataWriter->QueryInterface(
IID_IWICPersistStream,(void**)&piPersistStream);

hr = piPersistStream->Save(m_piStream, 
WICPersistOptions.WicPersistOptionDefault, 
true);
...
}

SetPalette

Solo i codec con formati indicizzati devono implementare il metodo SetPalette . Se un'immagine usa un formato indicizzato, usare questo metodo per specificare la tavolozza dei colori usati nell'immagine. Se il codec non ha un formato indicizzato, restituire WINCODEC_ERR_PALETTEUNAVAILABLE da questo metodo.

Informazioni concettuali

Implementazione di IWICBitmapCodecProgressNotification (codificatore)

Implementazione di IWICMetadataBlockWriter

Come scrivere un codec WIC-Enabled

Panoramica del componente Windows Imaging