WebP API-Dokumentation

In diesem Abschnitt wird die API für den Encoder und Decoder beschrieben, die in der WebP-Bibliothek enthalten sind. Diese API-Beschreibung bezieht sich auf Version 1.3.2.

Header und Bibliotheken

Wenn Sie libwebp installieren, wird ein Verzeichnis namens webp/ am typischen Speicherort für Ihre Plattform installiert. Auf Unix-Plattformen werden beispielsweise die folgenden Header-Dateien in /usr/local/include/webp/ kopiert.

decode.h
encode.h
types.h

Die Bibliotheken befinden sich in den üblichen Bibliotheksverzeichnissen. Die statischen und dynamischen Bibliotheken befinden sich auf Unix-Plattformen unter /usr/local/lib/.

Simple Decoding API

Damit Sie die Decoding API verwenden können, müssen Sie die Bibliotheks- und Header-Dateien wie oben beschrieben installiert haben.

Fügen Sie den Decoding API-Header wie folgt in Ihren C/C++-Code ein:

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

Diese Funktion validiert die WebP-Bildüberschrift und ruft die Bildbreite und -höhe ab. Den Mauszeigern *width und *height kann NULL übergeben werden, wenn sie als irrelevant eingestuft werden.

Eingabeattribute

daten
Zeiger auf WebP-Bilddaten
data_size
Dies ist die Größe des Arbeitsspeicherblocks, auf den data die Bilddaten verweist.

Rückgaben

false
Fehlercode, der bei (a) Formatierungsfehlern zurückgegeben wird
true
Bei Erfolg. *width und *height sind nur bei erfolgreicher Rückgabe gültig.
width
Ganzzahlwert. Der Bereich ist auf 1 bis 16.383 begrenzt.
height
Ganzzahlwert. Der Bereich ist auf 1 bis 16.383 begrenzt.
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);

Diese Funktion ruft Features aus dem Bitstream ab. Die *features-Struktur ist mit Informationen gefüllt, die aus dem Bitstream erfasst wurden:

Eingabeattribute

daten
Zeiger auf WebP-Bilddaten
data_size
Dies ist die Größe des Arbeitsspeicherblocks, auf den data die Bilddaten verweist.

Rückgaben

VP8_STATUS_OK
Wenn die Features erfolgreich abgerufen wurden.
VP8_STATUS_NOT_ENOUGH_DATA
Wenn mehr Daten erforderlich sind, um die Elemente aus Headern abzurufen.

In anderen Fällen zusätzliche VP8StatusCode-Fehlerwerte.

Funktionen
Zeiger auf die WebPBitstreamFeatures-Struktur.
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);

Mit diesen Funktionen wird ein WebP-Bild decodiert, auf das data verweist.

  • WebPDecodeRGBA gibt RGBA-Bildbeispiele in der Reihenfolge [r0, g0, b0, a0, r1, g1, b1, a1, ...] zurück.
  • WebPDecodeARGB gibt ARGB-Bildbeispiele in der Reihenfolge [a0, r0, g0, b0, a1, r1, g1, b1, ...] zurück.
  • WebPDecodeBGRA gibt BGRA-Bildbeispiele in der Reihenfolge [b0, g0, r0, a0, b1, g1, r1, a1, ...] zurück.
  • WebPDecodeRGB gibt RGB-Bildbeispiele in der Reihenfolge [r0, g0, b0, r1, g1, b1, ...] zurück.
  • WebPDecodeBGR gibt Beispiele für BGR-Bilder in der Reihenfolge [b0, g0, r0, b1, g1, r1, ...] zurück.

Der Code, der eine dieser Funktionen aufruft, muss den von diesen Funktionen mit WebPFree() zurückgegebenen Datenpuffer (uint8_t*) löschen.

Eingabeattribute

daten
Zeiger auf WebP-Bilddaten
data_size
Die Größe des Arbeitsspeicherblocks, auf den data mit den Bilddaten verweist.
width
Ganzzahlwert. Der Bereich ist derzeit auf 1 bis 16.383 begrenzt.
height
Ganzzahlwert. Der Bereich ist derzeit auf 1 bis 16.383 begrenzt.

Rückgaben

uint8_t*
Zeiger auf decodierte WebP-Bildbeispiele in linearer RGBA-/ARGB-/BGRA-/RGB-/BGR-Reihenfolge.
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);

