Share via

Implémentation d’IWICBitmapEncoder

  • Article

Iwicbitmapencoder

Cette interface est l’équivalent de l’interface IWICBitmapDecoder et est le point de départ pour l’encodage d’un fichier image. Tout comme IWICBitmapDecoder est utilisé pour récupérer des propriétés au niveau du conteneur et des images individuelles à partir du conteneur d’images, IWICBitmapEncoder est utilisé pour définir des propriétés au niveau du conteneur et sérialiser des images individuelles dans le conteneur. Vous implémentez cette interface sur votre classe d’encodeur au niveau du conteneur.

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);
};

Comme indiqué dans Implémentation d’IWICBitmapDecoder, certains formats d’image ont des miniatures globales, des contextes de couleurs ou des métadonnées, tandis que de nombreux formats d’image les fournissent uniquement par image. Par conséquent, les méthodes permettant de les définir sont facultatives sur IWICBitmapEncoder, mais sont requises sur IWICBitmapFrameEncode. Nous aborderons les méthodes facultatives sur IWICBitmapEncoder dans la section sur IWICBitmapFrameEncode, où elles sont le plus couramment implémentées.

Si vous ne prenez pas en charge les miniatures globales, retournez WINCODEC_ERR_CODECNOTHUMBNAIL à partir de la méthode SetThumbnail sur IWICBitmapEncoder. Si vous ne prenez pas en charge une palette au niveau du conteneur ou si l’image que vous encodagez n’a pas de format indexé, retournez WINCODEC_ERR_PALETTEUNAVAILABLE à partir de la méthode SetPalette. Pour toutes les autres méthodes non prises en charge, retournez WINCODEC_ERR_UNSUPPORTEDOPERATION.

Initialize

Initialize est la première méthode appelée sur un IWICBitmapEncoder après son instanciation. Un flux d’image est passé à l’encodeur, et un appelant peut éventuellement spécifier une option de cache. Dans le cas du décodeur, le flux est en lecture seule, mais le flux passé à un encodeur est un flux pouvant être écrit, dans lequel l’encodeur sérialise toutes les données et métadonnées d’image. Les options de cache sur l’encodeur sont également différentes.

enum WICBitmapEncoderCacheOption
{
   WICBitmapEncoderCacheInMemory,
   WICBitmapEncoderCacheTempFile,
   WICBitmapEncoderNoCache
}

L’application a le choix de demander à l’encodeur de mettre en cache les données d’image en mémoire, de les mettre en cache dans un fichier temporaire ou de les écrire directement dans le fichier disque sans mise en cache. Lorsqu’il est invité à mettre en cache les données dans un fichier temporaire, l’encodeur doit créer un fichier temporaire sur le disque et écrire directement dans ce fichier sans mise en cache en mémoire. Lorsque l’appelant sélectionne l’option aucun cache, chaque image doit être validée dans l’ordre avant que l’image suivante puisse être créée.

GetContainerFormat

GetContainerFormat est implémenté de la même façon que la méthode GetContainerFormat dans Implémentation de IWICBitmapDecoder.

GetEncoderInfo

GetEncoderInfo retourne un objet IWICBitmapEncoderInfo . Pour obtenir l’objet IWICBitmapEncoderInfo , transmettez simplement le GUID de votre encodeur à la méthode CreateComponentInfo sur IWICImagingFactory, puis demandez l’interface IWICBitmapEncoderInfo .

Consultez l’exemple dans Implémentation d’IWICBitmapDecoder sous GetDecoderInfo.

CreateNewFrame

CreateNewFrame est l’équivalent de l’encodeur GetFrame sur IWICBitmapDecoder. Cette méthode retourne un objet IWICBitmapFrameEncode , qui est l’objet qui sérialise les données d’image pour une image spécifique dans le conteneur.

