WebP Container API Documentation

دستکاری ظرف RIFF برای تصاویر WebP.

Mux API

به دستکاری تصاویر کانتینر WebP، حاوی ویژگی هایی مانند نمایه رنگی، ابرداده، انیمیشن و تصاویر تکه تکه شده اجازه می دهد.

نمونه های کد

یک MUX با داده های تصویر، نمایه رنگی و فراداده 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);

داده های نمایه تصویر و رنگ را از یک فایل 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);

زندگی یک شیء موکس

Enums

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

یک شی mux از داده های خام داده شده در قالب WebP RIFF ایجاد می کند.

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

پارامترها

جریان بیت -- (در) داده های جریان بیت در قالب WebP RIFF

copy_data -- (in) مقدار 1 نشان می دهد که داده های داده شده در mux کپی می شوند و مقدار 0 نشان می دهد که داده ها در شی mux کپی نمی شوند.

برمی گرداند

یک اشاره گر به شی mux ایجاد شده از داده های داده شده - در مورد موفقیت.

NULL - در صورت خطای داده یا حافظه نامعتبر.

تکه های غیر تصویری

WebPMuxSetChunk()

یک قطعه با id fourcc و data chunk_data را در شی mux اضافه می کند. هر تکه(های) موجود با همان شناسه حذف خواهد شد.

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

توجه: فقط تکه‌های غیر مرتبط با تصویر باید از طریق chunk API مدیریت شوند. (تکه های مربوط به تصویر عبارتند از: "ANMF"، "FRGM"، "VP8"، "VP8L" و "ALPH"). برای افزودن، دریافت و حذف تصاویر، از WebPMuxSetImage() , WebPMuxPushFrame() , WebPMuxGetFrame() و WebPMuxDeleteFrame() استفاده کنید.

پارامترها

mux -- (در/خارج) شیئی که قطعه باید به آن اضافه شود

fourcc -- (in) یک آرایه کاراکتر حاوی چهار سی سی از قطعه داده شده. به عنوان مثال، "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()

ارجاع به داده های قطعه با شناسه fourcc در شی mux می گیرد. تماس گیرنده نباید داده های برگشتی را آزاد کند.

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

پارامترها

mux -- (in) شیئی که قرار است داده های تکه از آن واکشی شود

fourcc -- (in) یک آرایه کاراکتری حاوی چهار سی سی قطعه; به عنوان مثال، "ICCP"، "XMP"، "EXIF" و غیره.

chunk_data -- (خارج) داده های تکه ای برگردانده شده است

برمی گرداند

WEBP_MUX_INVALID_ARGUMENT -- اگر mux، fourcc یا chunk_data NULL باشد یا اگر fourcc مربوط به یک قطعه تصویر باشد.

WEBP_MUX_NOT_FOUND - اگر mux شامل یک قطعه با شناسه داده شده نباشد.

WEBP_MUX_OK -- در موفقیت.

WebPMuxDeleteChunk()

قطعه را با چهار سی سی داده شده از شی mux حذف می کند.

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

پارامترها

mux -- (در/خارج) شیئی که قطعه از آن حذف می شود

fourcc -- (in) یک آرایه کاراکتری حاوی چهار سی سی قطعه; به عنوان مثال، "ICCP"، "XMP"، "EXIF" و غیره.

برمی گرداند

WEBP_MUX_INVALID_ARGUMENT -- اگر mux یا fourcc NULL باشد یا اگر fourcc مربوط به یک قطعه تصویر باشد.

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 -- (در/خارج) شیئی که قرار است تصویر در آن تنظیم شود

بیت استریم -- (در) می تواند یک جریان بیت خام VP8/VP8L یا یک فایل WebP تک تصویری (غیر متحرک و غیر تکه تکه) باشد.

copy_data -- (in) مقدار 1 نشان می دهد که داده های داده شده در mux کپی می شوند و مقدار 0 نشان می دهد که داده ها در شی mux کپی نمی شوند.

برمی گرداند

WEBP_MUX_INVALID_ARGUMENT -- اگر mux NULL یا بیت استریم NULL باشد.

WEBP_MUX_MEMORY_ERROR -- خطای تخصیص حافظه.

WEBP_MUX_OK -- در موفقیت.

WebPMuxPushFrame()

یک قاب در انتهای شیء mux اضافه می کند.

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

یادداشت ها:

1. frame.id باید یکی از WEBP_CHUNK_ANMF یا WEBP_CHUNK_FRGM باشد
2. برای تنظیم یک تصویر غیر متحرک غیر تکه تکه شده، به جای آن از WebPMuxSetImage() استفاده کنید.
3. نوع قاب تحت فشار باید مانند قاب های موجود در mux باشد.
4. از آنجایی که WebP فقط از آفست های زوج پشتیبانی می کند، هر آفست فرد با استفاده از: offset &=~1 به مکان زوج منتقل می شود.

