Dokumentacja interfejsu WebP Container API

Manipulacja kontenerami RIFF w przypadku obrazów WebP.

Interfejs API Mux

Umożliwia manipulowanie obrazami kontenerów WebP, w tym m.in. kolorami profilu, metadanych, animacji i obrazów pofragmentowanych.

Przykłady kodu

Utwórz MUX z danymi obrazu, profilem kolorów 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 obrazu i profilu kolorów 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, skompresowany szesnastkowo za pomocą funkcji 8 bitów dla każdej większej/mniejszej/wersji. Na przykład wersja 2.5.7 to 0x020507.

int WebPGetMuxVersion(void);

WebPMuxNew()

Tworzy pusty obiekt Mux.

WebPMux* WebPMuxNew(void);

Zwroty

Wskaźnik do nowo utworzonego pustego obiektu Mux.

WebPMuxDelete()

Usuwa obiekt Mux.

void WebPMuxDelete(WebPMux* mux);

Parametry

mux – obiekt (przychodzący/wychodzący) do usunięcia

Tworzenie Mux

WebPMuxCreate()

Tworzy obiekt Mux z nieprzetworzonych danych podanych w formacie WebP RIFF.

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

Parametry

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

copy_data – (in) wartość 1 oznacza, że podane dane BĘDĄ kopiowane do systemu Mux. a wartość 0 oznacza, że dane NIE zostaną skopiowane do obiektu mux.

Zwroty

Wskaźnik do obiektu Mux utworzonego na podstawie podanych danych – jeśli operacja się uda.

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

Fragmenty niebędące obrazami

WebPMuxSetChunk()

Dodaje fragment o identyfikatorze fourcc i danych chunk_data w obiekcie Mux. Dowolne 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: przez interfejsy API fragmentów należy zarządzać tylko fragmentami niepowiązanymi z obrazami. (Fragmenty powiązane z obrazami: „ANMF”, „FRGM”, „VP8”, „VP8L” i „ALPH”). Aby je dodać, pobieranie i usuwanie obrazów, korzystać z usługi WebPMuxSetImage(), WebPMuxPushFrame(), WebPMuxGetFrame() i WebPMuxDeleteFrame().

Parametry

mux – obiekt (w/wyjścia), do którego ma zostać dodany fragment.

fourcc – (in) tablica znaków zawierająca cyfry 4 cc chunk; np. „ICCP”, „XMP”, „EXIF” ip.

chunk_data – (w) danych fragmentu do dodania

copy_data – (in) wartość 1 oznacza, że podane dane BĘDĄ kopiowane do systemu Mux. a wartość 0 oznacza, że dane NIE zostaną skopiowane do obiektu mux.

Zwroty

WEBP_MUX_INVALID_ARGUMENT – jeśli wartości Mux, Fourcc lub chunk_data mają wartość NULL lub if Fourcc odpowiada fragmentowi zdjęcia.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WEBP_MUX_OK – w przypadku sukcesu.

WebPMuxGetChunk()

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

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

Parametry

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

fourcc – (in) tablica znaków zawierająca cztery cudzy fragment kodu; np. „ICCP”, „XMP”, „EXIF” ip.

chunk_data – (out) zwrócone dane fragmentu

Zwroty

WEBP_MUX_INVALID_ARGUMENT – jeśli wartości Mux, Fourcc lub chunk_data mają wartość NULL lub if Fourcc odpowiada fragmentowi zdjęcia.

WEBP_MUX_NOT_FOUND – jeśli funkcja mux nie zawiera fragmentu z podanym id.

WEBP_MUX_OK – w przypadku sukcesu.

WebPMuxDeleteChunk()

Usuwa z obiektu Mux fragment z podaną wartością fourcc.

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

Parametry

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

fourcc – (in) tablica znaków zawierająca cztery cudzy fragment kodu; np. „ICCP”, „XMP”, „EXIF” ip.

Zwroty

WEBP_MUX_INVALID_ARGUMENT – jeśli funkcje mux lub Fourcc są NULL lub if Fourcc odpowiada fragmentowi obrazu.

WEBP_MUX_NOT_FOUND – jeśli funkcja mux nie zawiera fragmentu z podanym Fourcc.

WEBP_MUX_OK – w przypadku sukcesu.

Obrazy

Obejmuje dane o pojedynczej ramce 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 niepofragmentowany) w obiekcie Mux. Uwaga: wszystkie istniejące obrazy (w tym ramki i fragmenty) zostaną usunięte.

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

Parametry

mux – obiekt (we/wy), w którym ma zostać ustawiony obraz.

