Tài liệu về API vùng chứa WebP

Thao tác với vùng chứa RIFF đối với hình ảnh WebP.

API Mux

Cho phép thao túng hình ảnh vùng chứa WebP, chứa các tính năng như màu sắc cấu hình, siêu dữ liệu, ảnh động và hình ảnh phân mảnh.

Ví dụ về mã

Tạo MUX với dữ liệu hình ảnh, cấu hình màu và siêu dữ liệu 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);

Lấy dữ liệu hồ sơ màu và hình ảnh từ tệp 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);

Vòng đời của một đối tượng Mux

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

Trả về số phiên bản của thư viện mux, được đóng gói theo hệ thập lục phân sử dụng 8 bit cho mỗi phần chính/nhỏ/bản sửa đổi. Ví dụ: phiên bản 2.5.7 là 0x020507.

int WebPGetMuxVersion(void);

WebPMuxNew()

Tạo một đối tượng mux trống.

WebPMux* WebPMuxNew(void);
Giá trị trả về
Con trỏ trỏ đến đối tượng mux trống mới tạo.

WebPMuxDelete()

Xoá đối tượng mux.

void WebPMuxDelete(WebPMux* mux);
Tham số
mux – đối tượng (vào/ra) sẽ bị xoá

Tạo tệp Mux

WebPMuxCreate()

Tạo một đối tượng mux từ dữ liệu thô được cung cấp ở định dạng WebP RIFF.

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

luồng bit – (trong) dữ liệu luồng bit ở định dạng WebP RIFF

copy_data – giá trị (in) 1 cho biết dữ liệu đã cho SẼ được sao chép sang tệp mux và giá trị 0 cho biết dữ liệu sẽ KHÔNG được sao chép vào đối tượng mux.

Giá trị trả về

Một con trỏ trỏ đến đối tượng mux được tạo từ dữ liệu đã cho – khi thành công.

NULL -- Trong trường hợp có lỗi dữ liệu hoặc bộ nhớ không hợp lệ.

Đoạn không phải hình ảnh

WebPMuxSetChunk()

Thêm một phân đoạn có mã fourcc và dữ liệu chunk_data trong đối tượng mux. Bất kỳ hạng nào (các) đoạn hiện tại có cùng mã thì sẽ bị xoá.

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

Lưu ý: Bạn chỉ nên quản lý các đoạn không liên quan đến hình ảnh thông qua API phân đoạn. (Các đoạn liên quan đến hình ảnh là: "ANMF", "FRGM", "VP8", "VP8L" và "ALPH"). Cách thêm: tải và xoá hình ảnh, hãy sử dụng WebPMuxSetImage(), WebPMuxPushFrame(), WebPMuxGetFrame() và WebPMuxDeleteFrame().

Tham số

mux – đối tượng (vào/ra) mà đoạn sẽ được thêm vào

fourcc – (trong) một mảng ký tự chứa bốncc của chunk; ví dụ: "ICCP", "XMP", "EXIF" và hơn thế nữa

chunk_data – (trong) dữ liệu phân đoạn cần thêm

copy_data – giá trị (in) 1 cho biết dữ liệu đã cho SẼ được sao chép sang tệp mux và giá trị 0 cho biết dữ liệu sẽ KHÔNG được sao chép vào đối tượng mux.

Giá trị trả về

WEBP_MUX_INVALID_ARGUMENT – nếu mux, 4cc hoặc chunk_data là giá trị NULL hoặc nếu bốncc tương ứng với một đoạn hình ảnh.

WEBP_MUX_MEMORY_ERROR – về lỗi phân bổ bộ nhớ.

WEBP_MUX_OK -- khi thành công.

WebPMuxGetChunk()

Lấy thông tin tham chiếu đến dữ liệu của phân đoạn có mã fourcc trong đối tượng mux. Phương thức gọi KHÔNG được giải phóng dữ liệu được trả về.

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

mux – đối tượng (trong) mà từ đó dữ liệu phân đoạn sẽ được tìm nạp

fourcc – (trong) một mảng ký tự chứa 4cc của đoạn; ví dụ: "ICCP", "XMP", "EXIF" và hơn thế nữa

