raysvg.h

/**********************************************************************************************
*
*   raysvg - SVG loading and animation for raylib
*
*   raysvg keeps a retained scene graph of the parsed document, so groups stay addressable
*   after load. Elements are looked up by id or class and animated through per-element
*   "channels" (transform, pivot, opacity, display, z-index, reparent, outline). Geometry is
*   tessellated once and cached; per frame only matrices and vertex colours change.
*
*   PORTABILITY
*     Rendering uses only the rlgl subset that behaves identically on stock raylib and on the
*     rayact backends (rlvk/Vulkan, rlwg/WebGPU, rlmt/Metal):
*       rlBegin(RL_TRIANGLES)/rlEnd/rlVertex2f/rlColor4ub/rlTexCoord2f/rlSetTexture,
*       rlPushMatrix/rlPopMatrix/rlTranslatef/rlRotatef/rlScalef, rlCheckRenderBatchLimit,
*       BeginScissorMode/EndScissorMode, LoadTextureFromImage/UpdateTexture/SetTextureFilter.
*     No stencil, no custom shaders, no vertex arrays, no render textures.
*
*   LICENSE: zlib/libpng
*
**********************************************************************************************/

#ifndef RAYSVG_H
#define RAYSVG_H

#include "raylib.h"

#include <stdbool.h>
#include <stdint.h>

#ifndef RAYSVGAPI
    #define RAYSVGAPI
#endif

#define RAYSVG_VERSION "0.1.0"