L’un des avantages du composant WIC (Windows Imaging Component) est qu’il fournit une couche d’abstraction pour les applications qui leur permet d’utiliser tous les formats d’image de la même manière. Toutefois, tous les formats d’image ne sont pas exactement identiques. Certains formats d’image ont des fonctionnalités que d’autres n’ont pas. Pour que les applications puissent tirer parti de ces fonctionnalités uniques, il est nécessaire de fournir au codec un moyen de les exposer. C’est l’objectif des options d’encodeur. Si votre codec prend en charge des options d’encodeur, vous devez créer un objet IPropertyBag2 qui expose les options d’encodeur que vous prenez en charge et le retourner dans le paramètre ppIEncoderOptions de cette méthode. L’appelant peut ensuite utiliser cet objet IPropertyBag2 pour déterminer les options d’encodeur que votre codec prend en charge. Si l’appelant souhaite spécifier des valeurs pour l’une des options d’encodeur prises en charge, il affecte la valeur à la propriété appropriée dans l’objet IPropertyBag2 et la transmet à l’objet IWICBitmapFrameEncode nouvellement créé dans sa méthode Initialize.

Pour instancier un objet IPropertyBag2 , vous devez d’abord créer un struct PROPBAG2 afin de spécifier chaque option d’encodeur prise en charge par votre encodeur et son type de données pour chaque propriété. Ensuite, vous devez implémenter un objet IPropertyBag2 qui applique les plages de valeurs pour chaque propriété en écriture et rapproche les valeurs en conflit ou se chevauchant. Pour les ensembles simples d’options d’encodeur sans conflit, vous pouvez appeler la méthode CreateEncoderPropertyBag , qui crée un objet IPropertyBag2 simple à l’aide des propriétés que vous spécifiez dans votre struct PROPBAG2. Vous devez toujours appliquer les plages de valeurs. Pour les options d’encodeur plus avancées ou si vous devez rapprocher des valeurs en conflit, vous devez écrire votre propre implémentation IPropertyBag2.

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 fournit un petit ensemble d’options d’encodeur canonique qui sont utilisées par certains formats d’image courants. Toutes les options d’encodeur canonique sont facultatives et les codecs ne sont pas nécessaires pour prendre en charge l’une d’elles. La raison pour laquelle ils sont fournis en tant qu’options canoniques est que de nombreuses applications exposent l’interface utilisateur pour que les utilisateurs spécifient ces options lors de l’enregistrement d’un fichier image dans un format qui les prend en charge. En fournissant un moyen canonique de spécifier ces options, les applications peuvent facilement les communiquer aux encodeurs de manière cohérente. Les options d’encodeur canonique sont répertoriées dans le tableau suivant.

Option d’encodeur VARTYPE Plage de valeurs
Lossless VT_BOOL Vrai/Faux
ImageQuality VT_R4 0.0-1.0
CompressionQuality VT_R4 0.0-1.0
BitmapTransform VT_UI1 WICBitmapTransformOptions

 

Si votre codec prend en charge l’encodage sans perte, vous devez exposer l’option d’encodeur sans perte comme moyen pour les applications de demander qu’une image soit encodée de manière sans perte. Si un appelant définit cette propriété sur True, vous devez ignorer l’option ImageQuality et encoder l’image sans perte.

L’option ImageQuality permet à une application de spécifier le degré de fidélité avec lequel encoder l’image. Cette option permet à un utilisateur de faire un compromis entre la qualité de l’image et la vitesse et/ou la taille du fichier. JPEG est un exemple de format d’image qui prend en charge ce compromis. La valeur 0,0 indique que la fidélité est de faible importance et que l’encodeur doit utiliser son algorithme le plus de perte. La valeur 1.0 indique que la fidélité est la plus importante et que l’encodeur doit conserver la fidélité la plus élevée possible. (Selon votre codec, cela peut être synonyme de l’option Sans perte. Toutefois, si votre codec prend en charge l’encodage sans perte et si l’option Sans perte a la valeur True, l’option ImageQuality doit être ignorée.)

