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

WebP API Belgeleri

Bu bölümde, pakete dahil olan kodlayıcı ve kod çözücü API'si açıklanmaktadır. depolarsınız. Bu API açıklaması sürümle ilgili 1.4.0.

Başlıklar ve Kitaplıklar

libwebp adlı dizini yüklediğinizde webp/ adlı bir dizin platformunuzun genel konumuna yüklenir. Örneğin, aşağıdaki başlık dosyaları, Unix platformlarında /usr/local/include/webp/

decode.h
encode.h
types.h

Kitaplıklar normal kitaplık dizinlerinde bulunur. Statik ve dinamik kitaplıklar, Unix platformlarında /usr/local/lib/ konumunda bulunur.

Basit Kod Çözme API'sı

Kod çözme API'sini kullanmaya başlamak için açıklandığı şekilde yüklenen kitaplık ve başlık dosyaları yukarıda.

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ğrular ve resim genişliğini alır ve yüksekliği belirtmelisiniz. *width ve *height işaretçileri, kabul edilirse NULL iletilebilir Alakasız.

Giriş Özellikleri

veri: İşaretçiden WebP resim verilerine yönlendirme
veri_boyutu: Bu, data tarafından işaret edilen bellek bloğunun boyutudur. resim verileri.

İadeler

false: (a) Biçimlendirme hataları durumunda döndürülen hata kodu.
true: Başarı üzerine. *width ve *height yalnızca başarılı iade durumunda geçerlidir.
genişlik: Tam sayı değeri. Bu aralık 1 ile 16.383 arasında sınırlıdı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çiden WebP resim verilerine yönlendirme
veri_boyutu: Bu, data tarafından işaret edilen bellek bloğunun boyutudur. resim verileri.

İadeler

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

Başka durumlarda ek VP8StatusCode hata değerleri.

özellikler: İşaretçi ile WebPBitstreamFeatures yapısı.

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 ile işaret edilen bir WebP görüntüsünün kodunu çözer.

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

Bu işlevlerden herhangi birini çağıran kodun veri arabelleğini silmesi gerekir (uint8_t*), bu işlevler tarafından WebPFree() ile döndürüldü.

Giriş Özellikleri

veri: İşaretçiden WebP resim verilerine yönlendirme
veri_boyutu: Bu, data tarafından işaret edilen bellek bloğunun boyutudur. görüntü verileri
genişlik: Tam sayı değeri. Bu aralık şu anda 1 ile 16.383 arasında sınırlıdır.
yükseklik: Tam sayı değeri. Bu aralık şu anda 1 ile 16.383 ile sınırlıdır.

İadeler

uint8_t*: Doğrusal RGBA/ARGB/BGRA/RGB/BGR'de kodu çözülmüş WebP resim örneklerine işaretçi tıklayı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 çözer bir arabelleğe (output_buffer) yapıştırın. Şuralarda kullanılabilecek maksimum depolama alanı: bu tampon output_buffer_size ile gösterilir. Bu depolama alanı (veya bir hata oluştu) NULL hatası döndürülür. Aksi halde output_buffer, kolaylık sağlamak amacıyla iade edildi.

output_stride parametresi, veriler arasındaki mesafeyi (bayt cinsinden) belirtir taranır. Bu nedenle, output_buffer_size değerinin en az olması bekleniyor output_stride * picture - height.

Giriş Özellikleri

veri: İşaretçiden WebP resim verilerine yönlendirme
veri_boyutu: Bu, data tarafından işaret edilen bellek bloğunun boyutudur. görüntü verileri
output_buffer_size: Tam sayı değeri. Ayrılan tamponun boyutu
output_stride: Tam sayı değeri. Tarama çizgileri arasındaki mesafeyi belirtir.

İadeler

output_buffer: Kodu çözülmüş WebP resminin işaretçisi.
uint8_t*: İşlev başarılı olursa output_buffer; Aksi takdirde NULL.

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

WebP kod çözme özelliği, anında erişim imkanı sağlamak için gelişmiş bir API'yi destekler. kırpma ve yeniden ölçeklendirme işlevleri bulunur. Bu da bellek kısıtlamalı mobil cihazlar için de geçerlidir. Temel olarak bellek kullanımı, çıkışın boyutunu, girişin yalnızca hızlı önizlemeye veya yakınlaştırılmış bir resimdir. Bazı CPU'lar kaydedilebilir hem de tesadüfen.

WebP kod çözme, tam resim kodu çözme ve artımlı kod çözmeyi öğreteceğim. Kullanıcılar isteğe bağlı olarak harici bir resmin kodunu çözmek için bellek arabelleği. Aşağıdaki kod örneğine bakalım. gelişmiş kod çözme API'sini kullanma adımlarına değineceğiz.

Öncelikle bir yapılandırma nesnesini ilk kullanıma hazırlamamı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 içinde toplanır. yapı:

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 config.input, uyarlayabilirsiniz. Örneğin, iş kırılım yapısının olup olmadığını kontrol edin. Bu işlemin bit akışının başlığını da ayrıştırır. Bu nedenle, olup olmadığını kontrol edin.

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