chunk_data – (out) trả về dữ liệu phân đoạn

Giá trị trả về

WEBP_MUX_INVALID_ARGUMENT – nếu mux, 4cc hoặc chunk_data là giá trị NULL hoặc nếu bốncc tương ứng với một đoạn hình ảnh.

WEBP_MUX_NOT_FOUND – Nếu mux không chứa phân đoạn có giá trị mã nhận dạng.

WEBP_MUX_OK -- khi thành công.

WebPMuxDeleteChunk()

Xoá đoạn có fourcc đã cho khỏi đối tượng mux.

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

mux – đối tượng (vào/ra) mà từ đó đoạn sẽ bị xoá

fourcc – (trong) một mảng ký tự chứa 4cc của đoạn; ví dụ: "ICCP", "XMP", "EXIF" và hơn thế nữa

Giá trị trả về

WEBP_MUX_INVALID_ARGUMENT – nếu mux hoặc4cc là NULL hoặc nếu là bốncc tương ứng với một đoạn hình ảnh.

WEBP_MUX_NOT_FOUND – Nếu mux không chứa phân đoạn có giá trị 4 cc.

WEBP_MUX_OK -- khi thành công.

Hình ảnh

Đóng gói dữ liệu về một khung/mảnh.

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

Đặt hình ảnh (không động và không bị phân mảnh) trong đối tượng mux. Lưu ý: Mọi hình ảnh hiện có (bao gồm cả khung/mảnh) sẽ bị xoá.

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

mux – đối tượng (vào/ra) mà trong đó hình ảnh sẽ được đặt

bitstream – (in) có thể là luồng bit VP8/VP8L thô hoặc WebP đơn hình ảnh tệp (không động và không bị phân mảnh)

copy_data – giá trị (in) 1 cho biết dữ liệu đã cho SẼ được sao chép sang tệp mux và giá trị 0 cho biết dữ liệu sẽ KHÔNG được sao chép vào đối tượng mux.

Giá trị trả về

WEBP_MUX_INVALID_ARGUMENT – nếu mux là giá trị NULL hoặc luồng bit là giá trị NULL.

WEBP_MUX_MEMORY_ERROR – về lỗi phân bổ bộ nhớ.

WEBP_MUX_OK -- khi thành công.

WebPMuxPushFrame()

Thêm một khung ở cuối đối tượng mux.

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

Lưu ý:

  1. frame.id phải là một trong WEBP_CHUNK_ANMF hoặc WEBP_CHUNK_FRGM
  2. Để đặt hình ảnh tĩnh, không phân mảnh, hãy sử dụng WebPMuxSetImage().
  3. Loại khung được đẩy phải giống với khung ở chế độ kết hợp.
  4. Vì WebP chỉ hỗ trợ độ lệch chẵn, nên mọi độ lệch lẻ sẽ bị chụp nhanh đến vị trí bằng nhau sử dụng: độ lệch &= ~1
Tham số

mux – đối tượng (vào/ra) mà khung hình sẽ được thêm vào

frame -- dữ liệu (trong) khung.

copy_data – giá trị (in) 1 cho biết dữ liệu đã cho SẼ được sao chép sang tệp mux và giá trị 0 cho biết dữ liệu sẽ KHÔNG được sao chép vào đối tượng mux.

Giá trị trả về

WEBP_MUX_INVALID_ARGUMENT – nếu mux hoặc khung là NULL hoặc nếu nội dung của khung là không hợp lệ.

WEBP_MUX_MEMORY_ERROR – về lỗi phân bổ bộ nhớ.

WEBP_MUX_OK -- khi thành công.

WEBP_MUX_MEMORY_ERROR – về lỗi phân bổ bộ nhớ.

WebPMuxGetFrame()

Lấy khung thứ n từ đối tượng mux. Nội dung của frame->bitstream là được phân bổ bằng Malloc() và KHÔNG thuộc sở hữu của đối tượng mux. Phải là được phương thức gọi giải quyết bằng cách gọi WebPDataClear(). n=0 có ý nghĩa đặc biệt - vị trí cuối cùng.

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

