Dokumentacja interfejsu WebP Container API

Manipulacja kontenerem RIFF w przypadku obrazów WebP.

Interfejs API Mux

Umożliwia manipulowanie obrazami kontenera WebP z funkcjami takimi jak profil kolorów, metadane, animacje i obrazy podzielone na fragmenty.

Przykłady kodu

Utwórz MUX z danymi obrazu, profilem koloru i metadanymi 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);

Pobierz dane profilu kolorów i obrazu z pliku 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);

Życie obiektu Mux

Wartości w polu enum

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

Zwraca numer wersji biblioteki MUX w postaci szesnastkowej z użyciem 8 bitów dla każdego statusu głównego/podrzędnego/wersji. np. wersja 2.5.7 to 0x020507.

int WebPGetMuxVersion(void);

WebPMuxNew()

Tworzy pusty obiekt MUX.

WebPMux* WebPMuxNew(void);
Akcje powrotne
Wskaźnik do nowo utworzonego pustego obiektu Mux.

WebPMuxDelete()

Usuwa obiekt Mux.

void WebPMuxDelete(WebPMux* mux);
Parametry
mux – (wejście/wyjście) obiekt do usunięcia

Tworzenie Mux

WebPMuxCreate()

Tworzy obiekt Mux na podstawie nieprzetworzonych danych podanych w formacie WebP RIFF.

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

bitstream – (w) strumienia danych bitowych danych w formacie WebP RIFF

copy_data – (w) wartość 1 oznacza, że dane dane zostaną skopiowane do MUX, a wartość 0 oznacza, że dane NIE zostaną skopiowane do obiektu mux.

Akcje powrotne

Wskaźnik do obiektu Mux utworzonego na podstawie podanych danych – w przypadku powodzenia.

NULL – w przypadku nieprawidłowych danych lub błędu pamięci.

Fragmenty inne niż obraz

WebPMuxSetChunk()

Dodaje fragment o identyfikatorze fourcc i dane chunk_data w obiekcie Mux. Wszystkie istniejące fragmenty o tym samym identyfikatorze zostaną usunięte.

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

Uwaga: za pomocą interfejsów API fragmentów należy zarządzać tylko fragmentami niepowiązanymi z obrazami. (Fragmenty związane z obrazem to: „ANMF”, „FRGM”, „VP8 ”, „VP8L” i „ALPH”). Aby dodawać, pobierać i usuwać obrazy, użyj poleceń WebPMuxSetImage(), WebPMuxPushFrame(), WebPMuxGetFrame() i WebPMuxDeleteFrame().

Parametry

mux – obiekt (w/out), do którego ma zostać dodany fragment

fourcc – (w) tablica znaków zawierająca cztery cm danego fragmentu, np. „ICCP”, „XMP”, „EXIF” itp.

chunk_data – (w) danych fragmentu do dodania

copy_data – (w) wartość 1 oznacza, że dane dane zostaną skopiowane do MUX, a wartość 0 oznacza, że dane NIE zostaną skopiowane do obiektu mux.

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux, 4cc lub chunk_data ma wartość NULL lub fourcc odpowiada fragmentowi obrazu.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WEBP_MUX_OK – sukces.

WebPMuxGetChunk()

Pobiera odwołanie do danych fragmentu o identyfikatorze fourcc w obiekcie Mux. Element wywołujący NIE powinien zwolnić zwróconych danych.

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

mux – (w) obiekt, z którego mają zostać pobrane dane fragmentu.

fourcc – (w) tablica znaków zawierająca fragment „4cc”, np. „ICCP”, „XMP”, „EXIF” itp.

chunk_data – (out) zwrócone dane fragmentu

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux, 4cc lub chunk_data ma wartość NULL lub fourcc odpowiada fragmentowi obrazu.

WEBP_MUX_NOT_FOUND – jeśli mux nie zawiera fragmentu o podanym identyfikatorze.

WEBP_MUX_OK – sukces.

WebPMuxDeleteChunk()

Usuwa fragment z określonym parametrem fourcc z obiektu Mux.

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

mux – (we/wy) obiekt, z którego ma zostać usunięty fragment

fourcc – (w) tablica znaków zawierająca fragment „4cc”, np. „ICCP”, „XMP”, „EXIF” itp.

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux lub4cc ma wartość NULL lub Fourcc odpowiada fragmentowi obrazu.

