本頁面由 Cloud Translation API 翻譯而成。

WebP Container API 說明文件

WebP 映像檔的 RIFF 容器操控。

Mux API

可操控含有顏色等功能的 WebP 容器映像檔個人資料、中繼資料、動畫和分段圖片

程式碼範例

使用影像資料、色彩設定檔和 XMP 中繼資料建立 MUX

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

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

多支物件的生命週期

列舉

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

傳回以十六進制封裝的 mux 程式庫版本號碼每個主要/次要/修訂版本 8 位元。例如 2.5.7 版為 0x020507。

int WebPGetMuxVersion(void);

`WebPMuxNew()`

建立空白的 mux 物件。

WebPMux* WebPMuxNew(void);

傳回: 指向新建的空白 mux 物件的指標。

`WebPMuxDelete()`

刪除 mux 物件。

void WebPMuxDelete(WebPMux* mux);

參數: 要刪除的物件 -- (插入/輸出)

多重建立

`WebPMuxCreate()`

使用 WebP RIFF 格式提供的原始資料建立 mux 物件。

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

參數: bitstream -- (使用) WebP RIFF 格式的位元流資料; copy_data -- (in) 值 1 表示指定資料「會」複製到多工且值 0 表示資料「不會」複製到 mux 物件。
傳回: 指標：指標在成功時，根據指定資料建立的 mux 物件。; NULL -- 如果資料無效或記憶體錯誤。

非圖片區塊

`WebPMuxSetChunk()`

在 mux 物件中，新增 ID 為 fourcc 且資料 chunk_data 的區塊。不限系統會移除 ID 相同的現有區塊。

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

注意：只能透過區塊 API 管理與圖片無關的區塊。 (圖片相關區塊為：「ANMF」、「FRGM」、「VP8」、「VP8L」和「ALPH」)。如何新增取得及刪除圖片、使用 WebPMuxSetImage()、 WebPMuxPushFrame(), WebPMuxGetFrame() 和 WebPMuxDeleteFrame()。

參數: mux -- (加入/輸出) 要新增區塊的物件; fourcc -- (in) 字元陣列，包含指定 4cc 的指定值 chunk;例如：「ICCP」、「XMP」、「EXIF」依此類推; chunk_data -- (放入) 要新增的區塊資料; copy_data -- (in) 值 1 表示指定資料「會」複製到多工且值 0 表示資料「不會」複製到 mux 物件。
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果 mux、4cc 或 chunk_data 為 NULL，或者四個 cc 對應至一個影像區塊; WEBP_MUX_MEMORY_ERROR -- 發生記憶體配置錯誤。; WEBP_MUX_OK -- 成功。

`WebPMuxGetChunk()`

取得 mux 物件中 ID 為 fourcc 的區塊資料的參照。呼叫端「不得」釋放傳回的資料。

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

參數: mux -- (要用來擷取區塊資料的物件); fourcc -- (in) 包含區塊四 cc 的字元陣列；例如：「ICCP」、「XMP」、「EXIF」依此類推; chunk_data -- (傳出) 傳回的區塊資料
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果 mux、4cc 或 chunk_data 為 NULL，或者四個 cc 對應至一個影像區塊; WEBP_MUX_NOT_FOUND - 如果 mux 不含含有指定值的區塊編號。; WEBP_MUX_OK -- 成功。

`WebPMuxDeleteChunk()`

從 mux 物件中刪除具有指定 fourcc 的區塊。

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

參數: mux -- (插入/輸出) 物件，以便刪除區塊; fourcc -- (in) 包含區塊四 cc 的字元陣列；例如：「ICCP」、「XMP」、「EXIF」依此類推
傳回: WEBP_MUX_INVALID_ARGUMENT：如果 mux 或 4cc 為 NULL，或者是 4cc 都會對應至一個圖像區塊; WEBP_MUX_NOT_FOUND - 如果 mux 不含含有指定值的區塊四件副本; WEBP_MUX_OK -- 成功。

圖片

封裝單一影格/片段的相關資料。

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

設定 mux 物件中的 (非動畫和非分段) 圖像。 注意：系統會移除所有現有圖片 (包括頁框/片段)。

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

