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()
メジャー/マイナー/リビジョンごとに 8 ビットを使用し、マルチプレクサ ライブラリのバージョン番号を 16 進数で返します。たとえば、v2.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 -- WebP RIFF 形式のビットストリーム データ
copy_data --(in)値 1 は特定のデータが mux にコピーされることを示し、値 0 はデータが mux オブジェクトにコピーされないことを示します。
- 戻り値
特定のデータから作成された mux オブジェクトへのポインタ。成功時です。
NULL -- 無効なデータエラーまたはメモリエラーの場合。
非画像チャンク
WebPMuxSetChunk()
ID fourcc と data chunk_data のチャンクを mux オブジェクトに追加します。同じ 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、fourcc または chunk_data が NULL の場合、または fourcc がイメージ チャンクに対応している場合。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 --(中)チャンクの 4cc を含む文字配列。例:「ICCP」、「XMP」、「EXIF」など
chunk_data -- 返されたチャンクデータ(出力)
- 戻り値
WEBP_MUX_INVALID_ARGUMENT
-- mux、fourcc または chunk_data が NULL の場合、または fourcc がイメージ チャンクに対応している場合。WEBP_MUX_NOT_FOUND
- 指定された ID のチャンクが mux に含まれていない場合。WEBP_MUX_OK
-- 成功の場合。
WebPMuxDeleteChunk()
指定された fourcc を持つチャンクを mux オブジェクトから削除します。
WebPMuxError WebPMuxDeleteChunk(WebPMux* mux, const char fourcc[4]);
- パラメータ
mux -- チャンクを削除する(入出力)オブジェクト
fourcc --(中)チャンクの 4cc を含む文字配列。例:「ICCP」、「XMP」、「EXIF」など
- 戻り値
WEBP_MUX_INVALID_ARGUMENT
-- mux または fourcc が NULL の場合、または fourcc がイメージ チャンクに対応している場合。WEBP_MUX_NOT_FOUND
- 指定された fourcc で 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 -- 画像を設定する(in/out)オブジェクト
bitstream -- (in)は、未加工の VP8/VP8L ビットストリーム、または単一画像の WebP ファイル(アニメーションおよび非断片化)です。
copy_data --(in)値 1 は特定のデータが mux にコピーされることを示し、値 0 はデータが mux オブジェクトにコピーされないことを示します。
- 戻り値
WEBP_MUX_INVALID_ARGUMENT
-- マルチプレクサが NULL またはビットストリームが NULL の場合。WEBP_MUX_MEMORY_ERROR
-- メモリ割り当てエラー。WEBP_MUX_OK
-- 成功の場合。
WebPMuxPushFrame()
マルチプレクサ オブジェクトの最後にフレームを追加します。
WebPMuxError WebPMuxPushFrame(WebPMux* mux,
const WebPMuxFrameInfo* frame,
int copy_data);
Notes:
- image.id は
WEBP_CHUNK_ANMF
またはWEBP_CHUNK_FRGM
のいずれかにする必要があります。 - アニメーションなし、断片化されていない画像を設定するには、代わりに
WebPMuxSetImage()
を使用します。 - プッシュされるフレームのタイプは、マルチプレクサのフレームと同じである必要があります。
- WebP は偶数のオフセットのみをサポートしているため、奇数オフセットは、offset &= ~1 を使用して偶数の位置にスナップされます。
- パラメータ
mux -- フレームを追加する(in/out)オブジェクト
frame -- (内)フレームデータ。
copy_data --(in)値 1 は特定のデータが mux にコピーされることを示し、値 0 はデータが mux オブジェクトにコピーされないことを示します。
- 戻り値
WEBP_MUX_INVALID_ARGUMENT
-- mux またはフレームが NULL の場合、または frame のコンテンツが無効な場合。WEBP_MUX_MEMORY_ERROR
-- メモリ割り当てエラー。WEBP_MUX_OK
-- 成功の場合。WEBP_MUX_MEMORY_ERROR
-- メモリ割り当てエラー。
WebPMuxGetFrame()
マルチプレクサ オブジェクトから n 番目のフレームを取得します。frame->bitstream のコンテンツは malloc() を使用して割り当てられ、mux オブジェクトによって所有されません。呼び出し元が WebPDataClear()
を呼び出して割り当てを解除しなければなりません。nth=0 には、最後の位置という特別な意味があります。
WebPMuxError WebPMuxGetFrame(const WebPMux* mux,
uint32_t nth,
WebPMuxFrameInfo* frame);
- パラメータ
mux -- 情報を取得する対象の(内)オブジェクト
nth -- mux オブジェクト内のフレームの(in)インデックス
frame -- 返されたフレームの(出力)データ
- 戻り値
WEBP_MUX_INVALID_ARGUMENT
-- mux またはフレームが NULL の場合。WEBP_MUX_NOT_FOUND
-- mux オブジェクト内のフレームが n 個未満の場合。WEBP_MUX_BAD_DATA
-- Mux の n 番目のフレーム チャンクが無効な場合。WEBP_MUX_OK
-- 成功の場合。
WebPMuxDeleteFrame()
マルチプレクサ オブジェクトからフレームを削除します。nth=0 には、最後の位置という特別な意味があります。
WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);
- パラメータ
mux -- フレームを削除する(in/out)オブジェクト
nth --(in)フレームを削除する位置
- 戻り値
WEBP_MUX_INVALID_ARGUMENT
-- mux が NULL の場合。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 チャンクが設定/追加される(in/out)オブジェクト
params --(in)アニメーション パラメータ。
- 戻り値
WEBP_MUX_INVALID_ARGUMENT
-- マルチプレクサまたはパラメータが NULL の場合。WEBP_MUX_MEMORY_ERROR
-- メモリ割り当てエラー。WEBP_MUX_OK
-- 成功の場合。
WebPMuxGetAnimationParams()
mux オブジェクトからアニメーション パラメータを取得します。
WebPMuxError WebPMuxGetAnimationParams(const WebPMux* mux,
WebPMuxAnimParams* params);
- パラメータ
mux -- 取得するアニメーション パラメータの(内)オブジェクト
params -- ANIM チャンクから抽出された(out)アニメーション パラメータ
- 戻り値
WEBP_MUX_INVALID_ARGUMENT
-- マルチプレクサまたはパラメータが NULL の場合。WEBP_MUX_NOT_FOUND
-- mux オブジェクトに ANIM チャンクが存在しない場合。WEBP_MUX_OK
-- 成功の場合。
その他ユーティリティ
WebPMuxGetCanvasSize()
マルチプレクサ オブジェクトからキャンバス サイズを取得します。
WebPMuxError WebPMuxGetCanvasSize(const WebPMux* mux,
int* width,
int* height);
注: このメソッドは、VP8X チャンク(存在する場合)が最新であることを前提としています。つまり、mux オブジェクトは、前回の WebPMuxAssemble()
または WebPMuxCreate()
の呼び出し以降変更されていません。
- パラメータ
mux -- キャンバス サイズの取得元となるオブジェクト(内)
幅 -- キャンバスの幅(外側)
height -- キャンバスの高さ(外側)
- 戻り値
WEBP_MUX_INVALID_ARGUMENT
-- mux、width、height が 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
-- マルチプレクサまたはフラグが 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
-- mux または num_elements が NULL の場合。WEBP_MUX_OK
-- 成功の場合。
WebPMuxAssemble()
すべてのチャンクを WebP RIFF 形式でアセンブルして、assembled_data で返します。この関数は mux オブジェクトも検証します。
WebPMuxError WebPMuxAssemble(WebPMux* mux, WebPData* assembled_data);
注: sembd_data の内容は無視され、上書きされます。また、assembled_data の内容は malloc() を使用して割り当てられ、assembled_data オブジェクトによって所有されません。呼び出し元が WebPDataClear()
を呼び出して割り当てを解除しなければなりません。
- パラメータ
mux -- チャンクが組み立てられる対象の(入/出)オブジェクト
assembled_data -- 生成された WebP データ(外部)
- 戻り値
WEBP_MUX_BAD_DATA
-- mux オブジェクトが無効な場合。WEBP_MUX_INVALID_ARGUMENT
-- mux または sembd_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 を返します。 enc_options オブジェクトを使用する前に、WebPAnimEncoderOptionsInit() が正常に終了している必要があります。
- パラメータ
- enc_options -- アニメーションのエンコードに使用する(in/out)オプション
- 戻り値
- 成功の場合は正しい。
int WebPAnimEncoderOptionsInit(
WebPAnimEncoderOptions* enc_options);
WebPAnimEncoderNew()
WebPAnimEncoder オブジェクトを作成して初期化します。
- パラメータ
幅/高さ -- キャンバス内でのアニメーションの幅と高さ。
enc_options -- (in)エンコード オプション。適切なデフォルトを選択するには、NULL を渡すことができます。
- 戻り値
新しく作成された WebPAnimEncoder オブジェクトへのポインタ。メモリエラーの場合は NULL。
WebPAnimEncoder* WebPAnimEncoderNew(
int width, int height, const WebPAnimEncoderOptions* enc_options);
WebPAnimEncoderAdd()
指定されたフレームを WebP 用に最適化し、エンコードして、WebPAnimEncoder オブジェクトに追加します。
WebPAnimEncoderAdd の最後の呼び出しは frame = NULL
で行います。これは、フレームがこれ以上追加されないことを示します。この呼び出しは、最後のフレームの継続時間の決定にも使用されます。
- パラメータ
enc -- フレームを追加する(in/out)オブジェクト。
frame -- ARGB または YUV(A) 形式の(イン/アウト)フレームデータ。YUV(A) 形式では ARGB に変換されるため、わずかな損失が発生します。
timestamp_ms -- このフレームのタイムスタンプ(ミリ秒単位)。フレームの長さは「次のフレームのタイムスタンプ - このフレームのタイムスタンプ」として計算されます。そのため、タイムスタンプは降順にする必要があります。
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 -- フレームの作成元となる(in/out)オブジェクト。
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 ビットを使用し、16 進数でパックして返します。たとえば、v2.5.7 は 0x020507
です。
int WebPGetDemuxVersion(void);
WebPDemux()
data で指定された完全な WebP ファイルを解析します。
WebPDemuxer WebPDemux(const WebPData* data);
解析が成功した場合は WebPDemuxer
オブジェクトを返し、それ以外の場合は NULL を返します。
WebPDemuxPartial()
data で指定された未完了の可能性のある WebP ファイルを解析します。state が NULL 以外の場合、デマルチプレクサーのステータスを示すように設定されます。
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()
フラグメント番号 fragment_num を反映するように 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 は、返されるチャンクの fourcc を含む文字配列です。例:「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, ×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.
グローバル オプション
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 を返します。 dec_options オブジェクトを使用するには、WebPAnimDecoderOptionsInit() が正常に終了している必要があります。
パラメータ
dec_options -- アニメーションのデコードに使用される(in/out)オプション
- 戻り値
- 成功の場合は正しい
int WebPAnimDecoderOptionsInit(
WebPAnimDecoderOptions* dec_options);
WebPAnimDecoderNew()
WebPAnimDecoder オブジェクトを作成して初期化します。
- パラメータ
webp_data -- (内)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 -- 情報を取得する(内)デコーダ インスタンス。
info -- アニメーションから取得された(out)グローバル情報。
- 戻り値
成功は「真実」。
int WebPAnimDecoderGetInfo(const WebPAnimDecoder* dec,
WebPAnimInfo* info);
WebPAnimDecoderGetNext()
WebPAnimDecoderNew()
に指定されたオプションに基づいて、dec から次のフレームを取得します。これはフレームのサブレクタングルだけでなく、サイズ canvas_width * 4 * canvas_height
の完全に再構築されたキャンバスになります。返されたバッファ buf は、WebPAnimDecoderGetNext()
、WebPAnimDecoderReset()
、または WebPAnimDecoderDelete()
の次の呼び出しまで有効です。
- パラメータ
dec -- 次のフレームを取得するデコーダ インスタンス(イン/アウト)。
buf -- (out)デコードされたフレーム。
timestamp -- フレームの(out)タイムスタンプ(ミリ秒単位)。
- 戻り値
いずれかの引数が NULL の場合、解析エラーまたはデコード エラーが発生した場合、これ以上フレームがない場合は False です。それ以外の場合は、true を返します。
int WebPAnimDecoderGetNext(WebPAnimDecoder* dec,
uint8_t** buf, int* timestamp);
WebPAnimDecoderHasMoreFrames()
デコードするフレームが残っているかどうかを確認します。
- パラメータ
- dec -- チェック対象の(内)デコーダ インスタンス。
- 戻り値
- dec が NULL でなく、一部のフレームがまだデコードされていない場合は true です。 それ以外の場合は、false を返します。
int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);
WebPAnimDecoderReset()
次回の WebPAnimDecoderGetNext()
呼び出しで最初のフレームからデコードが再開されるように、WebPAnimDecoder オブジェクトをリセットします。これは、dec オブジェクトを破棄して再作成せずにすべてのフレームを複数回(info.loop_count 回など)デコードする必要がある場合に役立ちます。
- パラメータ
- 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);