mux – đối tượng (trong) mà từ đó thông tin được tìm nạp

nth – chỉ mục (in) của khung trong đối tượng mux

frame -- dữ liệu (out) của khung được trả về

Giá trị trả về

WEBP_MUX_INVALID_ARGUMENT -- if mux or frame is NULL.

WEBP_MUX_NOT_FOUND – nếu có ít hơn khung thứ n trong tệp kết hợp .

WEBP_MUX_BAD_DATA – nếu đoạn khung thứ n trong chương trình kết hợp không hợp lệ.

WEBP_MUX_OK -- khi thành công.

WebPMuxDeleteFrame()

Xoá một khung khỏi đối tượng mux. nth=0 có ý nghĩa đặc biệt - cuối cùng vị trí.

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);
Tham số

mux – đối tượng (vào/ra) mà từ đó khung hình sẽ bị xoá

nth -- (in) Vị trí mà khung hình sẽ bị xoá từ đó

Giá trị trả về

WEBP_MUX_INVALID_ARGUMENT -- if mux is NULL.

WEBP_MUX_NOT_FOUND – Nếu có ít hơn khung thứ n trong tệp kết hợp trước khi xoá.

WEBP_MUX_OK -- khi thành công.

Hoạt ảnh

Tham số ảnh động

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

Đặt tham số ảnh động trong đối tượng mux. Mọi phân đoạn ANIM hiện có sẽ bị gỡ bỏ.

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

mux – đối tượng (vào/ra) trong đó đoạn ANIM sẽ được đặt/thêm vào

params - tham số ảnh động (in).

Giá trị trả về

WEBP_MUX_INVALID_ARGUMENT – nếu mux hoặc tham số là giá trị NULL.

WEBP_MUX_MEMORY_ERROR – về lỗi phân bổ bộ nhớ.

WEBP_MUX_OK -- khi thành công.

WebPMuxGetAnimationParams()

Lấy tham số ảnh động từ đối tượng mux.

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

mux – đối tượng (trong) mà từ đó tham số ảnh động được tìm nạp

params - tham số ảnh động (out) được trích xuất từ phân đoạn ANIM

Giá trị trả về

WEBP_MUX_INVALID_ARGUMENT – nếu mux hoặc tham số là giá trị NULL.

WEBP_MUX_NOT_FOUND – nếu đoạn ANIM không có trong đối tượng mux.

WEBP_MUX_OK -- khi thành công.

Công tác thi công phụ trợ khác Phần mềm tiện ích

WebPMuxGetCanvasSize()

Lấy kích thước canvas từ đối tượng mux.

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

Lưu ý: Phương thức này giả định rằng phân đoạn VP8X (nếu có) đã được cập nhật. Tức là đối tượng mux chưa được sửa đổi kể từ lần gọi gần đây nhất đến WebPMuxAssemble() hoặc WebPMuxCreate().

Tham số

mux – đối tượng (trong) mà từ đó kích thước canvas được tìm nạp

width -- (out) chiều rộng canvas

height -- (out) chiều cao canvas

Giá trị trả về

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

WEBP_MUX_BAD_DATA – nếu phân đoạn VP8X/VP8/VP8L hoặc kích thước canvas không hợp lệ.

WEBP_MUX_OK -- khi thành công.

WebPMuxGetFeatures()

Lấy cờ tính năng từ đối tượng mux.

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

Lưu ý: Phương thức này giả định rằng phân đoạn VP8X (nếu có) đã được cập nhật. Tức là đối tượng mux chưa được sửa đổi kể từ lần gọi gần đây nhất đến WebPMuxAssemble() hoặc WebPMuxCreate().

Tham số

mux – đối tượng (trong) mà từ đó các đối tượng sẽ được tìm nạp

flags -- (bỏ) cờ chỉ định tính năng nào có trong tệp tổng hợp . Đây sẽ là OR của nhiều giá trị cờ. Liệt kê WebPFeatureFlags có thể được sử dụng để kiểm tra từng giá trị cờ.

Giá trị trả về

WEBP_MUX_INVALID_ARGUMENT -- if mux or flags is NULL.

