مستندات WebP Container API

معالجة حاوية RIFF لصور WebP.

واجهة برمجة تطبيقات Mux

السماح بمعالجة صور حاويات WebP التي تحتوي على ميزات مثل اللون الملف الشخصي والبيانات الوصفية والرسوم المتحركة والصور المجزأة.

أمثلة على الرموز

إنشاء MUX باستخدام بيانات الصور وColor Profile والبيانات الوصفية لـ 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);

حياة جسم مختلَطة

عمليات التعداد

// 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 -- كائن (داخل/خارج) مطلوب حذفه

إنشاء مزيج

WebPMuxCreate()

تنشئ كائن mux من البيانات الأولية المقدمة بتنسيق WebP RIFF.

WebPMux* WebPMuxCreate(const WebPData* bitstream, int copy_data);
المعلمات

bitstream -- (في) بيانات البث المباشر بتنسيق WebP RIFF

copy_data -- تشير القيمة 1 (في) إلى أنّه سيتم نسخ البيانات المحدّدة إلى الجهاز وتشير القيمة 0 إلى أنه لن يتم نسخ البيانات إلى الكائن mux.

المرتجعات

مؤشر إلى كائن mux الذي تم إنشاؤه من بيانات معينة عند نجاح العملية

NULL -- في حالة وجود بيانات غير صالحة أو خطأ في الذاكرة.

أجزاء لا تتضمّن صورًا

WebPMuxSetChunk()

تضيف مقطعًا بالمعرف fourcc وبيانات chunk_data في الكائن mux. أي تقييم ستتم إزالة المقاطع الحالية بنفس المعرف.

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

ملاحظة: يجب إدارة المقاطع غير المرتبطة بالصور فقط من خلال واجهات برمجة تطبيقات المقطع. (الأجزاء ذات الصلة بالصور هي: "ANMF" و"FRGM" و"VP8" و"VP8L" و"ALPH"). للإضافة، الحصول على الصور وحذفها، استخدام WebPMuxSetImage() WebPMuxPushFrame(), WebPMuxGetFrame() و WebPMuxDeleteFrame().

المعلمات

mux -- كائن (in/out) المطلوب إضافة المقطع إليه

fourcc -- (in) مصفوفة أحرف تحتوي على أربعة مواضع chunk; مثلاً: "ICCP" أو "XMP " أو "EXIF" وهكذا.

chunk_data -- (في) بيانات المقطع المطلوب إضافتها

copy_data -- تشير القيمة 1 (في) إلى أنّه سيتم نسخ البيانات المحدّدة إلى الجهاز وتشير القيمة 0 إلى أنه لن يتم نسخ البيانات إلى الكائن mux.

المرتجعات

WEBP_MUX_INVALID_ARGUMENT -- إذا كانت mux أو fourcc أو box_data قيمة NULL أو إذا كانت يتوافق f4cc مع مقطع صورة.

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 -- (out) عرض بيانات المقطع

المرتجعات

WEBP_MUX_INVALID_ARGUMENT -- إذا كانت mux أو fourcc أو box_data قيمة NULL أو إذا كانت يتوافق f4cc مع مقطع صورة.

WEBP_MUX_NOT_FOUND -- إذا كان mux لا يحتوي على مقطع يتضمّن السمة المحددة المعرّف.

WEBP_MUX_OK -- عند تحقيق النجاح.

WebPMuxDeleteChunk()

تحذف المقطع الذي يحتوي على fourcc المحدد من كائن mux.

WebPMuxError WebPMuxDeleteChunk(WebPMux* mux, const char fourcc[4]);
المعلمات

mux -- الكائن المطلوب حذف المقطع منه (in/out)

fourcc -- (in) مصفوفة أحرف تحتوي على أربعة أقسام من المقطع؛ مثلاً: "ICCP" أو "XMP " أو "EXIF" وهكذا.

المرتجعات

WEBP_MUX_INVALID_ARGUMENT -- إذا كانت mux أو fourcc هي فارغة أو إذا كانت أربعة سي سي مع مقطع صورة.

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 -- كائن (in/out) سيتم تعيين الصورة فيه

bitstream: (in) يمكن أن تكون بثًا مباشرًا VP8/VP8L للبيانات أو تنسيق WebP أحادي الصورة ملف (غير متحركة وغير مجزأة)

copy_data -- تشير القيمة 1 (في) إلى أنّه سيتم نسخ البيانات المحدّدة إلى الجهاز وتشير القيمة 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);

