Dokumentation zur WebP Container API

RIFF-Containermanipulation für WebP-Bilder.

Mux-API

Ermöglicht die Bearbeitung von WebP-Container-Images, die Features wie Farbprofil, Metadaten, Animation und fragmentierte Images enthalten.

Codebeispiele

Erstellen eines MUX mit Bilddaten, Farbprofil und XMP-Metadaten

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

Bild- und Farbprofildaten aus einer WebP-Datei abrufen

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

Leben eines Mux-Objekts

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()

Gibt die Versionsnummer der Mux-Bibliothek zurück, die in hexadezimal verpackt ist und jeweils 8 Bit für Haupt-, Neben- und Überarbeitungselemente verwendet wird. Beispiel: Version 2.5.7 ist 0x020507.

int WebPGetMuxVersion(void);

WebPMuxNew()

Erstellt ein leeres mux-Objekt.

WebPMux* WebPMuxNew(void);

Rückgaben

Ein Zeiger auf das neu erstellte leere Mux-Objekt.

WebPMuxDelete()

Löscht das Mux-Objekt.

void WebPMuxDelete(WebPMux* mux);

Parameter

mux – Objekt, das gelöscht werden soll (Ein-/Ausgang)

Mux-Erstellung

WebPMuxCreate()

Erstellt ein Mux-Objekt aus Rohdaten, die im WebP RIFF-Format angegeben wurden.

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

Parameter

bitstream – (in) die Bitstream-Daten im WebP-RIFF-Format

copy_data – (in) Wert 1 gibt an, dass bestimmte Daten in den Mux kopiert werden, und Wert 0 gibt an, dass Daten NICHT in das mux-Objekt kopiert werden.

Rückgaben

Ein Zeiger auf das Mux-Objekt, das bei Erfolg aus den angegebenen Daten erstellt wurde.

NULL: bei ungültigen Daten oder Speicherfehlern.

Nicht-Image-Blöcke

WebPMuxSetChunk()

Fügt einen Chunk mit der ID fourcc und den Daten chunk_data im mux-Objekt hinzu. Alle vorhandenen Blöcke mit derselben ID werden entfernt.

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

Hinweis: Nur Blöcke, die sich nicht auf Bilder beziehen, sollten über Chunk-APIs verwaltet werden. Zu den bildbezogenen Teilstücken gehören "ANMF", "FRGM", "VP8 ", "VP8L" und "ALPH". Verwenden Sie zum Hinzufügen, Abrufen und Löschen von Bildern WebPMuxSetImage(), WebPMuxPushFrame(), WebPMuxGetFrame() und WebPMuxDeleteFrame().

Parameter

mux – Ein-/Ausgangsobjekt, dem der Chunk hinzugefügt werden soll.

fourcc – (in) ein Zeichenarray, das die Fourcc des angegebenen Chunks enthält, z.B. „ICCP“, „XMP“, „EXIF“ usw.

chunk_data – (in) die hinzuzufügenden Chunk-Daten

copy_data – (in) Wert 1 gibt an, dass bestimmte Daten in den Mux kopiert werden, und Wert 0 gibt an, dass Daten NICHT in das mux-Objekt kopiert werden.

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn mux, viercc oder chunk_data NULL sind oder wenn fourcc einem Bildblock entspricht.

WEBP_MUX_MEMORY_ERROR: bei einem Fehler bei der Arbeitsspeicherzuweisung.

WEBP_MUX_OK: bei Erfolg.

WebPMuxGetChunk()

Ruft einen Verweis auf die Daten des Chunks mit der ID fourcc im Mux-Objekt ab. Der Aufrufer sollte die zurückgegebenen Daten NICHT freigeben.

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

Parameter

mux – (in), von dem die Blockdaten abgerufen werden sollen

fourcc – (in) ein Zeichenarray, das die Fourcc des Blocks enthält, z.B. „ICCP“, „XMP“, „EXIF“ usw.

chunk_data – (out) zurückgegebene Chunk-Daten

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn mux, viercc oder chunk_data NULL sind oder wenn fourcc einem Bildblock entspricht.

