Questa pagina è stata tradotta dall'API Cloud Translation.

Documentazione dell'API WebP

Questa sezione descrive l'API per il codificatore e il decodificatore inclusi nella libreria WebP. Questa descrizione dell'API riguarda la versione 1.6.0.

Intestazioni e librerie

Quando installi libwebp, una directory denominata webp/ verrà installata nella posizione tipica della tua piattaforma. Ad esempio, sulle piattaforme Unix, i seguenti file di intestazione verranno copiati in /usr/local/include/webp/.

decode.h
encode.h
types.h

Le librerie si trovano nelle directory delle librerie abituali. Le librerie statiche e dinamiche si trovano in /usr/local/lib/ sulle piattaforme Unix.

API Simple Decoding

Per iniziare a utilizzare l'API di decodifica, devi assicurarti di aver installato la libreria e i file di intestazione come descritto sopra.

Includi l'intestazione dell'API di decodifica nel codice C/C++ nel seguente modo:

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

Questa funzione convalida l'intestazione dell'immagine WebP e recupera la larghezza e l'altezza dell'immagine. I puntatori *width e *height possono essere ignorati NULL se ritenuti irrilevanti.

Attributi di input

dati: Puntatore ai dati dell'immagine WebP
data_size: Queste sono le dimensioni del blocco di memoria a cui fa riferimento data contenente i dati dell'immagine.

Resi

falso: Codice di errore restituito in caso di errori di formattazione.
true: In caso di esito positivo. *width e *height sono validi solo per i resi andati a buon fine.
larghezza: Valore intero. L'intervallo è limitato da 1 a 16383.
altezza: Valore intero. L'intervallo è limitato da 1 a 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);

Questa funzione recupererà le caratteristiche dal bitstream. La struttura *features viene compilata con le informazioni raccolte dal bitstream:

Attributi di input

dati: Puntatore ai dati dell'immagine WebP
data_size: Queste sono le dimensioni del blocco di memoria a cui fa riferimento data contenente i dati dell'immagine.

Resi

VP8_STATUS_OK: Quando le funzionalità vengono recuperate correttamente.
VP8_STATUS_NOT_ENOUGH_DATA: Quando sono necessari più dati per recuperare le funzionalità dalle intestazioni.

Valori di errore VP8StatusCode aggiuntivi in altri casi.

funzionalità: Puntatore alla struttura 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);

Queste funzioni decodificano un'immagine WebP indicata da data.

WebPDecodeRGBA restituisce campioni di immagini RGBA in ordine [r0, g0, b0, a0, r1, g1, b1, a1, ...].
WebPDecodeARGB restituisce campioni di immagini ARGB in ordine [a0, r0, g0, b0, a1, r1, g1, b1, ...].
WebPDecodeBGRA restituisce campioni di immagini BGRA in ordine [b0, g0, r0, a0, b1, g1, r1, a1, ...].
WebPDecodeRGB restituisce campioni di immagini RGB in ordine [r0, g0, b0, r1, g1, b1, ...].
WebPDecodeBGR restituisce campioni di immagini BGR in ordine [b0, g0, r0, b1, g1, r1, ...].

Il codice che chiama una di queste funzioni deve eliminare il buffer di dati (uint8_t*) restituito da queste funzioni con WebPFree().

Attributi di input

dati: Puntatore ai dati dell'immagine WebP
data_size: Queste sono le dimensioni del blocco di memoria a cui fa riferimento data contenente i dati dell'immagine
larghezza: Valore intero. Al momento, l'intervallo è limitato da 1 a 16383.
altezza: Valore intero. Al momento l'intervallo è limitato da 1 a 16383.

Resi

uint8_t*: Puntatore ai campioni di immagini WebP decodificate nell'ordine RGBA/ARGB/BGRA/RGB/BGR lineare rispettivamente.

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

Queste funzioni sono varianti di quelle sopra indicate e decodificano l'immagine direttamente in un buffer preallocato output_buffer. Lo spazio di archiviazione massimo disponibile in questo buffer è indicato da output_buffer_size. Se questo spazio di archiviazione non è sufficiente (o si è verificato un errore), viene restituito NULL. In caso contrario, per comodità viene restituito output_buffer.

Il parametro output_stride specifica la distanza (in byte) tra le linee di scansione. Pertanto, output_buffer_size dovrebbe essere almeno output_stride * picture - height.

Attributi di input

dati: Puntatore ai dati dell'immagine WebP
data_size: Queste sono le dimensioni del blocco di memoria a cui fa riferimento data contenente i dati dell'immagine
output_buffer_size: Valore intero. Dimensione del buffer allocato
output_stride: Valore intero. Specifica la distanza tra le linee di scansione.

Resi

output_buffer: Puntatore all'immagine WebP decodificata.
uint8_t*: output_buffer se la funzione ha esito positivo; NULL in caso contrario.

API Advanced Decoding

La decodifica WebP supporta un'API avanzata per fornire la possibilità di ritagliare e ridimensionare al volo, il che è molto utile in ambienti con memoria limitata come i cellulari. In sostanza, l'utilizzo della memoria verrà scalato in base alle dimensioni dell'output, non dell'input, quando è necessaria solo un'anteprima rapida o una porzione ingrandita di un'immagine altrimenti troppo grande. Per inciso, è possibile risparmiare anche un po' di CPU.

La decodifica WebP è disponibile in due varianti: decodifica dell'immagine completa e decodifica incrementale su piccoli buffer di input. Gli utenti possono fornire facoltativamente un buffer di memoria esterno per decodificare l'immagine. Il seguente esempio di codice illustra i passaggi per utilizzare l'API di decodifica avanzata.

