این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

اسناد WebP API

این بخش API رمزگذار و رمزگشا را که در کتابخانه WebP گنجانده شده است، توضیح می دهد. این توضیحات API مربوط به نسخه 1.4.0 است.

سرفصل ها و کتابخانه ها

هنگامی که libwebp را نصب می کنید، دایرکتوری به نام webp/ در محل معمولی پلتفرم شما نصب می شود. برای مثال، در پلتفرم‌های یونیکس، فایل‌های هدر زیر در /usr/local/include/webp/ کپی می‌شوند.

decode.h
encode.h
types.h

کتابخانه ها در فهرست های معمول کتابخانه قرار دارند. کتابخانه های ایستا و پویا در /usr/local/lib/ در پلتفرم های یونیکس هستند.

API رمزگشایی ساده

برای شروع استفاده از API رمزگشایی، باید مطمئن شوید که کتابخانه و فایل‌های هدر را همانطور که در بالا توضیح داده شد نصب کرده‌اید.

هدر 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 حاوی داده های تصویر به آن اشاره می کنند.

برمی گرداند

نادرست: کد خطا در مورد (الف) خطای قالب‌بندی بازگردانده می‌شود.
درست است: در مورد موفقیت *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 نمونه های تصویر RGB را به ترتیب [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: اشاره گر به تصویر WebP رمزگشایی شده
uint8_t*: output_buffer در صورت موفقیت تابع؛ NULL در غیر این صورت.

API رمزگشایی پیشرفته

رمزگشایی WebP از یک API پیشرفته پشتیبانی می‌کند تا توانایی برش و تغییر مقیاس را در لحظه فراهم کند، چیزی که در محیط‌های دارای محدودیت حافظه مانند تلفن‌های همراه مفید است. اساساً، میزان استفاده از حافظه با اندازه خروجی مقیاس می شود، نه زمانی که فرد فقط به یک پیش نمایش سریع یا بزرگنمایی بخشی از یک تصویر بسیار بزرگ نیاز دارد. اتفاقاً می توان برخی از CPU را نیز ذخیره کرد.

رمزگشایی WebP در دو نوع وجود دارد، یعنی رمزگشایی کامل تصویر و رمزگشایی افزایشی از طریق بافرهای ورودی کوچک. کاربران می توانند به صورت اختیاری یک بافر حافظه خارجی برای رمزگشایی تصویر تهیه کنند. نمونه کد زیر مراحل استفاده از API رمزگشایی پیشرفته را طی می کند.

ابتدا باید یک شی پیکربندی را مقداردهی اولیه کنیم:

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

با استفاده از این API می توان تصویر را به فرمت های YUV و YUVA با استفاده از MODE_YUV و MODE_YUVA رمزگشایی کرد. این قالب Y'CbCr نیز نامیده می شود.

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

توجه داشته باشید که این توابع، مانند نسخه های با اتلاف، از تنظیمات پیش فرض کتابخانه استفاده کنید. برای Lossless این به این معنی است که "دقیق" غیرفعال است. مقادیر 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 پیچیده شوند. این ساختار بسته به مقدار پرچم use_argb می‌تواند نمونه‌های ورودی را در قالب RGBA یا YUVA ذخیره کند.

ساختار به شرح زیر سازماندهی شده است:

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 مراجعه کنید).

جریان کلی برای رمزگذاری با استفاده از API پیشرفته به صورت زیر است:

ابتدا باید یک پیکربندی رمزگذاری حاوی پارامترهای فشرده سازی را تنظیم کنیم. توجه داشته باشید که از همان پیکربندی می توان برای فشرده سازی چندین تصویر مختلف بعد از آن استفاده کرد.

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

برای استفاده پیشرفته تر از API و ساختار، توصیه می شود به اسناد موجود در سربرگ webp/encode.h نگاه کنید. خواندن مثال کد examples/cwebp.c می تواند برای کشف پارامترهای کمتر استفاده شده مفید باشد.