Sonra da kodu çözen bellek arabelleğini kurmamız gerekir. Belki bu tamponu kod çözücüye güvenmek yerine doğrudan uygulayabilirsiniz. Yapmamız gereken tek şey ve arabelleğin toplam boyutunu gösteren bir işaretleyiciyi belleğe satır adımı (tarama çizgileri arasındaki bayt cinsinden mesafe).

// 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ünün kodu çözülmeye hazır. Kod çözme için iki olası varyant vardır resim. Aşağıdakileri kullanarak resmin kodunu tek seferde çözebiliriz:

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

Alternatif olarak, kodu kademeli olarak çözmek için artımlı yeni baytlar kullanılabilir hale geldikçe resmin üzerinde çalışır:

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.Exit'de (veya config.Exit.u.RGBA'da) bu örnekte, istenen çıkış renk alanı MODE_BGRA olduğu için). Resim kaydedilemez, görüntülenemez veya başka şekilde işlenemez. Daha sonra, yalnızca yapılandırmanın nesnesinde ayrılan belleği geri almamız gerekir. Hafızaya takılı değilse ve öyle değilse bile bu işlevi çağırmak güvenli WebPDecode() tarafından ayrılmış:

WebPFreeDecBuffer(&config.output);

Bu API kullanılarak görüntü, Sırasıyla MODE_YUV ve MODE_YUVA. Bu biçim Y'CbCr

Basit Kodlama API'sı

RGBA örneklerinin kodlama dizileri için çok basit bazı işlevler sağlanır kullanabilirsiniz. Bu beyanlar webp/encode.h'nda beyan edilmiştir. üstbilgi şu şekildedir:

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 Sıkıştırma sırasında kaybı ve kaliteyi kontrol eder. 0 değeri düşük değerine karşılık gelir 100 ise en yüksek kalite ve en büyük çıktı boyutlarıdır. çıktı boyutu. İşlem başarılı olursa, sıkıştırılmış baytlar *output içine yerleştirilir. ve bayt cinsinden boyut döndürülür (aksi durumda, nedeniyle). Arayan, *output numaralı telefondan WebPFree() adlı kişiyi aramalıdır işaretçiyi kullanın.

Giriş dizisi, paketlenmiş bir bayt dizisi olmalıdır (her kanal için beklenen sonucun elde edilmesine yardımcı olur. stride, bir satırdan diğerine atlamak için gereken bayt sayısıdır. Örneğin, BGRA düzeni:

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 kitaplığın varsayılan ayarlarını kullandığını unutmayın Ayarlar'da devre dışı bırakabilirsiniz. Kayıpsız için bu, "tam" anlamına gelir devre dışı bırakıldı. RGB değerleri şeffaf alanlar, sıkıştırmayı iyileştirmek için değiştirilecek. Bunu önlemek için WebPEncode() ve WebPConfig::exact öğesini 1 olarak ayarlayın.

Gelişmiş Kodlama API'sı

Temelinde, kodlayıcı çok sayıda gelişmiş kodlama parametresiyle birlikte gelir. Bu öğeler, sıkıştırma işlemi arasındaki dengeyi daha iyi bir şekilde verimlilik ve işlem süresidir. 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 deneme için erişilebildiğini unutmayın cwebp komut satırı aracını kullanın.

Giriş örnekleri, WebPPicture yapısına entegre edilmelidir. Bu yapı, giriş örneklerini RGBA veya YUVA biçiminde depolayabilir. use_argb işaretinin değerine eklenir.

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ı, aynı zamanda sıkıştırılmış baytları yayımlayan bir kullanılabilir hale getirir. Bellek içi yazıcı ile ilgili aşağıdaki örneğe bakın. Diğer yazarlar verileri doğrudan bir dosyaya depolayabilir (bkz. examples/cwebp.c) bakın.

Gelişmiş API'yı kullanarak kodlamaya ilişkin genel akış aşağıdaki gibidir: takip etmek için:

Öncelikle, mevcut JavaScript'i içeren bir kodlama yapılandırması parametreleridir. Aynı yapılandırmanın kullanılabileceğini unutmayın sonradan birkaç farklı resmi sıkıştırmak için kullanılır.

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

Ardından, giriş örneklerinin bir WebPPicture içinde veya referans veya kopyadır. Aşağıda tamponu bekletme süresi için örnekler. Ancak kullanıcılar kolayca bir "görünüm" oluşturabilir daha önce tahsis edilmiş bir örnek dizisidir. WebPPictureView() işlevini inceleyin.

// 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ı yayınlamak için yeni baytlar her alındığında bir kanca çağrılır kullanılabilir. Burada, webp/encode.h Bu başlatma işlemi muhtemelen sıkıştırılacak her resim:

// 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 hafızayı 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 gelişmiş kullanımı için webp/encode.h başlığında bulunan dokümanlara bakın. Örnek kodu examples/cwebp.c okumak faydalı olabilir daha az kullanılan parametreleri keşfetmenizi sağlar.