ملاحظات:

  1. يجب أن يكون frame.id واحدًا من WEBP_CHUNK_ANMF أو WEBP_CHUNK_FRGM
  2. لإعداد صورة غير متحركة غير مجزأة، استخدم WebPMuxSetImage() بدلاً من ذلك.
  3. يجب أن يكون نوع الإطار الذي يتم دفعه مطابقًا للإطارات الموجودة في Gmail.
  4. بما أنّ تنسيق WebP متوافق مع علامات الإزاحة الزوجية فقط، سيتم إبعاد أي إزاحة فردية. إلى موقع متساوي باستخدام: إزاحة &= ~1
المعلمات

mux -- كائن (داخل/خارج) المطلوب إضافة الإطار إليه

frame -- (في) بيانات الإطار.

copy_data -- تشير القيمة 1 (في) إلى أنّه سيتم نسخ البيانات المحدّدة إلى الجهاز وتشير القيمة 0 إلى أنه لن يتم نسخ البيانات إلى الكائن mux.

المرتجعات

WEBP_MUX_INVALID_ARGUMENT -- إذا كان المزيج أو الإطار "خالٍ" أو إذا كان محتوى frame غير صالح.

WEBP_MUX_MEMORY_ERROR -- حدث خطأ في تخصيص الذاكرة.

WEBP_MUX_OK -- عند تحقيق النجاح.

WEBP_MUX_MEMORY_ERROR -- حدث خطأ في تخصيص الذاكرة.

WebPMuxGetFrame()

للحصول على الإطار nth من كائن mux. يخضع محتوى frame->bitstream تم تخصيصها باستخدام الطريقة الاختبارية()) ، وليست مملوكًا للكائن mux. يجب أن يكون تم تحديد قيمة المتّصل من خلال الاتصال على الرقم WebPDataClear(). ترتيب=0 وله معنى خاص؛ وهو الموضع الأخير.

WebPMuxError WebPMuxGetFrame(const WebPMux* mux,
                             uint32_t nth,
                             WebPMuxFrameInfo* frame);
المعلمات

mux -- الكائن الذي سيتم استرجاع المعلومات منه

nth -- فهرس الإطار في كائن mux

frame -- بيانات (خارج) للإطار المعروض

المرتجعات

WEBP_MUX_INVALID_ARGUMENT -- if mux or frame is NULL.

WEBP_MUX_NOT_FOUND -- إذا كان هناك أقل من nth من الإطارات في mux الخاص بك.

WEBP_MUX_BAD_DATA -- إذا كان مقطع الإطار nth في mux غير صالح.

WEBP_MUX_OK -- عند تحقيق النجاح.

WebPMuxDeleteFrame()

لحذف إطار من كائن mux nth=0 له معنى خاص - الأخير الموقع.

WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);
المعلمات

mux -- كائن (داخل/خارج) المطلوب حذف إطار منه

nth -- (في) الموضع الذي سيتم حذف الإطار منه

المرتجعات

WEBP_MUX_INVALID_ARGUMENT -- if mux is NULL.

WEBP_MUX_NOT_FOUND -- إذا كان هناك أقل من nth من الإطارات في mux كائن قبل الحذف.

WEBP_MUX_OK -- عند تحقيق النجاح.

Animation

معلمات الرسوم المتحركة

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 فيه

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 -- إذا لم يكن مقطع ANIM متوفرًا في كائن mux.

WEBP_MUX_OK -- عند تحقيق النجاح.

متنوع برامج خدمات

WebPMuxGetCanvasSize()

للحصول على حجم اللوحة من عنصر mux

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

ملاحظة: تفترض هذه الطريقة أن مقطع VP8X، إن وجد، حديث. وهذا يعني أنه لم يتم تعديل كائن mux منذ آخر استدعاء WebPMuxAssemble() أو WebPMuxCreate()

المعلمات

mux -- الكائن الذي سيتم جلب حجم لوحة الرسم منه

width -- (خارج) عرض اللوحة

height -- ارتفاع اللوحة (خارج)

المرتجعات

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

WEBP_MUX_BAD_DATA: إذا كان حجم المجموعة أو لوحة الرسم VP8X/VP8/VP8L غير صالح.

WEBP_MUX_OK -- عند تحقيق النجاح.

WebPMuxGetFeatures()

يحصل على علامات الميزة من كائن mux.

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

