WebP API-Dokumentation

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

Header und Bibliotheken

Wenn Sie libwebp installieren, wird ein Verzeichnis namens webp/ werden an dem für Ihre Plattform üblichen Speicherort installiert. Zum Beispiel auf werden die folgenden Header-Dateien kopiert und /usr/local/include/webp/

decode.h
encode.h
types.h

Die Bibliotheken befinden sich in den üblichen Bibliotheksverzeichnissen. Die statische und dynamische Bibliotheken befinden sich auf Unix-Plattformen in /usr/local/lib/.

Simple Decoding API

Um die Decoding API verwenden zu können, musst du sicherstellen, dass die Bibliotheks- und Headerdateien wie beschrieben siehe oben.

Fügen Sie den Decodierungs-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 den WebP-Bild-Header und ruft die Bildbreite ab und Höhe. Die Zeiger *width und *height können am NULL übergeben werden, wenn sie irrelevant sind.

Eingabeattribute

Daten
Zeiger auf WebP-Bilddaten
data_size
Dies ist die Größe des Speicherblocks, auf den data mit dem Bilddaten.

Gibt Folgendes zurück:

falsch
Bei (a) Formatierungsfehlern zurückgegebener Fehlercode
wahr
Bei Erfolg. *width und *height sind nur bei erfolgreicher Rückgabe gültig.
Breite
Ganzzahliger Wert. Der Bereich ist auf 1 bis 16.383 begrenzt.
Höhe
Ganzzahliger Wert. 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 Merkmale aus dem Bitstream ab. Das *features Struktur ist mit Informationen gefüllt, die aus dem Bitstream stammen:

Eingabeattribute

Daten
Zeiger auf WebP-Bilddaten
data_size
Dies ist die Größe des Speicherblocks, auf den data mit dem Bilddaten.

Gibt Folgendes zurück:

VP8_STATUS_OK
Wenn die Funktionen abgerufen wurden.
VP8_STATUS_NOT_ENOUGH_DATA
Wenn zum Abrufen der Merkmale aus Headern mehr Daten erforderlich sind.

Zusätzliche VP8StatusCode-Fehlerwerte in anderen Fällen.

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

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 Beispiele für ARGB-Bilder 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 Datenpuffer löschen. Von diesen Funktionen zurückgegebene (uint8_t*) mit WebPFree().

Eingabeattribute

Daten
Zeiger auf WebP-Bilddaten
data_size
Dies ist die Größe des Speicherblocks, auf den data mit dem Bilddaten
Breite
Ganzzahliger Wert. Der Bereich ist derzeit von 1 bis 16.383 begrenzt.
Höhe
Ganzzahliger Wert. Der Bereich ist derzeit von 1 bis 16.383 begrenzt.

Gibt Folgendes zurück:

uint8_t*
Zeiger auf decodierte WebP-Bildbeispiele in linearen RGBA-/ARGB-/BGRA-/RGB-/BGR-Farben 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 verschoben. Der maximale Speicherplatz, der in Dieser Zwischenspeicher wird durch output_buffer_size angegeben. Wenn dieser Speicher nicht ausreichend (oder ein Fehler aufgetreten ist), wird NULL zurückgegeben. Andernfalls output_buffer wird der Einfachheit halber zurückgegeben.

Der Parameter output_stride gibt den Abstand (in Byte) zwischen Scanlinien. Daher wird für output_buffer_size erwartet, dass dieser mindestens output_stride * picture - height.

Eingabeattribute

Daten
Zeiger auf WebP-Bilddaten
data_size
Dies ist die Größe des Speicherblocks, auf den data mit dem Bilddaten
output_buffer_size
Ganzzahliger Wert. Größe des zugewiesenen Zwischenspeichers
output_stride
Ganzzahliger Wert. Gibt den Abstand zwischen den Scanlinien an.

Gibt Folgendes zurück:

output_buffer
Zeiger auf decodiertes WebP-Bild
uint8_t*
output_buffer, wenn die Funktion erfolgreich ist; Andernfalls NULL.

API für erweiterte Decodierung

Die WebP-Decodierung unterstützt eine erweiterte API, um eine spontane Ausführung zu ermöglichen. Zuschneiden und Skalieren, was bei beschränktem Speicher sehr nützlich ist. wie Smartphones. Im Grunde wird die Arbeitsspeichernutzung nicht auf die Größe der Ausgabe, nicht auf die Eingabe, wenn nur eine kurze Vorschau oder ein in einem zu großen Bild herangezoomt. Ein Teil der CPU kann eingespart werden ebenfalls.

Die WebP-Decodierung gibt es in zwei Varianten: vollständige Bilddecodierung und inkrementelle mit kleinen Eingabepuffern zu decodieren. Nutzer können optional eine externe für die Decodierung des Bildes. Das folgende Codebeispiel durchläuft die Schritte zur Verwendung der API für die erweiterte Decodierung.

Zuerst müssen Sie 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 findest du im WebPDecoderConfig Struktur:

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 im Voraus wissen müssen. Zum Beispiel ist es praktisch, ob das Bild überhaupt transparent ist. Dadurch wird parsen auch den Header der Bitstreams. Dies ist eine gute Möglichkeit, ob der Bitstream wie ein gültiger WebP-Wert aussieht.

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