參數: mux -- (增加/輸出) 圖片，此物件要設為圖像; bitstream -- (in) 可以是原始 VP8/VP8L 位元串流或單一圖片 WebP 檔案 (非動畫和非片段檔案); copy_data -- (in) 值 1 表示指定資料「會」複製到多工且值 0 表示資料「不會」複製到 mux 物件。
傳回: WEBP_MUX_INVALID_ARGUMENT：如果 mux 為 NULL，或者 Bitstream 為 NULL。; WEBP_MUX_MEMORY_ERROR -- 發生記憶體配置錯誤。; WEBP_MUX_OK -- 成功。

`WebPMuxPushFrame()`

在多工物件的結尾處加上頁框。

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

注意：

frame.id 應為 WEBP_CHUNK_ANMF 或 WEBP_CHUNK_FRGM 其中之一
如要設定非動畫的非動畫圖片，請使用 WebPMuxSetImage()。
推送的影格類型必須與 mux 中的影格相同。
WebP 僅支援平均偏移，因此系統會比對所有奇數偏移移至偶數位置，然後使用： offset &= ~1

參數: mux -- (加入/結束) 要新增影格的目標物件; Frame -- (in) 影格資料。; copy_data -- (in) 值 1 表示指定資料「會」複製到多工且值 0 表示資料「不會」複製到 mux 物件。
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果多工或框架為 NULL，或者 Frame 無效。; WEBP_MUX_MEMORY_ERROR -- 發生記憶體配置錯誤。; WEBP_MUX_OK -- 成功。; WEBP_MUX_MEMORY_ERROR -- 發生記憶體配置錯誤。

`WebPMuxGetFrame()`

從 mux 物件取得第 n 個畫面。Frame->bitstream 的內容是使用 Malloc() 配置，且「不是」由 mux 物件擁有。一定要有呼叫 WebPDataClear() 即可由呼叫端取消定位。N=0 有特殊意義 - 最終位置

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

參數: mux -- (要擷取資訊的物件); nth -- (in) 多工物件中框架的索引; Frame -- (傳出) 傳回的影格資料
傳回: WEBP_MUX_INVALID_ARGUMENT -- if mux or frame is NULL.; WEBP_MUX_NOT_FOUND：如果多工影格數少於 n 個物件。; WEBP_MUX_BAD_DATA -- 如果 mux 中的第 n 個影格區塊無效。; WEBP_MUX_OK -- 成功。

`WebPMuxDeleteFrame()`

從多工物件中刪除外框。nth=0 有特殊意義 - 最後位置。

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);

參數: mux -- (加入/輸出) 物件，要刪除影格; nth -- (內) 要刪除影格的位置
傳回: WEBP_MUX_INVALID_ARGUMENT -- if mux is NULL.; WEBP_MUX_NOT_FOUND - 如果多工影格數少於 n 個物件後再刪除。; WEBP_MUX_OK -- 成功。

動畫

動畫參數

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

設定 mux 物件中的動畫參數。任何現有的 ANIM 區塊可能會移除。

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

參數: mux -- (傳入/傳出) 要設定/新增 ANIM 區塊的物件; params -- (in) 動畫參數。
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果 mux 或參數為 NULL。; WEBP_MUX_MEMORY_ERROR -- 發生記憶體配置錯誤。; WEBP_MUX_OK -- 成功。

`WebPMuxGetAnimationParams()`

從 mux 物件取得動畫參數。

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

參數: mux -- (in) 要擷取動畫參數的物件; params -- (傳出) 從 ANIM 區塊擷取的動畫參數
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果 mux 或參數為 NULL。; WEBP_MUX_NOT_FOUND -- 如果 ANIM 區塊不存在於多工物件中。; WEBP_MUX_OK -- 成功。

其他實用工具

`WebPMuxGetCanvasSize()`

從 mux 物件取得畫布大小。

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

注意：這個方法假設 VP8X 區塊 (如有) 是最新版本。這表示 mux 物件在上次呼叫 WebPMuxAssemble() 或 WebPMuxCreate()。

參數: mux -- (英寸) 物件，用於擷取畫布大小; 寬度 -- (離開) 畫布寬度; height -- (非) 畫布高度
傳回: WEBP_MUX_INVALID_ARGUMENT -- if mux, width or height is NULL.; WEBP_MUX_BAD_DATA -- 如果 VP8X/VP8/VP8L 區塊或畫布大小無效。; WEBP_MUX_OK -- 成功。

`WebPMuxGetFeatures()`

從 mux 物件取得功能旗標。

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