WEBP_MUX_NOT_FOUND – jeśli multipleks nie zawiera fragmentu z daną wartością fourcc.

WEBP_MUX_OK – sukces.

zdjęcia;

Obejmuje dane o pojedynczej klatce lub fragmencie.

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

Ustawia obraz (nieanimowany i niefragment) w obiekcie Mux. Uwaga: wszystkie istniejące obrazy (w tym ramki/fragmenty) zostaną usunięte.

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

mux – obiekt, w którym ma zostać ustawiony obraz

bitstream – (in) może być nieprzetworzonym strumieniem bitowym VP8/VP8L lub plikiem WebP z pojedynczym obrazem (bez animacji i bez fragmentu).

copy_data – (w) wartość 1 oznacza, że dane dane zostaną skopiowane do MUX, a wartość 0 oznacza, że dane NIE zostaną skopiowane do obiektu mux.

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux ma wartość NULL, lub strumień bitów ma wartość NULL.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WEBP_MUX_OK – sukces.

WebPMuxPushFrame()

Dodaje ramkę na końcu obiektu MUX.

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

Uwagi:

  1. Ramka.id powinna mieć wartość WEBP_CHUNK_ANMF lub WEBP_CHUNK_FRGM
  2. Aby ustawić obraz bez animacji, bez fragmentu, użyj parametru WebPMuxSetImage().
  3. Typ wypychanej klatki musi być taki sam jak w przypadku klatek w wielu elementach.
  4. WebP obsługuje tylko przesunięcia parzyste, dlatego każde nieparzyste przesunięcie zostanie przyciągnięte do lokalizacji parzystej za pomocą: przesunięcia &= ~1
Parametry

mux – obiekt (wejście/wyjście), do którego ma zostać dodana ramka

frame – dane ramki (w).

copy_data – (w) wartość 1 oznacza, że dane dane zostaną skopiowane do MUX, a wartość 0 oznacza, że dane NIE zostaną skopiowane do obiektu mux.

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux lub ramka ma wartość NULL albo zawartość frame jest nieprawidłowa.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WEBP_MUX_OK – sukces.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WebPMuxGetFrame()

Pobiera n-tą klatkę z obiektu MUX. Zawartość elementu frame->bitstream jest przydzielana za pomocą metody Malloc() i NIE należy do obiektu mux. Musi zostać usunięty przez rozmówcę, wywołując metodę WebPDataClear(). nth=0 ma specjalne znaczenie – ostatnią pozycję.

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

mux – (w) obiekt, z którego mają zostać pobrane informacje.

nth – (in) indeks klatki w obiekcie MUX

frame – (out) danych zwróconej klatki

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux lub ramka ma wartość NULL.

WEBP_MUX_NOT_FOUND – jeśli w obiekcie MUX jest mniej niż n-te klatki,

WEBP_MUX_BAD_DATA – jeśli n-ty fragment klatki w wielu parametrach jest nieprawidłowy.

WEBP_MUX_OK – sukces.

WebPMuxDeleteFrame()

Usuwa ramkę z obiektu MUX. nth=0 ma specjalne znaczenie – ostatnia pozycja.

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);
Parametry

mux – obiekt (wejście/wyjście), z którego ma zostać usunięta ramka.

nth – (w) pozycja, z której klatka ma zostać usunięta

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux ma wartość NULL.

WEBP_MUX_NOT_FOUND – jeśli przed usunięciem jest mniej niż n-ta liczba klatek w obiekcie MUX.

WEBP_MUX_OK – sukces.

Animacja

Parametry animacji

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

Ustawia parametry animacji w obiekcie Mux. Wszystkie fragmenty kodu ANIM zostaną usunięte.

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

mux – (w/poza) obiekt, do którego ma zostać ustawiony/dodany fragment ANIM

params – parametry animacji (w).

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux lub parametry mają wartość NULL.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WEBP_MUX_OK – sukces.

WebPMuxGetAnimationParams()

Pobiera parametry animacji z obiektu Mux.

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

mux – (w) obiekt, z którego mają zostać pobrane parametry animacji.

params – parametry animacji (poza) wyodrębnione z fragmentu ANIM.

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux lub parametry mają wartość NULL.

WEBP_MUX_NOT_FOUND – jeśli fragment ANIM nie jest obecny w obiekcie multipleksu.

WEBP_MUX_OK – sukces.

Różne narzędzia

