Ta strona została przetłumaczona przez Cloud Translation API.

Dokumentacja interfejsu WebP API

W tej sekcji opisano interfejs API kodera i dekodera, które są dostępne w bibliotece WebP. Ten opis interfejsu API dotyczy wersji 1.5.0.

Nagłówki i biblioteki

Po zainstalowaniu libwebp w typowej lokalizacji na danej platformie zostanie zainstalowany katalog o nazwie webp/. Na przykład na platformach Unixa do pliku /usr/local/include/webp/ zostaną skopiowane te pliki nagłówka:

decode.h
encode.h
types.h

Biblioteki znajdują się w zwykłych katalogach bibliotek. Biblioteki statyczne i dynamiczne są w /usr/local/lib/ na platformach Unix.

Simple Decoding API

Aby zacząć korzystać z interfejsu dekodowania API, musisz mieć zainstalowane biblioteki i pliki nagłówków zgodnie z opisem powyżej.

Umieść nagłówek interfejsu API do dekodowania w kodzie C/C++ w ten sposób:

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

Ta funkcja sprawdza nagłówek obrazu WebP i pobiera jego szerokość oraz wysokość. Wskaźniki *width i *height można przekazać jako NULL, jeśli są nieistotne.

Atrybuty wejściowe

dane: Wskaźnik do danych obrazu WebP
data_size: To rozmiar bloku pamięci wskazywanego przez zmienną data, który zawiera dane obrazu.

Zwroty

fałsz: Kod błędu zwracany w przypadku błędów formatowania.
prawda: W przypadku powodzenia. Wartości *width i *height są prawidłowe tylko w przypadku pomyślnego zwrotu.
szerokość: Wartość całkowita. Zakres jest ograniczony do wartości od 1 do 16383.
wysokość: Wartość całkowita. Zakres jest ograniczony do wartości od 1 do 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);

Ta funkcja pobiera właściwości z bitstremu. Struktura *features jest wypełniana informacjami zebranymi z strumienia bitów:

Atrybuty wejściowe

dane: Wskaźnik do danych obrazu WebP
data_size: To rozmiar bloku pamięci wskazywanego przez zmienną data, który zawiera dane obrazu.

Zwroty

VP8_STATUS_OK: Gdy funkcje zostały pobrane.
VP8_STATUS_NOT_ENOUGH_DATA: Gdy do pobrania funkcji z nagłówków potrzebnych jest więcej danych.

W innych przypadkach mogą wystąpić dodatkowe wartości błędów VP8StatusCode.

Funkcje: Wskaźnik do struktury 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);

Te funkcje dekodują obraz WebP wskazany przez zmienną data.

Funkcja WebPDecodeRGBA zwraca próbki obrazów RGBA w kolejności [r0, g0, b0, a0, r1, g1, b1, a1, ...].
Funkcja WebPDecodeARGB zwraca próbki obrazu ARGB w kolejności [a0, r0, g0, b0, a1, r1, g1, b1, ...].
Funkcja WebPDecodeBGRA zwraca próbki obrazu BGRA w kolejności [b0, g0, r0, a0, b1, g1, r1, a1, ...].
WebPDecodeRGB zwraca próbki obrazów RGB w kolejności [r0, g0, b0, r1, g1, b1, ...].
Funkcja WebPDecodeBGR zwraca próbki obrazu BGR w kolejności [b0, g0, r0, b1, g1, r1, ...].

Kod wywołujący dowolną z tych funkcji musi usunąć bufor danych (uint8_t*) zwracany przez te funkcje za pomocą WebPFree().

Atrybuty wejściowe

dane: Wskaźnik do danych obrazu WebP
data_size: To rozmiar bloku pamięci wskazywanego przez data, który zawiera dane obrazu.
szerokość: Wartość całkowita. Zakres jest obecnie ograniczony do wartości od 1 do 16383.
wysokość: Wartość całkowita. Obecnie zakres jest ograniczony do wartości od 1 do 16383.

Zwroty

uint8_t*: Wskaźnik do dekodowanych próbek obrazu WebP w kolejności 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);