ملاحظة: تفترض هذه الطريقة أن مقطع VP8X، إن وجد، حديث. وهذا يعني أنه لم يتم تعديل كائن mux منذ آخر استدعاء WebPMuxAssemble() أو WebPMuxCreate()

المعلمات

mux -- الكائن الذي سيتم استرجاع الميزات منه

flags -- (خارج) العلامات التي تحدّد الميزات المتوفّرة في المربّع الخاص بك. سيكون هذا عامل تشغيل OR لقيم علامات مختلفة. التعداد WebPFeatureFlags يمكن استخدامها لاختبار قيم علامة فردية.

المرتجعات

WEBP_MUX_INVALID_ARGUMENT -- if mux or flags is NULL.

WEBP_MUX_BAD_DATA: إذا كان حجم المجموعة أو لوحة الرسم VP8X/VP8/VP8L غير صالح.

WEBP_MUX_OK -- عند تحقيق النجاح.

WebPMuxNumChunks()

تحصل على عدد المجموعات التي تحتوي على قيمة العلامة المحددة في الكائن mux.

WebPMuxError WebPMuxNumChunks(const WebPMux* mux,
                              WebPChunkId id,
                              int* num_elements);
المعلمات

mux -- الكائن الذي سيتم استرجاع المعلومات منه

id -- (in) العنصر معرّف يحدد نوع المقطع

num_elements -- (out) عدد المقاطع التي تتضمّن معرّف المقطع المحدّد

المرتجعات

WEBP_MUX_INVALID_ARGUMENT -- if mux, or num_elements is NULL.

WEBP_MUX_OK -- عند تحقيق النجاح.

WebPMuxAssemble()

يتم تجميع كل المقاطع بتنسيق WebP RIFF وعرضها في شكل assembled_data. تتحقق هذه الدالة أيضًا من كائن mux.

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

ملاحظة: سيتم تجاهل محتوى assembled_data واستبداله. أيضًا، يتم تخصيص محتوى assembled_data باستخدام mailoc() ، وNOT يملكه الكائن mux. يجب أن يتم التعامل معه عن طريق الاتصال WebPDataClear()

المعلمات

mux -- كائن (in/out) سيتم تجميع أجزاءه

assembled_data -- (خارج) بيانات WebP المجمّعة

المرتجعات

WEBP_MUX_BAD_DATA -- إذا كان عنصر mux غير صالح.

WEBP_MUX_INVALID_ARGUMENT -- if mux or assembled_data is NULL.

WEBP_MUX_MEMORY_ERROR -- حدث خطأ في تخصيص الذاكرة.

WEBP_MUX_OK -- عند تحقيق النجاح.

واجهة برمجة تطبيقات WebPAnimEncoder

تسمح واجهة برمجة التطبيقات هذه بترميز (ربما) صور 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 جديدين. البنية قبل التعديل. تعرض القيمة "خطأ" في حال عدم تطابق النسخة. يجب أن تكون واجهة برمجة التطبيقات WebPAnimEncoderOptionsInit() ناجحة قبل استخدام enc_options.

المعلمات
enc_options -- خيارات (داخل/خارج) مستخدمة لترميز الرسوم المتحركة
المرتجعات
صحيح عند تحقيق النجاح.
int WebPAnimEncoderOptionsInit(
    WebPAnimEncoderOptions* enc_options);

WebPAnimEncoderNew()

تنشئ كائن WebPAnimEncoder وتهيئه.

المعلمات

width/height -- عرض اللوحة (بوصة) وارتفاع الصورة المتحركة.

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 لاختيار الافتراضية.

المرتجعات

في حال ظهور خطأ، يتم عرض القيمة "خطأ" ويتم ضبط السمة frame->error_code بشكل صحيح. وبخلاف ذلك، يتم عرض القيمة true.

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

WebPAnimEncoderAssemble()

يشير هذا المصطلح إلى تجميع كل الإطارات التي تمت إضافتها حتى الآن إلى بث مباشر WebP. يجب أن تكون هذه المكالمة يسبقه استدعاء WebPAnimEncoderAdd مع frame = NULL؛ وإذا لم يكن الأمر كذلك، سيتم تقدير مدة الإطار الأخير داخليًا.

المعلمات

enc -- كائن (in/out) الذي سيتم تجميع الإطارات منه.

webp_data -- (خارج نطاق البث المباشر الذي تم إنشاؤه بلغة WebP).

المرتجعات

