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

Dokumentacja interfejsu WebP API

W tej sekcji opisano interfejs API kodera i dekodera w bibliotece WebP. Ten opis interfejsu API dotyczy wersji 1.4.0.

Nagłówki i biblioteki

Podczas instalowania libwebp katalogu o nazwie webp/ zostanie zainstalowana w typowym miejscu dla Twojej platformy. Na przykład na stronie na platformach Unix, następujące pliki nagłówka zostaną skopiowane do /usr/local/include/webp/

decode.h
encode.h
types.h

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

Interfejs Simple Decoding API

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

Dodaj 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 weryfikuje nagłówek obrazu WebP i pobiera szerokość obrazu oraz wysokość. Wskaźniki *width i *height mogą zostać przekroczone NULL, jeśli zostaną uznane nieistotne.

Atrybuty wejściowe

dane: Wskaźnik danych obrazu w formacie WebP
rozmiar_danych: To rozmiar bloku pamięci wskazywanego przez parametr data, który zawiera zdjęcia.

Zwroty

fałsz: Kod błędu zwrócony w przypadku (a) błędów formatowania.
prawda: Powodzenie. Zasady *width i *height są ważne tylko po udanym zwrocie.
szerokość: Liczba całkowita. Zakres jest ograniczony od 1 do 16 383.
wysokość: Liczba całkowita. Zakres jest ograniczony od 1 do 16 383.

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 cechy ze strumienia bitowego. *features struktura jest wypełniana informacjami pozyskanymi ze strumienia bitowego:

Atrybuty wejściowe

dane: Wskaźnik danych obrazu w formacie WebP
rozmiar_danych: To rozmiar bloku pamięci wskazywanego przez parametr data, który zawiera zdjęcia.

Zwroty

VP8_STATUS_OK: Po pobraniu funkcji.
VP8_STATUS_NOT_ENOUGH_DATA: Gdy do pobrania cech z nagłówków potrzeba więcej danych.

Dodatkowe wartości błędu VP8StatusCode w innych przypadkach.

Funkcje: Wskaźnik na strukturę 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 wskazywany przez 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 obrazów ARGB w kolejności [a0, r0, g0, b0, a1, r1, g1, b1, ...].
Funkcja WebPDecodeBGRA zwraca próbki obrazów BGRA w kolejności [b0, g0, r0, a0, b1, g1, r1, a1, ...].
Funkcja WebPDecodeRGB zwraca próbki obrazów RGB w kolejności [r0, g0, b0, r1, g1, b1, ...].
Funkcja WebPDecodeBGR zwraca próbki obrazów BGR w kolejności [b0, g0, r0, b1, g1, r1, ...].

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

Atrybuty wejściowe

dane: Wskaźnik danych obrazu w formacie WebP
rozmiar_danych: To rozmiar bloku pamięci wskazywanego przez parametr data, który zawiera dane obrazów
szerokość: Liczba całkowita. Zakres jest obecnie ograniczony od 1 do 16 383.
wysokość: Liczba całkowita. Zakres jest obecnie ograniczony od 1 do 16 383.

Zwroty

uint8_t*: Wskaźnik zdekodowanych próbek obrazów WebP w liniowych kolorach RGBA/ARGB/BGRA/RGB/BGR kolejność odpowiednio.

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 bezpośrednio dekodują obraz w przydzielonym wstępnie buforze output_buffer. Maksymalna ilość miejsca na dane dostępna w ten bufor jest oznaczony przez output_buffer_size. Jeśli to miejsce na dane nie jest wystarczająca (lub wystąpił błąd), zwracana jest wartość NULL. W przeciwnym razie Dla wygody zwracany jest output_buffer.

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

Atrybuty wejściowe

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

Zwroty

output_buffer: Wskaźnik zdekodowanego obrazu WebP.
uint8_t*: output_buffer, jeśli funkcja działa prawidłowo; W innym przypadku NULL.

Zaawansowany interfejs API dekodowania

Dekodowanie WebP obsługuje zaawansowany interfejs API, co umożliwia pracę na bieżąco. przycinanie i zmiana skalowania, co bardzo przydaje się przy ograniczonych pamięci. takich jak telefony komórkowe. Wykorzystanie pamięci będzie skalowane wraz z rozmiaru wyjściowego, a nie danych wejściowych, jeśli potrzebne jest tylko szybki podgląd lub lub powiększania części obrazu, który w innym wypadku byłby zbyt duży. Część procesora można zaoszczędzić przez przypadek.

Dekodowanie WebP występuje w dwóch wariantach, takich jak pełne dekodowanie obrazu i przyrostowe na małych buforach wejściowych. Użytkownicy mogą opcjonalnie przesłać zewnętrzny identyfikator bufor pamięci masowej do dekodowania obrazu. Przeanalizujemy ten przykładowy kod oraz o krokach 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ą zbierane w interfejsie WebPDecoderConfig struktura:

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 strumienia bitowego mogą być odczytywane w config.input, na wypadek, gdybyśmy musieli poznać je z wyprzedzeniem. Możesz na przykład wiedzieć, czy obraz jest w ogóle przezroczysty. Pamiętaj, że spowoduje to również analizuje nagłówek strumienia bitowego, więc jest to dobry sposób jeśli strumień bitowy wygląda na prawidłowy dla formatu WebP.

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