WEBP_MUX_BAD_DATA – nếu phân đoạn VP8X/VP8/VP8L hoặc kích thước canvas không hợp lệ.

WEBP_MUX_OK -- khi thành công.

WebPMuxNumChunks()

Lấy số lượng phần có giá trị thẻ nhất định trong đối tượng mux.

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

mux – đối tượng (trong) mà từ đó thông tin được tìm nạp

id – (trong) mã phân đoạn chỉ định loại phân đoạn

num_elements – số lượng phân đoạn (ra) có mã phân đoạn đã cho

Giá trị trả về

WEBP_MUX_INVALID_ARGUMENT -- if mux, or num_elements is NULL.

WEBP_MUX_OK -- khi thành công.

WebPMuxAssemble()

Tập hợp tất cả các phân đoạn ở định dạng WebP RIFF và trả về trong assembled_data. Hàm này cũng xác thực đối tượng mux.

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

Lưu ý: Nội dung của assembled_data sẽ bị bỏ qua và ghi đè. Ngoài ra, nội dung của assembled_data được phân bổ bằng Malloc() và NOT thuộc sở hữu của đối tượng mux. Số điện thoại PHẢI được phương thức gọi giải quyết bằng cách gọi WebPDataClear().

Tham số

mux – (vào/ra) đối tượng có các đoạn cần được lắp ráp

assembled_data – dữ liệu WebP được tập hợp (ngoài)

Giá trị trả về

WEBP_MUX_BAD_DATA – nếu đối tượng mux không hợp lệ.

WEBP_MUX_INVALID_ARGUMENT -- if mux or assembled_data is NULL.

WEBP_MUX_MEMORY_ERROR – về lỗi phân bổ bộ nhớ.

WEBP_MUX_OK -- khi thành công.

API WebPAnimEncoder

API này cho phép mã hoá (có thể) hình ảnh WebP động.

Ví dụ về mã

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.

Lựa chọn chung

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

Phải luôn được gọi để khởi chạy một WebPAnimEncoderOptions mới cấu trúc trước khi sửa đổi. Trả về false trong trường hợp phiên bản không khớp. WebPAnimEncoderOptionsInit() phải thành công trước khi sử dụng enc_options.

Tham số
enc_options – các tuỳ chọn (in/out) dùng để mã hoá ảnh động
Giá trị trả về
Đúng là thành công.
int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderNew()

Tạo và khởi tạo một đối tượng WebPAnimEncoder.

Tham số

width/height -- (in) chiều rộng và chiều cao canvas của ảnh động.

enc_options – tuỳ chọn mã hoá (in); có thể được thông qua giá trị NULL để chọn mặc định hợp lý.

Giá trị trả về

Con trỏ trỏ đến đối tượng WebPAnimEncoder mới tạo hoặc NULL trong trường hợp lỗi bộ nhớ.

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

WebPAnimEncoderAdd()

Tối ưu hoá khung hình cụ thể cho WebP, mã hoá rồi thêm khung hình đó vào WebPAnimEncoder.

Lệnh gọi gần đây nhất đến WebPAnimEncoderAdd phải có frame = NULL, tức là cho biết rằng không cần thêm khung nào khác. Lệnh gọi này cũng được dùng để xác định thời lượng của khung hình cuối cùng.

Tham số

enc – đối tượng (vào/ra) mà khung hình sẽ được thêm vào.

frame -- dữ liệu khung (vào/ra) ở định dạng ARGB hoặc YUV(A). Nếu quốc gia đó ở YUV(A), thì sẽ được chuyển đổi sang ARGB, do đó chịu một thiệt hại nhỏ.

timestamp_ms -- (trong) dấu thời gian của khung này tính bằng mili giây. Thời gian ngủ của một khung hình sẽ được tính là "dấu thời gian của khung tiếp theo - dấu thời gian của khung này". Do đó, dấu thời gian phải theo thứ tự không giảm.

config -- (trong) các tùy chọn mã hóa; có thể được chuyển giá trị NULL để chọn giá trị hợp lý. mặc định.

Giá trị trả về

Khi có lỗi, trả về false và frame->error_code được đặt một cách thích hợp. Nếu không, hàm sẽ trả về giá trị true.

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