Diese Funktionen sind Varianten der obigen Funktionen und decodieren das Bild direkt in einen vorab zugewiesenen Zwischenspeicher output_buffer. Der maximal in diesem Zwischenspeicher verfügbare Speicherplatz wird durch output_buffer_size angegeben. Wenn dieser Speicherplatz nicht ausreicht oder ein Fehler aufgetreten ist, wird NULL zurückgegeben. Andernfalls wird output_buffer zurückgegeben.

Der Parameter output_stride gibt den Abstand (in Byte) zwischen den Scanlinien an. Daher sollte output_buffer_size mindestens den Wert output_stride * picture - height haben.

Eingabeattribute

daten
Zeiger auf WebP-Bilddaten
data_size
Die Größe des Arbeitsspeicherblocks, auf den data mit den Bilddaten verweist.
output_buffer_size
Ganzzahlwert. Größe des zugewiesenen Zwischenspeichers
output_stride
Ganzzahlwert. Gibt den Abstand zwischen den Scanlinien an.

Rückgaben

output_buffer
Zeiger auf das decodierte WebP-Bild.
uint8_t*
output_buffer, wenn die Funktion erfolgreich ist; andernfalls NULL.

Erweiterte Decoding API

Die WebP-Decodierung unterstützt eine fortschrittliche API, die die Möglichkeit zum sofortigen Zuschneiden und Skalieren bietet. Dies ist in Umgebungen mit begrenztem Arbeitsspeicher wie Smartphones von großem Nutzen. Im Grunde skaliert die Speichernutzung mit der Größe der Ausgabe und nicht mit der der Eingabe, wenn nur eine schnelle Vorschau oder ein vergrößerter Teil eines ansonsten zu großen Bilds benötigt wird. Auch ein Teil der CPU kann nebensächlich eingespart werden.

Die WebP-Decodierung besteht in zwei Varianten: die vollständige Bilddecodierung und die inkrementelle Decodierung über kleine Eingabepuffer. Nutzer können optional einen externen Speicherpuffer zum Decodieren des Bildes bereitstellen. Im folgenden Codebeispiel werden die Schritte zur Verwendung der Advanced Decoding API beschrieben.

Zuerst müssen wir ein Konfigurationsobjekt initialisieren:

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

Die Decodierungsoptionen sind in der WebPDecoderConfig-Struktur zusammengefasst:

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

Optional können die Bitstream-Features in config.input eingelesen werden, falls wir sie vorab kennen müssen. Beispielsweise ist es praktisch zu wissen, ob das Bild überhaupt transparent ist. Beachten Sie, dass dabei auch der Header des Bitstreams geparst wird. Dies ist daher eine gute Möglichkeit zu wissen, ob der Bitstream wie ein gültiger WebP aussieht.

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

Dann müssen wir den Decodierungs-Speicherzwischenspeicher einrichten, falls wir ihn direkt bereitstellen möchten, anstatt uns für seine Zuordnung auf den Decoder zu verlassen. Wir müssen nur den Zeiger auf den Speicher sowie die Gesamtgröße des Puffers und den Linienschritt (Entfernung in Byte zwischen den Scanzeilen) angeben.

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

Das Bild kann jetzt decodiert werden. Es gibt zwei mögliche Varianten der Bilddecodierung. Wir können das Bild in einem Durchlauf decodieren:

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

Alternativ können wir die inkrementelle Methode verwenden, um das Bild schrittweise zu decodieren, sobald neue Byte verfügbar sind:

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.

Das decodierte Bild befindet sich jetzt in config.output (oder besser in config.output.u.RGBA, in diesem Fall, da der angeforderte Ausgabefarbraum MODE_BGRA war). Das Bild kann gespeichert, angezeigt oder anderweitig verarbeitet werden. Danach muss nur der im config-Objekt zugewiesene Arbeitsspeicher zurückgefordert werden. Sie können diese Funktion auch dann aufrufen, wenn der Speicher extern ist und nicht von WebPDecode() zugewiesen wurde:

WebPFreeDecBuffer(&config.output);

Mit dieser API kann das Bild auch mit MODE_YUV bzw. MODE_YUVA in die Formate YUV und YUVA decodiert werden. Dieses Format wird auch als Y'CbCr bezeichnet.

