Documentation de l'API WebP Container

Manipulation du conteneur RIFF pour les images WebP

API Mux

Permet de manipuler des images de conteneur WebP qui contiennent des fonctionnalités telles que le profil de couleur, les métadonnées, l'animation et les images fragmentées.

Exemples de code

Créer un MUX avec des données d'image, un profil de couleur et des métadonnées XMP

int copy_data = 0;
WebPMux* mux = WebPMuxNew();
// ... (Prepare image data).
WebPMuxSetImage(mux, &image, copy_data);
// ... (Prepare ICCP color profile data).
WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data);
// ... (Prepare XMP metadata).
WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data);
// Get data from mux in WebP RIFF format.
WebPMuxAssemble(mux, &output_data);
WebPMuxDelete(mux);
// ... (Consume output_data; e.g. write output_data.bytes to file).
WebPDataClear(&output_data);

Obtenir les données de profil d'image et de couleur à partir d'un fichier WebP

int copy_data = 0;
// ... (Read data from file).
WebPMux* mux = WebPMuxCreate(&data, copy_data);
WebPMuxGetFrame(mux, 1, &image);
// ... (Consume image; e.g. call WebPDecode() to decode the data).
WebPMuxGetChunk(mux, "ICCP", &icc_profile);
// ... (Consume icc_data).
WebPMuxDelete(mux);
free(data);

Vie d'un objet Mux

Enums

// Error codes
typedef enum WebPMuxError {
  WEBP_MUX_OK                 =  1,
  WEBP_MUX_NOT_FOUND          =  0,
  WEBP_MUX_INVALID_ARGUMENT   = -1,
  WEBP_MUX_BAD_DATA           = -2,
  WEBP_MUX_MEMORY_ERROR       = -3,
  WEBP_MUX_NOT_ENOUGH_DATA    = -4
} WebPMuxError;

// IDs for different types of chunks.
typedef enum WebPChunkId {
  WEBP_CHUNK_VP8X,     // VP8X
  WEBP_CHUNK_ICCP,     // ICCP
  WEBP_CHUNK_ANIM,     // ANIM
  WEBP_CHUNK_ANMF,     // ANMF
  WEBP_CHUNK_ALPHA,    // ALPH
  WEBP_CHUNK_IMAGE,    // VP8/VP8L
  WEBP_CHUNK_EXIF,     // EXIF
  WEBP_CHUNK_XMP,      // XMP
  WEBP_CHUNK_UNKNOWN,  // Other chunks.
  WEBP_CHUNK_NIL
} WebPChunkId;

WebPGetMuxVersion()

Renvoie le numéro de version de la bibliothèque mux, compressé en hexadécimal à l'aide de 8 bits pour chacun des éléments majeurs/mineurs/révisions. Par exemple, la version 2.5.7 est 0x020507.

int WebPGetMuxVersion(void);

WebPMuxNew()

Crée un objet mux vide.

WebPMux* WebPMuxNew(void);
Renvoie
Pointeur vers l'objet mux vide nouvellement créé.

WebPMuxDelete()

Supprime l'objet mux.

void WebPMuxDelete(WebPMux* mux);
Paramètres
mux : objet (entrée/sortie) à supprimer

Mux Creation

WebPMuxCreate()

Crée un objet multiplex à partir de données brutes fournies au format WebP RIFF.

WebPMux* WebPMuxCreate(const WebPData* bitstream, int copy_data);
Paramètres

flux de bits : (dans) les données de flux de bits au format WebP RIFF

copy_data : la valeur 1 indique que les données données SERONT copiées dans le multiplex et la valeur 0 indique que les données ne seront PAS copiées dans l'objet mux.

Renvoie

Un pointeur vers l'objet mux créé à partir de données données, en cas de réussite.

NULL : en cas de données non valides ou d'erreur de mémoire.

Fragments non illustrés

WebPMuxSetChunk()

Ajoute un fragment avec l'ID fourcc et les données chunk_data dans l'objet mux. Tous les fragments existants ayant le même ID seront supprimés.

WebPMuxError WebPMuxSetChunk(WebPMux* mux,
                             const char fourcc[4],
                             const WebPData* chunk_data,
                             int copy_data);

