lws-gif.h

Go to the documentation of this file.

/*
 * lws gif
 *
 * Written in 2026 by Andy Green <andy@warmcat.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 *
 * Stateful, linewise GIF decoder for the first frame.  Compressed input is
 * consumed from arbitrarily-sized chunks and complete raster rows are issued
 * one at a time into a row buffer shared between every live gif object, so
 * heap use does not scale with anything about the gif except its logical
 * screen width (one row) and the fixed 12-bit LZW code tables.
 *
 * Rows are issued in logical screen coordinates as single bytes that index
 * the active colour table: every screen row is issued exactly once, with
 * areas the image rectangle does not cover filled with the background
 * index, and parts of the image rectangle falling outside the logical
 * screen clipped.  For interlaced images, rows are issued in gif interlace
 * order with their true y available at \p py, bookended by the background
 * rows above and below the image rectangle; linearizing interlaced rows
 * needs a whole framebuffer, so consumers that need strict top-down order
 * must re-decode from retained input, as the dlo integration does.
 *
 * Only the first image is decoded; any further images are walked structurally
 * to the trailer and their pixel data discarded.
 */
 
typedef struct lws_gif lws_gif_t;

LWS_VISIBLE LWS_EXTERN lws_gif_t *
lws_gif_new(void);

LWS_VISIBLE LWS_EXTERN void
lws_gif_free(lws_gif_t **gif);

LWS_VISIBLE LWS_EXTERN void
lws_gif_restart(lws_gif_t *gif);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_gif_emit_next_line(lws_gif_t *gif, const uint8_t **ppix, int *py,
                       const uint8_t **buf, size_t *len, char hold_at_metadata);

LWS_VISIBLE LWS_EXTERN unsigned int
lws_gif_get_width(const lws_gif_t *gif);

LWS_VISIBLE LWS_EXTERN unsigned int
lws_gif_get_height(const lws_gif_t *gif);

LWS_VISIBLE LWS_EXTERN char
lws_gif_get_interlaced(const lws_gif_t *gif);

LWS_VISIBLE LWS_EXTERN const uint8_t *
lws_gif_get_palette(const lws_gif_t *gif);

LWS_VISIBLE LWS_EXTERN unsigned int
lws_gif_get_palette_count(const lws_gif_t *gif);

LWS_VISIBLE LWS_EXTERN int
lws_gif_get_transparent_index(const lws_gif_t *gif);
 
/* indices are one byte each; provided for symmetry with the other decoders */
 
LWS_VISIBLE LWS_EXTERN unsigned int
lws_gif_get_bpp(const lws_gif_t *gif);
LWS_VISIBLE LWS_EXTERN unsigned int
lws_gif_get_bitdepth(const lws_gif_t *gif);
LWS_VISIBLE LWS_EXTERN unsigned int
lws_gif_get_components(const lws_gif_t *gif);
LWS_VISIBLE LWS_EXTERN unsigned int
lws_gif_get_pixelsize(const lws_gif_t *gif);