Bu sayfa, Cloud Translation API ile çevrilmiştir.

WebP API Belgeleri

Bu bölümde, WebP kitaplığında bulunan kodlayıcı ve kod çözücü API'si açıklanmaktadır. Bu API açıklaması 1.4.0 sürümüyle ilgilidir.

Başlıklar ve Kitaplıklar

libwebp uygulamasını yüklediğinizde platformunuzun tipik konumuna webp/ adlı bir dizin yüklenir. Örneğin, Unix platformlarında aşağıdaki başlık dosyaları /usr/local/include/webp/ öğesine kopyalanır.

decode.h
encode.h
types.h

Kitaplıklar normal kitaplık dizinlerinde bulunur. Statik ve dinamik kitaplıklar Unix platformlarında /usr/local/lib/ ürünündedir.

Simple Decoding API'si

Kod çözme API'sini kullanmaya başlamak için kitaplık ve başlık dosyalarının yukarıda açıklandığı gibi yüklendiğinden emin olmanız gerekir.

Kod çözme API başlığını C/C++ kodunuza aşağıdaki gibi ekleyin:

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

Bu işlev, WebP resim başlığını doğrulayıp resim genişliğini ve yüksekliğini alır. Alakasız olması durumunda *width ve *height işaretçileri NULL iletilebilir.

Giriş Özellikleri

veri: İşaretçi WebP resim verilerine
data_size: Bu, resim verilerini içeren data tarafından işaret edilen bellek bloğunun boyutudur.

İlerlemeler

false: (a) Biçimlendirme hatası durumunda döndürülen hata kodu.
true: Başarıda. *width ve *height yalnızca başarılı iade durumunda geçerlidir.
genişlik: Tam sayı değeri. Aralık 1 ile 16.383 arasındadır.
yükseklik: Tam sayı değeri. Aralık 1 ile 16383 arasında sınırlıdır.

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

Bu işlev, özellikleri bit akışından alır. *features yapısı, bit akışından toplanan bilgilerle doldurulur:

Giriş Özellikleri

veri: İşaretçi WebP resim verilerine
data_size: Bu, resim verilerini içeren data tarafından işaret edilen bellek bloğunun boyutudur.

İlerlemeler

VP8_STATUS_OK: Özellikler başarıyla alındığında.
VP8_STATUS_NOT_ENOUGH_DATA: Başlıklardan özellikleri almak için daha fazla veri gerektiğinde.

Diğer durumlardaki ek VP8StatusCode hata değerleri.

özellikler: İşaretçi WebPBitstreamFeatures yapısını gösterir.

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

Bu işlevler, data tarafından işaret edilen bir WebP resminin kodunu çözer.

WebPDecodeRGBA, RGBA resim örneklerini [r0, g0, b0, a0, r1, g1, b1, a1, ...] sırayla döndürür.
WebPDecodeARGB, ARGB resim örneklerini [a0, r0, g0, b0, a1, r1, g1, b1, ...] siparişinde döndürür.
WebPDecodeBGRA, BGRA resim örneklerini [b0, g0, r0, a0, b1, g1, r1, a1, ...] siparişinde döndürür.
WebPDecodeRGB, RGB resim örneklerini [r0, g0, b0, r1, g1, b1, ...] sırayla döndürür.
WebPDecodeBGR, BGR resim örneklerini [b0, g0, r0, b1, g1, r1, ...] siparişinde döndürür.

Bu işlevlerden herhangi birini çağıran kod, bu işlevlerin WebPFree() ile döndürdüğü (uint8_t*) veri arabelleğini silmelidir.

Giriş Özellikleri

veri: İşaretçi WebP resim verilerine
data_size: Bu, resim verilerini içeren data tarafından işaret edilen bellek bloğunun boyutudur
genişlik: Tam sayı değeri. Aralık şu anda 1 ile 16.383 arasındadır.
yükseklik: Tam sayı değeri. Aralık şu anda 1 ile 16.383 arasında sınırlıdır.

İlerlemeler

uint8_t*: Sırasıyla doğrusal RGBA/ARGB/BGRA/RGB/BGR sırasıyla, kodu çözülmüş WebP resim örneklerinin işaretçisini kullanın.

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

