تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

مستندات WebP API

يوضّح هذا القسم واجهة برمجة التطبيقات الخاصة ببرنامج الترميز وبرنامج فك الترميز المضمّنين في مكتبة WebP. ينطبق وصف واجهة برمجة التطبيقات هذا على الإصدار 1.6.0.

العناوين والمكتبات

عند تثبيت libwebp، سيتم تثبيت دليل باسم webp/ في الموقع المعتاد لمنصتك. على سبيل المثال، على منصات Unix، سيتم نسخ ملفات العناوين التالية إلى /usr/local/include/webp/.

decode.h
encode.h
types.h

تتوفّر المكتبات في أدلة المكتبات المعتادة. تتوفّر المكتبات الثابتة والديناميكية في /usr/local/lib/ على منصات Unix.

Simple Decoding API

لبدء استخدام واجهة برمجة التطبيقات الخاصة بفك التشفير، عليك التأكّد من تثبيت المكتبة وملفات العناوين على النحو الموضّح أعلاه.

أدرِج عنوان واجهة برمجة التطبيقات لفك التشفير في رمز C/C++ على النحو التالي:

#include "webp/decode.h"
int WebPGetInfo(const uint8_t* data, size_t data_size, int* width, int* height);

ستتحقّق هذه الدالة من عنوان صورة WebP وستستردّ عرض الصورة وارتفاعها. يمكن تجاهل المؤشّرَين *width و*height إذا كانا غير ذي صلة.NULL

سمات الإدخال

البيانات: مؤشر إلى بيانات صورة WebP
data_size: هذا هو حجم كتلة الذاكرة التي يشير إليها data والتي تحتوي على بيانات الصورة.

المرتجعات

خطأ: رمز الخطأ الذي يتم عرضه في حال حدوث أخطاء في التنسيق
صحيح: عند النجاح. لا يكون كل من *width و*height صالحًا إلا عند إرجاع المنتج بنجاح.
العرض: قيمة عدد صحيح يتراوح النطاق من 1 إلى 16383.
الطول: قيمة عدد صحيح يتراوح النطاق من 1 إلى 16383.

struct WebPBitstreamFeatures {
  int width;          // Width in pixels.
  int height;         // Height in pixels.
  int has_alpha;      // True if the bitstream contains an alpha channel.
  int has_animation;  // True if the bitstream is an animation.
  int format;         // 0 = undefined (/mixed), 1 = lossy, 2 = lossless
}

VP8StatusCode WebPGetFeatures(const uint8_t* data,
                              size_t data_size,
                              WebPBitstreamFeatures* features);

ستستردّ هذه الدالة الميزات من دفق البتات. يتم ملء بنية *features بالمعلومات التي يتم جمعها من دفق البتات:

سمات الإدخال

البيانات: مؤشر إلى بيانات صورة WebP
data_size: هذا هو حجم كتلة الذاكرة التي يشير إليها data والتي تحتوي على بيانات الصورة.

المرتجعات

VP8_STATUS_OK: عند استرداد الميزات بنجاح
VP8_STATUS_NOT_ENOUGH_DATA: عند الحاجة إلى المزيد من البيانات لاسترداد الميزات من العناوين

قيم الأخطاء الإضافية VP8StatusCode في حالات أخرى

الميزات: مؤشر إلى بنية WebPBitstreamFeatures.

uint8_t* WebPDecodeRGBA(const uint8_t* data, size_t data_size, int* width, int* height);
uint8_t* WebPDecodeARGB(const uint8_t* data, size_t data_size, int* width, int* height);
uint8_t* WebPDecodeBGRA(const uint8_t* data, size_t data_size, int* width, int* height);
uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size, int* width, int* height);
uint8_t* WebPDecodeBGR(const uint8_t* data, size_t data_size, int* width, int* height);

تعمل هاتان الدالتان على فك ترميز صورة WebP التي يشير إليها data.