注意：這個方法假設 VP8X 區塊 (如有) 是最新版本。這表示 mux 物件在上次呼叫 WebPMuxAssemble() 或 WebPMuxCreate()。

參數: mux -- (吋) 要被擷取特徵的物件; flags -- (結束) 用於指定 mux 中存在的功能物件。這會是不同旗標值的 OR。列舉 WebPFeatureFlags 可用來測試個別旗標值。
傳回: WEBP_MUX_INVALID_ARGUMENT -- if mux or flags is NULL.; WEBP_MUX_BAD_DATA -- 如果 VP8X/VP8/VP8L 區塊或畫布大小無效。; WEBP_MUX_OK -- 成功。

`WebPMuxNumChunks()`

取得 mux 物件中具有指定標記值的區塊數量。

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

參數: mux -- (要擷取資訊的物件); id -- (放入) 指定區塊類型的區塊 ID; num_elements -- (傳出) 具有指定區塊 ID 的區塊數量
傳回: WEBP_MUX_INVALID_ARGUMENT -- if mux, or num_elements is NULL.; WEBP_MUX_OK -- 成功。

`WebPMuxAssemble()`

以 WebP RIFF 格式組合所有區塊，並以 assembled_data 傳回。此函式也會驗證多工物件。

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

注意：系統會忽略並覆寫 compiled_data 的內容。此外，assembled_data 的內容會使用 malloc() 進行分配，而 NOT mux 物件的所有屬性。必須由呼叫端透過呼叫來分配其位置 WebPDataClear()。

參數: mux -- (輸入/輸出) 物件，其中要組合的區塊; assembled_data -- (傳出) 組合的 WebP 資料
傳回: WEBP_MUX_BAD_DATA -- 如果 mux 物件無效。; WEBP_MUX_INVALID_ARGUMENT -- if mux or assembled_data is NULL.; WEBP_MUX_MEMORY_ERROR -- 發生記憶體配置錯誤。; WEBP_MUX_OK -- 成功。

WebPAnimEncoder API

此 API 允許對 (可能) 動畫的 WebP 圖片進行編碼。

程式碼範例

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.

全域選項

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

應一律呼叫，以初始化全新的 WebPAnimEncoderOptions 所以再進行修改版本不符時會傳回 false。 WebPAnimEncoderOptionsInit() 必須成功執行，才能使用 enc_options 物件。

參數: enc_options -- (in/out) 編碼動畫所用的選項
傳回: 對成功才是正確答案。

int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

`WebPAnimEncoderNew()`

建立並初始化 WebPAnimEncoder 物件。

參數: width/height -- (以) 動畫的畫布寬度和高度。; enc_options -- (in) 編碼選項；可以傳遞空值合理的預設值
傳回: 指向新建 WebPAnimEncoder 物件的指標，如果發生這種情況，則指向 NULL 就可能發生這種錯誤

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

`WebPAnimEncoderAdd()`

針對 WebP 最佳化指定影格、進行編碼並將其新增至 WebPAnimEncoder 物件。

對 WebPAnimEncoderAdd 的最後一次呼叫應以 frame = NULL 表示，表示不會再新增任何頁框。這場通話也會用於決定最後一個影格的時間長度

參數: enc -- (加入/結束) 要加入影格的目標物件。; Frame -- (輸入/輸出) 影格資料，格式為 ARGB 或 YUV(A)。採用 YUV(A) 格式會轉換為 ARGB，這會造成些許損失。; timestamp_ms -- 這個影格的時間戳記，以毫秒為單位。時間長度會計算為「下一個影格的時間戳記 - 時間戳記的這個影格」。因此，時間戳記應以非遞減順序。; config -- (使用) 編碼選項；傳入 NULL，以選取預設值。
傳回: 如果發生錯誤，系統會傳回 false，並正確設定 frame->error_code。如果沒有，則會傳回 true。

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

`WebPAnimEncoderAssemble()`

將到目前為止新增的所有影格合併至 WebP 位元流。這場通話應該前面加上 frame = NULL 對 WebPAnimEncoderAdd 的呼叫；如果不是，最後一個影格的時間長度為內部預估值。

參數: enc -- (in/out) 物件，用來組合影格。; webp_data -- (傳出) 產生的 WebP 位元。
傳回: 對成功才是明智之舉。

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

`WebPAnimEncoderGetError()`

