本頁面由 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);

Mux 物體的生命週期

列舉

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

參數: mux -- 要刪除 (包含/傳出) 的物件

Mux 創作

`WebPMuxCreate()`

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

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

參數: bitstream -- (in) WebP RIFF 格式的位元串流資料; copy_data -- (in) 值 1 表示指定資料將會複製到 Mux，值 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 -- (其中) 字元陣列，包含指定區塊的 4cc，例如：「ICCP」、「XMP」、「EXIF」等; chunk_data -- (傳入) 要新增的區塊資料; copy_data -- (in) 值 1 表示指定資料將會複製到 Mux，值 0 表示資料「不會」複製到 mux 物件中。
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果 mux、4cc 或 chunk_data 是 NULL，或是 4cc 對應至圖片區塊; WEBP_MUX_MEMORY_ERROR -- 發生記憶體配置錯誤。; WEBP_MUX_OK -- 成功秘訣。

`WebPMuxGetChunk()`

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

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

參數: mux -- (in) 物件做為擷取區塊資料的來源; fourcc -- (in) 包含區塊四 cc 的字元陣列，例如：「ICCP」、「XMP」、「EXIF」等; chunk_data -- (out) 傳回的區塊資料
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果 mux、4cc 或 chunk_data 是 NULL，或是 4cc 對應至圖片區塊; WEBP_MUX_NOT_FOUND - 如果 mux 不包含具有指定 ID 的區塊。; 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 或四個副本是 NULL，或者 4cc 對應於圖片區塊。; WEBP_MUX_NOT_FOUND：如果 Mux 不含具有指定 4cc 的區塊。; 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 表示指定資料將會複製到 Mux，值 0 表示資料「不會」複製到 mux 物件中。
傳回: WEBP_MUX_INVALID_ARGUMENT：如果 mux 為 NULL 或 Bitstream 為 NULL，; WEBP_MUX_MEMORY_ERROR -- 發生記憶體配置錯誤。; WEBP_MUX_OK -- 成功秘訣。

`WebPMuxPushFrame()`

在 Mux 物件結尾加入影格。

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

附註：

frame.id 應為 WEBP_CHUNK_ANMF 或 WEBP_CHUNK_FRGM 其中之一
如要設定非動畫的非動畫圖片，請改用 WebPMuxSetImage()。
推送的影格類型必須與多工中的影格相同。
由於 WebP 僅支援平均偏移，因此任何奇數偏移值會使用偏移 &= ~1 對齊平均位置

參數: mux -- (包含) 要加入頁框的物件; frame -- (in) 影格資料。; copy_data -- (in) 值 1 表示指定資料將會複製到 Mux，值 0 表示資料「不會」複製到 mux 物件中。
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果 mux 或頁框為 NULL，或頁框的內容無效。; WEBP_MUX_MEMORY_ERROR -- 發生記憶體配置錯誤。; WEBP_MUX_OK -- 成功秘訣。; WEBP_MUX_MEMORY_ERROR -- 發生記憶體配置錯誤。

`WebPMuxGetFrame()`

從 Mux 物件取得第 n 個畫面。Frame->bitstream 的內容是使用 Malloc() 分配，但「不」屬於 mux 物件。呼叫端「必須」透過呼叫 WebPDataClear() 取消分配。nth=0 有特殊意義：最後位置。

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

參數: mux -- (in) 物件做為資訊擷取來源; nth -- (中) mux 物件中的影格索引; Frame -- 傳回頁框的資料 (外部) 資料
傳回: WEBP_MUX_INVALID_ARGUMENT：如果 mux 或頁框為空值。; WEBP_MUX_NOT_FOUND：如果 mux 物件中的影格少於第 n 個。; WEBP_MUX_BAD_DATA -- 如果 mux 中的第 n 個頁框區塊無效，; WEBP_MUX_OK -- 成功秘訣。

`WebPMuxDeleteFrame()`

從 mux 物件中刪除影格。nth=0 具有特殊意義：最後一個位置。

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);

參數: mux -- (包含) 物件，要從該物件刪除影格; nth -- (in) 刪除影格的位置
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果 mux 為空值。; WEBP_MUX_NOT_FOUND：如果 mux 物件中的影格少於第 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 -- (out) 從 ANIM 區塊擷取的動畫參數
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果 mux 或參數為 NULL。; WEBP_MUX_NOT_FOUND -- 如果 Mux 物件中沒有 ANIM 區塊。; WEBP_MUX_OK -- 成功秘訣。

其他公用程式

`WebPMuxGetCanvasSize()`

從 Mux 物件取得畫布大小。

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

注意：這個方法會假設 VP8X 區塊 (如有) 是最新版本。也就是說，mux 物件自上次呼叫 WebPMuxAssemble() 或 WebPMuxCreate() 以來都一直沒有修改。

參數: mux -- (in) 物件做為擷取畫布大小的物件; width -- (out) 畫布寬度; height -- (外) 畫布高度
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果 mux、寬度或高度為空值。; 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 -- (in) 物件，用於擷取地圖項目; flags -- (out) 標記，指定 mux 物件中存在哪些地圖項目。會是多個標記值的 OR。列舉 WebPFeatureFlags 可用於測試個別標記值。
傳回: WEBP_MUX_INVALID_ARGUMENT -- 如果 mux 或旗標為空值。; WEBP_MUX_BAD_DATA：如果 VP8X/VP8/VP8L 區塊或無框畫大小無效。; WEBP_MUX_OK -- 成功秘訣。

`WebPMuxNumChunks()`

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

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

參數: mux -- (in) 物件做為資訊擷取來源; id -- (傳入) 區塊 ID，用於指定區塊類型; num_elements -- (退出) 具有特定區塊 ID 的區塊數量
傳回: WEBP_MUX_INVALID_ARGUMENT：如果 mux 或 num_elements 為空值，; WEBP_MUX_OK -- 成功秘訣。