Per prima cosa, dobbiamo inizializzare un oggetto di configurazione:

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

Le opzioni di decodifica sono raccolte all'interno della struttura 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]
};

Facoltativamente, le funzionalità del bitstream possono essere lette in config.input, nel caso in cui sia necessario conoscerle in anticipo. Ad esempio, può essere utile sapere se l'immagine ha una trasparenza. Tieni presente che verrà analizzato anche l'intestazione del bitstream, quindi è un buon modo per sapere se il bitstream sembra un WebP valido.

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

Poi dobbiamo configurare il buffer di memoria di decodifica nel caso in cui vogliamo fornirlo direttamente anziché fare affidamento sul decodificatore per la sua allocazione. Dobbiamo solo fornire il puntatore alla memoria, nonché la dimensione totale del buffer e il passo della linea (distanza in byte tra le linee di scansione).

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

L'immagine è pronta per essere decodificata. Esistono due possibili varianti per la decodifica dell'immagine. Possiamo decodificare l'immagine in una sola volta utilizzando:

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

In alternativa, possiamo utilizzare il metodo incrementale per decodificare progressivamente l'immagine man mano che diventano disponibili nuovi byte:

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.

L'immagine decodificata si trova ora in config.output (o meglio, in config.output.u.RGBA in questo caso, poiché lo spazio colore di output richiesto era MODE_BGRA). L'immagine può essere salvata, visualizzata o elaborata in altro modo. Dopodiché, dobbiamo solo recuperare la memoria allocata nell'oggetto di configurazione. È sicuro chiamare questa funzione anche se la memoria è esterna e non è stata allocata da WebPDecode():

WebPFreeDecBuffer(&config.output);

Utilizzando questa API, l'immagine può anche essere decodificata nei formati YUV e YUVA, utilizzando rispettivamente MODE_YUV e MODE_YUVA. Questo formato è anche chiamato Y'CbCr.

API Simple Encoding

Vengono fornite alcune funzioni molto semplici per codificare array di campioni RGBA nei layout più comuni. Sono dichiarati nell'intestazione webp/encode.h come:

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

Il fattore di qualità quality_factor è compreso tra 0 e 100 e controlla la perdita e la qualità durante la compressione. Il valore 0 corrisponde a una qualità bassa e a dimensioni di output ridotte, mentre 100 corrisponde alla qualità più alta e alle dimensioni di output più grandi. In caso di esito positivo, i byte compressi vengono inseriti nel puntatore *output e viene restituita la dimensione in byte (in caso contrario, viene restituito 0). Il chiamante deve chiamare WebPFree() sul puntatore *output per recuperare la memoria.

L'array di input deve essere un array compresso di byte (uno per ogni canale, come previsto dal nome della funzione). stride corrisponde al numero di byte necessari per passare da una riga all'altra. Ad esempio, il layout BGRA è:

Esistono funzioni equivalenti per la codifica lossless, con le seguenti firme:

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

Tieni presente che queste funzioni, come le versioni con perdita, utilizzano le impostazioni predefinite della libreria. Per la compressione lossless, "esatto" è disabilitato. I valori RGB nelle aree trasparenti verranno modificati per migliorare la compressione. Per evitare questo problema, utilizza WebPEncode() e imposta WebPConfig::exact su 1.

API Advanced Encoding

Sotto il cofano, l'encoder è dotato di numerosi parametri di codifica avanzati. Possono essere utili per bilanciare meglio il compromesso tra efficienza della compressione e tempo di elaborazione. Questi parametri vengono raccolti all'interno della struttura WebPConfig. I campi più utilizzati di questa struttura sono:

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

Tieni presente che la maggior parte di questi parametri è accessibile per la sperimentazione utilizzando lo strumento a riga di comando cwebp.

Gli esempi di input devono essere inclusi in una struttura WebPPicture. Questa struttura può memorizzare i campioni di input in formato RGBA o YUVA, a seconda del valore del flag use_argb.

La struttura è organizzata come segue:

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

Questa struttura ha anche una funzione per emettere i byte compressi man mano che vengono resi disponibili. Di seguito è riportato un esempio con un writer in memoria. Altri autori possono archiviare direttamente i dati in un file (vedi examples/cwebp.c per un esempio).

Il flusso generale per la codifica utilizzando l'API avanzata è il seguente:

Innanzitutto, dobbiamo configurare una configurazione di codifica contenente i parametri di compressione. Tieni presente che la stessa configurazione può essere utilizzata in seguito per comprimere diverse immagini.

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

Successivamente, i campioni di input devono essere referenziati in un WebPPicture tramite riferimento o copia. Ecco un esempio di allocazione del buffer per contenere i campioni. Tuttavia, è possibile configurare facilmente una "visualizzazione" di un array di campioni già allocato. Consulta la funzione 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.

Per emettere i byte compressi, viene chiamato un hook ogni volta che sono disponibili nuovi byte. Ecco un semplice esempio con memory-writer dichiarato in webp/encode.h. Questa inizializzazione è probabilmente necessaria per comprimere ogni immagine:

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

Ora siamo pronti a comprimere i campioni di input (e a liberare la memoria in seguito):

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

Per un utilizzo più avanzato dell'API e della struttura, ti consigliamo di consultare la documentazione disponibile nell'intestazione webp/encode.h. La lettura del codice di esempio examples/cwebp.c può rivelarsi utile per scoprire parametri meno utilizzati.

Documentazione dell'API WebP Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Intestazioni e librerie

API Simple Decoding

Attributi di input

Resi

Attributi di input

Resi

Attributi di input

Resi

Attributi di input

Resi

API Advanced Decoding

API Simple Encoding

API Advanced Encoding

Documentazione dell'API WebP