تعرض WebPDecodeRGBA عيّنات صور RGBA بالترتيب [r0, g0, b0, a0, r1, g1, b1, a1, ...].
تعرض WebPDecodeARGB عيّنات صور ARGB بالترتيب [a0, r0, g0, b0, a1, r1, g1, b1, ...].
تعرض WebPDecodeBGRA عيّنات صور BGRA بالترتيب [b0, g0, r0, a0, b1, g1, r1, a1, ...].
تعرض WebPDecodeRGB عيّنات صور RGB بالترتيب [r0, g0, b0, r1, g1, b1, ...].
تعرض WebPDecodeBGR عيّنات صور BGR بالترتيب [b0, g0, r0, b1, g1, r1, ...].

يجب أن يحذف الرمز الذي يستدعي أيًا من هذه الدوال مخزن البيانات المؤقت (uint8_t*) الذي تعرضه هذه الدوال باستخدام WebPFree().

سمات الإدخال

البيانات: مؤشر إلى بيانات صورة WebP
data_size: هذا هو حجم كتلة الذاكرة التي يشير إليها data والتي تحتوي على بيانات الصورة
العرض: قيمة عدد صحيح يتراوح النطاق حاليًا بين 1 و16383.
الطول: قيمة عدد صحيح يتراوح النطاق حاليًا بين 1 و16383.

المرتجعات

uint8_t*: مؤشر لعينات صور WebP التي تم فك ترميزها بترتيب RGBA/ARGB/BGRA/RGB/BGR الخطي على التوالي.

uint8_t* WebPDecodeRGBAInto(const uint8_t* data, size_t data_size,
                            uint8_t* output_buffer, int output_buffer_size, int output_stride);
uint8_t* WebPDecodeARGBInto(const uint8_t* data, size_t data_size,
                            uint8_t* output_buffer, int output_buffer_size, int output_stride);
uint8_t* WebPDecodeBGRAInto(const uint8_t* data, size_t data_size,
                            uint8_t* output_buffer, int output_buffer_size, int output_stride);
uint8_t* WebPDecodeRGBInto(const uint8_t* data, size_t data_size,
                           uint8_t* output_buffer, int output_buffer_size, int output_stride);
uint8_t* WebPDecodeBGRInto(const uint8_t* data, size_t data_size,
                           uint8_t* output_buffer, int output_buffer_size, int output_stride);

هذه الدوال هي صيغ مختلفة من الدوال المذكورة أعلاه، وهي تفك ترميز الصورة مباشرةً في مخزن مؤقت output_buffer تم تخصيصه مسبقًا. يتم تحديد الحد الأقصى لمساحة التخزين المتاحة في هذا المخزن المؤقت من خلال output_buffer_size. إذا لم تكن مساحة التخزين هذه كافية (أو حدث خطأ)، سيتم عرض NULL. بخلاف ذلك، يتم عرض output_buffer لتوفير الوقت.

تحدّد المَعلمة output_stride المسافة (بالبايت) بين خطوط المسح. وبالتالي، من المتوقّع أن تكون قيمة output_buffer_size output_stride * picture - height على الأقل.

سمات الإدخال

البيانات: مؤشر إلى بيانات صورة WebP
data_size: هذا هو حجم كتلة الذاكرة التي يشير إليها data والتي تحتوي على بيانات الصورة
output_buffer_size: قيمة عدد صحيح حجم ذاكرة التخزين المؤقت المخصّصة
output_stride: قيمة عدد صحيح تحدّد هذه السمة المسافة بين خطوط المسح.

المرتجعات

output_buffer: مؤشر إلى صورة WebP التي تم فك ترميزها.
uint8_t*: output_buffer إذا نجحت الدالة، أو NULL في حال عدم النجاح.

Advanced Decoding API

