Manipulación de contenedores RIFF para imágenes WebP.
API de Mux
Permite la manipulación de imágenes de contenedor WebP, que contienen funciones como el perfil de color, los metadatos, la animación y las imágenes fragmentadas.
Ejemplos de código
Crea un archivo MUX con datos de imagen, perfil de color y metadatos de XMP
int copy_data = 0;
WebPMux* mux = WebPMuxNew();
// ... (Prepare image data).
WebPMuxSetImage(mux, &image, copy_data);
// ... (Prepare ICCP color profile data).
WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data);
// ... (Prepare XMP metadata).
WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data);
// Get data from mux in WebP RIFF format.
WebPMuxAssemble(mux, &output_data);
WebPMuxDelete(mux);
// ... (Consume output_data; e.g. write output_data.bytes to file).
WebPDataClear(&output_data);
Cómo obtener datos de perfiles de imagen y color de un archivo WebP
int copy_data = 0;
// ... (Read data from file).
WebPMux* mux = WebPMuxCreate(&data, copy_data);
WebPMuxGetFrame(mux, 1, &image);
// ... (Consume image; e.g. call WebPDecode() to decode the data).
WebPMuxGetChunk(mux, "ICCP", &icc_profile);
// ... (Consume icc_data).
WebPMuxDelete(mux);
free(data);
La vida de un objeto Mux
Enumeradores
// Error codes
typedef enum WebPMuxError {
WEBP_MUX_OK = 1,
WEBP_MUX_NOT_FOUND = 0,
WEBP_MUX_INVALID_ARGUMENT = -1,
WEBP_MUX_BAD_DATA = -2,
WEBP_MUX_MEMORY_ERROR = -3,
WEBP_MUX_NOT_ENOUGH_DATA = -4
} WebPMuxError;
// IDs for different types of chunks.
typedef enum WebPChunkId {
WEBP_CHUNK_VP8X, // VP8X
WEBP_CHUNK_ICCP, // ICCP
WEBP_CHUNK_ANIM, // ANIM
WEBP_CHUNK_ANMF, // ANMF
WEBP_CHUNK_ALPHA, // ALPH
WEBP_CHUNK_IMAGE, // VP8/VP8L
WEBP_CHUNK_EXIF, // EXIF
WEBP_CHUNK_XMP, // XMP
WEBP_CHUNK_UNKNOWN, // Other chunks.
WEBP_CHUNK_NIL
} WebPChunkId;
WebPGetMuxVersion()
Muestra el número de versión de la biblioteca de multiples empaquetados en hexadecimales con 8 bits para cada uno de los valores principales, secundarios o de revisión. P.ej., v2.5.7 es 0x020507
.
int WebPGetMuxVersion(void);
WebPMuxNew()
Crea un objeto mux vacío.
WebPMux* WebPMuxNew(void);
- Devuelve
- Es un puntero al objeto mux vacío que se creó recientemente.
WebPMuxDelete()
Borra el objeto mux.
void WebPMuxDelete(WebPMux* mux);
- Parámetros
- mux: Es el objeto (de entrada/salida) que se borrará.
Creación de Mux
WebPMuxCreate()
Crea un objeto mux a partir de datos sin procesar proporcionados en formato WebP RIFF.
WebPMux* WebPMuxCreate(const WebPData* bitstream, int copy_data);
- Parámetros
bitstream (en) los datos de flujo de bits en formato WebP RIFF
copy_data -- (in) El valor 1 indica que los datos dados se copiarán al mux, y el valor 0 indica que los datos NO se copiarán al objeto mux.
- Devuelve
Un puntero para el objeto mux creado a partir de datos determinados (en caso de éxito).
NULL: En caso de datos no válidos o error de memoria.
Fragmentos que no son de imagen
WebPMuxSetChunk()
Agrega un bloque con el ID fourcc y datos chunk_data en el objeto mux. Se quitarán los fragmentos existentes con el mismo ID.
WebPMuxError WebPMuxSetChunk(WebPMux* mux,
const char fourcc[4],
const WebPData* chunk_data,
int copy_data);
Nota: Solo los fragmentos no relacionados con imágenes deben administrarse a través de las APIs de fragmentos.
(Los fragmentos relacionados con la imagen son "ANMF", "FRGM", "VP8 ", "VP8L" y "ALPH"). Para agregar, obtener y borrar imágenes, usa WebPMuxSetImage()
, WebPMuxPushFrame()
, WebPMuxGetFrame()
y WebPMuxDeleteFrame()
.
- Parámetros
mux: objeto (dentro/salida) al que se agregará el bloque
fourcc -- (in) una matriz de caracteres que contiene los {4}cc del fragmento dado; p.ej., "ICCP", "XMP ", "EXIF", etc.
chunk_data (dentro) de los datos del fragmento que se agregarán
copy_data -- (in) El valor 1 indica que los datos dados se copiarán al mux, y el valor 0 indica que los datos NO se copiarán al objeto mux.
- Devuelve
WEBP_MUX_INVALID_ARGUMENT
: si mux, Fourcc o chunk_data es NULL, o si Fourcc corresponde a un fragmento de imagen.WEBP_MUX_MEMORY_ERROR
: en el error de asignación de memoriaWEBP_MUX_OK
: en caso de éxito.
WebPMuxGetChunk()
Obtiene una referencia a los datos del bloque con el ID fourcc en el objeto mux. El emisor NO debe liberar los datos que se muestran.
WebPMuxError WebPMuxGetChunk(const WebPMux* mux,
const char fourcc[4],
WebPData* chunk_data);
- Parámetros
mux (in): el objeto desde el que se recuperan los datos del fragmento
fourcc -- (in) una matriz de caracteres que contiene los cuatro cc del bloque; p.ej., "ICCP", "XMP ", "EXIF", etc.
chunk_data (salida) muestra los datos del fragmento.
- Devuelve
WEBP_MUX_INVALID_ARGUMENT
: si mux, Fourcc o chunk_data es NULL, o si Fourcc corresponde a un fragmento de imagen.WEBP_MUX_NOT_FOUND
: Si mux no contiene un fragmento con el ID dado.WEBP_MUX_OK
: en caso de éxito.
WebPMuxDeleteChunk()
Borra el bloque con el fourcc dado del objeto mux.
WebPMuxError WebPMuxDeleteChunk(WebPMux* mux, const char fourcc[4]);
- Parámetros
mux: objeto (de entrada/salida) desde el que se borrará el bloque
fourcc -- (in) una matriz de caracteres que contiene los cuatro cc del bloque; p.ej., "ICCP", "XMP ", "EXIF", etc.
- Devuelve
WEBP_MUX_INVALID_ARGUMENT
-- si mux o Fourcc es NULL o si cuatrocc corresponde a un fragmento de imagen.WEBP_MUX_NOT_FOUND
: si el elemento mux no contiene un fragmento con el Fourcc especificado.WEBP_MUX_OK
: en caso de éxito.
Imágenes
Encapsula datos sobre un solo marco o fragmento.
struct WebPMuxFrameInfo {
WebPData bitstream; // image data: can be a raw VP8/VP8L bitstream
// or a single-image WebP file.
int x_offset; // x-offset of the frame.
int y_offset; // y-offset of the frame.
int duration; // duration of the frame (in milliseconds).
WebPChunkId id; // frame type: should be one of WEBP_CHUNK_ANMF,
// WEBP_CHUNK_FRGM or WEBP_CHUNK_IMAGE
WebPMuxAnimDispose dispose_method; // Disposal method for the frame.
WebPMuxAnimBlend blend_method; // Blend operation for the frame.
};
WebPMuxSetImage()
Configura la imagen (no animada y no fragmentada) en el objeto mux. Nota: Se quitarán todas las imágenes existentes (incluidos los marcos y fragmentos).
WebPMuxError WebPMuxSetImage(WebPMux* mux,
const WebPData* bitstream,
int copy_data);
- Parámetros
mux: objeto (entrada/salida) en el que se configurará la imagen
transmisión de bits (dentro) puede ser una transmisión de bits VP8/VP8L sin procesar o un archivo WebP de una sola imagen (no animado y no fragmentado).
copy_data -- (in) El valor 1 indica que los datos dados se copiarán al mux, y el valor 0 indica que los datos NO se copiarán al objeto mux.
- Devuelve
WEBP_MUX_INVALID_ARGUMENT
: Si el mux es NULL o el flujo de bits es NULL.WEBP_MUX_MEMORY_ERROR
: en el error de asignación de memoriaWEBP_MUX_OK
: en caso de éxito.
WebPMuxPushFrame()
Agrega un marco al final del objeto mux.
WebPMuxError WebPMuxPushFrame(WebPMux* mux,
const WebPMuxFrameInfo* frame,
int copy_data);
Notas:
- fotograma.id debe ser
WEBP_CHUNK_ANMF
oWEBP_CHUNK_FRGM
- Para configurar una imagen no animada no fragmentada, usa
WebPMuxSetImage()
en su lugar. - El tipo de fotograma que se envía debe ser el mismo que los fotogramas del comando mux.
- Como WebP solo admite desplazamientos pares, cualquier desplazamiento impar se ajustará a una ubicación par con offset &= ~1.
- Parámetros
mux: objeto (entrada/salida) al que se agregará el marco
marco -- (dentro) de los datos del marco.
copy_data -- (in) El valor 1 indica que los datos dados se copiarán al mux, y el valor 0 indica que los datos NO se copiarán al objeto mux.
- Devuelve
WEBP_MUX_INVALID_ARGUMENT
: Si el multiplexor o marco es NULL o si el contenido del marco no es válido.WEBP_MUX_MEMORY_ERROR
: en el error de asignación de memoriaWEBP_MUX_OK
: en caso de éxito.WEBP_MUX_MEMORY_ERROR
: en el error de asignación de memoria
WebPMuxGetFrame()
Obtiene el enésimo fotograma del objeto mux. El contenido de frame->bitstream se asigna con malloc(), y NO es propiedad del objeto mux. El llamador DEBE desasignarla llamando a WebPDataClear()
. nth=0 tiene un significado
especial: última posición.
WebPMuxError WebPMuxGetFrame(const WebPMux* mux,
uint32_t nth,
WebPMuxFrameInfo* frame);
- Parámetros
mux (dentro) del objeto desde el que se recupera la información
nth: (in) el índice del marco en el objeto mux
frame -- (fuera) del marco que se muestra
- Devuelve
WEBP_MUX_INVALID_ARGUMENT
: Si el mux o el marco son NULL.WEBP_MUX_NOT_FOUND
: Si hay menos de enésimas fotogramas en el objeto mux.WEBP_MUX_BAD_DATA
: Si el fragmento de enésimo fotograma del mux no es válidoWEBP_MUX_OK
: en caso de éxito.
WebPMuxDeleteFrame()
Borra un fotograma del objeto mux. nth=0 tiene un significado especial: última posición.
WebPMuxError WebPMuxDeleteFrame(WebPMux* mux, uint32_t nth);
- Parámetros
mux: objeto (de entrada/salida) desde el que se borrará un fotograma
nth (in) Es la posición desde la que se borrará el fotograma.
- Devuelve
WEBP_MUX_INVALID_ARGUMENT
: Si el mux es NULL.WEBP_MUX_NOT_FOUND
: si hay menos de enésimas fotogramas en el objeto mux antes de la eliminación.WEBP_MUX_OK
: en caso de éxito.
Animación
Parámetros de animación
struct WebPMuxAnimParams {
uint32_t bgcolor; // Background color of the canvas stored (in MSB order) as:
// Bits 00 to 07: Alpha.
// Bits 08 to 15: Red.
// Bits 16 to 23: Green.
// Bits 24 to 31: Blue.
int loop_count; // Number of times to repeat the animation [0 = infinite].
};
WebPMuxSetAnimationParams()
Establece los parámetros de animación en el objeto mux. Se eliminarán los fragmentos de ANIM existentes.
WebPMuxError WebPMuxSetAnimationParams(WebPMux* mux,
const WebPMuxAnimParams* params);
- Parámetros
mux: objeto (dentro/salida) en el que se debe colocar/agregar el bloque ANIM
params: (en) parámetros de animación.
- Devuelve
WEBP_MUX_INVALID_ARGUMENT
: Si el parámetro mux o los parámetros son NULL.WEBP_MUX_MEMORY_ERROR
: en el error de asignación de memoriaWEBP_MUX_OK
: en caso de éxito.
WebPMuxGetAnimationParams()
Obtiene los parámetros de animación del objeto mux.
WebPMuxError WebPMuxGetAnimationParams(const WebPMux* mux,
WebPMuxAnimParams* params);
- Parámetros
mux (dentro) del objeto desde el que se recuperarán los parámetros de animación
params: parámetros de animación (out) extraídos del bloque ANIM.
- Devuelve
WEBP_MUX_INVALID_ARGUMENT
: Si el parámetro mux o los parámetros son NULL.WEBP_MUX_NOT_FOUND
: si el bloque ANIM no está presente en el objeto mux.WEBP_MUX_OK
: en caso de éxito.
Varios servicios públicos
WebPMuxGetCanvasSize()
Obtiene el tamaño del lienzo del objeto mux.
WebPMuxError WebPMuxGetCanvasSize(const WebPMux* mux,
int* width,
int* height);
Nota: Este método supone que el fragmento VP8X, si está presente, está actualizado.
Es decir, el objeto mux no se modificó desde la última llamada a WebPMuxAssemble()
o WebPMuxCreate()
.
- Parámetros
mux: (in) el objeto desde el que se debe recuperar el tamaño del lienzo
width -- (fuera) del lienzo
height: (altura) del lienzo
- Devuelve
WEBP_MUX_INVALID_ARGUMENT
: Si el valor de mux, el ancho o la altura son NULL.WEBP_MUX_BAD_DATA
: Si el tamaño de lienzo o fragmento de VP8X/VP8/VP8L no es válido.WEBP_MUX_OK
: en caso de éxito.
WebPMuxGetFeatures()
Obtiene las marcas de función del objeto mux.
WebPMuxError WebPMuxGetFeatures(const WebPMux* mux, uint32_t* flags);
Nota: Este método supone que el fragmento VP8X, si está presente, está actualizado.
Es decir, el objeto mux no se modificó desde la última llamada a WebPMuxAssemble()
o WebPMuxCreate()
.
- Parámetros
mux (dentro) del objeto desde el que se recuperan los atributos
flags: (fuera) las marcas que especifican los componentes que están presentes en el objeto mux. Este será un operador OR de varios valores de marca. La enumeración
WebPFeatureFlags
se puede usar para probar valores de marcas individuales.- Devuelve
WEBP_MUX_INVALID_ARGUMENT
: Si el mux o las marcas son NULL.WEBP_MUX_BAD_DATA
: Si el tamaño de lienzo o fragmento de VP8X/VP8/VP8L no es válido.WEBP_MUX_OK
: en caso de éxito.
WebPMuxNumChunks()
Obtiene la cantidad de fragmentos que tienen el valor de etiqueta determinado en el objeto mux.
WebPMuxError WebPMuxNumChunks(const WebPMux* mux,
WebPChunkId id,
int* num_elements);
- Parámetros
mux (dentro) del objeto desde el que se recupera la información
id -- (en) ID de fragmento que especifica el tipo de bloque
num_elements -- (fuera) cantidad de fragmentos con el ID de fragmento dado
- Devuelve
WEBP_MUX_INVALID_ARGUMENT
: Si mux o num_elements es NULL.WEBP_MUX_OK
: en caso de éxito.
WebPMuxAssemble()
Ensambla todos los fragmentos en formato WebP RIFF y se muestra en assembled_data. Esta función también valida el objeto mux.
WebPMuxError WebPMuxAssemble(WebPMux* mux, WebPData* assembled_data);
Nota: Se ignorará y reemplazará el contenido de joind_data.
Además, el contenido de assembled_data se asigna mediante malloc() y NO es propiedad del objeto assembled_data. El emisor DEBE desasignarla llamando a WebPDataClear()
.
- Parámetros
mux: Es un objeto (de entrada/salida) cuyos fragmentos se deben ensamblar.
assembled_data: (basadas) en datos WebP ensamblados
- Devuelve
WEBP_MUX_BAD_DATA
: Si el objeto mux no es válido.WEBP_MUX_INVALID_ARGUMENT
: Si mux o joind_data son NULL.WEBP_MUX_MEMORY_ERROR
: en el error de asignación de memoriaWEBP_MUX_OK
: en caso de éxito.
API de WebPAnimEncoder
Esta API permite codificar (posiblemente) imágenes WebP animadas.
Ejemplo de código
WebPAnimEncoderOptions enc_options;
WebPAnimEncoderOptionsInit(&enc_options);
// Tune 'enc_options' as needed.
WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options);
while(<there are more frames>) {
WebPConfig config;
WebPConfigInit(&config);
// Tune 'config' as needed.
WebPAnimEncoderAdd(enc, frame, timestamp_ms, &config);
}
WebPAnimEncoderAdd(enc, NULL, timestamp_ms, NULL);
WebPAnimEncoderAssemble(enc, webp_data);
WebPAnimEncoderDelete(enc);
// Write the 'webp_data' to a file, or re-mux it further.
typedef struct WebPAnimEncoder WebPAnimEncoder; // Main opaque object.
Opciones globales
struct WebPAnimEncoderOptions {
WebPMuxAnimParams anim_params; // Animation parameters.
int minimize_size; // If true, minimize the output size (slow). Implicitly
// disables key-frame insertion.
int kmin;
int kmax; // Minimum and maximum distance between consecutive key
// frames in the output. The library may insert some key
// frames as needed to satisfy this criteria.
// Note that these conditions should hold: kmax > kmin
// and kmin >= kmax / 2 + 1. Also, if kmax <= 0, then
// key-frame insertion is disabled; and if kmax == 1,
// then all frames will be key-frames (kmin value does
// not matter for these special cases).
int allow_mixed; // If true, use mixed compression mode; may choose
// either lossy and lossless for each frame.
int verbose; // If true, print info and warning messages to stderr.
};
WebPAnimEncoderOptionsInit()
Siempre se debe llamar para inicializar una estructura WebPAnimEncoderOptions nueva antes de la modificación. El resultado es falso en caso de que la versión no coincida. WebPAnimEncoderOptionsInit() debe tener éxito antes de usar el objeto enc_options.
- Parámetros
- enc_options: Son opciones (in/out) que se usan para codificar la animación.
- Devuelve
- Verdadero.
int WebPAnimEncoderOptionsInit(
WebPAnimEncoderOptions* enc_options);
WebPAnimEncoderNew()
Crea e inicializa un objeto WebPAnimEncoder.
- Parámetros
width/height: (en) el ancho y la altura del lienzo de la animación.
enc_options (en) opciones de codificación; se puede pasar NULL para elegir valores predeterminados razonables.
- Devuelve
Un puntero para el objeto WebPAnimEncoder recién creado, o NULL en caso de un error de memoria.
WebPAnimEncoder* WebPAnimEncoderNew(
int width, int height, const WebPAnimEncoderOptions* enc_options);
WebPAnimEncoderAdd()
Optimiza un marco determinado para WebP, codifícalo y agrégalo al objeto WebPAnimEncoder.
La última llamada a WebPAnimEncoderAdd debe ser con frame = NULL
, que indica que no se deben agregar más marcos. Esta llamada también se usa para determinar la duración del último fotograma.
- Parámetros
enc: Es el objeto (de entrada/salida) al que se agregará el marco.
marco: Son datos de fotograma (entrada/salida) en formato ARGB o YUV(A). Si está en formato YUV(A), se convertirá en ARGB, lo que generará una pequeña pérdida.
timestamp_ms -- (en) marca de tiempo de este fotograma en milisegundos. La duración de un fotograma se calcularía como “marca de tiempo del siguiente fotograma - marca de tiempo de este fotograma”. Por lo tanto, las marcas de tiempo no deben disminuir.
config -- (en) opciones de codificación; se puede pasar NULL para elegir valores predeterminados razonables.
- Devuelve
Si se produce un error, muestra un valor falso y
frame->error_code
se configuró correctamente. De lo contrario, muestra el valor true.
int WebPAnimEncoderAdd(
WebPAnimEncoder* enc, struct WebPPicture* frame, int timestamp_ms,
const struct WebPConfig* config);
WebPAnimEncoderAssemble()
Ensambla todos los fotogramas agregados hasta ahora en un flujo de bits de WebP. Esta llamada debe estar precedida por una llamada a WebPAnimEncoderAdd con frame = NULL
. De lo contrario, la duración del último fotograma se estimará internamente.
- Parámetros
enc: Es el objeto (de entrada/salida) a partir del cual se ensamblarán los marcos.
webp_data: (fuera) se generó la transmisión de bits de WebP.
- Devuelve
Verdadero en el éxito.
int WebPAnimEncoderAssemble(WebPAnimEncoder* enc, WebPData* webp_data);
WebPAnimEncoderGetError()
Obtén la cadena de error correspondiente a la llamada más reciente mediante enc. La cadena que se muestra es propiedad de enc y es válida solo hasta la próxima llamada a WebPAnimEncoderAdd()
, WebPAnimEncoderAssemble()
o WebPAnimEncoderDelete()
.
- Parámetros
- enc: Es un objeto (de entrada/salida) desde el que se debe recuperar la string de error.
- Devuelve
- NULL if enc is NULL. De lo contrario, muestra la string de error si la última llamada a enc tuvo un error, o una string vacía si la última llamada fue exitosa.
const char* WebPAnimEncoderGetError(WebPAnimEncoder* enc);
WebPAnimEncoderDelete()
Borra el objeto WebPAnimEncoder.
- Parámetros
- enc -- (adentro/salida) objeto que se borrará
void WebPAnimEncoderDelete(WebPAnimEncoder* enc);
API de Demux
Permite la extracción de datos de imágenes y formato extendido de archivos WebP.
Ejemplos de código
Cómo depurar datos WebP para extraer todos los fotogramas, el perfil de ICC y los metadatos EXIF/XMP
WebPDemuxer* demux = WebPDemux(&webp_data);
uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH);
uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT);
// ... (Get information about the features present in the WebP file).
uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS);
// ... (Iterate over all frames).
WebPIterator iter;
if (WebPDemuxGetFrame(demux, 1, &iter)) {
do {
// ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(),
// ... and get other frame properties like width, height, offsets etc.
// ... see 'struct WebPIterator' below for more info).
} while (WebPDemuxNextFrame(&iter));
WebPDemuxReleaseIterator(&iter);
}
// ... (Extract metadata).
WebPChunkIterator chunk_iter;
if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter);
// ... (Consume the ICC profile in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter);
// ... (Consume the EXIF metadata in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter);
// ... (Consume the XMP metadata in 'chunk_iter.chunk').
WebPDemuxReleaseChunkIterator(&chunk_iter);
WebPDemuxDelete(demux);
La vida de un objeto Demux
Enumeradores
typedef enum WebPDemuxState {
WEBP_DEMUX_PARSE_ERROR = -1, // An error occurred while parsing.
WEBP_DEMUX_PARSING_HEADER = 0, // Not enough data to parse full header.
WEBP_DEMUX_PARSED_HEADER = 1, // Header parsing complete,
// data may be available.
WEBP_DEMUX_DONE = 2 // Entire file has been parsed.
} WebPDemuxState;
WebPGetDemuxVersion()
Muestra el número de versión de la biblioteca de DEX, empaquetado en hexadecimales con 8 bits para cada uno de los valores principales, secundarios o de revisión. P. ej., v2.5.7 es 0x020507
.
int WebPGetDemuxVersion(void);
WebPDemux()
Analiza el archivo WebP completo proporcionado por data.
WebPDemuxer WebPDemux(const WebPData* data);
Muestra un objeto WebPDemuxer
si el análisis se realiza correctamente; de lo contrario, muestra NULL.
WebPDemuxPartial()
Analiza el archivo WebP posiblemente incompleto que proporcionó data. Si state no es NULL, se configurará para indicar el estado del demuxer.
WebPDemuxer WebPDemuxPartial(const WebPData* data, WebPDemuxState* state);
Muestra NULL en caso de que se produzca un error o si no hay suficientes datos para comenzar el análisis, y un objeto WebPDemuxer
si el análisis se realiza correctamente.
Ten en cuenta que WebPDemuxer
mantiene los punteros internos en el segmento de memoria de datos. Si estos datos son volátiles, se debe borrar el objeto del demuxer (llama a WebPDemuxDelete()
) y se debe volver a llamar a WebPDemuxPartial()
en los datos nuevos. Por lo general, esta es una operación económica.
WebPDemuxDelete()
Libera memoria asociada con dmux.
void WebPDemuxDelete(WebPDemuxer* dmux);
Extracción de información y datos
typedef enum WebPFormatFeature {
WEBP_FF_FORMAT_FLAGS, // bit-wise combination of WebPFeatureFlags
// corresponding to the 'VP8X' chunk (if present).
WEBP_FF_CANVAS_WIDTH,
WEBP_FF_CANVAS_HEIGHT,
WEBP_FF_LOOP_COUNT, // only relevant for animated file
WEBP_FF_BACKGROUND_COLOR, // idem.
WEBP_FF_FRAME_COUNT // Number of frames present in the demux object.
// In case of a partial demux, this is the number
// of frames seen so far, with the last frame
// possibly being partial.
} WebPFormatFeature;
WebPDemuxGetI()
Obtén el valor feature de dmux.
uint32_t WebPDemuxGetI(const WebPDemuxer* dmux, WebPFormatFeature feature);
Nota: Los valores solo son válidos si se usó WebPDemux()
o si WebPDemuxPartial()
mostró un estado > WEBP_DEMUX_PARSING_HEADER
.
Iteración de fotogramas
struct WebPIterator {
int frame_num;
int num_frames; // equivalent to WEBP_FF_FRAME_COUNT.
int fragment_num;
int num_fragments;
int x_offset, y_offset; // offset relative to the canvas.
int width, height; // dimensions of this frame or fragment.
int duration; // display duration in milliseconds.
WebPMuxAnimDispose dispose_method; // dispose method for the frame.
int complete; // true if 'fragment' contains a full frame. partial images
// may still be decoded with the WebP incremental decoder.
WebPData fragment; // The frame or fragment given by 'frame_num' and
// 'fragment_num'.
int has_alpha; // True if the frame or fragment contains transparency.
WebPMuxAnimBlend blend_method; // Blend operation for the frame.
};
WebPDemuxGetFrame()
Recupera el marco frame_number de dmux.
int WebPDemuxGetFrame(const WebPDemuxer* dmux,
int frame_number,
WebPIterator* iter);
iter->fragment apunta al primer fragmento cuando se muestra desde esta función.
Se pueden extraer fragmentos individuales con WebPDemuxSelectFragment()
. Si estableces frame_number en 0, se mostrará el último fotograma de la imagen.
El resultado es falso si dmux es NULL o si el marco frame_number no está presente.
Llama a WebPDemuxReleaseIterator()
cuando se complete el uso del iterador.
Nota: dmux debe persistir durante la vida útil de iter.
WebPDemuxNextFrame()
, WebPDemuxPrevFrame()
Configura iter->fragment para que apunte al marco siguiente (iter->fragment + 1) o anterior (iter->fragment - 1). Estas funciones no se repiten indefinidamente.
int WebPDemuxNextFrame(WebPIterator* iter);
int WebPDemuxPrevFrame(WebPIterator* iter);
Muestra true en caso de éxito, false de lo contrario.
WebPDemuxSelectFragment()
Configura iter->fragment para que refleje el número del fragmento iter->fragment.
int WebPDemuxSelectFragment(WebPIterator* iter, int fragment_num);
Muestra true si el fragmento fragment_num está presente; de lo contrario, muestra false.
WebPDemuxReleaseIterator()
Libera cualquier memoria asociada con iter.
void WebPDemuxReleaseIterator(WebPIterator* iter);
Se debe llamar antes de cualquier llamada posterior a WebPDemuxGetChunk()
en el mismo iteración. También se debe llamar antes de destruir el WebPDemuxer
asociado con WebPDemuxDelete()
.
Iteración de fragmentos
struct WebPChunkIterator {
// The current and total number of chunks with the fourcc given to
// WebPDemuxGetChunk().
int chunk_num;
int num_chunks;
WebPData chunk; // The payload of the chunk.
};
WebPDemuxGetChunk()
Recupera la instancia chunk_number del bloque con el ID fourcc de dmux.
int WebPDemuxGetChunk(const WebPDemuxer* dmux,
const char fourcc[4], int chunk_number,
WebPChunkIterator* iter);
fourcc es un conjunto de caracteres que contiene los cuatro cc del bloque que se desea mostrar, p.ej., "ICCP", "XMP ", "EXIF", etcétera.
Si estableces chunk_number igual a 0, se mostrará el último bloque de un conjunto.
Muestra true si se encuentra el fragmento; de lo contrario, muestra false. Se accede a las cargas útiles de fragmentos relacionados con imágenes a través de WebPDemuxGetFrame()
y las funciones relacionadas. Llama a WebPDemuxReleaseChunkIterator()
cuando se complete el uso del iterador.
Nota: dmux debe persistir durante la vida útil del iterador.
WebPDemuxNextChunk()
, WebPDemuxPrevChunk()
Configura iter->chunk para que apunte al siguiente (iter->chunk_num + 1) o al fragmento anterior (iter->chunk_num - 1). Estas funciones no se repiten indefinidamente.
int WebPDemuxNextChunk(WebPChunkIterator* iter);
int WebPDemuxPrevChunk(WebPChunkIterator* iter);
Muestra true en caso de éxito, false de lo contrario.
WebPDemuxReleaseChunkIterator()
Libera cualquier memoria asociada con iter.
void WebPDemuxReleaseChunkIterator(WebPChunkIterator* iter);
Se debe llamar antes de destruir el WebPDemuxer
asociado con WebPDemuxDelete()
.
API de WebPAnimDecoder
Esta API permite decodificar (posiblemente) imágenes WebP animadas.
Ejemplo de código
WebPAnimDecoderOptions dec_options;
WebPAnimDecoderOptionsInit(&dec_options);
// Tune 'dec_options' as needed.
WebPAnimDecoder* dec = WebPAnimDecoderNew(webp_data, &dec_options);
WebPAnimInfo anim_info;
WebPAnimDecoderGetInfo(dec, &anim_info);
for (uint32_t i = 0; i < anim_info.loop_count; ++i) {
while (WebPAnimDecoderHasMoreFrames(dec)) {
uint8_t* buf;
int timestamp;
WebPAnimDecoderGetNext(dec, &buf, ×tamp);
// ... (Render 'buf' based on 'timestamp').
// ... (Do NOT free 'buf', as it is owned by 'dec').
}
WebPAnimDecoderReset(dec);
}
const WebPDemuxer* demuxer = WebPAnimDecoderGetDemuxer(dec);
// ... (Do something using 'demuxer'; e.g. get EXIF/XMP/ICC data).
WebPAnimDecoderDelete(dec);
typedef struct WebPAnimDecoder WebPAnimDecoder; // Main opaque object.
Opciones globales
struct WebPAnimDecoderOptions {
// Output colorspace. Only the following modes are supported:
// MODE_RGBA, MODE_BGRA, MODE_rgbA and MODE_bgrA.
WEBP_CSP_MODE color_mode;
int use_threads; // If true, use multi-threaded decoding.
};
WebPAnimDecoderOptionsInit()
Siempre se debe llamar para inicializar una estructura WebPAnimDecoderOptions nueva antes de la modificación. El resultado es falso en caso de que la versión no coincida. WebPAnimDecoderOptionsInit() debe tener éxito antes de usar el objeto dec_options.
Parámetros
dec_options: Son opciones (de entrada/salida) que se usan para decodificar animación.
- Devuelve
- Verdadero en el éxito
int WebPAnimDecoderOptionsInit(
WebPAnimDecoderOptions* dec_options);
WebPAnimDecoderNew()
Crea y, luego, inicializa un objeto WebPAnimDecoder.
- Parámetros
webp_data -- (en) transmisión de bits WebP. No debe modificarse durante la vida útil del objeto WebPAnimDecoder de salida.
dec_options: (en) las opciones de decodificación. Se puede pasar NULL para elegir valores predeterminados razonables (en particular, se elegirá el modo de color MODE_RGBA).
- Devuelve
Un puntero para el objeto WebPAnimDecoder recién creado o NULL en caso de que se produzca un error de análisis, una opción no válida o un error de memoria.
WebPAnimDecoder* WebPAnimDecoderNew(
const WebPData* webp_data, const WebPAnimDecoderOptions* dec_options);
Información global sobre la animación.
struct WebPAnimInfo {
uint32_t canvas_width;
uint32_t canvas_height;
uint32_t loop_count;
uint32_t bgcolor;
uint32_t frame_count;
};
WebPAnimDecoderGetInfo()
Obtén información global sobre la animación.
- Parámetros
dec: (en) instancia de decodificador de la que se debe obtener información.
info: la información global (fuera) recuperada de la animación.
- Devuelve
Verdadero en el éxito.
int WebPAnimDecoderGetInfo(const WebPAnimDecoder* dec,
WebPAnimInfo* info);
WebPAnimDecoderGetNext()
Recupera el siguiente fotograma de dec según las opciones proporcionadas a WebPAnimDecoderNew()
. Este será un lienzo completamente reconstruido de tamaño canvas_width * 4 * canvas_height
, no solo el subrectángulo del marco. El buf del búfer que se muestra es válido solo hasta la próxima llamada a WebPAnimDecoderGetNext()
, WebPAnimDecoderReset()
o WebPAnimDecoderDelete()
.
- Parámetros
dec: instancia de decodificador (entrada/salida) a partir de la cual se recuperará el siguiente fotograma.
buf -- (fuera) marco decodificado.
timestamp: marca de tiempo (fuera) del fotograma en milisegundos.
- Devuelve
Falso si alguno de los argumentos es NULL, si hay un error de análisis o decodificación, o si no hay más marcos. De lo contrario, muestra el valor true.
int WebPAnimDecoderGetNext(WebPAnimDecoder* dec,
uint8_t** buf, int* timestamp);
WebPAnimDecoderHasMoreFrames()
Comprueba si quedan más fotogramas para decodificar.
- Parámetros
- dec: (in) instancia de decodificador que se verificará.
- Devuelve
- Verdadero si dec no es NULO y algunos marcos aún no se decodifican. De lo contrario, el resultado es falso.
int WebPAnimDecoderHasMoreFrames(const WebPAnimDecoder* dec);
WebPAnimDecoderReset()
Restablece el objeto WebPAnimDecoder de modo que la próxima llamada a WebPAnimDecoderGetNext()
reinicie la decodificación desde el primer fotograma. Esto sería útil cuando todos los marcos deban decodificarse varias veces (p.ej., info.loop_count veces) sin destruir y volver a crear el objeto dec.
- Parámetros
- dec: se debe restablecer la instancia de decodificador (entrada/salida)
void WebPAnimDecoderReset(WebPAnimDecoder* dec);
WebPAnimDecoderGetDemuxer()
Obtén el objeto de demuxer interno.
Obtener el objeto de demuxer puede ser útil si se quieren usar operaciones que solo están disponibles a través del demuxer; p.ej., para obtener metadatos XMP/EXIF/ICC. El objeto de demuxer que se muestra es propiedad de dec y solo es válido hasta la próxima llamada a WebPAnimDecoderDelete()
.
- Parámetros
- dec: (in) instancia de decodificador desde la que se recuperará el objeto de demuxer.
const WebPDemuxer* WebPAnimDecoderGetDemuxer(const WebPAnimDecoder* dec);
WebPAnimDecoderDelete()
Borra el objeto WebPAnimDecoder.
- Parámetros
- dec: La instancia de decodificador (entrada/salida) se borrará.
- Devuelve
- Verdadero.
void WebPAnimDecoderDelete(WebPAnimDecoder* dec);
Tipos de datos comunes
Enumeradores
typedef enum WebPFeatureFlags {
FRAGMENTS_FLAG = 0x00000001,
ANIMATION_FLAG = 0x00000002,
XMP_FLAG = 0x00000004,
EXIF_FLAG = 0x00000008,
ALPHA_FLAG = 0x00000010,
ICCP_FLAG = 0x00000020
} WebPFeatureFlags;
// Dispose method (animation only). Indicates how the area used by the current
// frame is to be treated before rendering the next frame on the canvas.
typedef enum WebPMuxAnimDispose {
WEBP_MUX_DISPOSE_NONE, // Do not dispose.
WEBP_MUX_DISPOSE_BACKGROUND // Dispose to background color.
} WebPMuxAnimDispose;
// Blend operation (animation only). Indicates how transparent pixels of the
// current frame are blended with those of the previous canvas.
typedef enum WebPMuxAnimBlend {
WEBP_MUX_BLEND, // Blend.
WEBP_MUX_NO_BLEND // Do not blend.
} WebPMuxAnimBlend;
WebPDataInit()
Inicializa el contenido del objeto webp_data con valores predeterminados.
void WebPDataInit(WebPData* webp_data);
WebPDataClear()
Borra el contenido del objeto webp_data mediante una llamada a free()
. No desasigna el objeto en sí.
void WebPDataClear(WebPData* webp_data);
WebPDataCopy()
Asigna el almacenamiento necesario para dst y copia el contenido de src. Muestra true en caso de éxito.
int WebPDataCopy(const WebPData* src, WebPData* dst);