مستندات WebP Container API

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

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

تسمح هذه السياسة بمعالجة صور حاوية 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);

حياة كائن Mux

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

// Error codes
typedef enum WebPMuxError {
  WEBP_MUX_OK                 =  1,
  WEBP_MUX_NOT_FOUND          =  0,
  WEBP_MUX_INVALID_ARGUMENT   = -1,
  WEBP_MUX_BAD_DATA           = -2,
  WEBP_MUX_MEMORY_ERROR       = -3,
  WEBP_MUX_NOT_ENOUGH_DATA    = -4
} WebPMuxError;

// IDs for different types of chunks.
typedef enum WebPChunkId {
  WEBP_CHUNK_VP8X,     // VP8X
  WEBP_CHUNK_ICCP,     // ICCP
  WEBP_CHUNK_ANIM,     // ANIM
  WEBP_CHUNK_ANMF,     // ANMF
  WEBP_CHUNK_ALPHA,    // ALPH
  WEBP_CHUNK_IMAGE,    // VP8/VP8L
  WEBP_CHUNK_EXIF,     // EXIF
  WEBP_CHUNK_XMP,      // XMP
  WEBP_CHUNK_UNKNOWN,  // Other chunks.
  WEBP_CHUNK_NIL
} WebPChunkId;

WebPGetMuxVersion()

لعرض رقم إصدار مكتبة mux، معبأة بنظام سداسي عشري باستخدام 8 بت لكل مراجعة رئيسية/ثانوية/مراجعة. على سبيل المثال، الإصدار 2.5.7 هو 0x020507.

int WebPGetMuxVersion(void);

WebPMuxNew()

لإنشاء كائن mux فارغ.

WebPMux* WebPMuxNew(void);

المرتجعات

مؤشر إلى كائن mux الفارغ الذي تم إنشاؤه حديثًا.

WebPMuxDelete()

لحذف كائن mux.

void WebPMuxDelete(WebPMux* mux);

المَعلمات

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

إنشاء المسك

WebPMuxCreate()

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

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

المَعلمات

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

copy_data -- تشير القيمة 1 (في) إلى أنه سيتم نسخ البيانات المحددة إلى mux وتشير القيمة 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 -- (في) مصفوفة أحرف تحتوي على4cc الخاص بجزء معين، على سبيل المثال "ICCP" و"XMP " و"EXIF" وما إلى ذلك.

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

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

المرتجعات

WEBP_MUX_INVALID_ARGUMENT - إذا كان mux أو4cc أو box_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 -- (في) مصفوفة أحرف تحتوي على4cc من المقطع، على سبيل المثال، "ICCP" و"XMP " و"EXIF" وما إلى ذلك.

chunk_data -- (out) عرض بيانات المقطع

المرتجعات

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

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

WEBP_MUX_OK -- عند النجاح

WebPMuxDeleteChunk()

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

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

المَعلمات

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

fourcc -- (في) مصفوفة أحرف تحتوي على4cc من المقطع، على سبيل المثال، "ICCP" و"XMP " و"EXIF" وما إلى ذلك.

المرتجعات

WEBP_MUX_INVALID_ARGUMENT: إذا كانت قيمة mux أو4cc فارغة أو إذا كانت كلها تتجاوب مع مقطع صورة.

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

WEBP_MUX_OK -- عند النجاح

الصور

تغليف البيانات حول إطار واحد/جزء واحد.

struct WebPMuxFrameInfo {
  WebPData    bitstream;  // image data: can be a raw VP8/VP8L bitstream
                          // or a single-image WebP file.
  int         x_offset;   // x-offset of the frame.
  int         y_offset;   // y-offset of the frame.
  int         duration;   // duration of the frame (in milliseconds).

  WebPChunkId id;         // frame type: should be one of WEBP_CHUNK_ANMF,
                          // WEBP_CHUNK_FRGM or WEBP_CHUNK_IMAGE
  WebPMuxAnimDispose dispose_method;  // Disposal method for the frame.
  WebPMuxAnimBlend   blend_method;    // Blend operation for the frame.
};

WebPMuxSetImage()

لتعيين الصورة (غير المتحركة وغير المجزأة) في كائن mux. ملاحظة: ستتم إزالة أي صور حالية (بما في ذلك الإطارات/الأجزاء).

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

المَعلمات

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

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

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

المرتجعات

WEBP_MUX_INVALID_ARGUMENT -- إذا كانت قيمة mux فارغة أو في ساحة المشاركات فارغة (NULL).

WEBP_MUX_MEMORY_ERROR -- خطأ في تخصيص الذاكرة

WEBP_MUX_OK -- عند النجاح

WebPMuxPushFrame()

لإضافة إطار في نهاية عنصر mux.

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

ملاحظات:

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

المَعلمات

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

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

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

المرتجعات

WEBP_MUX_INVALID_ARGUMENT -- إذا كان العنصر المختلط أو الإطار فارغًا أو إذا كان محتوى الإطار غير صالح.

WEBP_MUX_MEMORY_ERROR -- خطأ في تخصيص الذاكرة

WEBP_MUX_OK -- عند النجاح

WEBP_MUX_MEMORY_ERROR -- خطأ في تخصيص الذاكرة

WebPMuxGetFrame()

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

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

المَعلمات

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

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

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

المرتجعات

WEBP_MUX_INVALID_ARGUMENT: إذا كان العنصر المضيء أو الإطار فارغًا

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 -- إذا كانت قيمة mux فارغة.