يتوافق فك ترميز WebP مع واجهة برمجة تطبيقات متقدّمة تتيح إمكانية الاقتصاص وتغيير الحجم أثناء التنفيذ، وهو أمر مفيد جدًا في البيئات ذات الذاكرة المحدودة، مثل الهواتف الجوّالة. بشكل أساسي، سيتناسب استخدام الذاكرة مع حجم الناتج، وليس مع حجم الإدخال، وذلك عندما يحتاج المستخدم فقط إلى معاينة سريعة أو جزء مكبَّر من صورة كبيرة جدًا. يمكن أيضًا توفير بعض سعة وحدة المعالجة المركزية (CPU) بشكل عرضي.

يتوفّر ترميز WebP بنوعَين، هما ترميز الصورة الكاملة والترميز التدريجي عبر مخازن مؤقتة صغيرة للإدخال. يمكن للمستخدمين تقديم مخزن مؤقت اختياري للذاكرة الخارجية من أجل فك ترميز الصورة. سيمرّ نموذج الرمز التالي بخطوات استخدام واجهة برمجة التطبيقات المتقدّمة لفك الترميز.

أولاً، علينا تهيئة عنصر إعدادات:

#include "webp/decode.h"

WebPDecoderConfig config;
CHECK(WebPInitDecoderConfig(&config));

// One can adjust some additional decoding options:
config.options.no_fancy_upsampling = 1;
config.options.use_scaling = 1;
config.options.scaled_width = scaledWidth();
config.options.scaled_height = scaledHeight();
// etc.

يتم جمع خيارات فك الترميز ضمن بنية WebPDecoderConfig التالية:

struct WebPDecoderOptions {
  int bypass_filtering;             // if true, skip the in-loop filtering
  int no_fancy_upsampling;          // if true, use faster pointwise upsampler
  int use_cropping;                 // if true, cropping is applied first 
  int crop_left, crop_top;          // top-left position for cropping.
                                    // Will be snapped to even values.
  int crop_width, crop_height;      // dimension of the cropping area
  int use_scaling;                  // if true, scaling is applied afterward
  int scaled_width, scaled_height;  // final resolution
  int use_threads;                  // if true, use multi-threaded decoding
  int dithering_strength;           // dithering strength (0=Off, 100=full)
  int flip;                         // if true, flip output vertically
  int alpha_dithering_strength;     // alpha dithering strength in [0..100]
};

يمكن اختياريًا قراءة ميزات دفق البت في config.input، في حال احتجنا إلى معرفتها مسبقًا. على سبيل المثال، قد يكون من المفيد معرفة ما إذا كانت الصورة تتضمّن أي شفافية على الإطلاق. يُرجى العِلم أنّ هذا الأمر سيؤدي أيضًا إلى تحليل عنوان البث، وبالتالي فهو طريقة جيدة لمعرفة ما إذا كان البث يبدو صالحًا بتنسيق WebP.

CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK);

بعد ذلك، علينا إعداد مخزن مؤقت لفك الترميز في حال أردنا توفيره مباشرةً بدلاً من الاعتماد على أداة فك الترميز لتخصيصه. ما علينا سوى توفير مؤشر إلى الذاكرة بالإضافة إلى الحجم الإجمالي للمخزن المؤقت وخطوة السطر (المسافة بالبايت بين خطوط المسح).

// Specify the desired output colorspace:
config.output.colorspace = MODE_BGRA;
// Have config.output point to an external buffer:
config.output.u.RGBA.rgba = (uint8_t*)memory_buffer;
config.output.u.RGBA.stride = scanline_stride;
config.output.u.RGBA.size = total_size_of_the_memory_buffer;
config.output.is_external_memory = 1;

الصورة جاهزة لفك ترميزها. هناك صيغتان محتملتان لفك ترميز الصورة. يمكننا فك ترميز الصورة دفعة واحدة باستخدام:

CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK);

بدلاً من ذلك، يمكننا استخدام طريقة الزيادة التدريجية لفك ترميز الصورة بشكل تدريجي عند توفّر وحدات بايت جديدة:

