Implémentation de IWICBitmapFrameEncode

  • Article

IWICBitmapFrameEncode

IWICBitmapFrameEncode est l’équivalent de l’encodeur à l’interface IWICBitmapFrameDecode . Vous pouvez implémenter cette interface sur votre classe d’encodage au niveau de l’image, qui est la classe qui effectue l’encodage réel des bits d’image pour chaque image.

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 est la première méthode appelée sur un objet IWICBitmapFrameEncode après son instanciation. Cette méthode a un paramètre, qui peut être défini sur NULL. Ce paramètre représente les options de l’encodeur et est le même instance IPropertyBag2 que vous avez créé dans la méthode CreateNewFrame sur le décodeur au niveau du conteneur, puis transmis à l’appelant dans le paramètre pIEncoderOptions de cette méthode. À ce moment-là, vous avez rempli le struct IPropertyBag2 avec des propriétés qui représentent les options d’encodage prises en charge par votre encodeur au niveau de l’image. L’appelant a maintenant fourni des valeurs pour ces propriétés afin d’indiquer certains paramètres d’option d’encodage et vous transmet le même objet pour initialiser l’objet IWICBitmapFrameEncode . Vous devez appliquer les options spécifiées lors de l’encodage des bits d’image.

SetSize et SetResolution

SetSize et SetResolution sont explicites. L’appelant utilise ces méthodes pour spécifier la taille et la résolution de l’image encodée.

SetPixelFormat

SetPixelFormat est utilisé pour demander un format de pixel dans lequel encoder l’image. Si le format de pixel demandé n’est pas pris en charge, vous devez retourner le GUID du format de pixel le plus proche pris en charge dans pPixelFormat, qui est un paramètre d’entrée/sortie.

SetColorContexts

SetColorContexts permet de spécifier un ou plusieurs contextes de couleurs valides (également appelés profils de couleur) pour cette image. Il est important de spécifier les contextes de couleur afin qu’une application qui décode l’image ultérieurement puisse convertir le profil de couleur source en profil de destination de l’appareil utilisé pour afficher ou imprimer l’image. Sans profil de couleur, il n’est pas possible d’obtenir des couleurs cohérentes sur différents appareils. Cela peut être frustrant pour les utilisateurs finaux lorsque leurs photos sont différentes sur différents écrans et qu’ils ne peuvent pas obtenir les impressions correspondant à ce qu’ils voient à l’écran.

GetMetadataQueryWriter

GetMetadataQueryWriter retourne un IWICMetadataQueryWriter qu’une application peut utiliser pour insérer ou modifier des propriétés de métadonnées spécifiques dans un bloc de métadonnées sur le cadre de l’image.

Vous pouvez instancier un IWICMetadataQueryWriter à partir de L’IWICComponentFactory de plusieurs façons. Vous pouvez le créer à partir de votre IWICMetadataBlockWriter, de la même façon que IWICMetadataQueryReader a été créé à partir d’un IWICMetadataBlockReader dans la méthode GetMetadataQueryReader sur l’interface IWICBitmapFrameDecode .

IWICMetadataQueryWriter* piMetadataQueryWriter = NULL;
HRESULT hr;

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

Vous pouvez également le créer à partir d’un IWICMetadataQueryReader existant, tel que celui obtenu à l’aide de la méthode précédente.

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

Le paramètre pguidVendor vous permet de spécifier un fournisseur particulier pour l’enregistreur de requêtes à utiliser lors de l’instanciation d’un enregistreur de métadonnées. Par exemple, si vous fournissez vos propres enregistreurs de métadonnées, vous pouvez spécifier votre propre GUID de fournisseur. Vous pouvez passer NULL à ce paramètre si vous n’avez pas de préférence.

SetThumbnail

SetThumbnail est utilisé pour fournir une miniature. Toutes les images doivent fournir une miniature globalement, sur chaque image ou les deux. Les méthodes GetThumbnail et SetThumbnail sont facultatives au niveau du conteneur, mais, si un codec retourne WINCODEC_ERR_CODECNOTHUMBNAIL à partir de la méthode GetThumbnail , Windows Imaging Component (WIC) appelle la méthode GetThumbnail pour Frame 0. Si aucune miniature n’est trouvée à l’un ou l’autre endroit, WIC doit décoder l’image complète et la mettre à l’échelle à la taille de la miniature, ce qui peut entraîner une pénalité de performances importante pour les images plus volumineuses.

La miniature doit être d’une taille et d’une résolution qui facilitent le décodage et l’affichage. Pour cette raison, les miniatures sont généralement des images JPEG. Notez que, si vous utilisez JPEG pour vos miniatures, vous n’avez pas besoin d’écrire un encodeur JPEG pour les encoder, ni un décodeur JPEG pour les décoder. Vous devez toujours déléguer au codec JPEG fourni avec la plateforme WIC pour l’encodage et le décodage des miniatures.

WritePixels

