Gestire il formato WebP in C++
Usare libwebp direttamente da C++ significa lavorare alla fonte: tutte le opzioni dell'encoder, il ridimensionamento in codifica e in decodifica, il pieno controllo del contenitore e delle animazioni sono a portata di mano, senza le semplificazioni imposte dai binding degli altri linguaggi.
Quasi tutte le librerie che gestiscono WebP negli altri linguaggi, da sharp in Node.js a Pillow in Python, da GD e Imagick in PHP ai binding JNI di Java, sono costruite sopra la stessa base: libwebp, la libreria di riferimento scritta in C e sviluppata dal progetto WebM di Google. In C++ possiamo usarla direttamente, senza strati intermedi, e questo ci dà accesso a tutto: l'API semplice per le conversioni rapide, l'API avanzata con il controllo completo dell'encoder, il ridimensionamento integrato, la decodifica con ridimensionamento al volo, i moduli per le animazioni e per i metadati.
Il prezzo da pagare è che libwebp è un'API C, con puntatori grezzi, strutture da inizializzare e memoria da liberare con funzioni specifiche. In questo articolo vedremo come avvolgerla in un'interfaccia C++ moderna, con RAII e std::expected dello standard C++23, e costruiremo un piccolo toolkit: parser dell'intestazione, codifica e decodifica, ridimensionamento, gestione dei metadati, animazioni, controlli di sicurezza e conversione parallela di un archivio.
Le librerie di libwebp
libwebp è suddivisa in più librerie, ciascuna con il proprio header:
libwebp, conwebp/encode.hewebp/decode.h: codifica e decodifica di immagini statiche;libwebpmux, conwebp/mux.h: manipolazione del contenitore, cioè aggiunta e rimozione di chunk ICC, EXIF e XMP, e l'encoder di animazioniWebPAnimEncoder;libwebpdemux, conwebp/demux.h: lettura dei chunk e decoder di animazioniWebPAnimDecoder;libsharpyuv: la conversione RGB verso YUV di alta qualità usata dall'opzioneuse_sharp_yuv.
Su Debian e Ubuntu i pacchetti di sviluppo si installano con apt install libwebp-dev libpng-dev; libpng ci servirà per leggere e scrivere le immagini di ingresso e di uscita. Con CMake, il modo più portabile per trovare le librerie è pkg-config:
# CMakeLists.txt
cmake_minimum_required(VERSION 3.24)
project(webp_toolkit LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(PkgConfig REQUIRED)
pkg_check_modules(WEBP REQUIRED IMPORTED_TARGET libwebp libwebpmux libwebpdemux)
find_package(PNG REQUIRED)
add_library(webp_toolkit
src/webp_info.cpp
src/codec.cpp
src/png_io.cpp
src/metadata.cpp
src/animation.cpp)
target_include_directories(webp_toolkit PUBLIC include)
target_link_libraries(webp_toolkit PUBLIC PkgConfig::WEBP PNG::PNG)
target_compile_options(webp_toolkit PRIVATE -Wall -Wextra -Wpedantic)
add_executable(webptool src/main.cpp)
target_link_libraries(webptool PRIVATE webp_toolkit)
add_executable(webp_tests tests/tests.cpp)
target_link_libraries(webp_tests PRIVATE webp_toolkit)
Una nota prima di cominciare: nel settembre 2023 la vulnerabilità CVE-2023-4863, un heap overflow nella decodifica senza perdita sfruttato attivamente, ha colpito libwebp e, a cascata, browser e applicazioni di tutto il mondo. La correzione è arrivata con la versione 1.3.2. Se l'applicazione collega libwebp staticamente, aggiornare il pacchetto di sistema non basta: bisogna ricompilare. Stampare la versione all'avvio, come faremo nel programma principale, aiuta a sapere sempre cosa gira in produzione.
Il formato e un parser dell'intestazione
Un file WebP è un contenitore RIFF: quattro byte RIFF, la dimensione del resto del file come intero a 32 bit little-endian, quattro byte WEBP e una sequenza di chunk, ciascuno con un identificatore di quattro caratteri, una dimensione e il contenuto. Il primo chunk identifica la variante: VP8 , con lo spazio, per la compressione con perdita senza alfa; VP8L per quella senza perdita; VP8X per il formato esteso, che serve per l'alfa con perdita, i profili ICC, i metadati EXIF e XMP e le animazioni.
libwebp offre WebPGetFeatures() per leggere le caratteristiche principali, ma scrivere il parser a mano è istruttivo e ci dà accesso anche ai flag dei metadati. Partiamo dai tipi comuni, raccolti in un header.
// include/webp_toolkit/types.hpp
#pragma once
#include <cstdint>
#include <expected>
#include <string>
#include <vector>
namespace webp_toolkit {
// Immagine RGBA a 8 bit per canale, con le righe contigue
struct Image {
int width = 0;
int height = 0;
std::vector<std::uint8_t> rgba;
[[nodiscard]] int stride() const { return width * 4; }
};
using Bytes = std::vector<std::uint8_t>;
template <typename T>
using Result = std::expected<T, std::string>;
} // namespace webp_toolkit
// include/webp_toolkit/webp_info.hpp
#pragma once
#include <cstdint>
#include <optional>
#include <span>
#include <string_view>
namespace webp_toolkit {
enum class WebpFormat { Lossy, Lossless, Extended };
struct WebpInfo {
WebpFormat format;
int width;
int height;
bool alpha = false;
bool animated = false;
bool icc = false;
bool exif = false;
bool xmp = false;
};
// Legge solo i primi 30 byte: nessuna decodifica dei pixel
std::optional<WebpInfo> parse_webp_info(std::span<const std::uint8_t> data);
std::string_view to_string(WebpFormat format);
} // namespace webp_toolkit
// src/webp_info.cpp
#include "webp_toolkit/webp_info.hpp"
#include <cstring>
namespace webp_toolkit {
namespace {
constexpr std::uint8_t flag_icc = 0x20;
constexpr std::uint8_t flag_alpha = 0x10;
constexpr std::uint8_t flag_exif = 0x08;
constexpr std::uint8_t flag_xmp = 0x04;
constexpr std::uint8_t flag_animation = 0x02;
// Letture little-endian indipendenti dall'architettura e dall'allineamento
std::uint32_t le16(std::span<const std::uint8_t> d, std::size_t at) {
return d[at] | d[at + 1] << 8;
}
std::uint32_t le24(std::span<const std::uint8_t> d, std::size_t at) {
return d[at] | d[at + 1] << 8 | d[at + 2] << 16;
}
std::uint32_t le32(std::span<const std::uint8_t> d, std::size_t at) {
return le24(d, at) | static_cast<std::uint32_t>(d[at + 3]) << 24;
}
bool tag_equals(std::span<const std::uint8_t> d, std::size_t at, const char* tag) {
return std::memcmp(d.data() + at, tag, 4) == 0;
}
} // namespace
std::optional<WebpInfo> parse_webp_info(std::span<const std::uint8_t> d) {
if (d.size() < 30 || !tag_equals(d, 0, "RIFF") || !tag_equals(d, 8, "WEBP")) {
return std::nullopt;
}
if (tag_equals(d, 12, "VP8 ")) {
// Codice di sincronizzazione del fotogramma chiave
if (d[23] != 0x9d || d[24] != 0x01 || d[25] != 0x2a) {
return std::nullopt;
}
return WebpInfo{.format = WebpFormat::Lossy,
.width = static_cast<int>(le16(d, 26) & 0x3fff),
.height = static_cast<int>(le16(d, 28) & 0x3fff)};
}
if (tag_equals(d, 12, "VP8L")) {
if (d[20] != 0x2f) {
return std::nullopt;
}
const std::uint32_t bits = le32(d, 21);
return WebpInfo{.format = WebpFormat::Lossless,
.width = static_cast<int>(bits & 0x3fff) + 1,
.height = static_cast<int>((bits >> 14) & 0x3fff) + 1,
.alpha = ((bits >> 28) & 0x1) != 0};
}
if (tag_equals(d, 12, "VP8X")) {
const std::uint8_t flags = d[20];
return WebpInfo{.format = WebpFormat::Extended,
.width = static_cast<int>(le24(d, 24)) + 1,
.height = static_cast<int>(le24(d, 27)) + 1,
.alpha = (flags & flag_alpha) != 0,
.animated = (flags & flag_animation) != 0,
.icc = (flags & flag_icc) != 0,
.exif = (flags & flag_exif) != 0,
.xmp = (flags & flag_xmp) != 0};
}
return std::nullopt;
}
std::string_view to_string(WebpFormat format) {
switch (format) {
case WebpFormat::Lossy: return "lossy";
case WebpFormat::Lossless: return "lossless";
case WebpFormat::Extended: return "extended";
}
return "unknown";
}
} // namespace webp_toolkit
Il parser compone gli interi byte per byte invece di copiare la memoria in un uint32_t: il risultato è corretto su qualsiasi architettura, indipendentemente dall'ordine dei byte della CPU, e non dipende dall'allineamento. std::span rende esplicito che la funzione osserva i dati senza possederli, e accetta indifferentemente un std::vector, un array o un buffer mappato in memoria. Gli inizializzatori designati, standard da C++20, rendono leggibile la costruzione delle strutture.
RAII attorno all'API C
Le risorse di libwebp seguono schemi diversi: i buffer restituiti dalle funzioni di decodifica vanno liberati con WebPFree(), una WebPPicture con WebPPictureFree(), un WebPMemoryWriter con WebPMemoryWriterClear(), e così via. Dimenticarne uno su un percorso di errore significa una perdita di memoria. Il rimedio classico del C++ è affidare ogni risorsa a un oggetto il cui distruttore la rilascia.
// include/webp_toolkit/raii.hpp
#pragma once
#include <memory>
#include <stdexcept>
#include <webp/decode.h>
#include <webp/encode.h>
namespace webp_toolkit::detail {
// Buffer allocati da libwebp: si liberano con WebPFree
struct WebpDeleter {
void operator()(void* p) const noexcept { WebPFree(p); }
};
template <typename T>
using WebpPtr = std::unique_ptr<T, WebpDeleter>;
class Picture {
public:
Picture() {
// L'inizializzazione verifica anche la compatibilità ABI dell'header con la libreria
if (!WebPPictureInit(&picture_)) {
throw std::runtime_error("libwebp: versione incompatibile");
}
}
~Picture() { WebPPictureFree(&picture_); }
Picture(const Picture&) = delete;
Picture& operator=(const Picture&) = delete;
WebPPicture* get() noexcept { return &picture_; }
WebPPicture* operator->() noexcept { return &picture_; }
private:
WebPPicture picture_{};
};
class MemoryWriter {
public:
MemoryWriter() { WebPMemoryWriterInit(&writer_); }
~MemoryWriter() { WebPMemoryWriterClear(&writer_); }
MemoryWriter(const MemoryWriter&) = delete;
MemoryWriter& operator=(const MemoryWriter&) = delete;
// Collega il writer alla picture: l'encoder vi accoderà i byte prodotti
void attach(WebPPicture* picture) noexcept {
picture->writer = WebPMemoryWrite;
picture->custom_ptr = &writer_;
}
[[nodiscard]] const std::uint8_t* data() const noexcept { return writer_.mem; }
[[nodiscard]] std::size_t size() const noexcept { return writer_.size; }
private:
WebPMemoryWriter writer_{};
};
} // namespace webp_toolkit::detail
Il deleter di std::unique_ptr è una struttura senza stato, quindi il puntatore intelligente occupa esattamente lo spazio di un puntatore grezzo. Le classi Picture e MemoryWriter vietano la copia: una copia superficiale della struttura C porterebbe a una doppia liberazione della memoria.
Codifica con l'API avanzata
libwebp offre un'API semplice, con funzioni come WebPEncodeRGBA() e WebPEncodeLosslessRGBA(), comoda ma limitata alla qualità. L'API avanzata ruota attorno a due strutture: WebPConfig, che contiene tutti i parametri dell'encoder, e WebPPicture, che contiene l'immagine da codificare. I parametri principali di WebPConfig sono questi:
lossless: 0 per la compressione con perdita, 1 per quella senza perdita;quality, da 0 a 100: la qualità visiva nella modalità con perdita, lo sforzo di compressione in quella senza perdita;method, da 0 a 6: il compromesso tra velocità e dimensione del file;alpha_quality, da 0 a 100: la qualità del canale alfa nella modalità con perdita;exact: conserva i valori RGB dei pixel trasparenti, che altrimenti l'encoder modifica per comprimere meglio;use_sharp_yuv: una conversione RGB verso YUV più lenta ma più fedele sui bordi tra colori saturi;near_lossless, da 0 a 100: con la compressione senza perdita attiva una preelaborazione che altera leggermente i pixel; 100 la disattiva;thread_level: permette all'encoder di usare più thread.
La funzione WebPConfigPreset() inizializza la configurazione con valori adatti al tipo di contenuto (foto, disegno, icona, testo), mentre WebPConfigLosslessPreset() imposta in un colpo solo method e quality per la modalità senza perdita, con un livello da 0 a 9.
// include/webp_toolkit/codec.hpp
#pragma once
#include <span>
#include "webp_toolkit/types.hpp"
namespace webp_toolkit {
struct EncodeOptions {
float quality = 80.0f;
int method = 4;
bool lossless = false;
int lossless_level = 6;
int alpha_quality = 100;
int near_lossless = 100;
bool exact = false;
bool sharp_yuv = false;
// Se diversi da zero, l'immagine viene ridimensionata prima della codifica
int resize_width = 0;
int resize_height = 0;
};
Result<Bytes> encode(const Image& image, const EncodeOptions& options = {});
struct DecodeOptions {
// Larghezza desiderata: il decoder ridimensiona durante la decodifica
int target_width = 0;
long long max_pixels = 40'000'000;
};
Result<Image> decode(std::span<const std::uint8_t> data, const DecodeOptions& options = {});
std::string library_version();
} // namespace webp_toolkit
// src/codec.cpp
#include "webp_toolkit/codec.hpp"
#include <format>
#include "webp_toolkit/raii.hpp"
namespace webp_toolkit {
namespace {
std::string encoding_error(WebPEncodingError code) {
switch (code) {
case VP8_ENC_ERROR_OUT_OF_MEMORY: return "memoria esaurita";
case VP8_ENC_ERROR_BAD_DIMENSION: return "dimensioni non valide";
case VP8_ENC_ERROR_PARTITION0_OVERFLOW: return "partizione troppo grande, ridurre la qualità";
case VP8_ENC_ERROR_FILE_TOO_BIG: return "file oltre i 4 GB";
default: return std::format("errore di codifica {}", static_cast<int>(code));
}
}
} // namespace
Result<Bytes> encode(const Image& image, const EncodeOptions& options) {
if (image.width <= 0 || image.height <= 0 || image.width > WEBP_MAX_DIMENSION ||
image.height > WEBP_MAX_DIMENSION || image.rgba.size() != static_cast<std::size_t>(image.stride()) * image.height) {
return std::unexpected("immagine non valida");
}
WebPConfig config;
if (!WebPConfigPreset(&config, WEBP_PRESET_DEFAULT, options.quality)) {
return std::unexpected("libwebp: versione incompatibile");
}
config.method = options.method;
config.alpha_quality = options.alpha_quality;
config.exact = options.exact ? 1 : 0;
config.use_sharp_yuv = options.sharp_yuv ? 1 : 0;
config.thread_level = 1;
if (options.lossless) {
WebPConfigLosslessPreset(&config, options.lossless_level);
config.near_lossless = options.near_lossless;
}
if (!WebPValidateConfig(&config)) {
return std::unexpected("parametri dell'encoder non validi");
}
detail::Picture picture;
picture->width = image.width;
picture->height = image.height;
// La modalità senza perdita lavora in ARGB, quella con perdita in YUV
picture->use_argb = options.lossless ? 1 : 0;
if (!WebPPictureImportRGBA(picture.get(), image.rgba.data(), image.stride())) {
return std::unexpected(encoding_error(picture->error_code));
}
if (options.resize_width > 0 || options.resize_height > 0) {
// Un valore zero mantiene le proporzioni
if (!WebPPictureRescale(picture.get(), options.resize_width, options.resize_height)) {
return std::unexpected("ridimensionamento non riuscito");
}
}
detail::MemoryWriter writer;
writer.attach(picture.get());
if (!WebPEncode(&config, picture.get())) {
return std::unexpected(encoding_error(picture->error_code));
}
return Bytes(writer.data(), writer.data() + writer.size());
}
Result<Image> decode(std::span<const std::uint8_t> data, const DecodeOptions& options) {
WebPDecoderConfig config;
if (!WebPInitDecoderConfig(&config)) {
return std::unexpected("libwebp: versione incompatibile");
}
if (WebPGetFeatures(data.data(), data.size(), &config.input) != VP8_STATUS_OK) {
return std::unexpected("intestazione WebP non valida");
}
const auto& features = config.input;
if (features.has_animation) {
return std::unexpected("le animazioni richiedono WebPAnimDecoder");
}
// Il controllo avviene prima di allocare il buffer dei pixel
if (static_cast<long long>(features.width) * features.height > options.max_pixels) {
return std::unexpected(std::format("dimensioni eccessive: {}x{}", features.width, features.height));
}
Image image;
image.width = features.width;
image.height = features.height;
if (options.target_width > 0 && options.target_width < features.width) {
config.options.use_scaling = 1;
config.options.scaled_width = options.target_width;
config.options.scaled_height = static_cast<int>(
static_cast<long long>(features.height) * options.target_width / features.width);
image.width = config.options.scaled_width;
image.height = config.options.scaled_height;
}
config.options.use_threads = 1;
// Il decoder scrive direttamente nel buffer gestito dal vector
image.rgba.resize(static_cast<std::size_t>(image.stride()) * image.height);
config.output.colorspace = MODE_RGBA;
config.output.is_external_memory = 1;
config.output.u.RGBA.rgba = image.rgba.data();
config.output.u.RGBA.stride = image.stride();
config.output.u.RGBA.size = image.rgba.size();
const VP8StatusCode status = WebPDecode(data.data(), data.size(), &config);
WebPFreeDecBuffer(&config.output);
if (status != VP8_STATUS_OK) {
return std::unexpected(std::format("decodifica fallita, stato {}", static_cast<int>(status)));
}
return image;
}
std::string library_version() {
const int v = WebPGetEncoderVersion();
return std::format("{}.{}.{}", (v >> 16) & 0xff, (v >> 8) & 0xff, v & 0xff);
}
} // namespace webp_toolkit
Alcuni dettagli meritano attenzione. WebPConfigPreset(), WebPPictureInit() e WebPInitDecoderConfig() non si limitano ad azzerare le strutture: confrontano la versione ABI dell'header con cui il programma è stato compilato con quella della libreria caricata, e falliscono se sono incompatibili. Ignorarne il valore di ritorno significa rischiare un comportamento indefinito quando la libreria di sistema viene aggiornata.
Il ridimensionamento con WebPPictureRescale() avviene all'interno di libwebp e rende superflua una libreria esterna per generare le varianti. Simmetricamente, in decodifica le opzioni use_scaling, scaled_width e scaled_height chiedono al decoder di produrre direttamente un'immagine ridotta: per le miniature è molto più efficiente che decodificare a piena risoluzione e poi ridimensionare, perché il buffer allocato ha già le dimensioni finali. Con is_external_memory il decoder scrive nel nostro std::vector, e WebPFreeDecBuffer() in quel caso non libera nulla di nostro: chiamarla resta comunque corretto e rende il codice robusto a modifiche future.
Leggere e scrivere PNG
Per avere immagini da convertire ci serve un decoder per i formati tradizionali. libpng offre una simplified API, introdotta con la versione 1.6, che riduce la lettura e la scrittura di un PNG a poche chiamate, con la conversione automatica in RGBA a 8 bit qualunque sia il formato del file: tavolozza, scala di grigi, 16 bit per canale.
// include/webp_toolkit/png_io.hpp
#pragma once
#include <filesystem>
#include "webp_toolkit/types.hpp"
namespace webp_toolkit {
Result<Image> read_png(const std::filesystem::path& path, long long max_pixels = 40'000'000);
Result<void> write_png(const Image& image, const std::filesystem::path& path);
} // namespace webp_toolkit
// src/png_io.cpp
#include "webp_toolkit/png_io.hpp"
#include <format>
#include <png.h>
namespace webp_toolkit {
Result<Image> read_png(const std::filesystem::path& path, long long max_pixels) {
png_image png{};
png.version = PNG_IMAGE_VERSION;
if (!png_image_begin_read_from_file(&png, path.c_str())) {
return std::unexpected(std::format("PNG non leggibile: {}", png.message));
}
// Dimensioni note dall'intestazione: controllo prima di allocare
if (static_cast<long long>(png.width) * png.height > max_pixels) {
png_image_free(&png);
return std::unexpected("PNG troppo grande");
}
png.format = PNG_FORMAT_RGBA;
Image image;
image.width = static_cast<int>(png.width);
image.height = static_cast<int>(png.height);
image.rgba.resize(PNG_IMAGE_SIZE(png));
if (!png_image_finish_read(&png, nullptr, image.rgba.data(), 0, nullptr)) {
png_image_free(&png);
return std::unexpected(std::format("decodifica PNG fallita: {}", png.message));
}
return image;
}
Result<void> write_png(const Image& image, const std::filesystem::path& path) {
png_image png{};
png.version = PNG_IMAGE_VERSION;
png.width = static_cast<png_uint_32>(image.width);
png.height = static_cast<png_uint_32>(image.height);
png.format = PNG_FORMAT_RGBA;
if (!png_image_write_to_file(&png, path.c_str(), 0, image.rgba.data(), 0, nullptr)) {
return std::unexpected(std::format("scrittura PNG fallita: {}", png.message));
}
return {};
}
} // namespace webp_toolkit
Per i JPEG il discorso è analogo: l'API TurboJPEG di libjpeg-turbo offre funzioni di alto livello per decodificare in RGBA. Chi preferisce una soluzione senza dipendenze di sistema può usare stb_image, una libreria contenuta in un singolo header che legge JPEG, PNG, GIF e BMP con la funzione stbi_load(). In tutti i casi, il risultato è un buffer RGBA che si copia nella nostra struttura Image.
Metadati con libwebpmux
L'encoder produce un flusso che contiene solo l'immagine: niente profilo colore, niente EXIF. Per aggiungerli, o per toglierli da un file esistente, si usa WebPMux, che lavora sul contenitore senza ricodificare i pixel. È lo strumento giusto per due operazioni frequenti: incorporare il profilo ICC di una foto in uno spazio colore ampio, senza il quale i colori apparirebbero spenti, e rimuovere i dati EXIF prima della pubblicazione, perché le foto degli smartphone contengono spesso coordinate GPS e modello del dispositivo.
// include/webp_toolkit/metadata.hpp
#pragma once
#include <optional>
#include <span>
#include "webp_toolkit/types.hpp"
namespace webp_toolkit {
// Restituisce un nuovo file con il profilo ICC impostato
Result<Bytes> set_icc_profile(std::span<const std::uint8_t> webp, std::span<const std::uint8_t> icc);
// Rimuove EXIF e XMP lasciando intatti i pixel e il profilo colore
Result<Bytes> strip_private_metadata(std::span<const std::uint8_t> webp);
std::optional<Bytes> get_chunk(std::span<const std::uint8_t> webp, const char fourcc[5]);
} // namespace webp_toolkit
// src/metadata.cpp
#include "webp_toolkit/metadata.hpp"
#include <memory>
#include <webp/mux.h>
namespace webp_toolkit {
namespace {
struct MuxDeleter {
void operator()(WebPMux* mux) const noexcept { WebPMuxDelete(mux); }
};
using MuxPtr = std::unique_ptr<WebPMux, MuxDeleter>;
MuxPtr open_mux(std::span<const std::uint8_t> webp) {
const WebPData data{webp.data(), webp.size()};
// copy_data = 0: il mux fa riferimento ai nostri byte senza copiarli
return MuxPtr(WebPMuxCreate(&data, 0));
}
Result<Bytes> assemble(WebPMux* mux) {
WebPData output;
WebPDataInit(&output);
if (WebPMuxAssemble(mux, &output) != WEBP_MUX_OK) {
return std::unexpected("assemblaggio del contenitore fallito");
}
Bytes result(output.bytes, output.bytes + output.size);
WebPDataClear(&output);
return result;
}
} // namespace
Result<Bytes> set_icc_profile(std::span<const std::uint8_t> webp, std::span<const std::uint8_t> icc) {
MuxPtr mux = open_mux(webp);
if (!mux) {
return std::unexpected("contenitore WebP non valido");
}
const WebPData chunk{icc.data(), icc.size()};
// copy_data = 1: il profilo viene copiato e il chiamante resta proprietario dei suoi byte
if (WebPMuxSetChunk(mux.get(), "ICCP", &chunk, 1) != WEBP_MUX_OK) {
return std::unexpected("impossibile impostare il profilo ICC");
}
return assemble(mux.get());
}
Result<Bytes> strip_private_metadata(std::span<const std::uint8_t> webp) {
MuxPtr mux = open_mux(webp);
if (!mux) {
return std::unexpected("contenitore WebP non valido");
}
// WEBP_MUX_NOT_FOUND non è un errore: il chunk semplicemente non c'era
for (const char* fourcc : {"EXIF", "XMP "}) {
const WebPMuxError error = WebPMuxDeleteChunk(mux.get(), fourcc);
if (error != WEBP_MUX_OK && error != WEBP_MUX_NOT_FOUND) {
return std::unexpected("rimozione dei metadati fallita");
}
}
return assemble(mux.get());
}
std::optional<Bytes> get_chunk(std::span<const std::uint8_t> webp, const char fourcc[5]) {
MuxPtr mux = open_mux(webp);
WebPData chunk;
if (!mux || WebPMuxGetChunk(mux.get(), fourcc, &chunk) != WEBP_MUX_OK) {
return std::nullopt;
}
// Il chunk punta alla memoria del file: va copiato prima di distruggere il mux
return Bytes(chunk.bytes, chunk.bytes + chunk.size);
}
} // namespace webp_toolkit
L'argomento copy_data è il dettaglio su cui si sbaglia più spesso con libwebpmux. Con il valore 0 il mux non copia i dati ma li referenzia: è efficiente, ma i byte originali devono restare validi finché il mux esiste. Con il valore 1 il mux fa una copia privata. Nel codice qui sopra il file sorgente sopravvive sempre al mux, mentre per il profilo ICC scegliamo la copia, così la funzione non impone vincoli di durata al chiamante. Quando si aggiunge un chunk ICC, WebPMuxAssemble() converte automaticamente il file nel formato esteso VP8X e imposta il flag corrispondente.
Animazioni
Per creare un WebP animato si usa WebPAnimEncoder: si aggiunge un fotogramma alla volta con il suo istante di inizio in millisecondi, poi un'ultima chiamata con picture nulla indica la fine dell'animazione e quindi la durata dell'ultimo fotogramma. L'encoder confronta ogni fotogramma con il precedente e codifica solo i rettangoli che cambiano, scegliendo per ciascuno la modalità più compatta se allow_mixed è attivo. Per leggere un'animazione si usa WebPAnimDecoder, che restituisce ogni fotogramma già composto sulla tela, pronto per essere mostrato.
// include/webp_toolkit/animation.hpp
#pragma once
#include <span>
#include "webp_toolkit/codec.hpp"
namespace webp_toolkit {
struct Frame {
Image image;
int duration_ms = 100;
};
struct Animation {
int width = 0;
int height = 0;
int loop_count = 0;
std::vector<Frame> frames{};
};
Result<Bytes> encode_animation(const Animation& animation, const EncodeOptions& options = {});
Result<Animation> decode_animation(std::span<const std::uint8_t> data, int max_frames = 500);
} // namespace webp_toolkit
// src/animation.cpp
#include "webp_toolkit/animation.hpp"
#include <cstring>
#include <format>
#include <memory>
#include <webp/demux.h>
#include <webp/mux.h>
#include "webp_toolkit/raii.hpp"
namespace webp_toolkit {
namespace {
struct EncoderDeleter {
void operator()(WebPAnimEncoder* e) const noexcept { WebPAnimEncoderDelete(e); }
};
struct DecoderDeleter {
void operator()(WebPAnimDecoder* d) const noexcept { WebPAnimDecoderDelete(d); }
};
} // namespace
Result<Bytes> encode_animation(const Animation& animation, const EncodeOptions& options) {
if (animation.frames.empty()) {
return std::unexpected("animazione senza fotogrammi");
}
WebPAnimEncoderOptions anim_options;
if (!WebPAnimEncoderOptionsInit(&anim_options)) {
return std::unexpected("libwebpmux: versione incompatibile");
}
anim_options.anim_params.loop_count = animation.loop_count;
// Fotogrammi con e senza perdita nella stessa animazione
anim_options.allow_mixed = options.lossless ? 0 : 1;
std::unique_ptr<WebPAnimEncoder, EncoderDeleter> encoder(
WebPAnimEncoderNew(animation.width, animation.height, &anim_options));
if (!encoder) {
return std::unexpected("creazione dell'encoder fallita");
}
WebPConfig config;
WebPConfigPreset(&config, WEBP_PRESET_DEFAULT, options.quality);
config.method = options.method;
config.lossless = options.lossless ? 1 : 0;
int timestamp = 0;
for (const Frame& frame : animation.frames) {
if (frame.image.width != animation.width || frame.image.height != animation.height) {
return std::unexpected("tutti i fotogrammi devono avere le dimensioni della tela");
}
detail::Picture picture;
picture->width = frame.image.width;
picture->height = frame.image.height;
picture->use_argb = 1;
if (!WebPPictureImportRGBA(picture.get(), frame.image.rgba.data(), frame.image.stride()) ||
!WebPAnimEncoderAdd(encoder.get(), picture.get(), timestamp, &config)) {
return std::unexpected(std::format("fotogramma rifiutato: {}", WebPAnimEncoderGetError(encoder.get())));
}
timestamp += frame.duration_ms;
}
// La chiamata finale con picture nulla fissa la durata dell'ultimo fotogramma
WebPAnimEncoderAdd(encoder.get(), nullptr, timestamp, nullptr);
WebPData output;
WebPDataInit(&output);
if (!WebPAnimEncoderAssemble(encoder.get(), &output)) {
return std::unexpected(std::format("assemblaggio fallito: {}", WebPAnimEncoderGetError(encoder.get())));
}
Bytes result(output.bytes, output.bytes + output.size);
WebPDataClear(&output);
return result;
}
Result<Animation> decode_animation(std::span<const std::uint8_t> data, int max_frames) {
WebPAnimDecoderOptions decoder_options;
if (!WebPAnimDecoderOptionsInit(&decoder_options)) {
return std::unexpected("libwebpdemux: versione incompatibile");
}
decoder_options.color_mode = MODE_RGBA;
decoder_options.use_threads = 1;
const WebPData webp_data{data.data(), data.size()};
std::unique_ptr<WebPAnimDecoder, DecoderDeleter> decoder(WebPAnimDecoderNew(&webp_data, &decoder_options));
if (!decoder) {
return std::unexpected("animazione non valida");
}
WebPAnimInfo info;
if (!WebPAnimDecoderGetInfo(decoder.get(), &info)) {
return std::unexpected("informazioni sull'animazione non disponibili");
}
if (static_cast<int>(info.frame_count) > max_frames) {
return std::unexpected(std::format("troppi fotogrammi: {}", info.frame_count));
}
Animation animation{.width = static_cast<int>(info.canvas_width),
.height = static_cast<int>(info.canvas_height),
.loop_count = static_cast<int>(info.loop_count)};
const std::size_t frame_size = static_cast<std::size_t>(animation.width) * animation.height * 4;
int previous = 0;
while (WebPAnimDecoderHasMoreFrames(decoder.get())) {
std::uint8_t* pixels = nullptr;
int timestamp = 0;
if (!WebPAnimDecoderGetNext(decoder.get(), &pixels, ×tamp)) {
return std::unexpected("decodifica del fotogramma fallita");
}
// Il buffer appartiene al decoder e viene riusato: va copiato subito
Frame frame{.image = {animation.width, animation.height, Bytes(pixels, pixels + frame_size)},
.duration_ms = timestamp - previous};
animation.frames.push_back(std::move(frame));
previous = timestamp;
}
return animation;
}
} // namespace webp_toolkit
Il decoder restituisce timestamp cumulativi, cioè l'istante in cui termina ciascun fotogramma, quindi la durata si ottiene per differenza. Il buffer di pixel restituito da WebPAnimDecoderGetNext() appartiene al decoder e viene sovrascritto alla chiamata successiva: copiarlo subito è obbligatorio. Il limite sul numero di fotogrammi va controllato prima del ciclo, perché ogni fotogramma decodificato occupa l'intera tela in memoria.
Il programma principale e la conversione parallela
Mettiamo insieme i pezzi in uno strumento a riga di comando con tre sottocomandi: info per ispezionare un file, convert per convertire un PNG con varianti di larghezza, batch per convertire in parallelo un'intera cartella. Per il parallelismo usiamo std::jthread, che si unisce automaticamente nel distruttore, e un indice atomico condiviso da cui ogni worker preleva il file successivo.
// src/main.cpp
#include <algorithm>
#include <atomic>
#include <filesystem>
#include <format>
#include <fstream>
#include <iostream>
#include <mutex>
#include <string_view>
#include <thread>
#include <vector>
#include "webp_toolkit/codec.hpp"
#include "webp_toolkit/png_io.hpp"
#include "webp_toolkit/webp_info.hpp"
namespace fs = std::filesystem;
using namespace webp_toolkit;
namespace {
Bytes read_file(const fs::path& path) {
std::ifstream in(path, std::ios::binary);
return Bytes(std::istreambuf_iterator<char>(in), {});
}
// Scrittura su file temporaneo e rinomina: nessun lettore vede un file incompleto
void write_file_atomic(const fs::path& path, const Bytes& data) {
fs::path temporary = path;
temporary += ".tmp";
{
std::ofstream out(temporary, std::ios::binary | std::ios::trunc);
out.write(reinterpret_cast<const char*>(data.data()), static_cast<std::streamsize>(data.size()));
if (!out) {
throw std::runtime_error("scrittura fallita: " + temporary.string());
}
}
fs::rename(temporary, path);
}
// Stima dei colori distinti su un campione: le grafiche piatte ne hanno pochi
bool is_flat_graphic(const Image& image, std::size_t max_colors = 256) {
const int step = std::max(1, std::min(image.width, image.height) / 128);
std::vector<std::uint32_t> colors;
for (int y = 0; y < image.height; y += step) {
for (int x = 0; x < image.width; x += step) {
const auto* p = &image.rgba[(static_cast<std::size_t>(y) * image.width + x) * 4];
const std::uint32_t c = p[0] | p[1] << 8 | p[2] << 16 | static_cast<std::uint32_t>(p[3]) << 24;
if (std::ranges::find(colors, c) == colors.end()) {
colors.push_back(c);
if (colors.size() > max_colors) {
return false;
}
}
}
}
return true;
}
EncodeOptions options_for(const Image& image) {
if (is_flat_graphic(image)) {
return {.quality = 100.0f, .lossless = true, .lossless_level = 9};
}
return {.quality = 80.0f, .method = 5, .alpha_quality = 90, .sharp_yuv = true};
}
int command_info(const fs::path& path) {
const Bytes data = read_file(path);
const auto info = parse_webp_info(data);
if (!info) {
std::cerr << std::format("{}: non è un file WebP", path.string()) << '\n';
return 1;
}
std::cout << std::format("{}: {} {}x{} alpha={} animated={} icc={} exif={} xmp={}\n", path.string(),
to_string(info->format), info->width, info->height, info->alpha,
info->animated, info->icc, info->exif, info->xmp);
return 0;
}
int command_convert(const fs::path& source, const fs::path& output_dir) {
auto image = read_png(source);
if (!image) {
std::cerr << std::format("{}", image.error()) << '\n';
return 1;
}
fs::create_directories(output_dir);
const EncodeOptions base = options_for(*image);
for (const int width : {320, 640, 960, 1280, 1920, 0}) {
// Zero indica la larghezza originale
if (width > image->width) {
continue;
}
EncodeOptions options = base;
options.resize_width = width;
auto encoded = encode(*image, options);
if (!encoded) {
std::cerr << std::format("{}", encoded.error()) << '\n';
return 1;
}
const std::string suffix = width == 0 ? "" : "-" + std::to_string(width);
const fs::path target = output_dir / (source.stem().string() + suffix + ".webp");
write_file_atomic(target, *encoded);
std::cout << std::format("{} ({} byte)", target.string(), encoded->size()) << '\n';
}
return 0;
}
int command_batch(const fs::path& source_dir, const fs::path& target_dir) {
std::vector<fs::path> files;
for (const auto& entry : fs::recursive_directory_iterator(source_dir)) {
if (entry.is_regular_file() && entry.path().extension() == ".png") {
files.push_back(entry.path());
}
}
std::atomic<std::size_t> next{0};
std::atomic<int> failed{0};
std::mutex output_mutex;
const unsigned workers = std::max(1u, std::thread::hardware_concurrency());
{
std::vector<std::jthread> pool;
for (unsigned i = 0; i < workers; ++i) {
pool.emplace_back([&] {
// Ogni worker preleva l'indice successivo finché ci sono file
for (std::size_t index = next++; index < files.size(); index = next++) {
const fs::path& source = files[index];
fs::path target = target_dir / fs::relative(source, source_dir);
target.replace_extension(".webp");
auto result = read_png(source).and_then([](const Image& image) {
return encode(image, options_for(image));
});
std::scoped_lock lock(output_mutex);
if (!result) {
++failed;
std::cerr << std::format("{}: {}", source.string(), result.error()) << '\n';
continue;
}
fs::create_directories(target.parent_path());
write_file_atomic(target, *result);
std::cout << std::format("{} -> {} byte", source.string(), result->size()) << '\n';
}
});
}
} // i jthread si uniscono qui
std::cout << std::format("Convertiti {} file, falliti {}", files.size() - failed, failed.load()) << '\n';
return failed > 0 ? 1 : 0;
}
} // namespace
int main(int argc, char** argv) {
const std::vector<std::string_view> args(argv + 1, argv + argc);
std::cerr << std::format("libwebp {}", library_version()) << '\n';
try {
if (args.size() == 2 && args[0] == "info") {
return command_info(args[1]);
}
if (args.size() == 3 && args[0] == "convert") {
return command_convert(args[1], args[2]);
}
if (args.size() == 3 && args[0] == "batch") {
return command_batch(args[1], args[2]);
}
} catch (const std::exception& error) {
std::cerr << std::format("Errore: {}", error.what()) << '\n';
return 1;
}
std::cerr << std::format("Uso: webptool info <file> | convert <png> <dir> | batch <src> <dst>") << '\n';
return 2;
}
Il metodo and_then di std::expected concatena lettura e codifica: se la lettura fallisce, l'errore attraversa la catena senza che la codifica venga tentata, senza un solo if intermedio. Il mutex protegge sia l'output sulla console sia la creazione delle cartelle, operazioni rapide rispetto alla codifica, che resta pienamente parallela. Per l'output usiamo std::format, disponibile da C++20 in tutti i compilatori principali; con GCC 14 o Clang 18 si può passare a std::println di C++23.
Sicurezza
Un decoder di immagini scritto in C che elabora file non fidati è, per definizione, superficie di attacco. La vulnerabilità del 2023 lo ha dimostrato su scala mondiale. Oltre a mantenere libwebp aggiornata, le contromisure a livello applicativo sono quelle che abbiamo già incontrato: controllare le dimensioni con WebPGetFeatures() prima di allocare, limitare il numero di fotogrammi delle animazioni, non fidarsi delle estensioni ma dei byte iniziali. A queste si aggiungono pratiche specifiche del C++: compilare e testare con gli sanitizer (-fsanitize=address,undefined) e sottoporre le funzioni che analizzano input esterni, come il nostro parser, a fuzzing con libFuzzer. Un harness minimo è questo:
// fuzz/fuzz_webp_info.cpp
#include <cstddef>
#include <cstdint>
#include <span>
#include "webp_toolkit/codec.hpp"
#include "webp_toolkit/webp_info.hpp"
// Compilare con: clang++ -std=c++23 -fsanitize=fuzzer,address ...
extern "C" int LLVMFuzzerTestOneInput(const std::uint8_t* data, std::size_t size) {
const std::span<const std::uint8_t> input(data, size);
(void)webp_toolkit::parse_webp_info(input);
// Limite basso per evitare che il fuzzer misuri solo l'allocazione di memoria
(void)webp_toolkit::decode(input, {.target_width = 0, .max_pixels = 4'000'000});
return 0;
}
Per i servizi che elaborano caricamenti degli utenti, infine, isolare la decodifica in un processo separato con risorse limitate, per esempio tramite setrlimit o un container dedicato, fa sì che un eventuale crash o un'esplosione di memoria non coinvolgano il processo principale.
Test
I test generano immagini sintetiche, le codificano in tutte le varianti e verificano parser, decodifica con ridimensionamento, metadati e animazioni. Per brevità usiamo semplici asserzioni; in un progetto reale lo stesso codice si inserisce senza modifiche in Catch2 o GoogleTest.
// tests/tests.cpp
#include <cassert>
#include <iostream>
#include "webp_toolkit/animation.hpp"
#include "webp_toolkit/codec.hpp"
#include "webp_toolkit/metadata.hpp"
#include "webp_toolkit/webp_info.hpp"
using namespace webp_toolkit;
namespace {
Image solid(int width, int height, std::uint8_t alpha, std::uint8_t red = 200) {
Image image{width, height, Bytes(static_cast<std::size_t>(width) * height * 4)};
for (std::size_t i = 0; i < image.rgba.size(); i += 4) {
image.rgba[i] = red;
image.rgba[i + 1] = 30;
image.rgba[i + 2] = 60;
image.rgba[i + 3] = alpha;
}
return image;
}
} // namespace
int main() {
const auto lossy = encode(solid(123, 45, 255)).value();
auto info = parse_webp_info(lossy).value();
assert(info.format == WebpFormat::Lossy && info.width == 123 && info.height == 45 && !info.alpha);
const auto lossless = encode(solid(123, 45, 128), {.lossless = true}).value();
info = parse_webp_info(lossless).value();
assert(info.format == WebpFormat::Lossless && info.alpha);
const auto lossy_alpha = encode(solid(123, 45, 128)).value();
assert(parse_webp_info(lossy_alpha)->format == WebpFormat::Extended);
// Il ridimensionamento in codifica mantiene le proporzioni
const auto resized = encode(solid(400, 200, 255), {.resize_width = 100}).value();
assert(parse_webp_info(resized)->height == 50);
// Decodifica ridotta e limite sui pixel
const auto decoded = decode(lossy, {.target_width = 60}).value();
assert(decoded.width == 60 && decoded.height == 21);
assert(!decode(lossy, {.max_pixels = 100}).has_value());
// Metadati: ICC aggiunto, poi EXIF rimosso senza toccare il profilo
const Bytes icc{1, 2, 3, 4, 5, 6, 7, 8};
const auto with_icc = set_icc_profile(lossy, icc).value();
assert(parse_webp_info(with_icc)->icc);
assert(get_chunk(with_icc, "ICCP").value() == icc);
const auto stripped = strip_private_metadata(with_icc).value();
assert(parse_webp_info(stripped)->icc && !parse_webp_info(stripped)->exif);
// Animazione: tre fotogrammi, durate e ripetizioni conservate
Animation animation{.width = 40, .height = 30, .loop_count = 2};
for (std::uint8_t red : {255, 128, 0}) {
animation.frames.push_back({solid(40, 30, 255, red), 120});
}
const auto anim_bytes = encode_animation(animation, {.lossless = true}).value();
assert(parse_webp_info(anim_bytes)->animated);
const auto read_back = decode_animation(anim_bytes).value();
assert(read_back.frames.size() == 3 && read_back.loop_count == 2);
assert(read_back.frames[1].duration_ms == 120);
assert(read_back.frames[2].image.rgba[0] == 0);
std::cout << "Tutti i test superati\n";
return 0;
}
Il test sulle animazioni è significativo: codifichiamo senza perdita, quindi i pixel letti devono coincidere esattamente con quelli scritti, e il canale rosso del terzo fotogramma deve valere zero. Il test sui metadati conferma che WebPMux converte il file nel formato esteso quando si aggiunge un profilo e che la rimozione dell'EXIF lascia intatto il chunk ICC.
Conclusioni
Usare libwebp direttamente da C++ significa lavorare alla fonte: tutte le opzioni dell'encoder, il ridimensionamento in codifica e in decodifica, il pieno controllo del contenitore e delle animazioni sono a portata di mano, senza le semplificazioni imposte dai binding degli altri linguaggi. La disciplina richiesta è quella tipica dell'interfacciamento con una libreria C: verificare i valori di ritorno, in particolare quelli delle funzioni di inizializzazione che controllano la compatibilità ABI, affidare ogni risorsa a un oggetto RAII, conoscere con precisione chi possiede ogni buffer, come insegnano copy_data di libwebpmux e i fotogrammi di WebPAnimDecoder. Con std::span, std::expected e std::jthread, il C++ moderno trasforma queste regole in un'interfaccia sicura e piacevole da usare, e i sanitizer e il fuzzing aiutano a mantenerla tale nel tempo.