WEBP_MUX_NOT_FOUND: Wenn mux keinen Chunk mit der angegebenen ID enthält.

WEBP_MUX_OK: bei Erfolg.

WebPMuxDeleteChunk()

Löscht den Chunk mit dem angegebenen fourcc aus dem mux-Objekt.

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

Parameter

mux – Ein-/Ausgangsobjekt, aus dem der Block gelöscht werden soll.

fourcc – (in) ein Zeichenarray, das die Fourcc des Blocks enthält, z.B. „ICCP“, „XMP“, „EXIF“ usw.

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn „mux“ oder „viercc“ den Wert NULL hat oder wenn „viercc“ einem Bildblock entspricht.

WEBP_MUX_NOT_FOUND: Wenn mux keinen Chunk mit der angegebenen Fourcc enthält.

WEBP_MUX_OK: bei Erfolg.

Bilder

Kapselt Daten zu einem einzelnen Frame/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()

Legt das (nicht animierte und nicht fragmentierte) Bild im mux-Objekt fest. Hinweis:Alle vorhandenen Bilder, einschließlich Frames und Fragmente, werden entfernt.

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

Parameter

mux – Objekt, in dem das Bild festgelegt werden soll.

bitstream – (in) kann ein unformatierter VP8-/VP8L-Bitstream oder eine WebP-Datei mit einem einzelnen Bild (nicht animiert und nicht fragmentiert) sein.

copy_data – (in) Wert 1 gibt an, dass bestimmte Daten in den Mux kopiert werden, und Wert 0 gibt an, dass Daten NICHT in das mux-Objekt kopiert werden.

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn mux NULL ist oder der Bitstream NULL ist.

WEBP_MUX_MEMORY_ERROR: bei einem Fehler bei der Arbeitsspeicherzuweisung.

WEBP_MUX_OK: bei Erfolg.

WebPMuxPushFrame()

Fügt einen Frame am Ende des Mux-Objekts hinzu.

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

Hinweise:

1. Frame.id muss WEBP_CHUNK_ANMF oder WEBP_CHUNK_FRGM sein.
2. Wenn du ein nicht animiertes, nicht fragmentiertes Bild festlegen möchtest, verwende stattdessen WebPMuxSetImage().
3. Der Typ des übertragenen Frames muss mit dem Frame in mux übereinstimmen.
4. Da WebP nur gerade Offsets unterstützt, wird jeder ungerade Offset mithilfe von: offset &= ~1 an einer geraden Position ausgerichtet.

Parameter

mux – Ein-/Ausgangsobjekt, dem der Frame hinzugefügt werden soll.

frame – (in) Frame-Daten

copy_data – (in) Wert 1 gibt an, dass bestimmte Daten in den Mux kopiert werden, und Wert 0 gibt an, dass Daten NICHT in das mux-Objekt kopiert werden.

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn mux oder Frame NULL ist oder wenn der Inhalt des frames ungültig ist.

WEBP_MUX_MEMORY_ERROR: bei einem Fehler bei der Arbeitsspeicherzuweisung.

WEBP_MUX_OK: bei Erfolg.

WEBP_MUX_MEMORY_ERROR: bei einem Fehler bei der Arbeitsspeicherzuweisung.

WebPMuxGetFrame()

Ruft den n-ten Frame aus dem Mux-Objekt ab. Der Inhalt von frame->bitstream wird mithilfe von malloc() zugewiesen und NICHT dem Objekt mux gehört. Sie MUSS vom Aufrufer durch Aufrufen von WebPDataClear() aufgehoben werden. hat nth=0 eine besondere Bedeutung: die letzte Position.

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

Parameter

mux – (in), von dem die Informationen abgerufen werden sollen

nth – (in) Index des Frames im Mux-Objekt

frame – Daten des zurückgegebenen Frames (aus)

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn Mux oder Frame NULL ist.

WEBP_MUX_NOT_FOUND: Wenn das mux-Objekt weniger als n-te Frames enthält.