WEBP_MUX_NOT_FOUND -- إذا كان هناك أقل من عدد الإطارات في عنصر 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 -- الكائن (in) الذي يتم استرجاع حجم لوحة الرسم منه

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

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

المرتجعات

WEBP_MUX_INVALID_ARGUMENT -- إذا كانت القيم مضاعفة أو العرض أو الارتفاع 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 -- الكائن (in) الذي يتم جلب الميزات منه

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

المرتجعات

WEBP_MUX_INVALID_ARGUMENT: إذا كانت القيم العشوائية أو العلامات فارغة (NULL).

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

WEBP_MUX_OK -- عند النجاح

WebPMuxNumChunks()

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

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

المَعلمات

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

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

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 باستخدام albumoc() بحيث لا يكون ملكًا للكائن mux. يجب أن يحدّد المتصل المكالمة من خلال الاتصال على WebPDataClear().

المَعلمات

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

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

المرتجعات

WEBP_MUX_BAD_DATA: إذا كان الكائن mux غير صالح.

WEBP_MUX_INVALID_ARGUMENT: إذا كانت قيمة mux أو assembled_data فارغة.

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 -- (في) خيارات الترميز، يمكن تمريرها فارغة (NULL) لاختيار قيم تلقائية معقولة.

المرتجعات

مؤشر يشير إلى الكائن WebPAnimEncoder الذي تم إنشاؤه حديثًا، أو NULL في حال حدوث خطأ في الذاكرة.

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

WebPAnimEncoderAdd()

يمكنك تحسين الإطار المحدّد لـ WebP وترميزه وإضافته إلى الكائن WebPAnimEncoder.

يجب أن تكون المكالمة الأخيرة لـ WebPAnimEncoderAdd مع frame = NULL، والتي تشير إلى عدم إضافة المزيد من الإطارات. يُستخدم هذا الاستدعاء أيضًا لتحديد مدة الإطار الأخير.

المَعلمات

enc -- الكائن (داخل/خارج) الذي ستتم إضافة الإطار إليه.

frame: بيانات إطار (داخل/خارج) بتنسيق ARGB أو YUV(A) وإذا كان بتنسيق YUV(A)، سيتم تحويله إلى ARGB، ما ينتج عنه خسائر طفيفة.

timestamp_ms -- الطابع الزمني لهذا الإطار بالمللي ثانية. ويتم احتساب مدة الإطار على أنّها "الطابع الزمني للإطار التالي - الطابع الزمني لهذا الإطار". وبالتالي، يجب أن تكون الطوابع الزمنية بترتيب غير تنازلي.

config -- (في) خيارات الترميز، ويمكن تمريره فارغة لاختيار إعدادات تلقائية معقولة.

المرتجعات

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

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

يتم عرض "NULL" (فارغ) في حال حدوث خطأ أو في حال عدم توفّر بيانات كافية لبدء التحليل، وعرض كائن 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->fragment إلى الجزء الأول عند الرجوع من هذه الدالة. يمكن استخراج الأجزاء الفردية باستخدام WebPDemuxSelectFragment(). وعند ضبط frame_number على قيمة مساوية لـ 0، سيتم عرض آخر إطار للصورة.

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

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

WebPDemuxNextFrame()، WebPDemuxPrevFrame()

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

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

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

WebPDemuxSelectFragment()

لضبط iter->fragment لإظهار رقم الجزء iter->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 هي مصفوفة أحرف تحتوي على4cc من المقطع المطلوب عرضه، مثلاً "ICCP" و"XMP " و"EXIF" وما إلى ذلك.

في حال ضبط chunk_number على قيمة مساوية لـ 0، سيتم عرض آخر مقطع في المجموعة.

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

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

WebPDemuxNextChunk()، WebPDemuxPrevChunk()

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

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

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

WebPDemuxReleaseChunkIterator()

يؤدي إلى تحرير أي ذكرى مرتبطة iter.

void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);

يجب الاتصال به قبل إتلاف 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 -- (في) خيارات فك الترميز. يمكن تمريره "فارغ" لاختيار قيم افتراضية معقولة (على وجه الخصوص، سيتم اختيار وضع اللون 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 -- (خارج) إطار تم فك ترميزه.

timestamp -- الطابع الزمني للإطار بالمللي ثانية.

المرتجعات

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

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

WebPAnimDecoderHasMoreFrames()

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

المَعلمات

dec -- (في) مثيل أداة فك الترميز المطلوب التحقق منه.

المرتجعات

صحيح إذا لم تكن القيمة dec فارغة (ولا يلزم فك ترميز بعض الإطارات) بعد. وبخلاف ذلك، سيتم عرض false.

int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);

WebPAnimDecoderReset()

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

المَعلمات

dec -- مطلوب إعادة ضبط مثيل برنامج فك الترميز (in/out)

void WebPAnimDecoderReset(WebPAnimDecoder* dec);

WebPAnimDecoderGetDemuxer()

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

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

المَعلمات

dec -- (في) مثيل أداة فك الترميز الذي يتم جلب كائن أداة إزالة الترميز منه.

const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);

WebPAnimDecoderDelete()

يؤدي إلى حذف الكائن WebPAnimDecoder.

المَعلمات

dec -- سيتم حذف مثيل برنامج فك الترميز (in/out).

المرتجعات

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

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. لعرض true عند النجاح.

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