Remarque:Seuls les fragments qui ne sont pas liés à des images doivent être gérés via des API fragmentées. (Les blocs liés à l'image sont: "ANMF", "FRGM", "VP8", "VP8L" et "ALPH"). Pour ajouter, obtenir et supprimer des images, utilisez WebPMuxSetImage(), WebPMuxPushFrame(), WebPMuxGetFrame() et WebPMuxDeleteFrame().

Paramètres

mux : objet (entrée/sortie) auquel le fragment doit être ajouté

fourcc : (dans) un tableau de caractères contenant les quatre cc du fragment donné ; par exemple, "ICCP", "XMP ", "EXIF", etc.

chunk_data : (dans) les données fragmentées à ajouter

copy_data : la valeur 1 indique que les données données SERONT copiées dans le multiplex et la valeur 0 indique que les données ne seront PAS copiées dans l'objet mux.

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si mux, fourcc ou bloc_data est NULL, ou si fourcc correspond à un fragment d'image.

WEBP_MUX_MEMORY_ERROR : erreur d'allocation de mémoire.

WEBP_MUX_OK -- en cas de réussite.

WebPMuxGetChunk()

Récupère une référence aux données du fragment ayant l'ID fourcc dans l'objet mux. L'appelant ne doit PAS libérer les données renvoyées.

WebPMuxError WebPMuxGetChunk(const WebPMux* mux,
                             const char fourcc[4],
                             WebPData* chunk_data);
Paramètres

mux : objet (in) à partir duquel les données fragmentées doivent être extraites.

fourcc : (dans) un tableau de caractères contenant les quatre cc du fragment ; par exemple, "ICCP", "XMP ", "EXIF", etc.

chunk_data : (sortie) des données fragmentées renvoyées

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si mux, fourcc ou bloc_data est NULL, ou si fourcc correspond à un fragment d'image.

WEBP_MUX_NOT_FOUND : si le multiplex ne contient pas de fragment avec l'ID donné.

WEBP_MUX_OK -- en cas de réussite.

WebPMuxDeleteChunk()

Supprime le fragment avec le fourcc donné de l'objet mux.

WebPMuxError WebPMuxDeleteChunk(WebPMux* mux, const char fourcc[4]);
Paramètres

mux : objet (entrée/sortie) dans lequel le fragment doit être supprimé

fourcc : (dans) un tableau de caractères contenant les quatre cc du fragment ; par exemple, "ICCP", "XMP ", "EXIF", etc.

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si mux ou fourcc est NULL ou si fourcc correspond à un fragment d'image.

WEBP_MUX_NOT_FOUND : si le multiplexeur ne contient pas de bloc avec le fourcc donné.

WEBP_MUX_OK -- en cas de réussite.

Images

Encapsule les données sur une seule image/fragment.

struct WebPMuxFrameInfo {
  WebPData    bitstream;  // image data: can be a raw VP8/VP8L bitstream
                          // or a single-image WebP file.
  int         x_offset;   // x-offset of the frame.
  int         y_offset;   // y-offset of the frame.
  int         duration;   // duration of the frame (in milliseconds).

  WebPChunkId id;         // frame type: should be one of WEBP_CHUNK_ANMF,
                          // WEBP_CHUNK_FRGM or WEBP_CHUNK_IMAGE
  WebPMuxAnimDispose dispose_method;  // Disposal method for the frame.
  WebPMuxAnimBlend   blend_method;    // Blend operation for the frame.
};

WebPMuxSetImage()

Définit l'image (non animée et non fragmentée) dans l'objet mux. Remarque:Toutes les images existantes (y compris les cadres/fragments) seront supprimées.

WebPMuxError WebPMuxSetImage(WebPMux* mux,
                             const WebPData* bitstream,
                             int copy_data);
Paramètres

mux : objet (entrée/sortie) dans lequel l'image doit être définie

flux de bits : (dans) peut être un flux de bits VP8/VP8L brut ou un fichier WebP à une seule image (non animé et non fragmenté)

copy_data : la valeur 1 indique que les données données SERONT copiées dans le multiplex et la valeur 0 indique que les données ne seront PAS copiées dans l'objet mux.

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si mux est NULL ou si le flux de bits est NULL.

WEBP_MUX_MEMORY_ERROR : erreur d'allocation de mémoire.

WEBP_MUX_OK -- en cas de réussite.

WebPMuxPushFrame()

Ajoute un frame à la fin de l'objet mux.

WebPMuxError WebPMuxPushFrame(WebPMux* mux,
                              const WebPMuxFrameInfo* frame,
                              int copy_data);

Remarques :

  1. frame.id doit être WEBP_CHUNK_ANMF ou WEBP_CHUNK_FRGM
  2. Pour définir une image non animée et non fragmentée, utilisez plutôt WebPMuxSetImage().
  3. Le type de frame intégré doit être identique à celui des cadres mux.
  4. Comme WebP n'accepte que les décalages pairs, tout décalage impair sera ancré à un emplacement pair avec offset &= ~1
Paramètres

mux : objet (entrée/sortie) auquel la trame doit être ajoutée

frame : données de frame.

copy_data : la valeur 1 indique que les données données SERONT copiées dans le multiplex et la valeur 0 indique que les données ne seront PAS copiées dans l'objet mux.

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si le multiplex ou le frame est NULL ou si le contenu de frame n'est pas valide.

WEBP_MUX_MEMORY_ERROR : erreur d'allocation de mémoire.

WEBP_MUX_OK -- en cas de réussite.

WEBP_MUX_MEMORY_ERROR : erreur d'allocation de mémoire.

WebPMuxGetFrame()

Récupère le nième frame de l'objet mux. Le contenu de frame->bitstream est alloué à l'aide de malloc() et n'appartient PAS à l'objet mux. Il DOIT être désalloué par l'appelant en appelant WebPDataClear(). nth=0 a une signification particulière : dernière position.

WebPMuxError WebPMuxGetFrame(const WebPMux* mux,
                             uint32_t nth,
                             WebPMuxFrameInfo* frame);
Paramètres

mux : objet (dans) à partir duquel les informations doivent être extraites.

nth : indice (in) de la trame dans l'objet mux.

frame : données (out) de la trame renvoyée

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si le multiplex ou la trame est NULL.

WEBP_MUX_NOT_FOUND : s'il y a moins de nièmes frames dans l'objet mux.

WEBP_MUX_BAD_DATA : si le nième fragment de frame dans mux n'est pas valide.

WEBP_MUX_OK -- en cas de réussite.

WebPMuxDeleteFrame()

Supprime une image de l'objet multiplex. nth=0 a une signification particulière : dernière position.

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);
Paramètres