WebPAnimEncoderAssemble()

Tập hợp tất cả các khung đã thêm tính đến thời điểm hiện tại vào một luồng bit WebP. Cuộc gọi này sẽ theo sau lệnh gọi đến WebPAnimEncoderAdd với frame = NULL; nếu không, thời lượng của khung hình cuối cùng sẽ được ước tính nội bộ.

Tham số

enc – đối tượng (vào/ra) mà từ đó các khung sẽ được lắp ráp.

webp_data – (ngoài) luồng bit WebP được tạo.

Giá trị trả về

Đúng là thành công.

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

WebPAnimEncoderGetError()

Nhận chuỗi lỗi tương ứng với lệnh gọi gần đây nhất bằng enc. Chiến lược phát hành đĩa đơn chuỗi trả về thuộc sở hữu của enc và chỉ hợp lệ cho đến khi thực hiện lệnh gọi tiếp theo WebPAnimEncoderAdd() hoặc WebPAnimEncoderAssemble() hoặc WebPAnimEncoderDelete()

Tham số
enc – đối tượng (vào/ra) mà từ đó chuỗi lỗi sẽ được tìm nạp.
Giá trị trả về
NULL if enc is NULL. Nếu không, hàm sẽ trả về chuỗi lỗi nếu giá trị cuối cùng lệnh gọi đến enc đã gặp lỗi hoặc chuỗi trống nếu lệnh gọi gần đây nhất là thành công.
const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

WebPAnimEncoderDelete()

Xoá đối tượng WebPAnimEncoder.

Tham số
enc – đối tượng (vào/ra) sẽ bị xoá
void WebPAnimEncoderDelete(WebPAnimEncoder* enc);

API Demux

Cho phép trích xuất hình ảnh và dữ liệu định dạng mở rộng từ tệp WebP.

Ví dụ về mã

Gỡ bỏ dữ liệu WebP để trích xuất tất cả các khung hình, cấu hình ICC và siêu dữ liệu 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);

Vòng đời của Đối tượng Demux

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

Trả về số phiên bản của thư viện demux, được đóng gói theo hệ thập lục phân sử dụng 8 bit cho mỗi phần chính/nhỏ/bản sửa đổi. Ví dụ: phiên bản 2.5.7 là 0x020507.

int WebPGetDemuxVersion(void);

WebPDemux()

Phân tích cú pháp tệp WebP đầy đủ do dữ liệu cung cấp.

WebPDemuxer WebPDemux(const WebPData* data);

Trả về đối tượng WebPDemuxer khi phân tích cú pháp thành công, nếu không thì trả về giá trị NULL.

WebPDemuxPartial()

Phân tích cú pháp tệp WebP có thể chưa hoàn chỉnh do dữ liệu cung cấp. Nếu state là không phải là NULL (Rỗng), thì nó sẽ được đặt để cho biết trạng thái của bộ demuxer.

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

Trả về giá trị NULL trong trường hợp xảy ra lỗi hoặc nếu không có đủ dữ liệu để bắt đầu phân tích cú pháp; và đối tượng WebPDemuxer khi phân tích cú pháp thành công.

Xin lưu ý rằng WebPDemuxer giữ con trỏ nội bộ đến phân đoạn bộ nhớ dữ liệu. Nếu dữ liệu này có biến động, nên đối tượng bộ phân bổ sẽ bị xoá (bằng cách gọi WebPDemuxDelete()) và Đã gọi lại WebPDemuxPartial() trên dữ liệu mới. Đây là thường là một thao tác có chi phí thấp.

WebPDemuxDelete()

Giải phóng bộ nhớ liên kết với dmux.

void WebPDemuxDelete(WebPDemuxer* dmux);

Trích xuất dữ liệu/thông tin

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

Lấy giá trị feature từ dmux.

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

Lưu ý: Các giá trị chỉ hợp lệ nếu bạn đã dùng WebPDemux() hoặc WebPDemuxPartial() trả về một trạng thái > WEBP_DEMUX_PARSING_HEADER.

Lặp lại khung hình

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