Te funkcje są wariantami powyższych funkcji i dekodują obraz bezpośrednio do wstępnie przydzielonego bufora output_buffer. Maksymalna ilość miejsca na dane dostępna w tym buforze jest oznaczona symbolem output_buffer_size. Jeśli nie ma wystarczającej ilości miejsca (lub wystąpił błąd), zwracana jest wartość NULL. W przeciwnym razie zwracana jest wartośćoutput_buffer.

Parametr output_stride określa odległość (w bajtach) między liniami skanowania. Dlatego wartość output_buffer_size powinna wynosić co najmniejoutput_stride * picture - height.

Atrybuty wejściowe

dane: Wskaźnik do danych obrazu WebP
data_size: To rozmiar bloku pamięci wskazywanego przez data, który zawiera dane obrazu.
output_buffer_size: Wartość całkowita. Rozmiar przydzielonego bufora
output_stride: Wartość całkowita. Określa odległość między liniami skanowania.

Zwroty

output_buffer: Wskaźnik do odkodowanego obrazu WebP.
uint8_t*: output_buffer, jeśli funkcja się powiedzie, w przeciwnym razie NULL.

Advanced Decoding API

Dekodowanie WebP obsługuje zaawansowany interfejs API, który umożliwia kadrowanie i przeskalowywanie na bieżąco. Jest to bardzo przydatne w środowiskach o ograniczonej ilości pamięci, takich jak telefony komórkowe. Korzystanie z pamięci będzie się zmieniać w zależności od rozmiaru wyjściowego, a nie wejściowego, gdy potrzebny jest tylko szybki podgląd lub powiększony fragment zbyt dużego zdjęcia. Poza tym można też zaoszczędzić trochę mocy procesora.

Dekodowanie WebP występuje w 2 wariantach: pełne dekodowanie obrazu i inkrementalne dekodowanie za pomocą małych buforów wejściowych. Użytkownicy mogą opcjonalnie podać zewnętrzny bufor pamięci na potrzeby dekodowania obrazu. W tym przykładowym kodzie znajdziesz instrukcje korzystania z zaawansowanego interfejsu API do dekodowania.

Najpierw musimy zainicjować obiekt konfiguracji:

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

Opcje dekodowania są zebrane w strukturze 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]
};

Opcjonalnie funkcje bitstreama można odczytać do config.input, jeśli zachodzi taka potrzeba. Może być na przykład przydatne, aby dowiedzieć się, czy obraz zawiera jakiekolwiek elementy przezroczyste. Pamiętaj, że ta metoda będzie również analizować nagłówek strumienia bitów, dzięki czemu możesz sprawdzić, czy strumień bitów wygląda jak prawidłowy strumień WebP.

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

Następnie musimy skonfigurować bufor pamięci do dekodowania na wypadek, gdybyśmy chcieli go podać bezpośrednio zamiast polegać na dekoderze w zakresie jego przydzielenia. Musimy tylko podać wskaźnik do pamięci oraz łączny rozmiar bufora i skok linii (odległość w bajtach między liniami skanowania).

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

Obraz jest gotowy do dekodowania. Istnieją 2 możliwe warianty dekodowania obrazu. Możemy odkodować obraz za jednym razem, używając:

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

Możemy też użyć metody przyrostowej, aby stopniowo dekodować obraz, gdy będą dostępne nowe bajty:

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.

Odkodowany obraz znajduje się teraz w pliku config.output (a ściślej mówiąc, w pliku config.output.u.RGBA, ponieważ żądana przestrzeń kolorów wyjściowej była MODE_BGRA). Obraz może zostać zapisany, wyświetlony lub w inny sposób przetworzony. Następnie wystarczy nam tylko odzyskać pamięć przydzieloną w obiekcie config. Funkcję tę można bezpiecznie wywołać, nawet jeśli pamięć jest zewnętrzna i nie została przydzielona przez WebPDecode():

WebPFreeDecBuffer(&config.output);