پارامترها

mux -- (در/خارج) شیئی که قرار است فریم به آن اضافه شود

قاب -- (در) داده قاب.

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

nامین فریم را از شی mux می گیرد. محتوای frame->bitstream با استفاده از malloc() تخصیص داده می شود و متعلق به شی mux نیست. باید توسط تماس گیرنده با فراخوانی WebPDataClear() توزیع شود. nth=0 معنای خاصی دارد - آخرین موقعیت.

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

پارامترها

mux -- (in) شیئی که قرار است اطلاعات از آن واکشی شود

n ام -- (in) اندیس فریم در شی mux

فریم -- (خارج) داده های فریم برگشتی

برمی گرداند

WEBP_MUX_INVALID_ARGUMENT -- اگر mux یا فریم NULL باشد.

WEBP_MUX_NOT_FOUND -- اگر کمتر از nامین فریم در شی mux وجود داشته باشد.

WEBP_MUX_BAD_DATA -- اگر تکه قاب n در mux نامعتبر باشد.

WEBP_MUX_OK -- در موفقیت.

WebPMuxDeleteFrame()

یک فریم را از شی mux حذف می کند. nth=0 معنای خاصی دارد - آخرین موقعیت.

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);

پارامترها

mux -- (در/خارج) شیئی که قرار است یک فریم از آن حذف شود

nth -- (in) موقعیتی که قرار است فریم از آن حذف شود

برمی گرداند

WEBP_MUX_INVALID_ARGUMENT -- اگر mux NULL باشد.

WEBP_MUX_NOT_FOUND -- اگر کمتر از nمین فریم در شی mux قبل از حذف وجود داشته باشد.

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 -- (in/out) شی که در آن قطعه ANIM قرار است تنظیم/افزودن شود

پارامترها -- (در) پارامترهای انیمیشن.

برمی گرداند

WEBP_MUX_INVALID_ARGUMENT -- اگر mux یا params NULL باشد.

WEBP_MUX_MEMORY_ERROR -- خطای تخصیص حافظه.

WEBP_MUX_OK -- در موفقیت.

WebPMuxGetAnimationParams()

پارامترهای انیمیشن را از شی mux دریافت می کند.

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

پارامترها

mux -- (in) شیئی که پارامترهای انیمیشن باید از آن واکشی شوند

پارامترها -- (خارج) پارامترهای انیمیشن استخراج شده از قطعه ANIM

برمی گرداند

WEBP_MUX_INVALID_ARGUMENT -- اگر mux یا params NULL باشد.

WEBP_MUX_NOT_FOUND -- اگر قطعه ANIM در شیء mux وجود نداشته باشد.

WEBP_MUX_OK -- در موفقیت.

متفرقه آب و برق

WebPMuxGetCanvasSize()

اندازه بوم را از شی mux می گیرد.

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

نکته: این روش فرض می کند که قطعه VP8X در صورت وجود، به روز است. یعنی شی mux از آخرین تماس با WebPMuxAssemble() یا WebPMuxCreate() تغییر نکرده است.

پارامترها

mux -- (in) شیئی که اندازه بوم باید از آن واکشی شود

عرض -- (خارج) عرض بوم

ارتفاع -- (بیرون) ارتفاع بوم

برمی گرداند

WEBP_MUX_INVALID_ARGUMENT -- اگر mux، عرض یا ارتفاع 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 از مقادیر مختلف پرچم خواهد بود. Enum WebPFeatureFlags را می توان برای آزمایش مقادیر تک تک پرچم ها استفاده کرد.

برمی گرداند

WEBP_MUX_INVALID_ARGUMENT -- اگر mux یا flags NULL باشد.

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 -- (in) chunk id که نوع قطعه را مشخص می کند

num_elements -- (خارج) تعداد تکه ها با شناسه قطعه داده شده

برمی گرداند

WEBP_MUX_INVALID_ARGUMENT -- اگر mux یا num_elements NULL باشد.

WEBP_MUX_OK -- در موفقیت.

WebPMuxAssemble()

همه تکه ها را در قالب WebP RIFF جمع می کند و در assembled_data برمی گرداند. این تابع همچنین شی mux را تایید می کند.

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

توجه: محتوای assembled_data نادیده گرفته می شود و بازنویسی می شود. همچنین، محتوای assembled_data با استفاده از malloc() تخصیص داده می شود و متعلق به شی mux نیست. باید توسط تماس گیرنده با فراخوانی WebPDataClear() توزیع شود.

پارامترها