stream bitstream – (in) może być nieprzetworzonym strumieniem bitowym VP8/VP8L lub pojedynczym obrazem WebP; plik (nieanimowany i niepofragmentowany)

copy_data – (in) wartość 1 oznacza, że podane dane BĘDĄ kopiowane do systemu Mux. a wartość 0 oznacza, że dane NIE zostaną skopiowane do obiektu mux.

Zwroty

WEBP_MUX_INVALID_ARGUMENT – jeśli element Mux ma wartość NULL lub strumień bitstream ma wartość NULL.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WEBP_MUX_OK – w przypadku sukcesu.

WebPMuxPushFrame()

Dodaje ramkę na końcu obiektu Mux.

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

Uwagi:

1. Parametr frame.id powinien mieć wartość WEBP_CHUNK_ANMF lub WEBP_CHUNK_FRGM
2. Aby ustawić obraz nieanimowany bez fragmentów, użyj WebPMuxSetImage().
3. Typ przekazywanej klatki musi być taki sam jak klatki w trybie MUX.
4. WebP obsługuje tylko przesunięcia parzyste, więc każde takie przesunięcie jest przyciągane do lokalizacji parzystej przy użyciu: przesunięcia &= ~1

Parametry

mux – obiekt (we/wyjścia), do którego ma zostać dodana ramka.

frame – dane ramki (in).

copy_data – (in) wartość 1 oznacza, że podane dane BĘDĄ kopiowane do systemu Mux. a wartość 0 oznacza, że dane NIE zostaną skopiowane do obiektu mux.

Zwroty

WEBP_MUX_INVALID_ARGUMENT – jeśli funkcje Mux lub frame mają wartość NULL lub jeśli zawartość Parametr frame jest nieprawidłowy.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WEBP_MUX_OK – w przypadku sukcesu.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WebPMuxGetFrame()

Pobiera n-tą ramkę z obiektu Mux. Zawartość parametru frame->bitstream jest przydzielone za pomocą Malloc() i NIE należą do obiektu mux. MUSI być ustalanych przez dzwoniącego, wywołując metodę WebPDataClear(). nth=0 ma szczególne znaczenie – ostatnia pozycja.

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

Parametry

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

nth – indeks (in) ramki w obiekcie Mux.

frame – (out) dane zwróconej klatki.

Zwroty

WEBP_MUX_INVALID_ARGUMENT -- if mux or frame is NULL.

WEBP_MUX_NOT_FOUND – jeśli w multipleksie jest mniej niż n-tych klatek obiektu.

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

WEBP_MUX_OK – w przypadku sukcesu.

WebPMuxDeleteFrame()

Usuwa ramkę z obiektu Mux. nth=0 ma specjalne znaczenie – last pozycji.

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);

Parametry

mux – obiekt (we/wy), z którego ma zostać usunięta ramka.

nth – (in) pozycja, z której ma zostać usunięta ramka.

Zwroty

WEBP_MUX_INVALID_ARGUMENT -- if mux is NULL.

WEBP_MUX_NOT_FOUND – jeśli w multipleksie jest mniej niż n-tych klatek przed usunięciem obiektu.

WEBP_MUX_OK – w przypadku sukcesu.

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 istniejące fragmenty ANIM zostaną usunięte.

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

Parametry

mux – obiekt (in/out), w którym ma zostać ustawiony/dodany fragment ANIM

params – parametry animacji (w).

Zwroty

WEBP_MUX_INVALID_ARGUMENT – jeśli funkcje Mux lub params mają wartość NULL.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WEBP_MUX_OK – w przypadku sukcesu.

WebPMuxGetAnimationParams()

Pobiera parametry animacji z obiektu Mux.

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

Parametry

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

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

Zwroty

WEBP_MUX_INVALID_ARGUMENT – jeśli funkcje Mux lub params mają wartość NULL.

WEBP_MUX_NOT_FOUND – jeśli fragmentu ANIM nie ma w obiekcie Mux.

WEBP_MUX_OK – w przypadku sukcesu.

Różne Usługi komunalne

WebPMuxGetCanvasSize()

Pobiera rozmiar obszaru roboczego z obiektu Mux.

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

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

Parametry

mux – obiekt (w), z którego ma zostać pobrany rozmiar obszaru roboczego.

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

height -- (out) wysokość obszaru roboczego

Zwroty

WEBP_MUX_INVALID_ARGUMENT -- if mux, width or height is NULL.

WEBP_MUX_BAD_DATA – jeśli rozmiar fragmentu VP8X/VP8/VP8L lub obszaru roboczego jest nieprawidłowy.