Truy xuất khung frame_number từ dmux.

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

iter-&gt;fragment trỏ đến mảnh đầu tiên khi trả về qua hàm này. Có thể trích xuất từng mảnh bằng WebPDemuxSelectFragment(). Chế độ cài đặt frame_number bằng 0 sẽ trả về khung cuối cùng của hình ảnh.

Trả về false nếu dmux là giá trị NULL hoặc không có khung dmux. Gọi WebPDemuxReleaseIterator() khi sử dụng biến lặp đã hoàn tất.

Lưu ý: dmux phải duy trì trong suốt thời gian hoạt động của iter.

WebPDemuxNextFrame(), WebPDemuxPrevFrame()

Đặt iter-&gt;fragment để trỏ đến mảnh tiếp theo (iter-&gt;fragment + 1) hoặc khung trước (iter-&gt;frame_num – 1). Các hàm này không lặp lại.

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

Trả về true khi thành công, trả về false nếu không thành công.

WebPDemuxSelectFragment()

Đặt iter-&gt;fragment để phản ánh số mảnh iter-&gt;fragment.

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

Trả về giá trị true nếu có mảnh fragment_num, nếu không thì trả về giá trị false.

WebPDemuxReleaseIterator()

Giải phóng mọi bộ nhớ liên kết với iter.

void WebPDemuxReleaseIterator(WebPIterator* iter);

Phải được gọi trước mọi lệnh gọi tiếp theo tới WebPDemuxGetChunk() trên cùng một lần lặp. Ngoài ra, phải được gọi trước khi huỷ WebPDemuxer được liên kết bằng WebPDemuxDelete().

Lặp lại phân đoạn

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

Truy xuất bản sao chunk_number của phân đoạn có mã fourcc từ dmux.

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

fourcc là một mảng ký tự chứa 4cc của đoạn cần trả về, ví dụ: "ICCP", "XMP", "EXIF", v.v.

Việc đặt chunk_number bằng 0 sẽ trả về phân đoạn cuối cùng trong tập hợp.

Trả về true nếu tìm thấy phân đoạn, trả về false nếu không tìm thấy phân đoạn. Đoạn có liên quan đến hình ảnh các tải trọng dữ liệu được truy cập thông qua WebPDemuxGetFrame() và các hàm liên quan. Gọi điện WebPDemuxReleaseChunkIterator() khi sử dụng của biến lặp đã hoàn tất.

Lưu ý: dmux phải duy trì trong suốt thời gian hoạt động của trình lặp.

WebPDemuxNextChunk(), WebPDemuxPrevChunk()

Đặt iter->chunk để trỏ đến phần tiếp theo (iter->chunk_num + 1) hoặc đoạn trước (iter->chunk_num – 1). Các hàm này không lặp lại.

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

Trả về true khi thành công, trả về false nếu không thành công.

WebPDemuxReleaseChunkIterator()

Giải phóng mọi bộ nhớ liên kết với iter.

void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);

Phải được gọi trước khi huỷ WebPDemuxer được liên kết bằng WebPDemuxDelete().

API WebPAnimDecoder

API này cho phép giải mã (có thể) hình ảnh WebP động.

Ví dụ về mã

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.

Lựa chọn chung

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

Phải luôn được gọi để khởi chạy một WebPAnimDecoderOptions mới cấu trúc trước khi sửa đổi. Trả về false trong trường hợp phiên bản không khớp. WebPAnimDecoderOptionsInit() phải thành công trước khi sử dụng dec_options.

Tham số

dec_options – các tuỳ chọn (vào/ra) dùng để giải mã ảnh động

Giá trị trả về
Đúng là thành công
int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options);

WebPAnimDecoderNew()

Tạo và khởi tạo đối tượng WebPAnimDecoder.

Tham số

webp_data – (trong) luồng bit WebP. Tác vụ này phải không thay đổi trong thời gian thời gian tồn tại của đối tượng đầu ra WebPAnimDecoder.

dec_options – (trong) cách giải mã. Có thể được đặt giá trị NULL để chọn mặc định hợp lý (cụ thể là chế độ màu MODE_RGBA sẽ được chọn).