صحيح عند النجاح.

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

WebPAnimEncoderGetError()

الحصول على سلسلة خطأ تتوافق مع أحدث مكالمة باستخدام enc. تشير رسالة الأشكال البيانية تكون السلسلة التي تم إرجاعها مملوكة من قِبل enc وهي صالحة فقط حتى يصبح الاتصال التالي WebPAnimEncoderAdd() أو WebPAnimEncoderAssemble() أو WebPAnimEncoderDelete()

المعلمات
enc -- عنصر (in/out) المطلوب استرجاع سلسلة الخطأ منه
المرتجعات
NULL if enc is NULL. بخلاف ذلك، يتم إرجاع سلسلة الخطأ إذا كانت آخر حدث خطأ في استدعاء enc أو سلسلة فارغة إذا كانت الاستدعاء الأخير للنجاح.
const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);

WebPAnimEncoderDelete()

تحذف الكائن WebPAnimEncoder.

المعلمات
enc -- مطلوب حذف عنصر (in/out)
void WebPAnimEncoderDelete(WebPAnimEncoder* enc);

واجهة برمجة تطبيقات Demux

تتيح هذه السياسة استخراج بيانات الصور والتنسيقات الموسّعة من ملفات 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()

يمكنك من خلال هذا الإجراء تحليل ملف WebP الكامل المقدَّم من data.

WebPDemuxer WebPDemux(const WebPData* data);

تعرض كائن WebPDemuxer عند التحليل الناجح، والقيم NULL في الحالات الأخرى.

WebPDemuxPartial()

يحلّل ملف WebP الذي قد يكون غير مكتمل والمقدّم من خلال data. إذا كانت state غير فارغ سيتم تعيينها للإشارة إلى حالة مُزيل التشويش.

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

عرض فارغ في حالة وجود خطأ أو إذا لم تكن هناك بيانات كافية لبدء التحليل؛ وكائن WebPDemuxer في التحليل الناجح.

يُرجى العِلم أنّ WebPDemuxer يحتفظ بالمؤشرات الداخلية المتعلّقة بشريحة الذاكرة البيانات. في حال حذف هذه البيانات متقلبة، فيجب حذف كائن إزالة التشويش (من خلال استدعاء 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-&gt;fragment إلى الجزء الأول عند عرض هذه الدالة. يمكن استخراج أجزاء فردية باستخدام WebPDemuxSelectFragment() الإعداد frame_number يساوي 0 سيؤدي إلى عرض آخر إطار للصورة.

يتم عرض false إذا كان dmux فارغًا أو قيمة الإطار dmux غير موجودة. طلب WebPDemuxReleaseIterator() عند استخدام فقد اكتمل المكرر.

ملاحظة: يجب أن يستمر dmux طوال مدة iter.

WebPDemuxNextFrame()، WebPDemuxPrevFrame()

تعيين iter-&gt;fragment للإشارة إلى العنصر التالي (iter-&gt;fragment + 1) أو الإطار السابق (iter-&gt;frame_num - 1) لا يتم تكرار هذه الدوال.

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

عرض true عند نجاح الإجراء، وخطأ في الحالات الأخرى.

WebPDemuxSelectFragment()

تعيين iter-&gt;fragment لإظهار رقم الجزء iter-&gt;fragment.

int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);

تعرض القيمة "صحيح" في حال توفّر الجزء fragment_num، وتعرض القيمة 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()

استرداد المثيل chunk_number للمقطع ذي المعرّف fourcc من dmux.

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

fourcc هي مصفوفة أحرف تحتوي على أَرْبَعَةcc للمقطع المطلوب عرضه، مثلاً: "ICCP" أو "XMP " أو "EXIF" أو غير ذلك

يؤدي ضبط chunk_number على قيمة 0 إلى عرض المقطع الأخير في المجموعة.

تعرض true، في حال العثور على المقطع، على false في الحالات الأخرى. مقطع مرتبط بالصورة يتم الوصول إلى الحمولات من خلال WebPDemuxGetFrame(). والدوال ذات الصلة بها. اتصل WebPDemuxReleaseChunkIterator() عند الاستخدام بالمكرر الكامل.

ملاحظة: يجب أن يستمر dmux طوال مدة المكرر.

WebPDemuxNextChunk()، WebPDemuxPrevChunk()

يتم ضبط iter->chunk على الإشارة إلى العنصر التالي (iter->chunk_num + 1) أو المقطع السابق (iter->chunk_num - 1). لا يتم تكرار هذه الدوال.

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