WEBP_MUX_OK – w przypadku sukcesu.

WebPMuxGetFeatures()

Pobiera flagi funkcji z obiektu Mux.

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

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

Parametry

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

flags – (out) flagi określające, które funkcje są obecne w trybie Mux; obiektu. To będzie operator LUB różnych wartości flag. Wyliczenie WebPFeatureFlags może służyć do testowania poszczególnych wartości flag.

Zwroty

WEBP_MUX_INVALID_ARGUMENT -- if mux or flags is NULL.

WEBP_MUX_BAD_DATA – jeśli rozmiar fragmentu VP8X/VP8/VP8L lub obszaru roboczego jest nieprawidłowy.

WEBP_MUX_OK – w przypadku sukcesu.

WebPMuxNumChunks()

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

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

Parametry

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

id -- (in) identyfikator fragmentu określający typ fragmentu

num_elements – (wychodząca) liczba fragmentów o podanym identyfikatorze fragmentu.

Zwroty

WEBP_MUX_INVALID_ARGUMENT -- if mux, or num_elements is NULL.

WEBP_MUX_OK – w przypadku sukcesu.

WebPMuxAssemble()

Łączy 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ść tagu assed_data zostanie zignorowana i zastąpiona. Poza tym zawartość danych assembled_data jest przydzielana za pomocą metody Malloc(), a NIE NIE. należący do obiektu mux. Trzeba ją przypisać przez dzwoniącego WebPDataClear()

Parametry

mux – obiekt (we/wy), którego fragmenty mają zostać złożone.

assembled_data – (gotowe) zebrane dane WebP

Zwroty

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

WEBP_MUX_INVALID_ARGUMENT -- if mux or assembled_data is NULL.

WEBP_MUX_MEMORY_ERROR – błąd alokacji pamięci.

WEBP_MUX_OK – w przypadku sukcesu.

Interfejs API WebPAnimEncoder

Ten interfejs API umożliwia kodowanie (prawdopodobnie) animowanych obrazów 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 właściwość powinna być zawsze wywoływana w celu zainicjowania nowego komponentu WebPAnimEncoderOptions. przed modyfikacjami. Zwraca wartość fałsz w przypadku niezgodności wersji. Funkcja WebPAnimEncoderOptionsInit() musi zostać wykonana przed użyciem enc_options.

Parametry

enc_options – opcje (we/wyjścia) używane do kodowania animacji

Zwroty

Prawda w odniesieniu do sukcesu

int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderNew()

Tworzy i inicjuje obiekt WebPAnimEncoder.

Parametry

width/height – (w calach) szerokość i wysokość animacji w obszarze roboczym;

enc_options – opcje kodowania; można przekazać wartość NULL, aby wybrać rozsądnych wartości domyślnych.

Zwroty

Wskaźnik do nowo utworzonego obiektu WebPAnimEncoder lub w przypadku wartości NULL 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 WebPAnimEncoder.

Ostatnie wywołanie funkcji WebPAnimEncoderAdd powinno być realizowane za pomocą parametru frame = NULL, który oznacza, że nie należy dodawać kolejnych klatek. Ta rozmowa jest też używana do: określić czas trwania ostatniej klatki.

Parametry

enc – obiekt (we/wy), do którego ma zostać dodana ramka.

frame – dane (we/wy) ramki w formacie ARGB lub YUV(A). Jeśli jest w YUV(A) zostanie przekonwertowany na ARGB, co wiąże się z niewielką stratą.

timestamp_ms – sygnatura czasowa (in) tej klatki w milisekundach. Czas trwania klatki są obliczane w ten sposób: „sygnatura czasowa następnej klatki – sygnatura czasowa w tej ramce”. Z tego względu sygnatury czasowe powinny mieć postać nie malejącą.

config -- (in) opcje kodowania; można przekazać wartość NULL, aby wybrać uzasadnione domyślnych.

Zwroty

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

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

WebPAnimEncoderAssemble()

Połącz wszystkie dodane do tej pory klatki w strumieniu bitowym WebP. Rozmowa ta powinna być poprzedzone wywołaniem WebPAnimEncoderAdd z parametrem frame = NULL; jeśli nie, czas wyświetlania ostatniej klatki zostanie wewnętrznie szacunkowy.

Parametry

enc – obiekt (we/wy), z którego mają zostać złożone ramki.

webp_data – (out) wygenerowany strumień bitu WebP.

Zwroty

Sukces tak,

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

WebPAnimEncoderGetError()