Bu işlevler yukarıdakilerin varyantlarıdır ve resmin kodunu doğrudan önceden ayrılmış bir arabelleğe output_buffer çözer. Bu arabellekte kullanılabilen maksimum depolama alanı output_buffer_size ile gösterilir. Bu depolama alanı yeterli değilse (veya bir hata oluştuysa) NULL döndürülür. Aksi takdirde, kolaylık olması için output_buffer döndürülür.

output_stride parametresi, tarama çizgileri arasındaki mesafeyi (bayt cinsinden) belirtir. Bu nedenle, output_buffer_size değerinin en az output_stride * picture - height olması beklenir.

Giriş Özellikleri

veri: İşaretçi WebP resim verilerine
data_size: Bu, resim verilerini içeren data tarafından işaret edilen bellek bloğunun boyutudur
output_buffer_size: Tam sayı değeri. Ayrılan arabelleğin boyutu
output_stride: Tam sayı değeri. Tarama çizgileri arasındaki mesafeyi belirtir.

İlerlemeler

output_buffer: İşaretçisi, kodu çözülmüş WebP resminin üzerine getirin.
uint8_t*: İşlev başarılı olursa output_buffer; aksi takdirde NULL.

Gelişmiş Kod Çözme API'sı

WebP kod çözme, cep telefonları gibi bellek kısıtlamalı ortamlarda büyük fayda sağlayan, anında kırpma ve yeniden ölçeklendirme olanağı sunma olanağı tanıyan gelişmiş bir API'yi destekler. Temel olarak, bellek kullanımı, yalnızca hızlı önizleme yapılması veya çok büyük bir resmin bir kısmının yakınlaştırılması gerektiğinde girişin değil, çıkışın boyutuyla ölçeklenir. Bazı CPU'lar tesadüf olarak kaydedilebilir.

WebP kod çözme özelliği, küçük giriş arabellekleri üzerinden tam resim kodu çözme ve artımlı kod çözme olmak üzere iki varyantla sunulur. Kullanıcılar isteğe bağlı olarak görüntünün kodunu çözmek için harici bir bellek arabelleği sağlayabilir. Aşağıdaki kod örneğinde, gelişmiş kod çözme API'sini kullanma adımları açıklanmaktadır.

Öncelikle bir yapılandırma nesnesini başlatmamız gerekir:

#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.

Kod çözme seçenekleri, WebPDecoderConfig yapısında toplanır:

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]
};

İsteğe bağlı olarak, bit akışı özellikleri önceden bilmemiz gerekirse config.input içinde okunabilir. Örneğin, resimde saydamlık düzeyinin olduğunu bilmek yararlı olabilir. Bunun aynı zamanda bit akışının başlığını ayrıştıracağını ve dolayısıyla bit akışının geçerli bir WebP olup olmadığını anlamanın iyi bir yolu olduğunu unutmayın.

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

Daha sonra, tahsisi için kod çözücüye güvenmek yerine doğrudan tedarik etmek istememiz ihtimaline karşı kod çözme belleği arabelleğini ayarlamamız gerekir. Yalnızca belleğe işaret edenin yanı sıra arabelleğin toplam boyutunu ve çizgi adımını (tarama çizgileri arasındaki bayt cinsinden mesafe) sağlamanız gerekir.

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

Görüntü, kodu çözülmeye hazır. Resmin kodunu çözmek için iki olası varyant vardır. Aşağıdakileri kullanarak resmin kodunu tek seferde çözebiliriz:

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

Alternatif olarak, yeni baytlar kullanılabilir hale geldikçe resmin kodunu kademeli olarak çözmek için artımlı yöntemi kullanabiliriz:

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.