mux : objet (entrée/sortie) dans lequel une trame doit être supprimée

nth : (in) position à partir de laquelle l'image doit être supprimée.

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si mux est nul.

WEBP_MUX_NOT_FOUND : s'il y a moins de n-ièmes frames dans l'objet mux avant la suppression.

WEBP_MUX_OK -- en cas de réussite.

Animation

Paramètres d'animation

struct WebPMuxAnimParams {
  uint32_t bgcolor;  // Background color of the canvas stored (in MSB order) as:
                     // Bits 00 to 07: Alpha.
                     // Bits 08 to 15: Red.
                     // Bits 16 to 23: Green.
                     // Bits 24 to 31: Blue.
  int loop_count;    // Number of times to repeat the animation [0 = infinite].
};

WebPMuxSetAnimationParams()

Définit les paramètres d'animation dans l'objet mux. Tous les fragments ANIM existants seront supprimés.

WebPMuxError WebPMuxSetAnimationParams(WebPMux* mux,
                                       const WebPMuxAnimParams* params);
Paramètres

mux : objet (entrée/sortie) dans lequel le bloc ANIM doit être défini/ajouté

params : (in) paramètres d'animation.

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si mux ou params est nul.

WEBP_MUX_MEMORY_ERROR : erreur d'allocation de mémoire.

WEBP_MUX_OK -- en cas de réussite.

WebPMuxGetAnimationParams()

Récupère les paramètres d'animation de l'objet mux.

WebPMuxError WebPMuxGetAnimationParams(const WebPMux* mux,
                                       WebPMuxAnimParams* params);
Paramètres

mux : objet (in) à partir duquel les paramètres d'animation doivent être extraits.

params : (out) paramètres d'animation extraits du bloc ANIM

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si mux ou params est nul.

WEBP_MUX_NOT_FOUND : si l'élément ANIM bloc n'est pas présent dans l'objet mux.

WEBP_MUX_OK -- en cas de réussite.

Utilitaires divers

WebPMuxGetCanvasSize()

Récupère la taille de la toile à partir de l'objet mux.

WebPMuxError WebPMuxGetCanvasSize(const WebPMux* mux,
                                  int* width,
                                  int* height);

Remarque:Cette méthode suppose que le fragment VP8X, s'il est présent, est à jour. Autrement dit, l'objet mux n'a pas été modifié depuis le dernier appel à WebPMuxAssemble() ou WebPMuxCreate().

Paramètres

mux : objet (in) à partir duquel la taille de la toile doit être extraite.

largeur : largeur (hors) du canevas

height : hauteur (hors) de la toile

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si le multiplex, la largeur ou la hauteur est NULL.

WEBP_MUX_BAD_DATA : si la taille du fragment ou du canevas VP8X/VP8/VP8L n'est pas valide.

WEBP_MUX_OK -- en cas de réussite.

WebPMuxGetFeatures()

Récupère les commutateurs de fonctionnalité à partir de l'objet mux.

WebPMuxError WebPMuxGetFeatures(const WebPMux* mux, uint32_t* flags);

Remarque:Cette méthode suppose que le fragment VP8X, s'il est présent, est à jour. Autrement dit, l'objet mux n'a pas été modifié depuis le dernier appel à WebPMuxAssemble() ou WebPMuxCreate().

Paramètres

mux : objet (dans) à partir duquel les caractéristiques doivent être extraites.