Uzyskanie ciągu błędu odpowiadającego ostatniemu wywołaniu przy użyciu polecenia enc. zwrócony ciąg jest własnością enc i jest ważny tylko do czasu następnego wywołania funkcji WebPAnimEncoderAdd() lub WebPAnimEncoderAssemble() lub WebPAnimEncoderDelete()

Parametry

enc – obiekt (we/wy), z którego ma zostać pobrany ciąg znaków błędu.

Zwroty

NULL if enc is NULL. W przeciwnym razie zwraca ciąg błędu, jeśli ostatni wywołanie enc zawiera błąd lub pusty ciąg znaków, jeśli ostatnie wywołanie .

const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

WebPAnimEncoderDelete()

Usuwa obiekt WebPAnimEncoder.

Parametry

enc – obiekt (we/wy) do usunięcia

void WebPAnimEncoderDelete(WebPAnimEncoder* enc);

Interfejs API Demux

Umożliwia wyodrębnianie obrazów i danych w rozszerzonym formacie 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, skompresowany szesnastkowo za pomocą funkcji 8 bitów dla każdej większej/mniejszej/wersji. Na przykład wersja 2.5.7 to 0x020507.

int WebPGetDemuxVersion(void);

WebPDemux()

Analizuje pełny plik WebP podany w polu data.

WebPDemuxer WebPDemux(const WebPData* data);

Zwraca obiekt WebPDemuxer po przeprowadzeniu analizy; w przeciwnym razie zwraca wartość NULL.

WebPDemuxPartial()

Analizuje prawdopodobnie niepełny plik WebP podany w polu dane. Jeśli stan to nie-NULL. zostanie ustawiony, by wskazać stan demuxera.

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. i obiekt WebPDemuxer podczas analizy.

Pamiętaj, że WebPDemuxer zachowuje wewnętrzne wskaźniki do segmentu pamięci danych. Jeśli te dane są zmienne, obiekt demuksera powinien zostać usunięty (przez wywołanie metody WebPDemuxDelete()) i Użytkownik WebPDemuxPartial() ponownie wywołał nowe dane. To jest co zwykle jest niedrogą.

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ść właściwości feature z dmux.

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

Uwaga: wartości są prawidłowe tylko wtedy, gdy użyto WebPDemux() lub WebPDemuxPartial() zwraca 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 dmux.

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

Element iter->fragment wskazuje na pierwszy fragment zwracany z tej funkcji. Poszczególne fragmenty można wyodrębnić za pomocą funkcji WebPDemuxSelectFragment() Ustawienie frame_number równy 0 zwraca ostatnią klatkę obrazu.

Zwraca wartość false, jeśli parametr dmux ma wartość NULL lub nie ma ramki dmux. Wywołaj WebPDemuxReleaseIterator(), gdy użyjesz iterator jest zakończony.

Uwaga: parametr dmux musi być aktywny przez cały czas trwania parametru iter.

WebPDemuxNextFrame(), WebPDemuxPrevFrame()

Ustawia element iter->fragment na następny (iter->fragment + 1) lub poprzednia (iter->frame_num – 1) ramka. Te funkcje nie zapętlają się.

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

Zwraca wartość „true” (prawda) w przypadku sukcesu, a wartość „false” (fałsz) w przeciwnym razie.

WebPDemuxSelectFragment()

Ustawia element iter->fragment, aby odzwierciedlał numer fragmentu iter->fragment.

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

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

WebPDemuxReleaseIterator()

Zwalnia pamięć powiązaną z iter.

void WebPDemuxReleaseIterator(WebPIterator* iter);

Ta nazwa musi być wywoływana przed wszystkimi kolejnymi wywołaniami WebPDemuxGetChunk() w ramach tego samego iteru. Musi być także wywołano przed zniszczeniem powiązanego elementu WebPDemuxer z WebPDemuxDelete()

Iteracja fragmentu

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 instancję 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 4 cc dla fragmentu do zwrócenia, np. „ICCP”, „XMP”, „EXIF” itp.

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

Zwraca wartość „true” (prawda), jeśli fragment został znaleziony. W przeciwnym razie zwraca wartość „false” (fałsz). Fragment powiązany z obrazem dostęp do ładunków: WebPDemuxGetFrame() i powiązanych funkcji. Zadzwoń do nas WebPDemuxReleaseChunkIterator(), gdy używasz iterator jest zakończony.

Uwaga: parametr dmux musi być niezmienny przez cały okres istnienia iteratora.

WebPDemuxNextChunk(), WebPDemuxPrevChunk()

Ustawia element iter->chunk tak, aby wskazywał następny (iter->chunk_num + 1) lub poprzedni (iter->chunk_num – 1) fragment. Te funkcje nie zapętlają się.

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