Giá trị trả về

Con trỏ trỏ đến đối tượng WebPAnimDecoder mới tạo hoặc NULL trong trường hợp lỗi phân tích cú pháp, tuỳ chọn không hợp lệ hoặc lỗi bộ nhớ.

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

Thông tin chung về ảnh động.

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

WebPAnimDecoderGetInfo()

Nhận thông tin chung về ảnh động.

Tham số

dec -- (trong) phiên bản bộ giải mã để lấy thông tin.

info -- (out) thông tin chung được tìm nạp từ ảnh động.

Giá trị trả về

Đúng là thành công.

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

WebPAnimDecoderGetNext()

Tìm nạp khung tiếp theo từ tháng 12 dựa trên các tuỳ chọn được cung cấp cho WebPAnimDecoderNew(). Đây sẽ là canvas được tái tạo có kích thước canvas_width * 4 * canvas_height, chứ không chỉ hình chữ nhật phụ của khung. Vùng đệm được trả về buf chỉ hợp lệ cho đến khi cuộc gọi tiếp theo đến WebPAnimDecoderGetNext(), WebPAnimDecoderReset() hoặc WebPAnimDecoderDelete().

Tham số

dec – phiên bản bộ giải mã (vào/ra) mà từ đó khung hình tiếp theo sẽ xuất hiện đã được tìm nạp.

buf -- (out) khung được giải mã.

timestamp -- dấu thời gian (hết) của khung hình tính bằng mili giây.

Giá trị trả về

False nếu có bất kỳ đối số nào là NULL hoặc nếu có lệnh phân tích cú pháp hoặc hoặc nếu không còn khung nào nữa. Nếu không, hàm sẽ trả về giá trị true.

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

WebPAnimDecoderHasMoreFrames()

Kiểm tra xem còn khung hình nào khác để giải mã hay không.

Tham số
dec -- (trong) phiên bản bộ giải mã cần kiểm tra.
Giá trị trả về
True nếu dec không phải là giá trị NULL và một số khung chưa được giải mã. Nếu không, trả về false.
int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

WebPAnimDecoderReset()

Đặt lại đối tượng WebPAnimDecoder để lệnh gọi tiếp theo đến WebPAnimDecoderGetNext() sẽ khởi động lại quá trình giải mã từ khung thứ nhất. Điều này sẽ hữu ích khi tất cả các khung cần được giải mã nhiều lần (ví dụ: info.loop_count lần) mà không huỷ và tạo lại đối tượng dec.

Tham số
dec -- phiên bản bộ giải mã (vào/ra) cần đặt lại
void WebPAnimDecoderReset(WebPAnimDecoder* dec);

WebPAnimDecoderGetDemuxer()

Lấy đối tượng bộ phân bổ bên trong.

Việc lấy đối tượng demuxer có thể hữu ích nếu người dùng chỉ muốn sử dụng các thao tác có sẵn thông qua bộ phân bổ; ví dụ: để nhận siêu dữ liệu XMP/EXIF/ICC. Được trả về đối tượng demuxer thuộc sở hữu của dec và chỉ hợp lệ cho đến khi thực hiện lệnh gọi tiếp theo đến WebPAnimDecoderDelete().

Tham số
dec -- (in) thực thể bộ giải mã mà từ đó đối tượng demuxer sẽ đã được tìm nạp.
const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

Xoá đối tượng WebPAnimDecoder.

Tham số
dec – phiên bản bộ giải mã (vào/ra) cần xoá.
Giá trị trả về
Đúng là thành công.
void WebPAnimDecoderDelete(WebPAnimDecoder* dec);

Các loại dữ liệu phổ biến

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

Khởi động nội dung của đối tượng webp_data bằng các giá trị mặc định.

void WebPDataInit(WebPData* webp_data);

WebPDataClear()

Xoá nội dung của đối tượng webp_data bằng cách gọi free(). Không phân bổ chính đối tượng.

void WebPDataClear(WebPData* webp_data);

WebPDataCopy()

Phân bổ dung lượng lưu trữ cần thiết cho dst và sao chép nội dung của src. Trả về giá trị true khi thành công.

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