flags : indicateurs spécifiant les fonctionnalités présentes dans l'objet mux. Il s'agira d'un OR de différentes valeurs d'indicateurs. L'énumération WebPFeatureFlags peut être utilisée pour tester les valeurs d'indicateurs individuels.

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si mux ou indicateurs sont NULL.

WEBP_MUX_BAD_DATA : si la taille du fragment ou du canevas VP8X/VP8/VP8L n'est pas valide.

WEBP_MUX_OK -- en cas de réussite.

WebPMuxNumChunks()

Récupère le nombre de fragments ayant la valeur de tag donnée dans l'objet mux.

WebPMuxError WebPMuxNumChunks(const WebPMux* mux,
                              WebPChunkId id,
                              int* num_elements);
Paramètres

mux : objet (dans) à partir duquel les informations doivent être extraites.

id : (in) ID de fragment spécifiant le type de fragment

num_elements : nombre (total) de fragments avec l'ID de fragment donné

Renvoie

WEBP_MUX_INVALID_ARGUMENT : si mux ou num_elements est nul.

WEBP_MUX_OK -- en cas de réussite.

WebPMuxAssemble()

Assemble tous les fragments au format WebP RIFF et les renvoie dans assembled_data. Cette fonction valide également l'objet mux.

WebPMuxError WebPMuxAssemble(WebPMux* mux, WebPData* assembled_data);

Remarque:Le contenu de assembled_data sera ignoré et écrasé. En outre, le contenu de assembled_data est alloué à l'aide de malloc(), et n'appartient PAS à l'objet mux. Il DOIT être désalloué par l'appelant en appelant WebPDataClear().

Paramètres

mux : objet (entrée/sortie) dont les fragments doivent être assemblés

assembled_data : données WebP assemblées (hors)

Renvoie

WEBP_MUX_BAD_DATA : si l'objet mux n'est pas valide.

WEBP_MUX_INVALID_ARGUMENT : si mux ou assembled_data est nul.

WEBP_MUX_MEMORY_ERROR : erreur d'allocation de mémoire.

WEBP_MUX_OK -- en cas de réussite.

API WebPAnimEncoder

Cette API permet d'encoder (éventuellement) des images WebP animées.

Exemple de code

WebPAnimEncoderOptions enc_options;
WebPAnimEncoderOptionsInit(&enc_options);
// Tune 'enc_options' as needed.
WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options);
while(<there are more frames>) {
  WebPConfig config;
  WebPConfigInit(&config);
  // Tune 'config' as needed.
  WebPAnimEncoderAdd(enc, frame, timestamp_ms, &config);
}
WebPAnimEncoderAdd(enc, NULL, timestamp_ms, NULL);
WebPAnimEncoderAssemble(enc, webp_data);
WebPAnimEncoderDelete(enc);
// Write the 'webp_data' to a file, or re-mux it further.

typedef struct WebPAnimEncoder WebPAnimEncoder;  // Main opaque object.

Options globales

struct WebPAnimEncoderOptions {
  WebPMuxAnimParams anim_params;  // Animation parameters.
  int minimize_size;    // If true, minimize the output size (slow). Implicitly
                        // disables key-frame insertion.
  int kmin;
  int kmax;             // Minimum and maximum distance between consecutive key
                        // frames in the output. The library may insert some key
                        // frames as needed to satisfy this criteria.
                        // Note that these conditions should hold: kmax > kmin
                        // and kmin >= kmax / 2 + 1. Also, if kmax <= 0, then
                        // key-frame insertion is disabled; and if kmax == 1,
                        // then all frames will be key-frames (kmin value does
                        // not matter for these special cases).
  int allow_mixed;      // If true, use mixed compression mode; may choose
                        // either lossy and lossless for each frame.
  int verbose;          // If true, print info and warning messages to stderr.
};

WebPAnimEncoderOptionsInit()

Doit toujours être appelé pour initialiser une nouvelle structure WebPAnimEncoderOptions avant la modification. Renvoie la valeur "false" en cas de non-concordance des versions. WebPAnimEncoderOptionsInit() doit avoir réussi avant d'utiliser l'objet enc_options.

Paramètres
enc_options : options (entrée/sortie) utilisées pour encoder l'animation
Renvoie
Véritablement efficace,
int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderNew()

Crée et initialise un objet WebPAnimEncoder.

Paramètres

width/height : largeur (pouce) et hauteur du canevas de l'animation.

enc_options : (dans) options d'encodage ; peut être transmis avec la valeur NULL pour choisir des valeurs par défaut raisonnables.

Renvoie

Pointeur vers l'objet WebPAnimEncoder nouvellement créé, ou valeur NULL en cas d'erreur de mémoire.

