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

مستندات WebP API

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

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

عند تثبيت libwebp، دليل يُسمى webp/ سيتم تثبيتها في المكان المعتاد لنظامك الأساسي. على سبيل المثال، في أنظمة التشغيل Unix، سيتم نسخ ملفات العناوين التالية إلى /usr/local/include/webp/

decode.h
encode.h
types.h

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

واجهة برمجة تطبيقات فك الترميز البسيطة

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

ضمِّن عنوان واجهة برمجة التطبيقات لفك ترميز المحتوى في رمز 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 وتحتوي على بيانات الصور.

المرتجعات

خطأ: تم عرض رمز خطأ في حالة (أ) أخطاء في التنسيق.
صحيح: تحقيق النجاح. ويمكن استخدام *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 وتحتوي على بيانات الصور.

المرتجعات

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 عيّنات صور نموذج أحمر أخضر أزرق بترتيب [r0, g0, b0, r1, g1, b1, ...].
تعرض ميزة "WebPDecodeBGR" عيّنات من صور BGR بترتيب [b0, g0, r0, b1, g1, r1, ...].

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

سمات الإدخال

البيانات: مؤشر إلى بيانات الصور بتنسيق WebP
حجم_البيانات: هذا هو حجم كتلة الذاكرة المشار إليه بواسطة 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 وتحتوي على بيانات الصورة
output_buffer_size: قيمة عدد صحيح حجم التخزين المؤقت المخصّص
output_stride: قيمة عدد صحيح تحدّد هذه السمة المسافة بين خطوط البحث.

المرتجعات

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

واجهة برمجة التطبيقات المتقدمة لفك الترميز

يدعم فك ترميز 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:

واجهة برمجة تطبيقات الترميز البسيطة

يتم توفير بعض الدوال البسيطة جدًا لصفائف ترميز عينات 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);

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

واجهة برمجة تطبيقات الترميز المتقدمة

الخيارات المتقدمة يأتي برنامج التشفير مزودًا بالعديد من معلَمات الترميز المتقدّمة. يمكن أن تكون مفيدة لتحقيق التوازن بشكل أفضل بين الضغط على الأزرار والكفاءة ووقت المعالجة. ويتم جمع هذه المعلَمات ضمن بنية 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.

لإصدار وحدات البايت المضغوطة، يتم استدعاء عنصر جذب في كل مرة يتم فيها المتوفرة. في ما يلي مثال بسيط مع تعريف مؤلف الذاكرة في 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 مفيدة. لاكتشاف المعاملات الأقل استخدامًا.