`WebPMuxAssemble()`

組合 WebP RIFF 格式的所有區塊，並以 assembled_data 傳回。這個函式也會驗證 mux 物件。

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

注意：系統會忽略並覆寫 joind_data 的內容。此外，assembled_data 的內容是使用 Malloc() 進行分配，但「不」由 assembled_data 物件擁有。呼叫端必須呼叫 WebPDataClear() 來取消分配。

參數: mux -- (輸入/輸出) 物件，要組合其中的區塊; assembled_data -- (輸出) 經過組合的 WebP 資料
傳回: WEBP_MUX_BAD_DATA -- 假如 mux 物件無效。; WEBP_MUX_INVALID_ARGUMENT：如果 mux 或 joind_data 為 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 -- 用於編碼動畫的選項
傳回: 滿載而歸。

int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

`WebPAnimEncoderNew()`

建立並初始化 WebPAnimEncoder 物件。

參數: width/height -- (in) 動畫的畫布寬度和高度。; enc_options -- (傳入) 編碼選項；可傳送 NULL 來挑選合理的預設值。
傳回: 指標指向新建立的 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 -- (in) 此影格的時間戳記 (以毫秒為單位)。影格的持續時間計算方式為「下一個影格的時間戳記 - 此影格的時間戳記」。因此，時間戳記應採用遞增順序。; config -- (in) 編碼選項；可傳遞 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 -- (傳入/傳出) 物件，也就是影格組合的來源。; webp_data -- (輸出) 產生的 WebP 位元串流。
傳回: 滿載而歸。

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

`WebPAnimEncoderGetError()`

使用 enc 取得與最近一次呼叫相對應的錯誤字串。傳回的字串為 enc 所有，且只會在下一次呼叫 WebPAnimEncoderAdd()、WebPAnimEncoderAssemble() 或 WebPAnimEncoderDelete() 時生效。

參數: enc -- (來自/傳出) 物件，用於擷取錯誤字串。
傳回: NULL if enc is NULL. 否則，如果上次呼叫 enc 發生錯誤，就會傳回錯誤字串；如果上次呼叫成功，則會傳回空白字串。

const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

`WebPAnimEncoderDelete()`

刪除 WebPAnimEncoder 物件。

參數: 「enc」 -- 要刪除的物件 (傳入/傳出)

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

傳回 Demux 程式庫的版本編號，針對每個主要/次要/修訂版本 8 位元封裝在十六進位數字中。例如，2.5.7 版是 0x020507。

int WebPGetDemuxVersion(void);

`WebPDemux()`

剖析由 data 提供的完整 WebP 檔案。

WebPDemuxer WebPDemux(const WebPData* data);

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

`WebPDemuxPartial()`

剖析資料提供的可能不完整 WebP 檔案。如果 state 為非 NULL，則會設定表示 demuxer 的狀態。

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

如果發生錯誤，或資料不足而無法開始剖析時，系統會傳回 NULL；剖析成功時，則傳回 WebPDemuxer 物件。

請注意，WebPDemuxer 會保留內部指標至「資料」記憶體片段。如果這項資料是易變性，系統應先呼叫 WebPDemuxDelete() 來刪除 Demuxer 物件，然後在新資料上再次呼叫 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()`

從 dmux 擷取頁框 frame_number。

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

iter->fragment 會指向從這個函式傳回的第一個片段。您可以使用 WebPDemuxSelectFragment() 擷取個別片段。將 frame_number 設為 0 就會傳回圖片的最後一個影格。

如果 dmux 是 NULL 或頁框 frame_number 沒有，就會傳回 false。使用疊代器時，請呼叫 WebPDemuxReleaseIterator()。

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

`WebPDemuxNextFrame()`、`WebPDemuxPrevFrame()`

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

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

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

`WebPDemuxSelectFragment()`

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

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

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

`WebPDemuxReleaseIterator()`

釋出任何與 iter 相關聯的記憶體。

void WebPDemuxReleaseIterator(WebPIterator* iter);

必須先呼叫，再呼叫相同疊代器上的 WebPDemuxGetChunk()。此外，在刪除與 WebPDemuxDelete() 相關聯的 WebPDemuxer 前，必須先呼叫此呼叫。

區塊疊代

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

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

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

fourcc 是包含要傳回的區塊 4cc 的字元陣列，例如：「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);

刪除與 WebPDemuxDelete() 相關聯的 WebPDemuxer 前，必須呼叫此方法。

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 -- (in) WebP 位元串流。在輸出 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()`

根據提供給 WebPAnimDecoderNew() 的選項，從 dec 擷取下一個影格。這將是經過完整重新建構的 canvas_width * 4 * canvas_height 畫布，而不只是影格子矩形。傳回的緩衝區 buf 只有在下次呼叫 WebPAnimDecoderGetNext()、WebPAnimDecoderReset() 或 WebPAnimDecoderDelete() 時才會生效。

參數: dec -- (傳入/傳出) 解碼器執行個體，用於擷取下一個影格。; buf -- (out) 解碼影格。; timestamp -- (退出) 影格的時間戳記，以毫秒為單位。
傳回: 如果任何引數為 NULL、有剖析或解碼錯誤，或已經沒有影格，則為 False。如果沒有，則會傳回 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 物件就非常實用。傳回的 Demuxer 物件由 dec 擁有，只有在下次呼叫 WebPAnimDecoderDelete() 時才會生效。

參數: dec -- (in) 解碼器執行個體，用於擷取 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 檔案取得圖片和顏色概況資料

Mux 物體的生命週期

列舉

WebPGetMuxVersion()

WebPMuxNew()

WebPMuxDelete()

Mux 創作

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