WebPIDecoder* idec = WebPINewDecoder(&config.output);
CHECK(idec != NULL);
while (additional_data_is_available) {
  // ... (get additional data in some new_data[] buffer)
  VP8StatusCode status = WebPIAppend(idec, new_data, new_data_size);
  if (status != VP8_STATUS_OK && status != VP8_STATUS_SUSPENDED) {
    break;
  }
  // The above call decodes the current available buffer.
  // Part of the image can now be refreshed by calling
  // WebPIDecGetRGB()/WebPIDecGetYUVA() etc.
}
WebPIDelete(idec);  // the object doesn't own the image memory, so it can
                    // now be deleted. config.output memory is preserved.

تكون الصورة التي تم فك ترميزها الآن في config.output (أو بالأحرى في config.output.u.RGBA في هذه الحالة، لأنّ مساحة اللون المطلوبة للإخراج كانت MODE_BGRA). يمكن حفظ الصورة أو عرضها أو معالجتها بأي طريقة أخرى. بعد ذلك، ما علينا سوى استرداد الذاكرة المخصّصة في عنصر الإعداد. يمكن استدعاء هذه الدالة بأمان حتى إذا كانت الذاكرة خارجية ولم يتم تخصيصها باستخدام WebPDecode():

WebPFreeDecBuffer(&config.output);

باستخدام واجهة برمجة التطبيقات هذه، يمكن أيضًا فك ترميز الصورة إلى تنسيقات YUV وYUVA باستخدام MODE_YUV وMODE_YUVA على التوالي. يُعرف هذا التنسيق أيضًا باسم Y'CbCr.

Simple Encoding API

يتم توفير بعض الدوال البسيطة جدًا لترميز مصفوفات عيّنات RGBA في معظم التنسيقات الشائعة. يتم تعريفها في العنوان webp/encode.h على النحو التالي:

size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride, float quality_factor, uint8_t** output);
size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride, float quality_factor, uint8_t** output);
size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride, float quality_factor, uint8_t** output);
size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride, float quality_factor, uint8_t** output);

يتراوح عامل الجودة quality_factor بين 0 و100 ويتحكّم في فقدان البيانات والجودة أثناء الضغط. تشير القيمة 0 إلى الجودة المنخفضة وأحجام الإخراج الصغيرة، بينما تشير القيمة 100 إلى أعلى جودة وأكبر حجم إخراج. عند النجاح، يتم وضع وحدات البايت المضغوطة في المؤشر *output، ويتم عرض الحجم بالبايت (أو 0 في حال حدوث خطأ). يجب أن يتصل المتصل بـ WebPFree() على المؤشر *output لاستعادة الذاكرة.

يجب أن يكون صفيف الإدخال عبارة عن صفيف مضغوط من وحدات البايت (واحدة لكل قناة، كما هو متوقع من اسم الدالة). يمثّل stride عدد وحدات البايت اللازمة للانتقال من صف إلى آخر. على سبيل المثال، يكون تنسيق BGRA كما يلي:

تتوفّر دوال مكافئة للترميز بدون فقدان البيانات، مع التواقيع التالية:

size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height, int stride, uint8_t** output);
size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height, int stride, uint8_t** output);
size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height, int stride, uint8_t** output);
size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height, int stride, uint8_t** output);

يُرجى العِلم أنّ هذه الدوال، مثل النُسخ المضغوطة، تستخدم الإعدادات التلقائية للمكتبة. بالنسبة إلى التنسيق بلا فقدان البيانات، يعني ذلك أنّ خيار "مطابق تمامًا" غير مفعَّل. سيتم تعديل قيم النموذج اللوني أحمر أخضر أزرق (RGB) في المناطق الشفافة لتحسين عملية الضغط. لتجنُّب ذلك، استخدِم WebPEncode() واضبط WebPConfig::exact على 1.

Advanced Encoding API