mux -- (داخل/خارج) شیئی که تکه های آن باید مونتاژ شوند

assembled_data -- (خارج) داده های WebP مونتاژ شده

برمی گرداند

WEBP_MUX_BAD_DATA -- اگر شیء mux نامعتبر باشد.

WEBP_MUX_INVALID_ARGUMENT -- اگر mux یا assembled_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 -- گزینه های (in/out) مورد استفاده برای رمزگذاری انیمیشن

برمی گرداند

در موفقیت درست است.

int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderNew()

یک شی WebPAnimEncoder را ایجاد و مقداردهی اولیه می کند.

پارامترها

عرض/ارتفاع -- (در) عرض بوم و ارتفاع انیمیشن.

enc_options -- (در) گزینه های رمزگذاری. برای انتخاب پیش‌فرض‌های معقول می‌توان NULL را پاس کرد.

برمی گرداند

اشاره گر به شی WebPAnimEncoder تازه ایجاد شده یا NULL در صورت خطای حافظه.

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

WebPAnimEncoderAdd()

فریم داده شده را برای WebP بهینه کنید، آن را رمزگذاری کنید و به شی WebPAnimEncoder اضافه کنید.

آخرین تماس با WebPAnimEncoderAdd باید با frame = NULL باشد که نشان می دهد فریم دیگری اضافه نمی شود. از این فراخوانی برای تعیین مدت زمان آخرین فریم نیز استفاده می شود.

پارامترها

enc -- (in/out) شیئی که قرار است فریم به آن اضافه شود.

فریم -- (داخل/خارج) داده قاب در قالب ARGB یا YUV(A). اگر در فرمت YUV(A) باشد به ARGB تبدیل می شود که ضرر کمی دارد.

timestamp_ms -- (در) مهر زمانی این فریم در میلی ثانیه. مدت زمان یک فریم به عنوان "مهر زمانی فریم بعدی - مهر زمانی این فریم" محاسبه می شود. بنابراین، مهرهای زمانی باید به ترتیب غیر کاهشی باشند.

پیکربندی -- (در) گزینه های رمزگذاری. برای انتخاب پیش‌فرض‌های معقول می‌توان NULL را پاس کرد.

برمی گرداند

در صورت خطا، false را برمی گرداند و frame->error_code به طور مناسب تنظیم می شود. در غیر این صورت، true را برمی گرداند.

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

WebPAnimEncoderAssemble()

همه فریم‌هایی که تاکنون اضافه شده‌اند را در یک جریان بیت WebP جمع‌آوری کنید. قبل از این فراخوانی باید به WebPAnimEncoderAdd با frame = NULL فراخوانی شود. در غیر این صورت، مدت زمان آخرین فریم به صورت داخلی برآورد می شود.

پارامترها

enc -- (در/خارج) شیئی که قرار است قابها از آن جمع شوند.

webp_data -- (خارج) بیت استریم WebP تولید شده است.

برمی گرداند

در موفقیت درست است.

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

WebPAnimEncoderGetError()

با استفاده از enc ، رشته خطای مربوط به آخرین تماس را دریافت کنید. رشته برگشتی متعلق به enc است و فقط تا تماس بعدی با WebPAnimEncoderAdd() یا WebPAnimEncoderAssemble() یا WebPAnimEncoderDelete() معتبر است.

پارامترها

enc -- (in/out) شی که رشته خطا از آن باید واکشی شود.

برمی گرداند

NULL اگر enc NULL باشد. در غیر این صورت، اگر آخرین تماس با enc خطا داشته باشد، رشته خطا را برمی‌گرداند، یا اگر آخرین تماس موفقیت‌آمیز بود، یک رشته خالی را برمی‌گرداند.

const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

WebPAnimEncoderDelete()

شی WebPAnimEncoder را حذف می کند.

پارامترها

enc -- (in/out) شیء که باید حذف شود

void WebPAnimEncoderDelete(WebPAnimEncoder* enc);

Demux API

استخراج تصویر و داده های فرمت توسعه یافته را از فایل های WebP فعال می کند.

نمونه های کد

Demuxing داده های 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

Enums

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

فایل WebP کامل داده شده توسط داده را تجزیه می کند.

WebPDemuxer WebPDemux(const WebPData* data);

یک شی WebPDemuxer را در تجزیه موفقیت آمیز، NULL برمی گرداند.

WebPDemuxPartial()

فایل WebP احتمالاً ناقص داده شده توسط داده را تجزیه می کند. اگر حالت غیر NULL باشد، برای نشان دادن وضعیت دموکسر تنظیم می شود.

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 دریافت کنید.

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 را از dmux بازیابی می کند.

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

در صورت موفقیت درست است، در غیر این صورت نادرست است.