L’option CompressionQuality permet à une application de spécifier l’efficacité de la compression à utiliser lors de l’encodage de l’image. Un algorithme très efficace peut produire un fichier image plus petit avec la même qualité qu’un algorithme de compression moins efficace, mais l’encodage peut prendre plus de temps. Cette option permet à un utilisateur de spécifier un compromis entre la taille du fichier et la vitesse d’encodage, tout en préservant le même niveau de qualité. TIFF est un exemple de format d’image qui prend en charge ce compromis. (Notez qu’un format tel que JPEG prend en charge différents niveaux de compression, mais qu’un taux de compression plus élevé entraîne une qualité d’image inférieure. Par conséquent, un format d’image JPEG expose l’option ImageQuality plutôt que l’option CompressionQuality.) La valeur 0,0 pour cette option indique que vous devez compresser l’image le plus rapidement possible, sans réduire la fidélité, au détriment d’une plus grande taille de fichier. La valeur 1.0 indique que vous devez créer la plus petite taille de fichier possible (au même niveau de qualité), quel que soit le temps nécessaire pour l’encoder. Un codec peut prendre en charge à la fois l’option ImageQuality et l’option CompressionQuality, où l’option ImageQuality spécifie le degré de perte acceptable et l’option CompressionQuality offre un compromis taille/vitesse au niveau de qualité spécifié.

L’option BitmapTransform permet à l’appelant de spécifier un angle de rotation ou une orientation de retournement vertical ou horizontal lors de l’encodage. L’énumération WICBitmapTransformOptions utilisée pour spécifier la transformation demandée est la même énumération que celle utilisée lors de la demande d’une transformation pendant le décodage via l’interface IWICBitmapSourceTransform.

Notez que les encodeurs ne sont pas limités aux options d’encodeur canonique. L’objectif des options d’encodeur est de permettre aux encodeurs d’exposer leurs fonctionnalités, et il n’existe aucune limite aux types de fonctionnalités que vous pouvez exposer. Assurez-vous que vos options d’encodeur sont bien documentées. Même si une application peut utiliser le conteneur de propriétés que vous retournez à partir de cette méthode pour découvrir les noms, les types et les plages de valeurs des options que vous prenez en charge, la seule façon pour elle de connaître leur signification ou de les exposer dans l’interface utilisateur est de votre documentation.

Commit

Commit est la méthode que vous appelez une fois que toutes les données et métadonnées d’image ont été sérialisées dans le flux. Vous devez utiliser cette méthode pour sérialiser les données d’image d’aperçu dans le flux, ainsi que toutes les miniatures globales, métadonnées, palettes ou autres éléments, le cas échéant. Cette méthode ne doit pas fermer le flux de fichiers, car l’application qui a ouvert le flux est censée le fermer.

La section sur la méthode IWICBitmapFrameEncode:Commit contient des détails sur la façon dont IWICBitmapEncoderCacheOptions affecte le comportement de cette méthode.

SetPreview

SetPreview est utilisé pour créer un aperçu de l’image. Bien qu’il ne soit pas strictement nécessaire que chaque image dispose d’un aperçu, il est fortement recommandé. Les appareils photo et scanneurs numériques modernes génèrent des images à très haute résolution, qui ont tendance à être très volumineuses et, par conséquent, prennent beaucoup de temps de traitement pour le décodage. Les images de la prochaine génération de caméras seront encore plus grandes. Il est judicieux de fournir une version plus petite et plus basse résolution d’une image, généralement au format JPEG, qui peut être rapidement décodée et affichée « instantanément » lorsqu’un utilisateur la demande. Une application peut demander un aperçu avant de demander le décodage de l’image réelle pour offrir une meilleure expérience aux utilisateurs et leur montrer une représentation de la taille de l’écran de l’image pendant qu’ils attendent de décoder l’image réelle. Bien que les codecs doivent fournir des aperçus, les codecs qui ne prennent pas en charge IWICBitmapSourceTransform doivent certainement le faire.

Si vous fournissez une préversion JPEG, vous n’avez pas besoin d’écrire un encodeur JPEG pour l’encoder. Vous devez déléguer à l’encodeur JPEG fourni avec la plateforme WIC pour l’encodage des préversions et des miniatures.

Informations de référence

Iwicbitmapencoder

IWICBitmapFrameEncode

Conceptuel

Interfaces d’encodeur

Implémentation de IWICBitmapCodecProgressNotification (Encodeur)

Comment écrire un codec WIC-Enabled

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