使用 enc 取得與最近一次呼叫相對應的錯誤字串。傳回的字串是由 enc 所擁有，且有效期限到下一個呼叫 WebPAnimEncoderAdd() 或 WebPAnimEncoderAssemble() 或 WebPAnimEncoderDelete()。

參數: enc -- (in/out) 物件，要擷取錯誤字串。
傳回: NULL if enc is NULL.否則，如果最後一個呼叫 enc 出現錯誤；如果上次呼叫是成效。

const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

`WebPAnimEncoderDelete()`

刪除 WebPAnimEncoder 物件。

參數: enc -- (in/out) 要刪除的物件

void WebPAnimEncoderDelete(WebPAnimEncoder* enc);

Demux API

啟用從 WebP 檔案擷取圖片和擴充格式資料的功能。

程式碼範例

解構 WebP 資料以擷取所有影格、ICC 設定檔和 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);

Demux 物件的生命週期

列舉

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

傳回以 16 進位格式封裝的 demux 程式庫版本號碼每個主要/次要/修訂版本 8 位元。例如 2.5.7 版是 0x020507。

int WebPGetDemuxVersion(void);

`WebPDemux()`

這個外掛程式能剖析資料提供的完整 WebP 檔案。

WebPDemuxer WebPDemux(const WebPData* data);

成功剖析時會傳回 WebPDemuxer 物件，否則傳回 NULL。

`WebPDemuxPartial()`

這個外掛程式能剖析由資料提供，但可能不完整的 WebP 檔案。如果 state 是如果不是空值，則會設為表示 demuxer 的狀態。

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

如果出現錯誤，或資料不足而無法開始剖析時，則會傳回 NULL；和 WebPDemuxer 物件。

請注意，WebPDemuxer 會保留內部指標至「資料」記憶體區段。如果這屬於易變性資料，刪除 demuxer 物件 (方法是呼叫 WebPDemuxDelete()) 和新資料再次呼叫 WebPDemuxPartial()。這是通常執行成本低廉

`WebPDemuxDelete()`

釋放與 dmux 相關聯的記憶體。

void WebPDemuxDelete(WebPDemuxer* dmux);

資料/資訊擷取

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

從 dmux 取得 feature 值。

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

注意：只有在使用 WebPDemux() 或 WebPDemuxPartial() 傳回狀態 > WEBP_DEMUX_PARSING_HEADER。

影格疊代

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

從 frame_number 擷取影格 frame_number。

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

iter->fragment ，會指向傳回此函式時的第一個片段。可使用以下程式碼擷取個別片段： WebPDemuxSelectFragment()。設定 frame_number 等於 0 會傳回圖片的最後一個影格。

如果 dmux 為 NULL，或者影格 dmux 不存在，就會傳回 false。使用WebPDemuxReleaseIterator() iterator 已完成。

注意： dmux 必須在 iter 的生命週期內持續存在。

`WebPDemuxNextFrame()`、`WebPDemuxPrevFrame()`

將 iter->fragment 設為指向下一個 (iter->fragment + 1) 或上一個 (iter->frame_num - 1) 影格。這些函式不會循環播放。

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

成功時會傳回 true，否則傳回 false。

`WebPDemuxSelectFragment()`

設定 iter->fragment 以反映片段編號 iter->fragment。

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

如果片段 fragment_num 存在，則傳回 true，否則傳回 false。

`WebPDemuxReleaseIterator()`

釋出與 iter 相關聯的所有記憶體。

void WebPDemuxReleaseIterator(WebPIterator* iter);

必須先呼叫，才能再呼叫使用相同疊代的 WebPDemuxGetChunk()。同時，你必須為才會刪除相關聯的 WebPDemuxer WebPDemuxDelete()。

區塊疊代

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

從 ID fourcc 擷取區塊的 chunk_number 執行個體。 dmux：

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

fourcc 是一個字元陣列，包含要傳回的區塊的四個 cc。例如：「ICCP」、「XMP」、「EXIF」等

將 chunk_number 設為 0 時會傳回集合中的最後一個區塊。

如果找到區塊，則傳回 true，否則傳回 false。圖片相關區塊可透過 WebPDemuxGetFrame() 存取酬載和相關函式致電 WebPDemuxReleaseChunkIterator() (使用時) 完成的疊代作業

注意： dmux 必須在疊代器的生命週期內持續保留。

`WebPDemuxNextChunk()`、`WebPDemuxPrevChunk()`