WebPAnimEncoder* WebPAnimEncoderNew(
    int width, int height, const WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderAdd()

Optimiser le frame donné pour WebP, l'encoder et l'ajouter à l'objet WebPAnimEncoder.

Le dernier appel à WebPAnimEncoderAdd doit être effectué avec frame = NULL, ce qui indique qu'aucun autre frame ne doit être ajouté. Cet appel permet également de déterminer la durée de la dernière image.

Paramètres

enc : objet (entrée/sortie) auquel l'image doit être ajoutée.

frame : données de frame (entrée/sortie) au format ARVB ou YUV(A). S'il est au format YUV(A), il est converti en ARVB, ce qui entraîne une légère perte.

timestamp_ms : horodatage (in) de cette image, en millisecondes. La durée d'une trame est calculée comme suit : "code temporel du frame suivant - horodatage de cette trame". Par conséquent, les codes temporels doivent être dans l'ordre non décroissant.

config : (dans) options d'encodage ; peut être transmis avec la valeur NULL pour choisir des valeurs par défaut raisonnables.

Renvoie

En cas d'erreur, renvoie la valeur "false" et frame->error_code est défini de manière appropriée. Sinon, renvoie la valeur "true".

int WebPAnimEncoderAdd(
    WebPAnimEncoder* enc, struct WebPPicture* frame, int timestamp_ms,
    const struct WebPConfig* config);

WebPAnimEncoderAssemble()

Assembler tous les frames ajoutés jusqu'à présent dans un flux de bits WebP. Cet appel doit être précédé d'un appel à WebPAnimEncoderAdd avec frame = NULL. Sinon, la durée de la dernière image sera estimée en interne.

Paramètres

enc : objet (entrée/sortie) à partir duquel les cadres doivent être assemblés.

webp_data : flux de bits WebP généré (sortant).

Renvoie

Vrai au succès.

int WebPAnimEncoderAssemble(WebPAnimEncoder* enc, WebPData* webp_data);

WebPAnimEncoderGetError()

Obtenir la chaîne d'erreur correspondant à l'appel le plus récent en utilisant enc La chaîne renvoyée appartient à enc et n'est valide que jusqu'au prochain appel de WebPAnimEncoderAdd(), WebPAnimEncoderAssemble() ou WebPAnimEncoderDelete().

Paramètres
enc : objet (entrant/sortant) à partir duquel la chaîne d'erreur doit être extraite.
Renvoie
NULL if enc is NULL. Sinon, renvoie la chaîne d'erreur si le dernier appel à enc a rencontré une erreur ou une chaîne vide si le dernier appel a abouti.
const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

WebPAnimEncoderDelete()

Supprime l'objet WebPAnimEncoder.

Paramètres
enc -- objet (entrée/sortie) à supprimer
void WebPAnimEncoderDelete(WebPAnimEncoder* enc);

API Demux

Permet d'extraire des données d'image et de format étendu à partir de fichiers WebP.

Exemples de code

Démuxing des données WebP pour extraire toutes les images, le profil ICC et les métadonnées EXIF/XMP

WebPDemuxer* demux = WebPDemux(&webp_data);

uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH);
uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT);
// ... (Get information about the features present in the WebP file).
uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS);

// ... (Iterate over all frames).
WebPIterator iter;
if (WebPDemuxGetFrame(demux, 1, &iter)) {
  do {
    // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(),
    // ... and get other frame properties like width, height, offsets etc.
    // ... see 'struct WebPIterator' below for more info).
  } while (WebPDemuxNextFrame(&iter));
  WebPDemuxReleaseIterator(&iter);
}

// ... (Extract metadata).
WebPChunkIterator chunk_iter;
if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter);
// ... (Consume the ICC profile in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter);
// ... (Consume the EXIF metadata in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter);
// ... (Consume the XMP metadata in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
WebPDemuxDelete(demux);

Vie d'un objet Demux

Enums

typedef enum WebPDemuxState {
  WEBP_DEMUX_PARSE_ERROR    = -1,  // An error occurred while parsing.
  WEBP_DEMUX_PARSING_HEADER =  0,  // Not enough data to parse full header.
  WEBP_DEMUX_PARSED_HEADER  =  1,  // Header parsing complete,
                                   // data may be available.
  WEBP_DEMUX_DONE           =  2   // Entire file has been parsed.
} WebPDemuxState;

WebPGetDemuxVersion()

Renvoie le numéro de version de la bibliothèque demux, compressé en hexadécimal à l'aide de 8 bits pour chacun des éléments majeurs/mineurs/révisions. Par exemple, la version 2.5.7 est 0x020507.

int WebPGetDemuxVersion(void);

WebPDemux()

Analyse le fichier WebP complet fourni par data.

WebPDemuxer WebPDemux(const WebPData* data);

Renvoie un objet WebPDemuxer en cas d'analyse réussie. Sinon, renvoie la valeur NULL.