WEBP_MUX_BAD_DATA: Wenn der n-te Frame-Chunk in mux ungültig ist.

WEBP_MUX_OK: bei Erfolg.

WebPMuxDeleteFrame()

Löscht einen Frame aus dem Mux-Objekt. "nth=0" hat eine besondere Bedeutung: "Letzte Position".

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);

Parameter

mux – Ein-/Ausgangsobjekt, aus dem ein Frame gelöscht werden soll.

nth – (in) die Position, von der aus der Frame gelöscht werden soll.

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn mux NULL ist.

WEBP_MUX_NOT_FOUND: Wenn vor dem Löschen weniger als n-te Frames im Mux-Objekt vorhanden sind.

WEBP_MUX_OK: bei Erfolg.

Animation

Animationsparameter

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()

Legt die Animationsparameter im Mux-Objekt fest. Alle vorhandenen ANIM-Blöcke werden entfernt.

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

Parameter

mux – Objekt, in dem ein ANIM-Chunk festgelegt/hinzugefügt werden soll.

params – (in) Animationsparameter.

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn mux oder params den Wert NULL hat.

WEBP_MUX_MEMORY_ERROR: bei einem Fehler bei der Arbeitsspeicherzuweisung.

WEBP_MUX_OK: bei Erfolg.

WebPMuxGetAnimationParams()

Ruft die Animationsparameter aus dem mux-Objekt ab.

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

Parameter

mux – (in), von dem die Animationsparameter abgerufen werden sollen

params -- (out) Animationsparameter, die aus dem ANIM-Chunk extrahiert wurden

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn mux oder params den Wert NULL hat.

WEBP_MUX_NOT_FOUND: Wenn der ANIM-Chunk nicht im Mux-Objekt vorhanden ist.

WEBP_MUX_OK: bei Erfolg.

Sonstige Dienstprogramme

WebPMuxGetCanvasSize()

Ruft die Canvasgröße aus dem Mux-Objekt ab.

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

Hinweis:Bei dieser Methode wird davon ausgegangen, dass der VP8X-Chunk, falls vorhanden, aktuell ist. Das heißt, das Mux-Objekt wurde seit dem letzten Aufruf von WebPMuxAssemble() oder WebPMuxCreate() nicht geändert.

Parameter

mux – Objekt (in), aus dem die Canvasgröße abgerufen werden soll

width – (aus) Canvasbreite

height – (out) Höhe der Leinwand

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn mux ist, sind Breite oder Höhe NULL.

WEBP_MUX_BAD_DATA: wenn die Chunk- oder Canvasgröße für VP8X/VP8/VP8L ungültig ist.

WEBP_MUX_OK: bei Erfolg.

WebPMuxGetFeatures()

Ruft die Funktions-Flags aus dem Mux-Objekt ab.

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

Hinweis:Bei dieser Methode wird davon ausgegangen, dass der VP8X-Chunk, falls vorhanden, aktuell ist. Das heißt, das Mux-Objekt wurde seit dem letzten Aufruf von WebPMuxAssemble() oder WebPMuxCreate() nicht geändert.

Parameter

mux – (in), aus dem die Merkmale abgerufen werden sollen

flags – (out) die Flags, die angeben, welche Merkmale im Mux-Objekt vorhanden sind. Dies ist eine ODER mit verschiedenen Flag-Werten. Mit dem Enum WebPFeatureFlags können einzelne Flag-Werte getestet werden.

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn mux oder Flags NULL sind.

WEBP_MUX_BAD_DATA: wenn die Chunk- oder Canvasgröße für VP8X/VP8/VP8L ungültig ist.

WEBP_MUX_OK: bei Erfolg.

WebPMuxNumChunks()

Ruft die Anzahl der Blöcke mit dem angegebenen Tag-Wert im mux-Objekt ab.

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

Parameter

mux – (in), von dem die Informationen abgerufen werden sollen

id – Die Chunk-ID (in), die den Typ des Chunks angibt.