يتضمّن برنامج الترميز العديد من مَعلمات الترميز المتقدّمة. ويمكن أن تكون مفيدة لتحقيق توازن أفضل بين كفاءة الضغط ووقت المعالجة. يتم جمع هذه المَعلمات ضمن بنية WebPConfig. الحقول الأكثر استخدامًا في هذه البنية هي:

struct WebPConfig {
  int lossless;           // Lossless encoding (0=lossy(default), 1=lossless).
  float quality;          // between 0 and 100. For lossy, 0 gives the smallest
                          // size and 100 the largest. For lossless, this
                          // parameter is the amount of effort put into the
                          // compression: 0 is the fastest but gives larger
                          // files compared to the slowest, but best, 100.
  int method;             // quality/speed trade-off (0=fast, 6=slower-better)

  WebPImageHint image_hint;  // Hint for image type (lossless only for now).

  // Parameters related to lossy compression only:
  int target_size;        // if non-zero, set the desired target size in bytes.
                          // Takes precedence over the 'compression' parameter.
  float target_PSNR;      // if non-zero, specifies the minimal distortion to
                          // try to achieve. Takes precedence over target_size.
  int segments;           // maximum number of segments to use, in [1..4]
  int sns_strength;       // Spatial Noise Shaping. 0=off, 100=maximum.
  int filter_strength;    // range: [0 = off .. 100 = strongest]
  int filter_sharpness;   // range: [0 = off .. 7 = least sharp]
  int filter_type;        // filtering type: 0 = simple, 1 = strong (only used
                          // if filter_strength > 0 or autofilter > 0)
  int autofilter;         // Auto adjust filter's strength [0 = off, 1 = on]
  int alpha_compression;  // Algorithm for encoding the alpha plane (0 = none,
                          // 1 = compressed with WebP lossless). Default is 1.
  int alpha_filtering;    // Predictive filtering method for alpha plane.
                          //  0: none, 1: fast, 2: best. Default if 1.
  int alpha_quality;      // Between 0 (smallest size) and 100 (lossless).
                          // Default is 100.
  int pass;               // number of entropy-analysis passes (in [1..10]).

  int show_compressed;    // if true, export the compressed picture back.
                          // In-loop filtering is not applied.
  int preprocessing;      // preprocessing filter (0=none, 1=segment-smooth)
  int partitions;         // log2(number of token partitions) in [0..3]
                          // Default is set to 0 for easier progressive decoding.
  int partition_limit;    // quality degradation allowed to fit the 512k limit on
                          // prediction modes coding (0: no degradation,
                          // 100: maximum possible degradation).
  int use_sharp_yuv;      // if needed, use sharp (and slow) RGB->YUV conversion
};

يُرجى العِلم أنّه يمكن الوصول إلى معظم هذه المَعلمات لإجراء التجارب باستخدام أداة سطر الأوامر cwebp.

يجب تضمين عيّنات الإدخال في بنية WebPPicture. يمكن لهذا البنية تخزين عيّنات الإدخال بتنسيق RGBA أو YUVA، وذلك حسب قيمة العلامة use_argb.

يتم تنظيم البنية على النحو التالي:

struct WebPPicture {
  int use_argb;              // To select between ARGB and YUVA input.

  // YUV input, recommended for lossy compression.
  // Used if use_argb = 0.
  WebPEncCSP colorspace;     // colorspace: should be YUVA420 or YUV420 for now (=Y'CbCr).
  int width, height;         // dimensions (less or equal to WEBP_MAX_DIMENSION)
  uint8_t *y, *u, *v;        // pointers to luma/chroma planes.
  int y_stride, uv_stride;   // luma/chroma strides.
  uint8_t* a;                // pointer to the alpha plane
  int a_stride;              // stride of the alpha plane

  // Alternate ARGB input, recommended for lossless compression.
  // Used if use_argb = 1.
  uint32_t* argb;            // Pointer to argb (32 bit) plane.
  int argb_stride;           // This is stride in pixels units, not bytes.