WebPDemuxPartial()

Analyse le fichier WebP potentiellement incomplet fourni par data. Si la valeur state est non NULL, elle est définie pour indiquer l'état du démuxeur.

WebPDemuxer WebPDemuxPartial(const WebPData* data, WebPDemuxState* state);

Renvoie la valeur NULL en cas d'erreur ou s'il n'y a pas assez de données pour commencer l'analyse, ainsi qu'un objet WebPDemuxer lorsque l'analyse aboutit.

Notez que WebPDemuxer conserve les pointeurs internes vers le segment de mémoire des données. Si ces données sont volatiles, l'objet de multiplexeur doit être supprimé (en appelant WebPDemuxDelete()) et appelé à nouveau WebPDemuxPartial() sur les nouvelles données. Cette opération est généralement peu coûteuse.

WebPDemuxDelete()

Libère de la mémoire associée à dmux.

void WebPDemuxDelete(WebPDemuxer* dmux);

Extraction de données/informations

typedef enum WebPFormatFeature {
  WEBP_FF_FORMAT_FLAGS,      // bit-wise combination of WebPFeatureFlags
                             // corresponding to the 'VP8X' chunk (if present).
  WEBP_FF_CANVAS_WIDTH,
  WEBP_FF_CANVAS_HEIGHT,
  WEBP_FF_LOOP_COUNT,        // only relevant for animated file
  WEBP_FF_BACKGROUND_COLOR,  // idem.
  WEBP_FF_FRAME_COUNT        // Number of frames present in the demux object.
                             // In case of a partial demux, this is the number
                             // of frames seen so far, with the last frame
                             // possibly being partial.
} WebPFormatFeature;

WebPDemuxGetI()

Obtenez la valeur de feature à partir du dmux.

uint32_t WebPDemuxGetI(const WebPDemuxer* dmux, WebPFormatFeature feature);

Remarque:Les valeurs ne sont valides que si WebPDemux() a été utilisé ou si WebPDemuxPartial() a renvoyé un état > WEBP_DEMUX_PARSING_HEADER.

Itération de frame

struct WebPIterator {
  int frame_num;
  int num_frames;          // equivalent to WEBP_FF_FRAME_COUNT.
  int fragment_num;
  int num_fragments;
  int x_offset, y_offset;  // offset relative to the canvas.
  int width, height;       // dimensions of this frame or fragment.
  int duration;            // display duration in milliseconds.
  WebPMuxAnimDispose dispose_method;  // dispose method for the frame.
  int complete;   // true if 'fragment' contains a full frame. partial images
                  // may still be decoded with the WebP incremental decoder.
  WebPData fragment;  // The frame or fragment given by 'frame_num' and
                      // 'fragment_num'.
  int has_alpha;      // True if the frame or fragment contains transparency.
  WebPMuxAnimBlend blend_method;  // Blend operation for the frame.
};

WebPDemuxGetFrame()

Récupère le frame frame_number à partir de dmux.

int WebPDemuxGetFrame(const WebPDemuxer* dmux,
                      int frame_number,
                      WebPIterator* iter);

iter->fragment pointe vers le premier fragment au retour de cette fonction. Les fragments individuels peuvent être extraits à l'aide de WebPDemuxSelectFragment(). Si vous définissez frame_number sur 0, la dernière image de l'image sera affichée.

Renvoie la valeur "false" si dmux est NULL ou si le cadre frame_number n'est pas présent. Appelez WebPDemuxReleaseIterator() lorsque l'utilisation de l'itérateur est terminée.

Remarque:dmux doit persister pendant toute la durée de vie de iter.

WebPDemuxNextFrame(), WebPDemuxPrevFrame()

Définit iter->fragment pour qu'il pointe vers l'image suivante (iter->frame_num + 1) ou précédente (iter->frame_num - 1). Ces fonctions ne sont pas lues en boucle.

int WebPDemuxNextFrame(WebPIterator* iter);
int WebPDemuxPrevFrame(WebPIterator* iter);

Renvoie la valeur "true" en cas de réussite, et la valeur "false" dans le cas contraire.

WebPDemuxSelectFragment()

Définit iter->fragment pour refléter le numéro de fragment fragment_num.

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

Renvoie la valeur "true" si le fragment fragment_num est présent, ou "false" dans le cas contraire.

WebPDemuxReleaseIterator()

Libère toute la mémoire associée à iter.

void WebPDemuxReleaseIterator(WebPIterator* iter);

Doit être appelé avant tout appel ultérieur à WebPDemuxGetChunk() sur le même itérateur. Elle doit également être appelée avant de détruire le WebPDemuxer associé avec WebPDemuxDelete().

Itération des fragments