WebPMuxGetCanvasSize()

Pobiera rozmiar kanwy z obiektu Mux.

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

Uwaga: ta metoda zakłada, że fragment VP8X (jeśli jest obecny) jest aktualny. Oznacza to, że obiekt Mux nie został zmodyfikowany od ostatniego wywołania WebPMuxAssemble() lub WebPMuxCreate().

Parametry

mux – (w) obiekt, z którego ma zostać pobrany rozmiar odbitki na płótnie.

width – szerokość obszaru roboczego (na zewnątrz)

height – wysokość obszaru roboczego (out)

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux, szerokość lub wysokość ma wartość NULL.

WEBP_MUX_BAD_DATA – jeśli rozmiar fragmentu VP8X/VP8/VP8L lub odbitki na płótnie jest nieprawidłowy.

WEBP_MUX_OK – sukces.

WebPMuxGetFeatures()

Pobiera flagi funkcji z obiektu Mux.

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

Uwaga: ta metoda zakłada, że fragment VP8X (jeśli jest obecny) jest aktualny. Oznacza to, że obiekt Mux nie został zmodyfikowany od ostatniego wywołania WebPMuxAssemble() lub WebPMuxCreate().

Parametry

mux – (w) obiekt, z którego mają zostać pobrane cechy

flags – (out) flagi określające, które cechy są dostępne w obiekcie mux. Będzie to LUB z różnymi wartościami flag. Enum WebPFeatureFlags może służyć do testowania wartości poszczególnych flag.

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux lub flagi mają wartość NULL.

WEBP_MUX_BAD_DATA – jeśli rozmiar fragmentu VP8X/VP8/VP8L lub odbitki na płótnie jest nieprawidłowy.

WEBP_MUX_OK – sukces.

WebPMuxNumChunks()

Pobiera liczbę fragmentów o określonej wartości tagu w obiekcie mux.

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

mux – (w) obiekt, z którego mają zostać pobrane informacje.

id – identyfikator fragmentu (w) określający typ fragmentu.

num_elements – (skończona) liczba fragmentów o danym identyfikatorze fragmentu

Akcje powrotne

WEBP_MUX_INVALID_ARGUMENT – jeśli mux lub num_elements ma wartość NULL.

WEBP_MUX_OK – sukces.

WebPMuxAssemble()

Składa wszystkie fragmenty w formacie WebP RIFF i zwraca w postaci assembled_data. Ta funkcja weryfikuje również obiekt Mux.

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

Uwaga: zawartość argumentu connectd_data zostanie zignorowana i zastąpiona. Poza tym zawartość elementu assembled_data jest przydzielana za pomocą Malloc() i NIE należy do obiektu assembled_data. MUSI zostać przydzielona przez rozmówcę, wywołując metodę WebPDataClear().

Parametry

mux – obiekt, którego fragmenty mają zostać połączone.

assembled_data – (out) zebrane dane WebP

Akcje powrotne

WEBP_MUX_BAD_DATA – jeśli obiekt Mux jest nieprawidłowy.

WEBP_MUX_INVALID_ARGUMENT – jeśli mux lub connected_data ma wartość NULL.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WEBP_MUX_OK – sukces.

Interfejs API WebPAnimEncoder

Ten interfejs API umożliwia kodowanie (prawdopodobnie) animowane obrazy WebP.

Przykładowy kod

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.

Opcje globalne

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

Ta wartość powinna być zawsze wywoływana w celu zainicjowania nowej struktury WebPAnimEncoderOptions przed modyfikacją. Zwraca wartość „false” (fałsz) w przypadku niezgodności wersji. Zanim użyjesz obiektu enc_options, funkcja WebPAnimEncoderOptionsInit() musi zakończyć się powodzeniem.

Parametry
enc_options – opcje (wejścia/wyjścia) używane do kodowania animacji
Akcje powrotne
Prawda o sukcesie.
int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderNew()

Tworzy i inicjuje obiekt WebPAnimEncoder.

Parametry

width/height – (in) szerokość i wysokość animacji.

enc_options – (w) opcje kodowania; można przekazywać wartości NULL, aby wybrać uzasadnione wartości domyślne.

Akcje powrotne

Wskaźnik do nowo utworzonego obiektu WebPAnimEncoder lub wartość NULL w przypadku błędu pamięci.

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

WebPAnimEncoderAdd()