num_elements – (out) Anzahl der Blöcke mit der angegebenen Chunk-ID

Rückgaben

WEBP_MUX_INVALID_ARGUMENT: Wenn mux oder num_elements NULL ist.

WEBP_MUX_OK: bei Erfolg.

WebPMuxAssemble()

Stellt alle Blöcke im WebP-RIFF-Format zusammen und gibt sie in assembled_data zurück. Diese Funktion validiert auch das mux-Objekt.

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

Hinweis:Der Inhalt von assed_data wird ignoriert und überschrieben. Außerdem wird der Inhalt von assembled_data mit Malloc() zugewiesen und NICHT dem Objekt assembled_data gehören. Sie MUSS vom Aufrufer freigegeben werden, indem er WebPDataClear() aufruft.

Parameter

mux – Objekt (in/out), dessen Chunks zusammengestellt werden sollen.

assembled_data – (out) zusammengestellte WebP-Daten

Rückgaben

WEBP_MUX_BAD_DATA: Wenn das Mux-Objekt ungültig ist.

WEBP_MUX_INVALID_ARGUMENT: Wenn mux oder assed_data NULL ist.

WEBP_MUX_MEMORY_ERROR: bei einem Fehler bei der Arbeitsspeicherzuweisung.

WEBP_MUX_OK: bei Erfolg.

WebPAnimEncoder-API

Diese API ermöglicht die Codierung animierter WebP-Bilder (möglicherweise).

Codebeispiel

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.

Globale Optionen

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()

Sollte immer aufgerufen werden, um vor der Änderung eine neue WebPAnimEncoderOptions-Struktur zu initialisieren. Gibt "false" zurück, falls Versionsdiskrepanzen auftreten. WebPAnimEncoderOptionsInit() muss erfolgreich gewesen sein, bevor das Objekt enc_options verwendet werden konnte.

Parameter

enc_options: Optionen zum Ein- und Ausschalten der Animation

Rückgaben

„True“, wenn der Vorgang erfolgreich war.

int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderNew()

Erstellt und initialisiert ein WebPAnimEncoder-Objekt.

Parameter

width/height: (in Zoll) Breite und Höhe der Animation

enc_options -- (in) Codierungsoptionen; kann NULL übergeben werden, um angemessene Standardwerte auszuwählen.

Rückgaben

Ein Zeiger auf das neu erstellte WebPAnimEncoder-Objekt oder NULL bei einem Speicherfehler.

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

WebPAnimEncoderAdd()

Optimieren Sie den gegebenen Frame für WebP, codieren Sie ihn und fügen Sie ihn dem Objekt WebPAnimEncoder hinzu.

Der letzte Aufruf von WebPAnimEncoderAdd sollte mit frame = NULL erfolgen. Damit wird angezeigt, dass keine weiteren Frames hinzugefügt werden sollen. Mit diesem Aufruf wird auch die Dauer des letzten Frames ermittelt.

Parameter

enc – Ein-/Ausgangsobjekt, dem der Frame hinzugefügt werden soll.

frame: (Ein-/Ausgang)-Framedaten im ARGB- oder YUV(A)-Format Liegt sie im YUV(A)-Format vor, wird sie in ARGB konvertiert, wodurch ein geringer Verlust entsteht.

timestamp_ms – Der Zeitstempel (in) dieses Frames in Millisekunden. Die Dauer eines Frames wird als „Zeitstempel des nächsten Frames – Zeitstempel dieses Frames“ berechnet. Daher sollten die Zeitstempel in nicht absteigender Reihenfolge angeordnet sein.

config -- (in)-Codierungsoptionen; kann NULL übergeben werden, um angemessene Standardwerte auszuwählen.

Rückgaben

Bei einem Fehler wird "false" zurückgegeben und frame->error_code ist entsprechend festgelegt. Andernfalls wird „true“ zurückgegeben.

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

WebPAnimEncoderAssemble()