Einfache Codierungs-API

Für die Codierung von Arrays mit RGBA-Beispielen in den gängigsten Layouts stehen einige sehr einfache Funktionen zur Verfügung. Sie werden im webp/encode.h-Header so deklariert:

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

Der Qualitätsfaktor quality_factor reicht von 0 bis 100 und steuert den Verlust und die Qualität während der Komprimierung. Der Wert 0 entspricht einer niedrigen Qualität und kleinen Ausgabegrößen, während 100 der höchsten Qualität und größten Ausgabegröße entspricht. Bei Erfolg werden die komprimierten Byte im Zeiger *output platziert und die Größe in Byte wird zurückgegeben. Andernfalls wird 0 zurückgegeben, falls ein Fehler auftritt. Der Aufrufer muss WebPFree() für den *output-Zeiger aufrufen, um Arbeitsspeicher freizugeben.

Das Eingabearray sollte ein gepacktes Array von Byte sein (eines für jeden Kanal, wie vom Namen der Funktion erwartet). stride entspricht der Anzahl der Byte, die erforderlich sind, um von einer Zeile zur nächsten zu springen. Das BGRA-Layout ist beispielsweise:

Es gibt gleichwertige Funktionen für die verlustfreie Codierung mit Signaturen:

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

Beachten Sie, dass diese Funktionen, wie die verlustbehafteten Versionen, die Standardeinstellungen der Bibliothek verwenden. Für verlustfreies bedeutet dies, dass „genau passend“ deaktiviert ist. RGB-Werte in transparenten Bereichen werden geändert, um die Komprimierung zu verbessern. Verwenden Sie WebPEncode() und legen Sie WebPConfig::exact auf 1 fest, um dies zu vermeiden.

Erweiterte Codierungs-API

Der Encoder verfügt über zahlreiche erweiterte Codierungsparameter. Sie können nützlich sein, um einen Kompromiss zwischen Komprimierungseffizienz und Verarbeitungszeit zu finden. Diese Parameter werden in der WebPConfig-Struktur zusammengefasst. Die am häufigsten verwendeten Felder dieser Struktur sind:

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

Die meisten dieser Parameter können mit dem cwebp-Befehlszeilentool getestet werden.

Die Eingabebeispiele sollten in eine WebPPicture-Struktur eingebunden sein. Diese Struktur kann Eingabebeispiele abhängig vom Wert des Flags use_argb im RGBA- oder YUVA-Format speichern.

Die Struktur ist wie folgt aufgebaut:

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

Diese Struktur hat auch eine Funktion, mit der die komprimierten Byte ausgegeben werden, sobald sie verfügbar sind. Unten finden Sie ein Beispiel mit einem In-Memory-Schreiber. Andere Autoren können Daten direkt in einer Datei speichern. Ein Beispiel dafür finden Sie unter examples/cwebp.c.

Der allgemeine Ablauf für die Codierung mit der erweiterten API sieht so aus:

Zuerst müssen wir eine Codierungskonfiguration mit den Komprimierungsparametern einrichten. Beachten Sie, dass dieselbe Konfiguration später auch für die Komprimierung mehrerer verschiedener Images verwendet werden kann.

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

Anschließend muss durch einen Verweis oder eine Kopie auf die Eingabebeispiele in einer WebPPicture verwiesen werden. Im Folgenden finden Sie ein Beispiel für den Zwischenspeicher für die Stichproben. Sie können jedoch einfach eine „Ansicht“ für ein bereits zugewiesenes Beispielarray einrichten. Siehe die Funktion 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.

Jedes Mal, wenn neue Byte verfügbar sind, wird ein Hook aufgerufen, um die komprimierten Byte auszugeben. Hier ist ein einfaches Beispiel mit dem in webp/encode.h deklarierten Memory-Writer. Diese Initialisierung ist wahrscheinlich erforderlich, damit jedes Bild komprimiert wird:

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

Die Eingabe-Samples können jetzt komprimiert und anschließend der Speicher freigegeben werden:

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

Für eine fortgeschrittenere Verwendung der API und der Struktur sollten Sie die Dokumentation im webp/encode.h-Header zurate ziehen. Der Beispielcode examples/cwebp.c kann sich zum Erkennen weniger verwendeter Parameter als nützlich erweisen.