عرض true عند نجاح الإجراء، وخطأ في الحالات الأخرى.

WebPDemuxReleaseChunkIterator()

تصدر أي ذاكرة مرتبطة بالبرنامج iter.

void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);

يجب الاتصال قبل إتلاف WebPDemuxer المرتبط بـ WebPDemuxDelete()

واجهة برمجة تطبيقات WebPAnimDecoder

تسمح واجهة برمجة التطبيقات هذه بفك ترميز صور 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 جديدين. البنية قبل التعديل. تعرض القيمة "خطأ" في حال عدم تطابق النسخة. يجب أن تكون واجهة برمجة التطبيقات WebPAnimDecoderOptionsInit() ناجحة قبل استخدام dec_options.

المعلمات

dec_options -- خيارات (داخل/خارج) تُستخدم لفك ترميز الرسوم المتحركة

المرتجعات
صحيح عند النجاح
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 -- (خارج) المعلومات العامة التي يتم جلبها من الصورة المتحركة.

المرتجعات

صحيح عند النجاح.

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

WebPAnimDecoderGetNext()

جلب الإطار التالي من ديسمبر استنادًا إلى الخيارات المقدمة إلى WebPAnimDecoderNew() سيكون هذا مسارًا كاملاً لوحة أعيد بناؤها بحجم canvas_width * 4 * canvas_height وليست فقط المستطيل الفرعي للإطار. يكون المخزن المؤقت الذي تم إرجاعه buf صالحًا فقط حتى المكالمة التالية إلى WebPAnimDecoderGetNext()، WebPAnimDecoderReset() أو WebPAnimDecoderDelete()

المعلمات

dec -- (داخل/خارج) مثيل برنامج فك الترميز الذي سيتم تحديد الإطار التالي منه تم جلبه.

buf -- إطار تم فك ترميزه (out).

timestamp -- (out) للإطار الزمني بالمللي ثانية.

المرتجعات

False إذا كانت أي من الوسيطات فارغة، أو إذا كان هناك تحليل أو أو إذا لم يكن هناك المزيد من الإطارات. وبخلاف ذلك، يتم عرض القيمة true.

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

WebPAnimDecoderHasMoreFrames()

تحقق مما إذا كان هناك المزيد من الإطارات المتبقية لفك ترميزها.

المعلمات
dec -- (في) مثيل برنامج فك الترميز المطلوب التحقُّق منه.
المرتجعات
صحيح إذا لم يكن dec NULL (فارغ) ولم يتم فك ترميز بعض الإطارات بعد. وبخلاف ذلك، يتم عرض القيمة false.
int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

WebPAnimDecoderReset()

إعادة ضبط كائن WebPAnimDecoder، بحيث يتعذّر الاتصال ستتم إعادة بدء عملية فك الترميز من قِبل WebPAnimDecoderGetNext(). من الإطار الأول. قد يكون ذلك مفيدًا عندما يلزم فك ترميز جميع الإطارات عدة مرات (على سبيل المثال، info.loop_count مرات) دون إتلاف وإعادة الإنشاء الكائن dec.

المعلمات
dec -- (داخل/خارج) ستتم إعادة ضبط مثيل برنامج فك الترميز
void WebPAnimDecoderReset(WebPAnimDecoder* dec);

WebPAnimDecoderGetDemuxer()

أمسِك كائن أداة إزالة التشويش الداخلي.

يمكن أن يكون الحصول على كائن إزالة التشويش مفيدًا إذا أراد المرء استخدام العمليات فقط المتاحة من خلال أداة إزالة التشويش مثلاً: للحصول على بيانات تعريف XMP/EXIF/ICC. تم إرجاع عنصر إزالة التشويش مملوك لـ dec وهو صالح فقط حتى طلب الاتصال التالي إلى WebPAnimDecoderDelete()

المعلمات
dec -- (في) مثيل برنامج فك الترميز الذي سيتم منه الوصول إلى عنصر إزالة الترميز تم جلبه.
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()

محو محتوى الكائن webp_data من خلال طلب free(). لا إعادة توزيع الكائن نفسه.

void WebPDataClear(WebPData* webp_data);

WebPDataCopy()

يؤدي هذا الإجراء إلى تخصيص مساحة التخزين اللازمة لـ dst ونسخ محتوى src. يتم عرض القيمة "صحيح" عند النجاح.

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