Zoptymalizuj daną ramkę pod kątem WebP, zakoduj ją i dodaj do obiektu WebPAnimEncoder.

Ostatnie wywołanie funkcji WebPAnimEncoderAdd powinno zawierać wartość frame = NULL, co oznacza, że nie należy dodawać kolejnych klatek. To wywołanie określa też czas trwania ostatniej klatki.

Parametry

enc – obiekt (wejście/wyjście), do którego ma zostać dodana ramka.

frame – (wejście/wyjście) danych klatki w formacie ARGB lub YUV(A). Jeśli jest w formacie YUV(A), zostanie przekonwertowany na ARGB, co wiąże się z niewielką stratą.

timestamp_ms – (in) sygnatura czasowa danej klatki w milisekundach. Czas trwania klatki jest obliczany jako „sygnatura czasowa następnej klatki – sygnatura czasowa tej klatki”. Dlatego sygnatury czasowe nie mogą się maleć.

config – (w) opcji kodowania. Można przekazywać wartości NULL, aby wybrać uzasadnione wartości domyślne.

Akcje powrotne

W przypadku błędu zwraca wartość „false” (fałsz), a ustawienie frame->error_code jest prawidłowo skonfigurowane. W przeciwnym razie zwraca wartość „true” (prawda).

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

WebPAnimEncoderAssemble()

Zbierz wszystkie dodane dotąd klatki w strumień bitowy WebP. Powinno być poprzedzone wywołaniem WebPAnimEncoderAdd o wartości frame = NULL. W przeciwnym razie czas trwania ostatniej klatki będzie wewnętrzny szacowany.

Parametry

enc – (wejściowy/wyjściowy) obiekt, z którego mają zostać złożone klatki.

webp_data – (out) wygenerowany strumień bitowy WebP.

Akcje powrotne

Prawda o sukcesie.

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

WebPAnimEncoderGetError()

Pobierz ciąg błędu odpowiadający ostatniemu wywołaniu za pomocą polecenia enc. Zwrócony ciąg znaków należy do zbioru enc i jest ważny tylko do następnego wywołania WebPAnimEncoderAdd(), WebPAnimEncoderAssemble() lub WebPAnimEncoderDelete().

Parametry
enc – obiekt (we/out), z którego ma zostać pobrany ciąg błędu.
Akcje powrotne
NULL if enc is NULL. W przeciwnym razie zwraca ciąg błędu, jeśli ostatnie wywołanie funkcji enc zakończyło się błędem, lub pusty ciąg, jeśli ostatnie wywołanie zakończyło się powodzeniem.
const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

WebPAnimEncoderDelete()

Usuwa obiekt WebPAnimEncoder.

Parametry
enc – (wejście/wyjście) obiekt do usunięcia
void WebPAnimEncoderDelete(WebPAnimEncoder* enc);

Interfejs API Demux

Umożliwia wyodrębnianie danych obrazów i danych w formacie rozszerzonym z plików WebP.

Przykłady kodu

Demuksowanie danych WebP w celu wyodrębnienia wszystkich ramek, profilu ICC i metadanych 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);

Życie obiektu Demux

Wartości w polu enum

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

Zwraca numer wersji biblioteki demux zapisanej w postaci szesnastkowej z użyciem 8 bitów dla każdego statusu głównego/podrzędnego/wersji. np.wersja 2.5.7 to 0x020507.

int WebPGetDemuxVersion(void);

WebPDemux()

Analizuje pełny plik WebP podany przez dane.

WebPDemuxer WebPDemux(const WebPData* data);

Zwraca obiekt WebPDemuxer w przypadku udanej analizy. W przeciwnym razie zwraca wartość NULL.

WebPDemuxPartial()

Analizuje prawdopodobnie niepełny plik WebP podany przez dane. Jeśli state nie ma wartości NULL, będzie wskazywać stan demiksera.

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

Zwraca wartość NULL w przypadku błędu lub gdy nie ma wystarczającej ilości danych do rozpoczęcia analizy, a także obiekt WebPDemuxer w przypadku udanej analizy.

Pamiętaj, że funkcja WebPDemuxer zachowuje wewnętrzne wskaźniki do segmentu pamięci dane. Jeśli dane są zmienne, obiekt demuksera należy usunąć (wywołując WebPDemuxDelete()) i ponownie wywołać metodę WebPDemuxPartial() z nowymi danymi. Zwykle jest to niedroga operacja.

