lws-svg.h

Go to the documentation of this file.

/*
 * lws svg
 *
 * 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 SVG renderer for the fill-only subset of SVG.
 *
 * The document is parsed streaming (the parser is not sensitive to the input
 * chunk sizes) into a retained vector scene in a single lwsac.  Curves are
 * flattened adaptively at parse time, to a tolerance derived from the
 * viewBox size.  Individual raster lines are then produced on demand by
 * scanline intersection against the retained geometry, so any line can be
 * rendered at any time, in any order.
 *
 * The supported subset is solid fills with nonzero or evenodd winding,
 * transforms, viewBox / preserveAspectRatio mapping, group fill property
 * inheritance and opacity.  Strokes, gradients, text and filters are not
 * rendered in this phase of the work.
 */
 
typedef struct lws_svg lws_svg_t;
 
/* rgba packing is r in bits 0-7, g in 8-15, b in 16-23, alpha in 24-31, so it
 * matches lws_display_colour_t layout */
 
#define LWS_SVG_RGBA(_r, _g, _b, _a) (uint32_t)( \
                ((uint32_t)(_r) & 0xff) | \
                (((uint32_t)(_g) & 0xff) << 8) | \
                (((uint32_t)(_b) & 0xff) << 16) | \
                (((uint32_t)(_a) & 0xff) << 24))
 
#define LWS_SVG_ALPHA(_c)       ((uint32_t)(((_c) >> 24) & 0xff))
 
/*
 * Render mapping policy from preserveAspectRatio, only meaningful when a
 * viewBox exists
 */
 
typedef enum {
        LWS_SVG_PAR_DEFAULT,    /* xMidYMid meet */
        LWS_SVG_PAR_NONE,       /* stretch to fill */
} lws_svg_par_t;

LWS_VISIBLE LWS_EXTERN lws_svg_t *
lws_svg_new(void);

LWS_VISIBLE LWS_EXTERN void
lws_svg_free(lws_svg_t **svg);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_svg_parse(lws_svg_t *svg, const uint8_t **buf, size_t *len,
              char hold_at_metadata);

LWS_VISIBLE LWS_EXTERN unsigned int
lws_svg_get_width(const lws_svg_t *svg);

LWS_VISIBLE LWS_EXTERN unsigned int
lws_svg_get_height(const lws_svg_t *svg);

LWS_VISIBLE LWS_EXTERN char
lws_svg_get_doc_complete(const lws_svg_t *svg);
 
/*
 * Span callback for rendered lines.  Filled spans are delivered in ascending
 * x with \p x0 the first covered pixel and \p x1 one past the last covered
 * pixel (so the span is half-open [x0, x1)).  \p rgba is the span fill colour
 * with composed-opacity alpha in the top byte.
 *
 * With ri->aa clear (the default), coverage is binary at pixel centres, and
 * each shape produces spans of the same alpha.  With ri->aa set, coverage is
 * the exact covered fraction of each pixel (area antialiasing), spans are
 * additionally split where the fraction changes, and the alpha byte is the
 * fill alpha scaled by the pixel's coverage.  Returning nonzero stops the
 * line rendering, which then returns LWS_SRET_OK.
 */
typedef int (*lws_svg_span_cb_t)(void *user, int x0, int x1, uint32_t rgba);
 
typedef struct lws_svg_render {
        int w;                  /* output raster width in px */
        int h;                  /* output raster height in px */
        char aa;                /* nonzero: area-antialiased coverage */
} lws_svg_render_t;

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_svg_render_line(lws_svg_t *svg, const lws_svg_render_t *ri, int y,
                    lws_svg_span_cb_t cb, void *user);