Documentação da API WebP

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Esta seção descreve a API do codificador e do decodificador incluídas na biblioteca WebP. Esta descrição da API refere-se à versão 1.2.4.

Cabeçalhos e bibliotecas

Quando você instalar libwebp, um diretório chamado webp/ será instalado no local típico da plataforma. Por exemplo, em plataformas Unix, os seguintes arquivos principais são copiados para /usr/local/include/webp/.

decode.h
encode.h
types.h

As bibliotecas ficam nos diretórios comuns da biblioteca. As bibliotecas estáticas e dinâmicas estão em /usr/local/lib/ em plataformas Unix.

API de decodificação simples

Para começar a usar a API de decodificação, verifique se você tem os arquivos de biblioteca e cabeçalho instalados, conforme descrito acima.

Inclua o cabeçalho da API de decodificação no código C/C++ da seguinte maneira:

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

Essa função validará o cabeçalho da imagem WebP e extrairá a largura e a altura da imagem. Os ponteiros *width e *height poderão ser transmitidos NULL se forem considerados irrelevantes.

Atributos de entrada

dados
Ponteiro para dados de imagem do WebP
tamanho dos dados
Esse é o tamanho do bloco de memória direcionado por data que contém os dados de imagem.

Retorna

false
Código de erro retornado no caso de (a) erros de formatação.
verdadeiro
Em sucesso. *width e *height só são válidos se houver retorno bem-sucedido.
largura
Valor inteiro. O intervalo é limitado de 1 a 16.383.
altura
Valor inteiro. O intervalo é limitado de 1 a 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);

Essa função vai recuperar recursos do bitstream. A estrutura *features é preenchida com informações coletadas do bitstream:

Atributos de entrada

dados
Ponteiro para dados de imagem do WebP
tamanho dos dados
Esse é o tamanho do bloco de memória direcionado por data que contém os dados de imagem.

Retorna

VP8_STATUS_OK
Quando os recursos forem recuperados.
VP8_STATUS_NOT_ENOUGH_DATA
Quando mais dados são necessários para recuperar os recursos dos cabeçalhos.

Valores adicionais de erro VP8StatusCode em outros casos.

recursos
Ponteiro para a estrutura 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);

Essas funções decodificam uma imagem WebP apontada por data.

  • WebPDecodeRGBA retorna amostras de imagens RGBA na ordem [r0, g0, b0, a0, r1, g1, b1, a1, ...].
  • WebPDecodeARGB retorna amostras de imagens ARGB na ordem [a0, r0, g0, b0, a1, r1, g1, b1, ...].
  • WebPDecodeBGRA retorna amostras de imagens BGRA na ordem [b0, g0, r0, a0, b1, g1, r1, a1, ...].
  • WebPDecodeRGB retorna amostras de imagens RGB em ordem [r0, g0, b0, r1, g1, b1, ...].
  • WebPDecodeBGR retorna amostras de imagens BGR na ordem [b0, g0, r0, b1, g1, r1, ...].

O código que chama qualquer uma dessas funções precisa excluir o buffer de dados (uint8_t*) retornado por essas funções com WebPFree().

Atributos de entrada

dados
Ponteiro para dados de imagem do WebP
tamanho dos dados
Esse é o tamanho do bloco de memória direcionado por data que contém os dados de imagem
largura
Valor inteiro. O intervalo atualmente é limitado de 1 a 16.383.
altura
Valor inteiro. O intervalo atualmente é limitado de 1 a 16.383.

Retorna

uint8_t*
Ponteiro para amostras de imagem WebP decodificadas em ordem linear RGBA/ARGB/BGRA/RGB/BGR, respectivamente.
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);

Essas funções são variantes das acima e decodificam a imagem diretamente em um buffer pré-alocado output_buffer. O armazenamento máximo disponível nesse buffer é indicado por output_buffer_size. Se esse armazenamento não for suficiente (ou tiver ocorrido um erro), NULL será retornado. Caso contrário, output_buffer será retornado, por conveniência.

O parâmetro output_stride especifica a distância (em bytes) entre linhas de verificação. Portanto, é esperado que output_buffer_size seja pelo menos output_stride * picture - height.

Atributos de entrada

dados
Ponteiro para dados de imagem do WebP
tamanho dos dados
Esse é o tamanho do bloco de memória direcionado por data que contém os dados de imagem
tamanho_de_buffer_de_saida
Valor inteiro. tamanho do buffer alocado
resultado_da_etapa
Valor inteiro. Especifica a distância entre as linhas de verificação.

Retorna

buffer de saída
Ponteiro para imagem WebP decodificada.
uint8_t*
output_buffer se a função for bem-sucedida. Caso contrário, será NULL.

API de decodificação avançada

A decodificação de WebP oferece suporte a uma API avançada para fornecer a capacidade de cortar e redimensionar imediatamente, algo de grande utilidade em ambientes com restrição de memória, como celulares. Basicamente, o uso da memória será dimensionado com o tamanho da saída, não com as entradas quando você só precisar de uma visualização rápida ou de um zoom em parte de uma imagem muito grande. Algumas CPUs também podem ser salvas de maneira acidental.