struct WebPChunkIterator {
  // The current and total number of chunks with the fourcc given to
  // WebPDemuxGetChunk().
  int chunk_num;
  int num_chunks;
  WebPData chunk;    // The payload of the chunk.
};

WebPDemuxGetChunk()

Récupère l'instance chunk_number du fragment ayant l'ID fourcc à partir de dmux.

int WebPDemuxGetChunk(const WebPDemuxer* dmux,
                      const char fourcc[4], int chunk_number,
                      WebPChunkIterator* iter);

fourcc est un tableau de caractères contenant les quatre cc du fragment à renvoyer, par exemple "ICCP", "XMP ", "EXIF", etc.

Si vous définissez chunk_number sur 0, le dernier fragment d'un ensemble sera renvoyé.

Renvoie la valeur "true" si le fragment est détecté, et la valeur "false" dans le cas contraire. Les charges utiles de fragments liées aux images sont accessibles via WebPDemuxGetFrame() et les fonctions associées. Appelez WebPDemuxReleaseChunkIterator() lorsque l'utilisation de l'itérateur est terminée.

Remarque:dmux doit persister pendant toute la durée de vie de l'itérateur.

WebPDemuxNextChunk(), WebPDemuxPrevChunk()

Définit iter->chunk pour qu'il pointe vers le fragment suivant (iter->chunk_num + 1) ou précédent (iter->chunk_num - 1). Ces fonctions ne sont pas lues en boucle.

int WebPDemuxNextChunk(WebPChunkIterator* iter);
int WebPDemuxPrevChunk(WebPChunkIterator* iter);

Renvoie la valeur "true" en cas de réussite, et la valeur "false" dans le cas contraire.

WebPDemuxReleaseChunkIterator()

Libère toute la mémoire associée à iter.

void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);

Doit être appelé avant de détruire le WebPDemuxer associé avec WebPDemuxDelete().

API WebPAnimDecoder

Cette API permet de décoder (éventuellement) des images WebP animées.

Exemple de code

WebPAnimDecoderOptions dec_options;
WebPAnimDecoderOptionsInit(&dec_options);
// Tune 'dec_options' as needed.
WebPAnimDecoder* dec = WebPAnimDecoderNew(webp_data, &dec_options);
WebPAnimInfo anim_info;
WebPAnimDecoderGetInfo(dec, &anim_info);
for (uint32_t i = 0; i < anim_info.loop_count; ++i) {
  while (WebPAnimDecoderHasMoreFrames(dec)) {
    uint8_t* buf;
    int timestamp;
    WebPAnimDecoderGetNext(dec, &buf, &timestamp);
    // ... (Render 'buf' based on 'timestamp').
    // ... (Do NOT free 'buf', as it is owned by 'dec').
  }
  WebPAnimDecoderReset(dec);
}
const WebPDemuxer* demuxer = WebPAnimDecoderGetDemuxer(dec);
// ... (Do something using 'demuxer'; e.g. get EXIF/XMP/ICC data).
WebPAnimDecoderDelete(dec);

typedef struct WebPAnimDecoder WebPAnimDecoder;  // Main opaque object.

Options globales

struct WebPAnimDecoderOptions {
  // Output colorspace. Only the following modes are supported:
  // MODE_RGBA, MODE_BGRA, MODE_rgbA and MODE_bgrA.
  WEBP_CSP_MODE color_mode;
  int use_threads;           // If true, use multi-threaded decoding.
};

WebPAnimDecoderOptionsInit()

Doit toujours être appelé pour initialiser une nouvelle structure WebPAnimDecoderOptions avant la modification. Renvoie la valeur "false" en cas de non-concordance des versions. WebPAnimDecoderOptionsInit() doit avoir réussi avant d'utiliser l'objet dec_options.

Paramètres

dec_options : options (entrée/sortie) utilisées pour décoder l'animation

Renvoie
La réussite, vraie
int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options);

WebPAnimDecoderNew()

Crée et initialise un objet WebPAnimDecoder.

Paramètres

webp_data : (dans) un flux de bits WebP. Cet élément ne doit pas être modifié pendant toute la durée de vie de l'objet WebPAnimDecoder de sortie.

dec_options : (in) options de décodage. La valeur NULL peut être transmise pour choisir des valeurs par défaut raisonnables (le mode couleur MODE_RVBA est en particulier choisi).

Renvoie

Pointeur vers le nouvel objet WebPAnimDecoder, ou valeur NULL en cas d'erreur d'analyse, d'option non valide ou d'erreur de mémoire.

WebPAnimDecoder* WebPAnimDecoderNew(
    const WebPData* webp_data, const WebPAnimDecoderOptions* dec_options);

Informations générales sur l'animation.

struct WebPAnimInfo {
  uint32_t canvas_width;
  uint32_t canvas_height;
  uint32_t loop_count;
  uint32_t bgcolor;
  uint32_t frame_count;
};