Dann müssen wir den Zwischenspeicher für die Decodierung einrichten, falls wir ihn bereitstellen möchten. anstatt sich für die Zuweisung auf den Decoder zu verlassen. Wir müssen nur den Zeiger an den Arbeitsspeicher liefern, sowie die Gesamtgröße des Zwischenspeichers Line stride (Abstand in Byte zwischen Scanlinien).

// 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 Image kann jetzt decodiert werden. Es gibt zwei mögliche Varianten für die Decodierung auf das Bild. Wir können das Bild auf einmal decodieren mit:

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

Alternativ können wir die inkrementelle Methode verwenden, um sobald neue Bytes 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 gesagt in config.output.u.RGBA). in diesem Fall, da der angeforderte Ausgabefarbraum MODE_BGRA war. Bild kann gespeichert, angezeigt oder anderweitig verarbeitet werden. Danach müssen wir nur noch den Arbeitsspeicher freigeben, der im -Objekt der Konfiguration zugewiesen ist. Es ist sicher, diese Funktion aufzurufen, auch wenn der Speicher extern ist und von WebPDecode() zugewiesen:

WebPFreeDecBuffer(&config.output);

Mit diesem API kann das Bild auch in die Formate YUV und YUVA decodiert werden. Dabei wird Folgendes verwendet: Entsprechend MODE_YUV und MODE_YUVA. Dieses Format wird auch als Y'CbCr:

Simple Encoding API

Für die Codierung von Arrays von RGBA-Stichproben werden einige sehr einfache Funktionen bereitgestellt. in den gängigsten Layouts. Sie werden in den webp/encode.h deklariert Überschrift als:

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 liegt zwischen 0 und 100. steuert den Verlust und die Qualität während der Komprimierung. Der Wert 0 entspricht einer niedrigen Qualität und die geringe Ausgabegröße, während 100 die höchste Qualität und die Ausgabegröße. Bei Erfolg werden die komprimierten Bytes im *output abgelegt. und die Größe in Byte wird zurückgegeben. Andernfalls wird 0 zurückgegeben, falls Fehler). Der Anrufer muss WebPFree() auf *output aufrufen zur Freigabe von Arbeitsspeicher.

Das Eingabearray sollte ein gepacktes Byte-Array sein (eines für jeden Kanal, des Funktionsnamens erwartet wird). stride entspricht dem Anzahl der Bytes, die benötigt werden, um von einer Zeile zur nächsten zu springen. Beispiel: Das BGRA-Layout ist:

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 Einstellungen. Bei verlustfreiem Zustand bedeutet dies „genau passend“, deaktiviert ist. RGB-Werte in Transparente Bereiche werden geändert, um die Komprimierung zu verbessern. Um dies zu vermeiden, verwenden Sie WebPEncode() und WebPConfig::exact auf 1 setzen.

Erweiterte Codierungs-API

Der Encoder verfügt über zahlreiche erweiterte Codierungsparameter. Sie können nützlich sein, um einen Ausgleich zwischen der Komprimierung zu finden Effizienz und Verarbeitungszeit. Diese Parameter werden in der WebPConfig-Struktur erfasst. 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 getestet werden. mit dem cwebp-Befehlszeilentool.

Die Eingabebeispiele sollten in eine WebPPicture-Struktur eingebunden werden. Diese Struktur kann Eingabe-Samples entweder im RGBA- oder YUVA-Format speichern, je nachdem, zum Wert des Flags use_argb.

Die Struktur ist wie folgt organisiert:

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 Bytes ausgegeben werden, sobald sie verfügbar gemacht werden. Unten finden Sie ein Beispiel mit einem In-Memory-Schreiber. Andere Autoren können Daten direkt in einer Datei speichern (siehe examples/cwebp.c).

Der allgemeine Ablauf für die Codierung mit der erweiterten API sieht wie folgt aus: Folgendes:

Zunächst müssen wir eine Codierungskonfiguration einrichten, die den Komprimierungsparameter. Dieselbe Konfiguration kann zur Komprimierung mehrerer Bilder anschließend.

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

Dann müssen die Eingabe-Samples in einem WebPPicture entweder durch Verweis oder Kopie. Hier ein Beispiel für die Zuweisung des Zwischenspeichers zu den Stichproben. Aber man kann ganz einfach eine „Ansicht“ zu einer bereits zugewiesenen Beispiel-Array. 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.

Um die komprimierten Byte auszugeben, wird jedes Mal ein Hook aufgerufen, wenn neue Byte verfügbar. Hier ist ein einfaches Beispiel, bei dem der Memory-Writer webp/encode.h Diese Initialisierung wird wahrscheinlich jedes zu komprimierende Bild:

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

Jetzt können die Eingabestichproben komprimiert und anschließend 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 Struktur wird empfohlen, finden Sie in der Dokumentation im webp/encode.h-Header. Der Beispielcode examples/cwebp.c kann sich als nützlich erweisen. weniger verwendete Parameter zu finden.