Następnie trzeba skonfigurować bufor pamięci dekodującej, na wypadek gdyby został on udostępniony bezpośrednio, zamiast polegać na dekoderze. Musimy tylko dostarcza wskaźnik do pamięci, jak również całkowity rozmiar bufora, krok 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ą dwa sposoby dekodowania zdjęcia. Obraz możemy zdekodować za jednym razem, używając:

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

Możemy też użyć metody przyrostowej do stopniowego dekodowania obraz w miarę dostępności nowych bajtów:

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.

Zdekodowany obraz znajduje się teraz w lokalizacji config.output (lub zamiast config.output.u.RGBA) w tym przypadku, ponieważ żądana przestrzeń kolorów wynosiła MODE_BGRA). Obraz może zapisane, wyświetlane ani w inny sposób przetwarzane. Później musimy odzyskać już tylko pamięć przydzieloną w obiekcie konfiguracji. Możesz bezpiecznie wywoływać tę funkcję, nawet jeśli pamięć jest zewnętrzna i nie została przydzielone przez WebPDecode():

WebPFreeDecBuffer(&config.output);

Za pomocą tego interfejsu API obraz można również dekodować do formatów YUV i YUVA przy użyciu MODE_YUV i MODE_YUVA. Format ten jest również nazywany Y'CbCr

Interfejs API Simple Encoding

Do kodowania tablic próbek RGBA dostarczono kilka bardzo prostych funkcji. w najpopularniejszych układach. Są one zadeklarowane w webp/encode.h nagłówek jako:

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 mieści się w zakresie od 0 do 100 oraz pozwala kontrolować straty i jakość podczas kompresji. Wartość 0 oznacza niską wartość. jakości i małych rozmiarów wyjściowych, natomiast 100 to najwyższa jakość rozmiarem wyjściowym. Po pomyślnym zakończeniu skompresowane bajty są umieszczane w sekcji *output i zwracany jest rozmiar w bajtach (w przeciwnym razie zwracana jest wartość 0, awarii). Rozmówca musi zadzwonić do: WebPFree() na: *output wskaźnik do odzyskania pamięci.

Tablica wejściowa powinna być spakowaną tablicą bajtów (po jednym dla każdego kanału, oczekiwanej od nazwy funkcji). stride odpowiada liczba bajtów niezbędnych do przejścia z jednego wiersza do następnego. Przykład: Układ BGRA:

Istnieją równoważne funkcje kodowania bezstratnego z podpisami:

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, takie jak wersje stratne, używają domyślnych ustawień biblioteki ustawieniach. W przypadku bezstratnych wartości oznacza to „ścisłe” jest wyłączona. Wartości RGB w przezroczyste obszary zostaną zmodyfikowane w celu zwiększenia kompresji. Aby tego uniknąć, użyj funkcji WebPEncode() i ustaw WebPConfig::exact na 1.

Advanced Encoding API

Koder ma wbudowane wiele zaawansowanych parametrów kodowania. Mogą być przydatne, gdy zależy Ci na lepszej równowadze kompromisu między kompresją wydajności i czasu przetwarzania. Parametry te są zbierane w strukturze 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ść z tych parametrów jest dostępna na potrzeby eksperymentów za pomocą narzędzia wiersza poleceń cwebp.

Próbki wejściowe powinny być umieszczone w strukturze WebPPicture. Ta struktura może przechowywać próbki danych wejściowych w formacie RGBA lub YUVA w zależności na wartości flagi use_argb.

Struktura ta wygląda tak:

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 ma również funkcję wysyłania skompresowanych bajtów zostaną udostępnione. Poniżej znajdziesz przykład zapisywania w pamięci. Inni zapisani mogą bezpośrednio przechowywać dane w pliku (patrz examples/cwebp.c).

Ogólny proces kodowania przy użyciu zaawansowanego interfejsu API wygląda tak :

Najpierw musimy ustawić konfigurację kodowania zawierającą za pomocą parametrów kompresji. Pamiętaj, że możesz użyć tej samej konfiguracji który skompresuje później kilka 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 należy odwoływać się do próbek wejściowych w elemencie WebPPicture: przez odwołanie lub kopię. Oto przykład przydzielania bufora do przechowywania i próbki. Można jednak łatwo skonfigurować widok do już przydzielonego przykładowej tablicy. Zobacz 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, punkt zaczepienia jest wywoływany za każdym razem, gdy nastąpią nowe bajty i dostępności informacji. Oto prosty przykład z zapisującym pamięć zadeklarowaną w webp/encode.h To zainicjowanie prawdopodobnie będzie wymagane w przypadku poszczególne zdjęcia do skompresowania:

// 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 (i 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);
}

Do bardziej zaawansowanych zastosowań interfejsu API i struktury zalecamy znajdziesz w dokumentacji dostępnej w nagłówku webp/encode.h. Zapoznanie się z przykładowym kodem examples/cwebp.c może okazać się przydatne do wykrywania rzadziej używanych parametrów.