WebPDemuxSelectFragment()

iter->fragment را طوری تنظیم می کند که شماره قطعه را منعکس کند fragment_num .

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

اگر fragment_num وجود داشته باشد true را برمی‌گرداند، در غیر این صورت false را برمی‌گرداند.

WebPDemuxReleaseIterator()

هر حافظه مرتبط با iter را آزاد می کند.

void WebPDemuxReleaseIterator(WebPIterator* iter);

باید قبل از هر تماس بعدی با WebPDemuxGetChunk() در همان iter فراخوانی شود. همچنین، باید قبل از از بین بردن 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()

نمونه chunk_number قطعه با شناسه fourcc را از dmux بازیابی می کند.

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

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

در صورت موفقیت درست است، در غیر این صورت نادرست است.

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 -- گزینه های (in/out) مورد استفاده برای رمزگشایی انیمیشن

برمی گرداند

در موفقیت درست است

int WebPAnimDecoderOptionsInit(
    WebPAnimDecoderOptions* dec_options);

WebPAnimDecoderNew()

یک شی WebPAnimDecoder را ایجاد و مقداردهی اولیه می کند.

پارامترها

webp_data -- (در) جریان بیتی WebP. این باید در طول عمر شیء خروجی WebPAnimDecoder بدون تغییر باقی بماند.

dec_options -- (در) گزینه های رمزگشایی. برای انتخاب پیش‌فرض‌های معقول می‌توان 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) نمونه رمزگشا برای دریافت اطلاعات از.

اطلاعات -- (خارج) اطلاعات جهانی که از انیمیشن گرفته شده است.

برمی گرداند

در موفقیت درست است.

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

WebPAnimDecoderGetNext()

فریم بعدی را از دسامبر بر اساس گزینه های ارائه شده به WebPAnimDecoderNew() واکشی کنید. این یک بوم کاملا بازسازی شده با اندازه canvas_width * 4 * canvas_height خواهد بود و نه فقط مستطیل فرعی فریم. باف بافر برگشتی فقط تا تماس بعدی با WebPAnimDecoderGetNext() ، WebPAnimDecoderReset() یا WebPAnimDecoderDelete() معتبر است.

پارامترها

dec -- نمونه رمزگشایی (in/out) که قرار است فریم بعدی از آن واکشی شود.

buf -- (خارج) قاب رمزگشایی شده.

برچسب زمانی -- (خارج) مهر زمانی فریم در میلی ثانیه.

برمی گرداند

اگر هر یک از آرگومان ها NULL باشد، یا خطای تجزیه یا رمزگشایی وجود داشته باشد، یا اگر فریم دیگری وجود نداشته باشد، نادرست است. در غیر این صورت، true را برمی گرداند.

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

WebPAnimDecoderHasMoreFrames()

بررسی کنید که آیا فریم های بیشتری برای رمزگشایی باقی مانده است یا خیر.

پارامترها

dec -- (in) نمونه رمزگشا باید بررسی شود.

برمی گرداند

درست است اگر dec NULL نباشد و برخی از فریم‌ها هنوز رمزگشایی نشده باشند. در غیر این صورت، false را برمی گرداند.

int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

WebPAnimDecoderReset()

شی WebPAnimDecoder را بازنشانی می کند، به طوری که تماس بعدی با WebPAnimDecoderGetNext() رمزگشایی را از فریم اول مجدداً شروع می کند. این زمانی مفید خواهد بود که همه فریم‌ها باید چندین بار رمزگشایی شوند (مثلاً بارها info.loop_count) بدون تخریب و ایجاد مجدد شیء dec .

پارامترها

dec -- (داخل/خارج) نمونه رمزگشا برای بازنشانی

void WebPAnimDecoderReset(WebPAnimDecoder* dec);

WebPAnimDecoderGetDemuxer()

شی دموکسر داخلی را بگیرید.

اگر کسی بخواهد از عملیاتی که فقط از طریق demuxer در دسترس است استفاده کند، دریافت شیء demuxer می تواند مفید باشد. به عنوان مثال برای دریافت فراداده XMP/EXIF/ICC. شی demuxer برگشتی متعلق به dec است و فقط تا تماس بعدی با WebPAnimDecoderDelete() معتبر است.

پارامترها

dec -- (in) نمونه رمزگشایی که شی demuxer باید از آن واکشی شود.

const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

شی WebPAnimDecoder را حذف می کند.

پارامترها

dec -- (در/خارج) نمونه رمزگشا حذف شود.

برمی گرداند

در موفقیت درست است.

void WebPAnimDecoderDelete(WebPAnimDecoder* dec);

انواع داده های رایج

Enums

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 را کپی می کند. با موفقیت واقعی برمی گردد.

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