Zwraca wartość „true” (prawda) w przypadku sukcesu, a wartość „false” (fałsz) w przeciwnym razie.

WebPDemuxReleaseChunkIterator()

Zwalnia pamięć powiązaną z iter.

void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);

Trzeba ją wywołać przed zniszczeniem powiązanego z nim elementu WebPDemuxer 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 właściwość powinna być zawsze wywoływana w celu zainicjowania nowego obiektu WebPAnimDecoderOptions przed modyfikacjami. Zwraca wartość fałsz w przypadku niezgodności wersji. Funkcja WebPAnimDecoderOptionsInit() musi zostać wykonana przed użyciem dec_options.

Parametry

dec_options – opcje (we/wyjścia) używane do dekodowania animacji

Zwroty

Prawda w przypadku sukcesu

int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options);

WebPAnimDecoderNew()

Tworzy i inicjuje obiekt WebPAnimDecoder.

Parametry

webp_data – (w) strumieniu bitowym WebP. Powinno się nie zmieniać przez czas życia wyjściowego obiektu WebPAnimDecoder.

dec_options – opcje dekodowania (in). Można przekazać wartość NULL do wyboru rozsądne ustawienia domyślne (w szczególności zostanie wybrany tryb kolorów MODE_RGBA).

Zwroty

Wskaźnik do nowo utworzonego obiektu WebPAnimDecoder lub wartości NULL w przypadku błąd analizy składni, nieprawidłowa opcja lub błąd 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()

Uzyskuj globalne informacje o animacji.

Parametry

dec -- (in) w instancji dekodera, z którego pobierane są informacje.

info – (out) informacje globalne pobrane z animacji.

Zwroty

Sukces tak,

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

WebPAnimDecoderGetNext()

Pobierz następną klatkę z dec na podstawie opcji dostarczonych do WebPAnimDecoderNew(). To będzie pełny to zrekonstruowana płótno o rozmiarze canvas_width * 4 * canvas_height, a nie tylko czyli podprostokątem ramki. Zwracany bufor buf jest ważny tylko do następne połączenie z numerem WebPAnimDecoderGetNext(), WebPAnimDecoderReset() lub WebPAnimDecoderDelete().

Parametry

dec – (we/wy) instancja dekodera, z której ma zostać pobrana następna ramka Pobrano.

buf – (out) zdekodowana ramka.

timestamp – sygnatura czasowa wyświetlenia klatki w milisekundach.

Zwroty

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

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

WebPAnimDecoderHasMoreFrames()

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

Parametry

dec – (in) instancja dekodera do sprawdzenia.

Zwroty

Prawda, jeśli dec nie ma wartości NULL, a niektóre klatki nie zostały jeszcze odkodowane. W przeciwnym razie zwraca wartość „fałsz”.

int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

WebPAnimDecoderReset()

Resetuje obiekt WebPAnimDecoder, aby następne wywołanie WebPAnimDecoderGetNext() ponownie uruchomi dekodowanie od pierwszej klatki. To przydatne, gdy wszystkie klatki muszą być zdekodowane wiele razy (np. info.loop_count times) bez niszczenia ani ponownego tworzenia obiekt dec.

Parametry

dec – instancja dekodera (we/wyj) do zresetowania

void WebPAnimDecoderReset(WebPAnimDecoder* dec);

WebPAnimDecoderGetDemuxer()

Pobierz wewnętrzny obiekt demuxera.

Uzyskanie obiektu demuxera może być przydatne, jeśli ktoś chce używać tylko operacji dostępne za pomocą demuxera; np. aby pobrać metadane XMP/EXIF/ICC. Zwrócone wartości obiekt demuxera jest własnością dec i jest ważny tylko do następnego wywołania WebPAnimDecoderDelete().

Parametry

dec – (in) instancja dekodera, z której ma być obiekt demuxera Pobrano.

const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

Usuwa obiekt WebPAnimDecoder.

Parametry

dec – instancja dekodera (we/wyjść) do usunięcia.

Zwroty

Prawda w odniesieniu do sukcesu

void WebPAnimDecoderDelete(WebPAnimDecoder* dec);

Typowe 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 użyciem wartości domyślnych.

void WebPDataInit(WebPData* webp_data);

WebPDataClear()

Czyści zawartość obiektu webp_data przez wywołanie metody free(). Nie i przetranskrybuj obiekt.

void WebPDataClear(WebPData* webp_data);

WebPDataCopy()

Przypisuje niezbędną pamięć dla dst i kopiuje zawartość src. Zwraca wartość prawda w przypadku sukcesu.

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