Za pomocą tego interfejsu API obraz można też zdekodować do formatów YUV i YUVA, używając odpowiednio parametrów MODE_YUV i MODE_YUVA. Ten format nazywany jest też Y'CbCr.

Simple Encoding API

Do kodowania tablic próbek RGBA w najczęstszych układach służą bardzo proste funkcje. Są one deklarowane w nagłówku webp/encode.hjako:

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

Współczynnik jakości quality_factor przyjmuje wartości od 0 do 100 i kontroluje utratę jakości podczas kompresji. Wartość 0 odpowiada niskiej jakości i małym rozmiarom wyjściowym, a wartość 100 – najwyższej jakości i największym rozmiarom wyjściowym. W przypadku powodzenia skompresowane bajty są umieszczane w wskaźniku *output, a rozmiar w bajtach jest zwracany (w przeciwnym razie zwracany jest 0). Aby odzyskać pamięć, wywołujący musi wywołać funkcję WebPFree() wskazującą *output.

Tablica wejściowa powinna być upakowaną tablicą bajtów (po jednej na każdy kanał, zgodnie z nazwą funkcji). stride odpowiada liczbie bajtów potrzebnych do przejścia z jednego wiersza na następny. Na przykład układ BGRA:

Istnieją też funkcje równoważne do kodowania bezstratnego z sygnaturami:

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

Pamiętaj, że te funkcje, podobnie jak wersje stratne, korzystają z domyślnych ustawień biblioteki. W przypadku bezstratnego oznacza to, że opcja „dokładne” jest wyłączona. Wartości RGB w nieprzezroczystych obszarach zostaną zmienione, aby poprawić kompresję. Aby tego uniknąć, użyj opcji WebPEncode() i ustaw wartość WebPConfig::exact na 1.

interfejs API kodowania zaawansowanego;

Pod maską koder ma wiele zaawansowanych parametrów kodowania. Mogą one pomóc w lepszym zrównoważeniu kompromisu między wydajnością kompresji a czasem przetwarzania. Te parametry są zbierane w ramach struktury WebPConfig. Najczęściej używane pola w tej strukturze to:

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

Pamiętaj, że większość tych parametrów jest dostępna do eksperymentowania za pomocą narzędzia wiersza poleceń cwebp.

Próbki wejściowe powinny być zapakowane w strukturę WebPPicture. Ta struktura może przechowywać próbki wejściowe w formacie RGBA lub YUVA, w zależności od wartości flagi use_argb.

Struktura jest zorganizowana w ten sposób:

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

Ta struktura zawiera też funkcję emitowania skompresowanych bajtów, gdy są one dostępne. Poniżej znajdziesz przykład z użyciem zapisu do pamięci. Inni autorzy mogą zapisywać dane bezpośrednio w pliku (patrz: examples/cwebp.c).

Ogólny proces kodowania za pomocą zaawansowanego interfejsu API wygląda tak:

Najpierw musimy skonfigurować kodowanie zawierające parametry kompresji. Pamiętaj, że tę samą konfigurację można później wykorzystać do skompresowania kilku różnych obrazów.

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

Następnie odniesienia do próbek danych wejściowych muszą być dodane do pliku WebPPicture za pomocą odwołania lub kopii. Oto przykład przydzielenia bufora do przechowywania próbek. Można jednak łatwo skonfigurować „widok” dla już przydzielonego tablicy próbek. Zapoznaj się z funkcją 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.

Aby emitować skompresowane bajty, za każdym razem, gdy są dostępne nowe bajty, wywoływany jest haczyk. Oto prosty przykład z deklaracją funkcji zapisu do pamięci w funkcji webp/encode.h. Ta inicjalizacja może być potrzebna do skompresowania każdego zdjęcia:

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

Możemy teraz skompresować próbki danych wejściowych (a potem zwolnić ich pamięć):

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

Aby dowiedzieć się więcej o zaawansowanym korzystaniu z interfejsu API i jego struktury, zapoznaj się z dokumentacją dostępną w nagłówku webp/encode.h. Przeczytaj przykładowy kod examples/cwebp.c, aby poznać mniej używane parametry.