設定 iter->chunk 指向下一個 (iter->chunk_num + 1) 或上 (iter->chunk_num - 1) 區塊。這些函式不會循環播放。

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

成功時會傳回 true，否則傳回 false。

`WebPDemuxReleaseChunkIterator()`

釋出與 iter 相關聯的所有記憶體。

void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);

必須先呼叫，才能刪除相關聯的 WebPDemuxer WebPDemuxDelete()。

WebPAnimDecoder API

這個 API 允許解碼 (可能) 動畫 WebP 圖片。

程式碼範例

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.

全域選項

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

應一律呼叫，以初始化全新的 WebPAnimDecoderOptions 結構版本不符時會傳回 false。 WebPAnimDecoderOptionsInit() 必須成功執行，才能使用 dec_options 物件。

參數

dec_options -- (增加/輸出) 用於解碼動畫的選項

傳回: 是成功的不二法門

int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options);

`WebPAnimDecoderNew()`

建立並初始化 WebPAnimDecoder 物件。

參數: webp_data -- (位於) WebP 位元流。在 2024 年 1 月 1 日輸出 WebPAnimDecoder 物件的生命週期。; dec_options -- (in) 解碼選項。如要選擇，您可以傳遞 NULL 值合理的預設值 (尤其是選擇色彩模式 MODE_RGBA)。
傳回: 指向新建 WebPAnimDecoder 物件的指標，如果發生這種情況，則指向 NULL 發生剖析錯誤、選項或記憶體錯誤。

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

動畫的全域資訊。

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

`WebPAnimDecoderGetInfo()`

取得動畫的全域資訊。

參數: dec -- (in) 解碼器執行個體，從中取得資訊。; info -- (傳出) 從動畫擷取的全域資訊。
傳回: 對成功才是明智之舉。

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

`WebPAnimDecoderGetNext()`

根據提供給以下的選項，從 dec 擷取下一個影格 WebPAnimDecoderNew()。這將是經過重建且大小為 canvas_width * 4 * canvas_height 的畫布，而不僅僅是影格子矩形。傳回的緩衝區 buf 僅在向 WebPAnimDecoderGetNext() 發出下一次呼叫 WebPAnimDecoderReset() 或 WebPAnimDecoderDelete()。

參數: dec -- (輸入/輸出) 解碼器例項，且下一個影格的顯示位置擷取。; buf -- (傳出) 經過解碼的框架。; timestamp -- (out) 影格的時間戳記，以毫秒為單位。
傳回: 如果任何引數為 NULL，或者有剖析或或沒有其他影格的話如果沒有，則會傳回 true。

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

`WebPAnimDecoderHasMoreFrames()`

檢查還有更多影格需要解碼。

參數: dec (以) 解碼器執行個體待檢查。
傳回: 如果 dec 不是 NULL，且部分影格尚未解碼，則為 True。如果沒有，則會傳回 false。

int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

`WebPAnimDecoderReset()`

重設 WebPAnimDecoder 物件，因此下一個呼叫「WebPAnimDecoderGetNext()」會重新開始解碼第 1 個畫面這對於需要為所有影格解碼時相當實用 (例如：info.loop_count 次)，而且並未刪除並重建 dec 物件。

參數: dec (傳入/傳出) 要重設的解碼器執行個體

void WebPAnimDecoderReset(WebPAnimDecoder* dec);

`WebPAnimDecoderGetDemuxer()`

取得內部 demuxer 物件。

如果需要只使用作業，取得 demuxer 物件是相當實用的做法可透過 demuxer 取得；例如：取得 XMP/EXIF/ICC 中繼資料。傳回的 demuxer 物件由 dec 所擁有，且有效期限到下次呼叫 WebPAnimDecoderDelete()。

參數: dec (使用) 解碼器執行個體，demuxer 物件的來源擷取。

const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

`WebPAnimDecoderDelete()`

刪除 WebPAnimDecoder 物件。

參數: dec (增加/輸出) 要刪除的解碼器執行個體。
傳回: 對成功才是正確答案。

void WebPAnimDecoderDelete(WebPAnimDecoder* dec);

常見資料類型

列舉

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

使用預設值初始化 webp_data 物件的內容。

void WebPDataInit(WebPData* webp_data);

`WebPDataClear()`

透過呼叫 free() 清除 webp_data 物件的內容。不行請先取消分配物件本身

void WebPDataClear(WebPData* webp_data);

`WebPDataCopy()`