#ifdef __cplusplus
extern "C" {
#endif

// Opaque document handle
typedef struct RaysvgDoc RaysvgDoc;

// Stable element reference, valid for the lifetime of the document.
// Reparenting, z-ordering and hiding never invalidate a handle.
typedef int32_t RaysvgHandle;

#define RAYSVG_INVALID_HANDLE ((RaysvgHandle) - 1)

//------------------------------------------------------------------------------------
// Document lifecycle
//------------------------------------------------------------------------------------

// Parse an SVG file. Returns NULL on failure; check RaysvgGetLastError().
RAYSVGAPI RaysvgDoc *RaysvgLoadFromFile(const char *fileName);

// Parse SVG markup held in memory. Pass len < 0 to use strlen(xml).
RAYSVGAPI RaysvgDoc *RaysvgLoadFromString(const char *xml, int len);

// Release the document and every GPU resource it owns.
RAYSVGAPI void RaysvgUnload(RaysvgDoc *doc);

// Intrinsic size in user units, taken from viewBox (falls back to width/height).
RAYSVGAPI Vector2 RaysvgGetDocSize(const RaysvgDoc *doc);

// Root element handle (the <svg> node).
RAYSVGAPI RaysvgHandle RaysvgGetRoot(const RaysvgDoc *doc);

// Message describing why the most recent load failed. Never NULL.
RAYSVGAPI const char *RaysvgGetLastError(void);

// Non-fatal problems collected while parsing (unsupported elements, bad attributes).
// Returns the count; pass a buffer to receive up to `cap` message pointers, owned by doc.
RAYSVGAPI int RaysvgGetWarnings(const RaysvgDoc *doc, const char **out, int cap);

//------------------------------------------------------------------------------------
// Queries
//------------------------------------------------------------------------------------

RAYSVGAPI RaysvgHandle RaysvgGetElementById(const RaysvgDoc *doc, const char *id);

// Fills `out` with up to `cap` handles of elements carrying `className`.
// Returns the total number of matches, which may exceed `cap`.
RAYSVGAPI int RaysvgGetElementsByClass(const RaysvgDoc *doc, const char *className, RaysvgHandle *out, int cap);

RAYSVGAPI RaysvgHandle RaysvgGetParent(const RaysvgDoc *doc, RaysvgHandle element);
RAYSVGAPI int RaysvgGetChildCount(const RaysvgDoc *doc, RaysvgHandle element);
RAYSVGAPI RaysvgHandle RaysvgGetChild(const RaysvgDoc *doc, RaysvgHandle element, int index);

// Element id, or "" when the element is anonymous. Owned by doc.
RAYSVGAPI const char *RaysvgGetElementId(const RaysvgDoc *doc, RaysvgHandle element);

//------------------------------------------------------------------------------------
// CSS custom properties
//
// Paints written as fill="var(--name)" resolve through this table at draw time, so a single
// call recolours every element referencing the variable.
//------------------------------------------------------------------------------------

RAYSVGAPI void RaysvgSetVar(RaysvgDoc *doc, const char *name, Color color);
RAYSVGAPI bool RaysvgGetVar(const RaysvgDoc *doc, const char *name, Color *out);

//------------------------------------------------------------------------------------
// Animation channels
//
// A transform channel replaces the element's parsed transform, matching how an inline
// style.transform overrides the transform attribute in the DOM. It is applied about the
// pivot: T(pivot) * translate * rotate * scale * T(-pivot).
// Pivot coordinates are in the element's own user-unit space.
//------------------------------------------------------------------------------------

RAYSVGAPI void RaysvgSetTransform(RaysvgDoc *doc, RaysvgHandle element,
                                  float translateX, float translateY,
                                  float rotationDeg, float scaleX, float scaleY);

// Drop the channel and fall back to the transform parsed from the document.
RAYSVGAPI void RaysvgClearTransform(RaysvgDoc *doc, RaysvgHandle element);

RAYSVGAPI void RaysvgSetPivot(RaysvgDoc *doc, RaysvgHandle element, float pivotX, float pivotY);

// opacity in [0,1]; pass a negative value to clear the channel.
RAYSVGAPI void RaysvgSetOpacity(RaysvgDoc *doc, RaysvgHandle element, float opacity);

RAYSVGAPI void RaysvgSetDisplay(RaysvgDoc *doc, RaysvgHandle element, bool visible);

// Siblings paint in (zIndex, document order) order. Default z is 0.
RAYSVGAPI void RaysvgSetZIndex(RaysvgDoc *doc, RaysvgHandle element, int zIndex);

// Move a subtree under a new parent, appending it as the last child.
// Fails when newParent is inside the moved subtree.
RAYSVGAPI bool RaysvgReparent(RaysvgDoc *doc, RaysvgHandle element, RaysvgHandle newParent);

// Draw a thick round-joined stroke of every contour in the subtree beneath its fills,
// producing the cartoon outline that an feMorphology dilate filter would give.
// `radius` is the dilate radius: the synthesized stroke is 2*radius wide.
RAYSVGAPI void RaysvgSetOutline(RaysvgDoc *doc, RaysvgHandle group, bool enabled, Color color, float radius);

//------------------------------------------------------------------------------------
// Rendering
//------------------------------------------------------------------------------------

// Fit the document into `dest` honouring preserveAspectRatio.
RAYSVGAPI void RaysvgDraw(RaysvgDoc *doc, Rectangle dest);

// Draw at an explicit origin and uniform scale (1.0 = one user unit per pixel).
RAYSVGAPI void RaysvgDrawEx(RaysvgDoc *doc, float x, float y, float scale);

// True when a channel or variable changed since the last draw. Hosts with on-demand frame
// scheduling can use this to decide whether another frame is needed. Cleared by drawing.
RAYSVGAPI bool RaysvgNeedsRedraw(const RaysvgDoc *doc);

// Curve flattening budget in device pixels (default 0.25). Lower is smoother and heavier.
RAYSVGAPI void RaysvgSetTolerance(RaysvgDoc *doc, float pixels);

// Drop every cached GPU resource. Call after a graphics device loss or context recreation;
// textures are rebuilt lazily on the next draw.
RAYSVGAPI void RaysvgNotifyGpuReset(RaysvgDoc *doc);

//------------------------------------------------------------------------------------
// Statistics (diagnostics and budget checks)
//------------------------------------------------------------------------------------

typedef struct RaysvgStats {
    int elementCount;       // nodes in the scene graph
    int shapeCount;         // drawable shapes
    int drawnShapes;        // shapes emitted by the last draw
    int drawnVertices;      // vertices emitted by the last draw
    int tessellations;      // (re)tessellations performed by the last draw
} RaysvgStats;

RAYSVGAPI RaysvgStats RaysvgGetStats(const RaysvgDoc *doc);

#ifdef __cplusplus
}
#endif

#endif // RAYSVG_H