Alle bisher hinzugefügten Frames zu einem WebP-Bitstream zusammenstellen Diesem Aufruf sollte ein Aufruf von WebPAnimEncoderAdd mit frame = NULL vorausgehen. Andernfalls wird die Dauer des letzten Frames intern geschätzt.

Parameter

enc – Ein-/Ausgangsobjekt, aus dem die Frames zusammengesetzt werden sollen.

webp_data – (out) der generierte WebP-Bitstream.

Rückgaben

True bei Erfolg.

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

WebPAnimEncoderGetError()

Rufen Sie mit enc den Fehlerstring ab, der dem letzten Aufruf entspricht. Der zurückgegebene String gehört enc und ist nur bis zum nächsten Aufruf von WebPAnimEncoderAdd(), WebPAnimEncoderAssemble() oder WebPAnimEncoderDelete() gültig.

Parameter

enc: Objekt, aus dem der Fehlerstring abgerufen werden soll.

Rückgaben

NULL if enc is NULL. Andernfalls wird der Fehlerstring zurückgegeben, wenn beim letzten Aufruf von enc ein Fehler aufgetreten ist. Wenn der letzte Aufruf erfolgreich war, wird ein leerer String zurückgegeben.

const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

WebPAnimEncoderDelete()

Löscht das Objekt WebPAnimEncoder.

Parameter

enc – (Ein-/Ausgang) Objekt, das gelöscht werden soll

void WebPAnimEncoderDelete(WebPAnimEncoder* enc);

Demux-API

Ermöglicht die Extraktion von Bilddaten und Daten im erweiterten Format aus WebP-Dateien.

Codebeispiele

Demuxing von WebP-Daten zum Extrahieren aller Frames, des ICC-Profils und der EXIF/XMP-Metadaten

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

Leben eines Demux-Objekts

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()

Gibt die Versionsnummer der Demux-Bibliothek zurück, gepackt in hexadezimal mit 8 Bit für jede von Haupt-/Nebenversions-/Versionsangabe. Beispiel: Version 2.5.7 ist 0x020507.

int WebPGetDemuxVersion(void);

WebPDemux()

Parst die vollständige WebP-Datei, die von data ausgegeben wird.

WebPDemuxer WebPDemux(const WebPData* data);

Gibt nach einem erfolgreichen Parsen ein WebPDemuxer-Objekt zurück, andernfalls NULL.

WebPDemuxPartial()

Parst die möglicherweise unvollständige WebP-Datei aus data. Wenn der state nicht NULL ist, wird er festgelegt, um den Status des Demuxer anzugeben.

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

Gibt NULL zurück, wenn ein Fehler auftritt oder nicht genügend Daten zum Starten des Parsens vorhanden sind. Bei erfolgreicher Analyse wird ein WebPDemuxer-Objekt zurückgegeben.

Beachten Sie, dass WebPDemuxer interne Zeiger auf das Datenspeichersegment behält. Wenn diese Daten flüchtig sind, sollte das Demuxerobjekt durch Aufrufen von WebPDemuxDelete() gelöscht und WebPDemuxPartial() für die neuen Daten noch einmal aufgerufen werden. Dies ist in der Regel ein kostengünstiger Vorgang.

WebPDemuxDelete()

Gibt den mit dmux verknüpften Arbeitsspeicher frei.

void WebPDemuxDelete(WebPDemuxer* dmux);

Daten-/Informationsextraktion

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()

Rufen Sie den feature-Wert aus dem dmux ab.

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

Hinweis: Werte sind nur gültig, wenn WebPDemux() verwendet wurde oder WebPDemuxPartial() einen Status > WEBP_DEMUX_PARSING_HEADER zurückgegeben hat.

Frame-Iteration

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()

Ruft den Frame frame_number von dmux ab.

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

iter->fragment verweist nach der Rückgabe von dieser Funktion auf das erste Fragment. Einzelne Fragmente können mit WebPDemuxSelectFragment() extrahiert werden. Wenn Sie frame_number auf 0 setzen, wird der letzte Frame des Bildes zurückgegeben.