WritePixels est la méthode utilisée pour passer des lignes d’analyse à partir d’une bitmap en mémoire à des fins d’encodage. La méthode est appelée à plusieurs reprises jusqu’à ce que toutes les lignes d’analyse aient été passées. Le paramètre lineCount indique le nombre de lignes d’analyse à écrire dans cet appel. Le paramètre cbStride indique le nombre d’octets par ligne d’analyse. cbBufferSize indique la taille de la mémoire tampon passée dans le paramètre pbPixels, qui contient les bits d’image réels à encoder. Si la hauteur combinée des lignes d’analyse des appels cumulés est supérieure à la hauteur spécifiée dans la méthode SetSize , retournez WINCODEC_ERR_TOOMANYSCANLINES.

Lorsque WICBitmapEncoderCacheOption est WICBitmapEncoderCacheInMemory, les lignes d’analyse doivent être mises en cache en mémoire jusqu’à ce que toutes les lignes d’analyse aient été passées. Si l’option de cache de l’encodeur est WICBitmapEncoderCacheTempFile, les lignes d’analyse doivent être mises en cache dans un fichier temporaire, créé lors de l’initialisation de l’objet. Dans l’un ou l’autre de ces cas, l’image ne doit pas être encodée tant que l’appelant n’a pas appelé Commit. Dans le cas où l’option de cache est WICBitmapEncoderNoCache, l’encodeur doit encoder les lignes d’analyse à mesure qu’elles sont reçues, si possible. (Dans certains formats, cela n’est pas possible, et les lignes d’analyse doivent être mises en cache jusqu’à ce que commit soit appelé.)

La plupart des codecs bruts n’implémentent pas WritePixels, car ils ne prennent pas en charge la modification des bits d’image dans le fichier brut. Toutefois, les codecs bruts doivent toujours implémenter WritePixels, car lorsque des métadonnées sont ajoutées, cela peut augmenter la taille du fichier, ce qui nécessite une réécriture du fichier sur le disque. Dans ce cas, il est nécessaire de pouvoir copier les bits d’image existants, ce que fait la méthode WritePixels .

WriteSource

WriteSource est utilisé pour encoder un objet IWICBitmapSource . Le premier paramètre est un pointeur vers un objet IWICBitmapSource . Le deuxième paramètre est un WICRect qui spécifie la région d’intérêt à encoder. Cette méthode peut être appelée plusieurs fois successivement, tant que la largeur de chaque rectangle est la même que celle de l’image finale à encoder. Si la largeur du rectangle passé dans le paramètre prc est différente de la largeur spécifiée dans la méthode SetSize, retournez WINCODEC_ERR_SOURCERECTDOESNOTMATCHDIMENSIONS. Si la hauteur combinée des lignes d’analyse des appels cumulés est supérieure à la hauteur spécifiée dans la méthode SetSize, retournez WINCODEC_ERR_TOOMANYSCANLINES.

Les options de cache fonctionnent de la même façon avec cette méthode qu’avec la méthode WritePixels décrite précédemment.

Commit

Commit est la méthode qui sérialise les bits d’image encodés dans le flux de fichiers et effectue une itération au sein de tous les enregistreurs de métadonnées pour le frame leur demandant de sérialiser leurs métadonnées dans le flux. Dans le cas où l’option de cache de l’encodeur est WICBitmapEncoderCacheInMemory ou WICBitmapEncoderCacheTempFile, cette méthode est également responsable de l’encodage de l’image. Lorsque l’option de cache est WICBitmapEncoderCacheTempFile, la méthode Commit doit également supprimer le fichier temporaire utilisé pour mettre en cache les données d’image avant l’encodage.

Cette méthode est toujours appelée une fois que toutes les lignes d’analyse ou rectangles qui composent l’image ont été passées à l’aide de la méthode Commit ou WriteSource . La taille du rectangle final composé par le biais des appels cumulés à WritePixels ou WriteSource doit être de la même taille que celle spécifiée dans la méthode SetSize. Si la taille ne correspond pas à la taille attendue, cette méthode doit retourner WINCODECERROR_UNEXPECTEDSIZE.

Pour itérer au sein des enregistreurs de métadonnées et indiquer à chaque enregistreur de métadonnées de sérialiser ses métadonnées dans le flux, appelez GetWriterByIndex pour itérer au sein des enregistreurs pour chaque bloc, puis appelez IWICPersistStream.Save sur chaque enregistreur de métadonnées.

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

Seuls les codecs qui ont des formats indexés doivent implémenter la méthode SetPalette . Si une image utilise un format indexé, utilisez cette méthode pour spécifier la palette de couleurs utilisée dans l’image. Si votre codec n’a pas de format indexé, retournez WINCODEC_ERR_PALETTEUNAVAILABLE à partir de cette méthode.

Conceptuel

Implémentation de IWICBitmapCodecProgressNotification (Encodeur)

Implémentation d’IWICMetadataBlockWriter

Comment écrire un codec WIC-Enabled

Vue d’ensemble du composant d’acquisition d’images Windows