WebPDemuxDelete()

Zwalnia pamięć powiązaną z dmux.

void WebPDemuxDelete(WebPDemuxer* dmux);

Wyodrębnianie danych/informacji

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

Pobierz wartość feature z dmux.

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

Uwaga: wartości są prawidłowe tylko wtedy, gdy użyto parametru WebPDemux() lub WebPDemuxPartial() zwróciło stan >WEBP_DEMUX_PARSING_HEADER.

Iteracja ramki

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

Pobiera ramkę frame_number z parametru dmux.

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

iter->fragment wskazuje pierwszy fragment po powrocie z tej funkcji. Poszczególne fragmenty można wyodrębnić za pomocą metody WebPDemuxSelectFragment(). Ustawienie wartości parametru frame_number na 0, zwróci ostatnią klatkę obrazu.

Zwraca wartość false, jeśli parametr dmux ma wartość NULL lub jest brak ramki frame_number. Wywołaj WebPDemuxReleaseIterator() po zakończeniu korzystania z iteratora.

Uwaga: plik dmux musi pozostawać bez zmian przez cały czas trwania funkcji iter.

WebPDemuxNextFrame(), WebPDemuxPrevFrame()

Ustawia iter->fragment wskazującą następną (iter->frame_num + 1) lub poprzednią klatkę (iter->frame_num – 1). Te funkcje nie zapętlają się.

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

Zwraca wartość „true” (prawda) w przypadku powodzenia; w przeciwnym razie zwraca wartość „false” (fałsz).

WebPDemuxSelectFragment()

Ustawia ciąg iter->fragment, by odzwierciedlić numer fragmentu fragment_num.

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

Zwraca wartość „true”, jeśli występuje fragment fragment_num. W przeciwnym razie zwraca wartość „false” (fałsz).

WebPDemuxReleaseIterator()

Zwalnia pamięć powiązaną z iter.

void WebPDemuxReleaseIterator(WebPIterator* iter);

Należy ją wywoływać przed kolejnymi wywołaniami WebPDemuxGetChunk() w tym samym iterowaniu. Należy go też wywołać przed zniszczeniem powiązanego WebPDemuxer przy użyciu WebPDemuxDelete().

Iteracja fragmentów

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

Pobiera wystąpienie chunk_number fragmentu o identyfikatorze fourcc z dmux.

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

fourcc to tablica znaków zawierająca czteropunktowy fragment do zwrócenia, np. „ICCP”, „XMP”, „EXIF” itp.

Ustawienie wartości parametru chunk_number na 0, spowoduje zwrócenie ostatniego fragmentu w zestawie.

Zwraca wartość „true”, jeśli fragment zostanie znaleziony, lub „false” (fałsz). Dostęp do ładunków fragmentów powiązanych z obrazami jest uzyskiwany za pomocą narzędzia WebPDemuxGetFrame() i powiązanych funkcji. Wywołaj WebPDemuxReleaseChunkIterator() po zakończeniu użycia iteratora.

Uwaga: plik dmux musi pozostawać bez zmian przez cały czas życia iteratora.

WebPDemuxNextChunk(), WebPDemuxPrevChunk()

Ustawia argument iter->chunk, który wskazuje następny (iter->chunk + 1) lub poprzedni (iter->chunk – 1). Te funkcje nie zapętlają się.

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

Zwraca wartość „true” (prawda) w przypadku powodzenia; w przeciwnym razie zwraca wartość „false” (fałsz).

WebPDemuxReleaseChunkIterator()

Zwalnia pamięć powiązaną z iter.

void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);

Należy wywołać przed zniszczeniem powiązanego WebPDemuxer z WebPDemuxDelete().

Interfejs API WebPAnimDecoder

Ten interfejs API umożliwia dekodowanie (prawdopodobnie) animowanych obrazów WebP.

Przykładowy kod

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.

Opcje globalne

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

Ta wartość powinna być zawsze wywoływana w celu zainicjowania nowej struktury WebPAnimDecoderOptions przed modyfikacją. Zwraca wartość „false” (fałsz) w przypadku niezgodności wersji. Zanim użyjesz obiektu dec_options, funkcja WebPAnimDecoderOptionsInit() musi zakończyć się powodzeniem.

Parametry

dec_options – opcje (wejściowe/wychodzące) używane do dekodowania animacji.

Akcje powrotne
Prawda o sukcesie
int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options);