A decodificação de WebP vem em duas variantes, ou seja, decodificação de imagem completa e decodificação incremental em pequenos buffers de entrada. Os usuários também podem fornecer um buffer de memória externo para decodificar a imagem. Veja na amostra de código a seguir as etapas para usar a API de decodificação avançada.

Primeiro precisamos inicializar um objeto de configuração:

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

As opções de decodificação são reunidas dentro da estrutura 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]
};

Opcionalmente, os recursos de bitstream podem ser lidos em config.input, caso seja necessário conhecê-los com antecedência. Por exemplo, pode ser útil saber se a imagem tem alguma transparência. Observe que isso também analisará o cabeçalho bitstream' e, portanto, é uma boa maneira de saber se o bitstream parece ser um WebP válido.

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

Em seguida, precisamos configurar o buffer de memória de decodificação para o caso de querermos fornecê-lo diretamente em vez de depender do decodificador para a alocação. Só precisamos fornecer o ponteiro para a memória, bem como o tamanho total do buffer e o ritmo da linha (distância em bytes entre linhas de verificação).

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

A imagem está pronta para ser decodificada. Há duas variantes possíveis para decodificar a imagem. Podemos decodificar a imagem de uma só vez usando:

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

Como alternativa, podemos usar o método incremental para decodificar progressivamente a imagem à medida que bytes novos forem disponibilizados:

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.

A imagem decodificada agora está em config.output ou, em vez, em config.output.u.RGBA neste caso, como o espaço de cores de saída solicitado era MODE_BGRA. A imagem pode ser salva, exibida ou processada de outra forma. Depois, precisamos recuperar apenas a memória alocada no objeto &config. É seguro chamar essa função mesmo que a memória seja externa e não tenha sido alocada por WebPDecode():

WebPFreeDecBuffer(&config.output);

Com essa API, a imagem também pode ser decodificada para os formatos YUV e YUVA, usando MODE_YUV e MODE_YUVA, respectivamente. Esse formato também é chamado de Y'CbCr.

API de codificação simples

Algumas funções muito simples são fornecidas para codificar matrizes de amostras RGBA nos layouts mais comuns. Elas são declaradas no cabeçalho webp/encode.h como:

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

O fator de qualidade quality_factor varia de 0 a 100 e controla a perda e a qualidade durante a compactação. O valor 0 corresponde aos tamanhos de saída de baixa qualidade e pequenos, enquanto 100 é o tamanho de saída de maior qualidade e maior. Após a conclusão, os bytes compactados são colocados no ponteiro *output, e o tamanho em bytes é retornado (caso contrário, 0 será retornado, em caso de falha). O autor da chamada precisa chamar WebPFree() no ponteiro *output para recuperar a memória.

A matriz de entrada deve ser uma matriz agrupada de bytes (um para cada canal, conforme esperado pelo nome da função). stride corresponde ao número de bytes necessários para pular de uma linha para a próxima. Por exemplo, o layout do BGRA é:

Existem funções equivalentes para codificação sem perda, com assinaturas:

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

Observe que essas funções, como as versões com perda, usam as configurações padrão da biblioteca. Para "sem perda", isso significa que "#39;exact'" está desativado. Os valores de RGB em áreas transparentes serão modificados para melhorar a compactação. Para evitar isso, use WebPEncode() e defina WebPConfig::exact como 1.

API Advanced Encoding

Internamente, o codificador vem com vários parâmetros de codificação avançados. Eles podem ser úteis para equilibrar melhor a compensação entre a eficiência da compactação e o tempo de processamento. Esses parâmetros são coletados na estrutura WebPConfig. Os campos mais usados dessa estrutura são:

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

Observe que a maioria desses parâmetros pode ser acessada usando a ferramenta de linha de comando cwebp.

Os exemplos de entrada precisam ser agrupados em uma estrutura WebPPicture. Essa estrutura pode armazenar amostras de entrada no formato RGBA ou YUVA, dependendo do valor da sinalização use_argb.

A estrutura é organizada da seguinte maneira:

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

Essa estrutura também tem uma função para emitir os bytes compactados à medida que são disponibilizados. Veja abaixo um exemplo com um gravador na memória. Outros gravadores podem armazenar dados diretamente em um arquivo. Consulte examples/cwebp.c para ver um exemplo.

O fluxo geral para codificar usando a API avançada é semelhante a este:

Primeiro, precisamos definir uma configuração de codificação que contenha os parâmetros de compactação. A mesma configuração pode ser usada para compactar várias imagens diferentes posteriormente.

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

Em seguida, as amostras de entrada precisam ser referenciadas em um WebPPicture por referência ou cópia. Veja a seguir um exemplo de alocação do buffer para armazenar as amostras. Mas é fácil configurar um "view" para uma matriz de amostra alocada. Consulte a função 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.

Para emitir os bytes compactados, um hook é chamado sempre que novos bytes estão disponíveis. Veja um exemplo simples com o gravador de memória declarado em webp/encode.h. É provável que essa inicialização seja necessária para que cada imagem seja compactada:

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

Agora estamos prontos para compactar as amostras de entrada e liberar a memória posteriormente:

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

Para um uso mais avançado da API e da estrutura, recomendamos consultar a documentação disponível no cabeçalho webp/encode.h. A leitura do código de exemplo examples/cwebp.c pode ser útil para descobrir parâmetros menos usados.