Gibt "false" zurück, wenn dmux NULL ist oder Frame frame_number nicht vorhanden ist. Rufen Sie WebPDemuxReleaseIterator() auf, wenn die Verwendung des Listeners abgeschlossen ist.

Hinweis:dmux muss für die Lebensdauer von iter bestehen bleiben.

WebPDemuxNextFrame(), WebPDemuxPrevFrame()

Legt fest, dass iter->fragment auf den nächsten Frame (iter->frame_num + 1) oder den vorherigen Frame (iter->frame_num - 1) verweist. Diese Funktionen werden nicht in Schleifen ausgeführt.

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

Gibt bei Erfolg „true“, andernfalls „false“ zurück.

WebPDemuxSelectFragment()

Legt iter->fragment so fest, dass die Fragmentnummer fragment_num widergespiegelt wird.

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

Gibt „true“ zurück, wenn das Fragment fragment_num vorhanden ist, andernfalls „false“.

WebPDemuxReleaseIterator()

Gibt jeden mit iter verknüpften Speicher frei.

void WebPDemuxReleaseIterator(WebPIterator* iter);

Muss vor allen nachfolgenden Aufrufen von WebPDemuxGetChunk() für denselben Iteration aufgerufen werden. Muss außerdem aufgerufen werden, bevor das verknüpfte WebPDemuxer mit WebPDemuxDelete() gelöscht wird.

Chunk-Iteration

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()

Ruft die chunk_number-Instanz des Chunks mit der ID fourcc von dmux ab.

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

fourcc ist ein Zeichenarray, das die Fourcc des zurückzugebenden Blocks enthält, z.B. "ICCP", "XMP ", "EXIF" usw.

Wenn für chunk_number gleich 0 festgelegt wird, wird der letzte Teil in einem Satz zurückgegeben.

Gibt „true“ zurück, wenn der Chunk gefunden wird, andernfalls „false“. Auf Image-bezogene Chunk-Nutzlasten kann über WebPDemuxGetFrame() und zugehörige Funktionen zugegriffen werden. Rufen Sie WebPDemuxReleaseChunkIterator() auf, wenn die Verwendung des Iteration abgeschlossen ist.

Hinweis:dmux muss für die Lebensdauer des Iterators bestehen bleiben.

WebPDemuxNextChunk(), WebPDemuxPrevChunk()

Legt fest, dass iter->chunk auf den nächsten (iter->chunk_num + 1) oder den vorherigen (iter->chunk_num - 1) verweist. Diese Funktionen werden nicht in Schleifen ausgeführt.

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

Gibt bei Erfolg „true“, andernfalls „false“ zurück.

WebPDemuxReleaseChunkIterator()

Gibt jeden mit iter verknüpften Speicher frei.

void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);

Muss aufgerufen werden, bevor die verknüpfte WebPDemuxer mit WebPDemuxDelete() gelöscht wird.

WebPAnimDecoder API

Diese API ermöglicht die Decodierung animierter WebP-Bilder (möglicherweise).

Codebeispiel

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.

Globale Optionen

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()

Sollte immer aufgerufen werden, um vor der Änderung eine neue WebPAnimDecoderOptions-Struktur zu initialisieren. Gibt "false" zurück, falls Versionsdiskrepanzen auftreten. WebPAnimDecoderOptionsInit() muss erfolgreich gewesen sein, bevor das Objekt dec_options verwendet werden konnte.

Parameter

dec_options – Ein-/Aus-Optionen, die zum Decodieren der Animation verwendet werden

Rückgaben

Bei Erfolg wahr

int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options);

WebPAnimDecoderNew()

Erstellt und initialisiert ein WebPAnimDecoder-Objekt.

Parameter

webp_data – (in) WebP-Bitstream. Dies sollte während der Lebensdauer des WebPAnimDecoder-Ausgabeobjekts unverändert bleiben.

dec_options – (in) Decodierungsoptionen. Kann NULL übergeben werden, um angemessene Standardeinstellungen auszuwählen (insbesondere der Farbmodus MODE_RGBA wird ausgewählt).