WebPAnimDecoderNew()

Tworzy i inicjuje obiekt WebPAnimDecoder.

Parametry

webp_data – (w) strumień bitów WebP. Ta wartość powinna pozostać niezmieniona przez cały czas istnienia wyjściowego obiektu WebPAnimDecoder.

dec_options – opcje dekodowania (w). Można przekazać wartość NULL, aby wybrać rozsądne wartości domyślne (w szczególności wybierany jest tryb kolorów MODE_RGBA).

Akcje powrotne

Wskaźnik do nowo utworzonego obiektu WebPAnimDecoder lub wartość NULL w przypadku błędu analizy, nieprawidłowej opcji lub błędu pamięci.

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

Globalne informacje o animacji.

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

WebPAnimDecoderGetInfo()

uzyskać globalne informacje o animacji,

Parametry

dec – (w) instancji dekodera, z którego będą pobierane informacje.

info – informacje globalne pobrane z animacji.

Akcje powrotne

Prawda o sukcesie.

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

WebPAnimDecoderGetNext()

Pobiera następną klatkę z gru na podstawie opcji dostarczonych do WebPAnimDecoderNew(). To będzie w pełni zrekonstruowana odbitka na płótnie o rozmiarze canvas_width * 4 * canvas_height, a nie tylko podprostokąt ramki. Zwrócony bufor buf jest prawidłowy tylko do następnego wywołania WebPAnimDecoderGetNext(), WebPAnimDecoderReset() lub WebPAnimDecoderDelete().

Parametry

dec – instancja dekodera (wejściowa/wyjściowa), z której ma zostać pobrana następna ramka.

buf – zdekodowana (wyjściowa) ramka.

timestamp – (koniec) sygnatura czasowa klatki w milisekundach.

Akcje powrotne

Fałsz, jeśli dowolny z argumentów ma wartość NULL, wystąpił błąd analizy lub dekodowania albo jeśli nie ma więcej ramek. W przeciwnym razie zwraca wartość „true” (prawda).

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

WebPAnimDecoderHasMoreFrames()

Sprawdź, czy zostało więcej klatek do zdekodowania.

Parametry
dec – (w) instancja dekodera do sprawdzenia.
Akcje powrotne
Prawda, jeśli dec nie ma wartości NULL, a niektóre ramki nie zostały jeszcze dekodowane. W przeciwnym razie zwraca wartość „fałsz”.
int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

WebPAnimDecoderReset()

Resetuje obiekt WebPAnimDecoder, przez co kolejne wywołanie metody WebPAnimDecoderGetNext() powoduje ponowne uruchomienie dekodowania od pierwszej klatki. Jest to przydatne, gdy wszystkie klatki muszą być dekodowane wiele razy (np. info.loop_count raza) bez niszczenia i ponownego tworzenia obiektu dec.

Parametry
dec – (wejściowa/wyjściowa) instancja dekodera do zresetowania
void WebPAnimDecoderReset(WebPAnimDecoder* dec);

WebPAnimDecoderGetDemuxer()

Chwyć wewnętrzny obiekt demuksera.

Uzyskiwanie obiektu demultipleksera może być przydatne, jeśli chcesz korzystać z operacji dostępnych tylko za pomocą tego narzędzia, na przykład aby pobierać metadane XMP/EXIF/ICC. Zwrócony obiekt demuksera jest własnością dec i jest prawidłowy tylko do następnego wywołania WebPAnimDecoderDelete().

Parametry
dec – (w) instancję dekodera, z której ma zostać pobrany obiekt demuksera.
const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

Usuwa obiekt WebPAnimDecoder.

Parametry
dec – (wejście/wyjście) instancji dekodera do usunięcia.
Akcje powrotne
Prawda o sukcesie.
void WebPAnimDecoderDelete(WebPAnimDecoder* dec);

Popularne typy danych

Wartości w polu enum

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

Inicjuje zawartość obiektu webp_data z wartościami domyślnymi.

void WebPDataInit(WebPData* webp_data);

WebPDataClear()

Usuwa zawartość obiektu webp_data, wywołując free(). Nie powoduje usunięcia alokacji samego obiektu.

void WebPDataClear(WebPData* webp_data);

WebPDataCopy()

Przydziela niezbędną pamięć na potrzeby dst i kopiuje zawartość parametru src. Zwraca wartość „prawda” w przypadku powodzenia.

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