  // Byte-emission hook, to store compressed bytes as they are ready.
  WebPWriterFunction writer;  // can be NULL
  void* custom_ptr;           // can be used by the writer.

  // Error code for the latest error encountered during encoding
  WebPEncodingError error_code;
};

يتضمّن هذا البناء أيضًا دالة لإرسال وحدات البايت المضغوطة عند توفّرها. اطّلِع أدناه على مثال يتضمّن أداة كتابة في الذاكرة. يمكن للكتاب الآخرين تخزين البيانات مباشرةً في ملف (راجِع examples/cwebp.c للحصول على مثال على ذلك).

يبدو المسار العام للترميز باستخدام واجهة برمجة التطبيقات المتقدّمة على النحو التالي:

أولاً، علينا إعداد إعدادات ترميز تتضمّن معلَمات الضغط. يُرجى العِلم أنّه يمكن استخدام الإعدادات نفسها لضغط عدة صور مختلفة بعد ذلك.

#include "webp/encode.h"

WebPConfig config;
if (!WebPConfigPreset(&config, WEBP_PRESET_PHOTO, quality_factor)) return 0;   // version error

// Add additional tuning:
config.sns_strength = 90;
config.filter_sharpness = 6;
config.alpha_quality = 90;
config_error = WebPValidateConfig(&config);  // will verify parameter ranges (always a good habit)

بعد ذلك، يجب الإشارة إلى عيّنات الإدخال في WebPPicture إما بالمرجع أو بالنسخ. في ما يلي مثال على تخصيص المخزن المؤقت لاحتواء العيّنات. ولكن يمكن بسهولة إعداد "عرض" لمصفوفة عيّنات تم تخصيصها مسبقًا. راجِع الدالة WebPPictureView().

// Setup the input data, allocating a picture of width x height dimension
WebPPicture pic;
if (!WebPPictureInit(&pic)) return 0;  // version error
pic.width = width;
pic.height = height;
if (!WebPPictureAlloc(&pic)) return 0;   // memory error

// At this point, 'pic' has been initialized as a container, and can receive the YUVA or RGBA samples.
// Alternatively, one could use ready-made import functions like WebPPictureImportRGBA(), which will take
// care of memory allocation. In any case, past this point, one will have to call WebPPictureFree(&pic)
// to reclaim allocated memory.

لإصدار البايتات المضغوطة، يتم استدعاء دالة ربط في كل مرة تتوفّر فيها بايتات جديدة. في ما يلي مثال بسيط يتضمّن تعريفًا لـ memory-writer في webp/encode.h. من المحتمل أن تكون عملية التهيئة هذه مطلوبة لضغط كل صورة:

// Set up a byte-writing method (write-to-memory, in this case):
WebPMemoryWriter writer;
WebPMemoryWriterInit(&writer);
pic.writer = WebPMemoryWrite;
pic.custom_ptr = &writer;

أصبحنا الآن على استعداد لضغط عيّنات الإدخال (وتحرير مساحة التخزين الخاصة بها بعد ذلك):

int ok = WebPEncode(&config, &pic);
WebPPictureFree(&pic);   // Always free the memory associated with the input.
if (!ok) {
  printf("Encoding error: %d\n", pic.error_code);
} else {
  printf("Output size: %d\n", writer.size);
}

للحصول على معلومات أكثر تقدّمًا حول استخدام واجهة برمجة التطبيقات وبنيتها، ننصحك بالاطّلاع على المستندات المتاحة في العنوان webp/encode.h. قد يكون من المفيد قراءة مثال الرمز البرمجي examples/cwebp.c للتعرّف على المعلَمات الأقل استخدامًا.

مستندات WebP API تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

العناوين والمكتبات

Simple Decoding API

سمات الإدخال

المرتجعات

سمات الإدخال

المرتجعات

سمات الإدخال

المرتجعات

سمات الإدخال

المرتجعات

Advanced Decoding API

Simple Encoding API

Advanced Encoding API

مستندات WebP API