WebPAnimDecoderGetInfo()

Permet d'obtenir des informations globales sur l'animation.

Paramètres

dec : (in) instance du décodeur à partir de laquelle récupérer les informations.

info : (out) des informations globales extraites de l'animation.

Renvoie

Vrai au succès.

int WebPAnimDecoderGetInfo(const WebPAnimDecoder* dec,
                           WebPAnimInfo* info);

WebPAnimDecoderGetNext()

Extrait la trame suivante de dec en fonction des options fournies à WebPAnimDecoderNew(). Il s'agira d'un canevas entièrement reconstruit de taille canvas_width * 4 * canvas_height, et pas seulement du sous-rectangle de l'image. Le tampon buf renvoyé n'est valide que jusqu'au prochain appel de WebPAnimDecoderGetNext(), WebPAnimDecoderReset() ou WebPAnimDecoderDelete().

Paramètres

dec : instance du décodeur (entrée/sortie) à partir de laquelle la trame suivante doit être extraite.

buf : trame décodée (sortante).

timestamp : horodatage (out) de la trame en millisecondes.

Renvoie

"False" si l'un des arguments est NULL, en cas d'erreur d'analyse ou de décodage, ou s'il n'y a plus de trames. Sinon, renvoie la valeur "true".

int WebPAnimDecoderGetNext(WebPAnimDecoder* dec,
                           uint8_t** buf, int* timestamp);

WebPAnimDecoderHasMoreFrames()

Vérifiez s'il reste d'autres images à décoder.

Paramètres
dec : (dans) l'instance du décodeur à vérifier.
Renvoie
Présente la valeur "true" si dec n'est pas NULL et que certains frames n'ont pas encore été décodés. Sinon, renvoie la valeur "false".
int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

WebPAnimDecoderReset()

Réinitialise l'objet WebPAnimDecoder, de sorte que le prochain appel à WebPAnimDecoderGetNext() redémarre le décodage à partir de la première image. Cela est utile lorsque tous les frames doivent être décodés plusieurs fois (par exemple, infos.loop_count fois) sans détruire et recréer l'objet dec.

Paramètres
dec -- l'instance de décodeur (entrée/sortie) à réinitialiser
void WebPAnimDecoderReset(WebPAnimDecoder* dec);

WebPAnimDecoderGetDemuxer()

Récupérez l'objet de multiplexeur interne.

L'obtention de l'objet de multiplexeur peut être utile si vous souhaitez utiliser des opérations disponibles uniquement via ce module, par exemple pour obtenir les métadonnées XMP/EXIF/ICC. L'objet demuxer renvoyé appartient à dec et n'est valide que jusqu'au prochain appel de WebPAnimDecoderDelete().

Paramètres
dec : (dans) l'instance du décodeur à partir de laquelle l'objet du démuxeur doit être extrait.
const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

Supprime l'objet WebPAnimDecoder.

Paramètres
dec : instance du décodeur (entrée/sortie) à supprimer.
Renvoie
Véritablement efficace,
void WebPAnimDecoderDelete(WebPAnimDecoder* dec);

Types de données courants

Enums

typedef enum WebPFeatureFlags {
  FRAGMENTS_FLAG  = 0x00000001,
  ANIMATION_FLAG  = 0x00000002,
  XMP_FLAG        = 0x00000004,
  EXIF_FLAG       = 0x00000008,
  ALPHA_FLAG      = 0x00000010,
  ICCP_FLAG       = 0x00000020
} WebPFeatureFlags;

// Dispose method (animation only). Indicates how the area used by the current
// frame is to be treated before rendering the next frame on the canvas.
typedef enum WebPMuxAnimDispose {
  WEBP_MUX_DISPOSE_NONE,       // Do not dispose.
  WEBP_MUX_DISPOSE_BACKGROUND  // Dispose to background color.
} WebPMuxAnimDispose;

// Blend operation (animation only). Indicates how transparent pixels of the
// current frame are blended with those of the previous canvas.
typedef enum WebPMuxAnimBlend {
  WEBP_MUX_BLEND,              // Blend.
  WEBP_MUX_NO_BLEND            // Do not blend.
} WebPMuxAnimBlend;

WebPDataInit()

Initialise le contenu de l'objet webp_data avec les valeurs par défaut.

void WebPDataInit(WebPData* webp_data);

WebPDataClear()

Efface le contenu de l'objet webp_data en appelant free(). ne désaffecte pas l'objet lui-même ;

void WebPDataClear(WebPData* webp_data);

WebPDataCopy()

Alloue l'espace de stockage nécessaire pour dst et copie le contenu de src. Renvoie la valeur "true" en cas de réussite.

int WebPDataCopy(const WebPData* src, WebPData* dst);