為 dst 分配必要儲存空間，並複製 src 的內容。成功時會傳回 true。

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

WebP Container API 說明文件

Mux API

程式碼範例

使用影像資料、色彩設定檔和 XMP 中繼資料建立 MUX

從 WebP 檔案取得圖片和色彩設定檔資料

多支物件的生命週期

列舉

WebPGetMuxVersion()

WebPMuxNew()

WebPMuxDelete()

多重建立

WebPMuxCreate()

非圖片區塊

WebPMuxSetChunk()

WebPMuxGetChunk()

WebPMuxDeleteChunk()

圖片

WebPMuxSetImage()

WebPMuxPushFrame()

WebPMuxGetFrame()

WebPMuxDeleteFrame()

動畫

動畫參數

WebPMuxSetAnimationParams()

WebPMuxGetAnimationParams()

其他實用工具

WebPMuxGetCanvasSize()

WebPMuxGetFeatures()

WebPMuxNumChunks()

WebPMuxAssemble()

WebPAnimEncoder API

WebPAnimEncoderOptionsInit()

WebPAnimEncoderNew()

WebPAnimEncoderAdd()

WebPAnimEncoderAssemble()

WebPAnimEncoderGetError()

WebPAnimEncoderDelete()

Demux API

程式碼範例

解構 WebP 資料以擷取所有影格、ICC 設定檔和 EXIF/XMP 中繼資料

Demux 物件的生命週期

列舉

WebPGetDemuxVersion()

WebPDemux()

WebPDemuxPartial()

WebPDemuxDelete()

資料/資訊擷取

WebPDemuxGetI()

影格疊代

WebPDemuxGetFrame()

WebPDemuxNextFrame()、WebPDemuxPrevFrame()

WebPDemuxSelectFragment()

WebPDemuxReleaseIterator()

區塊疊代

WebPDemuxGetChunk()

WebPDemuxNextChunk()、WebPDemuxPrevChunk()

WebPDemuxReleaseChunkIterator()

WebPAnimDecoder API

WebPAnimDecoderOptionsInit()

WebPAnimDecoderNew()

WebPAnimDecoderGetInfo()

WebPAnimDecoderGetNext()

WebPAnimDecoderHasMoreFrames()

WebPAnimDecoderReset()

WebPAnimDecoderGetDemuxer()

WebPAnimDecoderDelete()

常見資料類型

列舉

WebPDataInit()

WebPDataClear()

WebPDataCopy()

`WebPGetMuxVersion()`

`WebPMuxNew()`

`WebPMuxDelete()`

`WebPMuxCreate()`

`WebPMuxSetChunk()`

`WebPMuxGetChunk()`

`WebPMuxDeleteChunk()`

`WebPMuxSetImage()`

`WebPMuxPushFrame()`

`WebPMuxGetFrame()`

`WebPMuxDeleteFrame()`

`WebPMuxSetAnimationParams()`

`WebPMuxGetAnimationParams()`

`WebPMuxGetCanvasSize()`

`WebPMuxGetFeatures()`

`WebPMuxNumChunks()`

`WebPMuxAssemble()`

`WebPAnimEncoderOptionsInit()`

`WebPAnimEncoderNew()`

`WebPAnimEncoderAdd()`

`WebPAnimEncoderAssemble()`

`WebPAnimEncoderGetError()`

`WebPAnimEncoderDelete()`

`WebPGetDemuxVersion()`

`WebPDemux()`

`WebPDemuxPartial()`

`WebPDemuxDelete()`

`WebPDemuxGetI()`

`WebPDemuxGetFrame()`

`WebPDemuxNextFrame()`、`WebPDemuxPrevFrame()`

`WebPDemuxSelectFragment()`

`WebPDemuxReleaseIterator()`

`WebPDemuxGetChunk()`

`WebPDemuxNextChunk()`、`WebPDemuxPrevChunk()`

`WebPDemuxReleaseChunkIterator()`

`WebPAnimDecoderOptionsInit()`

`WebPAnimDecoderNew()`

`WebPAnimDecoderGetInfo()`

`WebPAnimDecoderGetNext()`

`WebPAnimDecoderHasMoreFrames()`

`WebPAnimDecoderReset()`

`WebPAnimDecoderGetDemuxer()`

`WebPAnimDecoderDelete()`

`WebPDataInit()`

`WebPDataClear()`

`WebPDataCopy()`