Rückgaben

Ein Zeiger auf das neu erstellte WebPAnimDecoder-Objekt oder NULL bei einem Parsing-Fehler, einer ungültigen Option oder einem Speicherfehler.

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

Globale Informationen zur Animation.

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

WebPAnimDecoderGetInfo()

Rufen Sie globale Informationen zur Animation ab.

Parameter

dec – (in) Decoderinstanz, von der Informationen abgerufen werden sollen.

info – (out) globale Informationen, die aus der Animation abgerufen werden.

Rückgaben

True bei Erfolg.

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

WebPAnimDecoderGetNext()

Ruft den nächsten Frame anhand der für WebPAnimDecoderNew() angegebenen Optionen von dec ab. Dies ist ein vollständig rekonstruiertes Canvas der Größe canvas_width * 4 * canvas_height und nicht nur das Unterrechteck des Frames. Der zurückgegebene Zwischenspeicher buf ist nur bis zum nächsten Aufruf von WebPAnimDecoderGetNext(), WebPAnimDecoderReset() oder WebPAnimDecoderDelete() gültig.

Parameter

dec – (Ein-/Ausgang)-Decoderinstanz, von der der nächste Frame abgerufen werden soll.

buf – (out)-decodierter Frame.

timestamp – (out) Zeitstempel des Frames in Millisekunden.

Rückgaben

False, wenn eines der Argumente NULL ist, ein Analyse- oder Decodierungsfehler auftritt oder keine Frames mehr vorhanden sind. Andernfalls wird „true“ zurückgegeben.

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

WebPAnimDecoderHasMoreFrames()

Prüfen Sie, ob mehr Frames decodiert werden müssen.

Parameter

dec – (in) die zu prüfende Decoderinstanz.

Rückgaben

„True“, wenn dec nicht NULL ist und einige Frames noch decodiert werden müssen. Andernfalls wird "false" zurückgegeben.

int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

WebPAnimDecoderReset()

Setzt das WebPAnimDecoder-Objekt zurück, sodass beim nächsten Aufruf von WebPAnimDecoderGetNext() die Decodierung vom 1. Frame neu gestartet wird. Dies ist hilfreich, wenn alle Frames mehrmals decodiert werden müssen (z.B. mit info.loop_count-Mal), ohne das Objekt dec zu zerstören und neu zu erstellen.

Parameter

dec – (Ein-/Ausgang)-Decoderinstanz, die zurückgesetzt werden soll

void WebPAnimDecoderReset(WebPAnimDecoder* dec);

WebPAnimDecoderGetDemuxer()

Greifen Sie das interne Demuxer-Objekt zu.

Das Abrufen des Demuxer-Objekts kann nützlich sein, wenn Sie Vorgänge verwenden möchten, die nur über den Demuxer verfügbar sind, z.B. um XMP/EXIF/ICC-Metadaten abzurufen. Das zurückgegebene Demuxer-Objekt gehört zu dec und ist nur bis zum nächsten Aufruf von WebPAnimDecoderDelete() gültig.

Parameter

dec – (in) Decoderinstanz, aus der das Demuxerobjekt abgerufen werden soll.

const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

Löscht das Objekt WebPAnimDecoder.

Parameter

dec – (Ein-/Ausgang)-Decoderinstanz, die gelöscht werden soll.

Rückgaben

„True“, wenn der Vorgang erfolgreich war.

void WebPAnimDecoderDelete(WebPAnimDecoder* dec);

Gängige Datentypen

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()

Initialisiert den Inhalt des Objekts webp_data mit Standardwerten.

void WebPDataInit(WebPData* webp_data);

WebPDataClear()

Löscht den Inhalt des Objekts webp_data durch Aufrufen von free(). Die Zuweisung des Objekts selbst wird nicht aufgehoben.

void WebPDataClear(WebPData* webp_data);

WebPDataCopy()

Ordnet den erforderlichen Speicher für dst zu und kopiert den Inhalt von src. Gibt bei Erfolg „true“ zurück.

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