Kodu çözülmüş görüntü artık config.output biçimindedir (veya istenen çıkış renk alanı MODE_BGRA olduğu için bu örnekte config.output.u.RGBA'da). Resim kaydedilebilir, görüntülenebilir veya başka bir şekilde işlenebilir. Daha sonra, yalnızca yapılandırma nesnesinde ayrılan belleği geri almamız gerekir. Bellek harici olsa ve WebPDecode() tarafından ayrılmamış olsa bile bu işlevi güvenli bir şekilde çağırabilirsiniz:

WebPFreeDecBuffer(&config.output);

Bu API kullanılarak resim, sırasıyla MODE_YUV ve MODE_YUVA kullanılarak YUV ve YUVA biçimlerine de çözülebilir. Bu biçim Y'CbCr olarak da adlandırılır.

Basit Kodlama API'sı

En yaygın düzenlerde, RGBA örneklerinin kodlama dizileri için çok basit bazı işlevler sağlanmıştır. Bunlar, webp/encode.h üst bilgisinde şu şekilde tanımlanır:

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

Kalite faktörü quality_factor 0 ile 100 arasında değişir ve sıkıştırma sırasında kaybı ve kaliteyi kontrol eder. 0 değeri, düşük kalite ve küçük çıktı boyutlarına karşılık gelir. 100 ise en yüksek kalite ve en büyük çıktı boyutunu ifade eder. İşlem başarılı olduğunda, sıkıştırılmış baytlar *output işaretçisine yerleştirilir ve bayt cinsinden boyut döndürülür (aksi takdirde, başarısızlık durumunda 0 döndürülür). Hafızayı geri kazanmak için çağrıyı yapanın *output işaretçisinde WebPFree() araması yapması gerekir.

Giriş dizisi, işlev adına göre beklendiği gibi, her kanal için bir tane olacak şekilde, işlenmiş bayt dizisi olmalıdır. stride, bir satırdan diğerine atlamak için gereken bayt sayısına karşılık gelir. Örneğin BGRA düzeni şöyledir:

Kayıpsız kodlama için imzalarla eşdeğer işlevler vardır:

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

Kayıplı sürümler gibi bu işlevlerin de kitaplığın varsayılan ayarlarını kullandığını unutmayın. Kayıpsız değeri için "tam" seçeneğinin devre dışı bırakıldığı anlamına gelir. Şeffaf alanlardaki RGB değerleri, sıkıştırmayı iyileştirmek için değiştirilir. Bunu önlemek için WebPEncode() özelliğini kullanın ve WebPConfig::exact değerini 1 olarak ayarlayın.

Gelişmiş Kodlama API'sı

Temel olarak kodlayıcı birçok gelişmiş kodlama parametresiyle gelir. Sıkıştırma verimliliği ile işleme süresi arasındaki dengeyi daha iyi dengelemek için yararlı olabilirler. Bu parametreler WebPConfig yapısı içinde toplanır. Bu yapının en çok kullanılan alanları şunlardır:

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

Bu parametrelerin çoğuna cwebp komut satırı aracı kullanılarak deneme amacıyla erişilebildiğini unutmayın.

Giriş örnekleri, bir WebPPicture yapısına sarmalanmalıdır. Bu yapı, use_argb işaretinin değerine bağlı olarak, giriş örneklerini RGBA veya YUVA biçiminde depolayabilir.

Yapı aşağıdaki gibi düzenlenmiştir:

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

Bu yapı, sıkıştırılmış baytları kullanıma sunuldukça yayınlama işlevine de sahiptir. Bellek içi yazıcıyla ilgili bir örnek için aşağıya bakın. Diğer yazarlar verileri doğrudan bir dosyaya depolayabilir (örneğin, examples/cwebp.c bkz.).

Gelişmiş API'yi kullanarak kodlamaya ilişkin genel akış aşağıdaki gibidir:

Öncelikle, sıkıştırma parametrelerini içeren bir kodlama yapılandırması oluşturmamız gerekir. Daha sonra birkaç farklı görüntüyü sıkıştırmak için aynı yapılandırmanın kullanılabileceğini unutmayın.

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

Daha sonra, giriş örneklerinin referans veya kopya yoluyla bir WebPPicture öğesine başvurulması gerekir. Aşağıda, örnekleri tutmak için tamponu ayıran bir örnek verilmiştir. Ancak halihazırda ayrılmış bir örnek dizi için kolayca "görünüm" oluşturulabilir. WebPPictureView() işlevine bakın.

// 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.

Sıkıştırılmış baytları yaymak için yeni baytlar her mevcut olduğunda bir kanca çağrılır. webp/encode.h öğesinde beyan edilen bellek yazıcısıyla ilgili basit bir örneği burada bulabilirsiniz. Her resmin sıkıştırılması için muhtemelen bu başlatma işlemi gerekecektir:

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

Artık giriş örneklerini sıkıştırmaya (ve daha sonra belleklerini boşaltmaya) hazırız:

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'nin ve yapının daha ileri düzey kullanımı için webp/encode.h başlığında bulunan belgelere bakmanız önerilir. examples/cwebp.c örnek kodunu okumak, daha az kullanılan parametreleri keşfetmek için faydalı olabilir.