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:
- Ramka.id powinna mieć wartość
WEBP_CHUNK_ANMF
lubWEBP_CHUNK_FRGM
- Aby ustawić obraz bez animacji, bez fragmentu, użyj parametru
WebPMuxSetImage()
. - Typ wypychanej klatki musi być taki sam jak w przypadku klatek w wielu elementach.
- 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, ×tamp);
// ... (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);