يصف هذا القسم واجهة برمجة التطبيقات الخاصة ببرنامج الترميز وفك الترميز المضمّنين في مكتبة 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_size
- هذا هو حجم كتلة الذاكرة المُشار إليها من خلال
dataوالتي تحتوي على بيانات الصورة.
المرتجعات
- false
- يتم عرض رمز خطأ في حالة (أ) أخطاء التنسيق.
- صحيح
- تحقيق النجاح يمكن إرجاع المشتريات بنجاح من خلال
*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عيّنات من الصور بنموذج أحمر أخضر أزرق بترتيب[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في الحالات الأخرى.
واجهة برمجة التطبيقات المتقدمة لفك الترميز
يدعم فك ترميز WebP واجهة برمجة تطبيقات متقدّمة لتوفير إمكانية الاقتصاص وتغيير الحجم بشكل فوري، وهو ما يمثل فائدة كبيرة على البيئات المحدودة الذاكرة مثل الهواتف الجوّالة. في الأساس، سيتغير استخدام الذاكرة مع حجم المخرجات، وليس الإدخال عندما يحتاج المرء فقط إلى معاينة سريعة أو تكبير جزء من صورة كبيرة جدًا. يمكن حفظ بعض وحدات المعالجة المركزية أيضًا، بالصدفة.
يأتي فك ترميز 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). يمكن حفظ الصورة أو عرضها أو معالجتها بأي طريقة أخرى. بعد ذلك، نحتاج فقط إلى استرداد الذاكرة المخصّصة في كائن config. من الآمن استدعاء هذه الدالة حتى إذا كانت الذاكرة خارجية ولم يتم تخصيصها بواسطة 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 مفيدة
لاكتشاف المعلَمات الأقل استخدامًا.