Systematically refine memory consumption

This introduces mechanisms to eliminate per-frame heap allocations from
the rendering hot path and provide memory visibility for constrained
devices:

Scratch arena: a 32 KB bump allocator on twin_screen_t, reset per screen
update. Polygon edge arrays (poly.c), composite mask pixmaps (path.c),
and convex hull arrays (hull.c) allocate from the arena first, falling
back to malloc only when exhausted. Save/restore semantics support
nested temporary allocations.

Reusable object caches: a 4-element path cache (acquire/release) avoids
repeated create/destroy for stroke rendering temporaries. A grow-only A8
mask cache on twin_screen_t eliminates per-composite malloc for masks
exceeding the scratch arena.

Inline path storage: struct _twin_path embeds 64-point and 4-sublen
arrays, avoiding heap allocation entirely for typical small paths
(rectangles, circles, rounded rectangles). Growth from inline to heap
uses malloc+memcpy; destroy only frees heap-allocated arrays.

Memory tracking (CONFIG_MEMORY_STATS, default y): twin_malloc/twin_free
wrapper macros route all core allocations through a tracking layer that
maintains current/peak byte counters and alloc/free counts. The tracker
uses a linear-scan table with inline storage -- no heap allocation for
bookkeeping itself. Public API: twin_memory_{get_info,reset_peak}.
twin_destroy() logs stats after teardown. CI workflow captures memory
statistics from headless test runs.

Budget-aware APIs: twin_pixmap_create_budget() computes the largest
pixmap fitting a byte budget while preserving aspect ratio.
twin_tvg_to_pixmap_budget() auto-scales TVG rendering to fit a memory
budget. CONFIG_TVG_MEMORY_BUDGET Kconfig option caps per-image memory.
The ARGB32-only restriction on TVG rendering is removed -- RGB16 now
works, halving memory for opaque content.

Additional optimizations: the image viewer app evicts previous pixmaps
instead of caching all six TVG images simultaneously. Background
loading skips full-screen scaling when the source fits within screen
dimensions. twin_destroy() centralizes screen teardown that backends
previously omitted.

Closes #149

Author: jserv

.github/workflows/headless-test.yml

@@ -35,8 +35,8 @@ jobs:
 
     - name: Run basic headless test
       run: |
-        # Start demo in background
-        timeout 30s ./demo-headless &
+        # Start demo in background, capture stderr for memory stats
+        timeout 30s ./demo-headless 2>demo_stderr.log &
         DEMO_PID=$!
         echo "Started demo-headless with PID $DEMO_PID"
 
@@ -62,6 +62,13 @@ jobs:
         wait $DEMO_PID || true
         echo "Basic test completed"
 
+    - name: Report memory statistics
+      if: always()
+      run: |
+        echo "=== Mado Memory Statistics ==="
+        grep -i "memory" demo_stderr.log 2>/dev/null || echo "(no memory stats in output)"
+        cat demo_stderr.log 2>/dev/null || true
+
     - name: Verify screenshot output
       run: |
         test -f test_output.png || (echo "Screenshot not created" && exit 1)
@@ -106,7 +113,7 @@ jobs:
           --errors-for-leak-kinds=definite \
           --error-exitcode=1 \
           --log-file=valgrind.log \
-          ./demo-headless &
+          ./demo-headless 2>valgrind_demo_stderr.log &
         VALGRIND_PID=$!
 
         sleep 5
@@ -124,6 +131,10 @@ jobs:
         grep -A 10 "LEAK SUMMARY" valgrind.log || true
         grep "ERROR SUMMARY" valgrind.log || true
 
+        # Display memory statistics from twin_destroy
+        echo "=== Mado Memory Statistics (Valgrind run) ==="
+        grep -i "memory" valgrind_demo_stderr.log 2>/dev/null || true
+
         # Check for definite leaks
         if grep -q "definitely lost: [1-9]" valgrind.log; then
           echo "ERROR: Memory leaks detected"

Makefile

@@ -87,6 +87,7 @@ src/composite-decls.h: scripts/gen-composite-decls.py
 
 libtwin.a_files-$(CONFIG_LOGGING) += src/log.c
 libtwin.a_files-$(CONFIG_CURSOR) += src/cursor.c
+libtwin.a_files-y += src/memstats.c
 
 # Rendering backends
 # Screen compositing operations (always needed for screen buffer management)

apps/image.c

@@ -20,8 +20,18 @@ static inline twin_pixmap_t *_apps_image_pixmap(twin_custom_widget_t *image)
 #define APP_WIDTH 400
 #define APP_HEIGHT 400
 
+static twin_pixmap_t *load_tvg(const char *path)
+{
+#if defined(CONFIG_TVG_MEMORY_BUDGET) && CONFIG_TVG_MEMORY_BUDGET > 0
+    return twin_tvg_to_pixmap_budget(path, TWIN_ARGB32,
+                                     (size_t) CONFIG_TVG_MEMORY_BUDGET * 1024);
+#else
+    return twin_tvg_to_pixmap_scale(path, TWIN_ARGB32, APP_WIDTH, APP_HEIGHT);
+#endif
+}
+
 typedef struct {
-    twin_pixmap_t **pixes;
+    twin_pixmap_t *current_pix; /* only the visible image is kept */
     int image_idx;
 } apps_image_data_t;
 
@@ -44,9 +54,11 @@ static void _apps_image_paint(twin_custom_widget_t *custom)
 {
     apps_image_data_t *img =
         (apps_image_data_t *) twin_custom_widget_data(custom);
+    if (!img->current_pix)
+        return;
     twin_operand_t srcop = {
         .source_kind = TWIN_PIXMAP,
-        .u.pixmap = img->pixes[img->image_idx],
+        .u.pixmap = img->current_pix,
     };
 
     twin_composite(_apps_image_pixmap(custom), 0, 0, &srcop, 0, 0, NULL, 0, 0,
@@ -67,6 +79,15 @@ static twin_dispatch_result_t _apps_image_dispatch(twin_widget_t *widget,
     case TwinEventPaint:
         _apps_image_paint(custom);
         break;
+    case TwinEventDestroy: {
+        apps_image_data_t *img =
+            (apps_image_data_t *) twin_custom_widget_data(custom);
+        if (img->current_pix) {
+            twin_pixmap_destroy(img->current_pix);
+            img->current_pix = NULL;
+        }
+        break;
+    }
     default:
         break;
     }
@@ -87,13 +108,15 @@ static twin_dispatch_result_t _apps_image_button_clicked(twin_widget_t *widget,
         (apps_image_data_t *) twin_custom_widget_data(custom);
     const int n = sizeof(tvg_files) / sizeof(tvg_files[0]);
     img->image_idx = img->image_idx == n - 1 ? 0 : img->image_idx + 1;
-    if (!img->pixes[img->image_idx]) {
-        twin_pixmap_t *pix = twin_tvg_to_pixmap_scale(
-            tvg_files[img->image_idx], TWIN_ARGB32, APP_WIDTH, APP_HEIGHT);
-        if (!pix)
-            return TwinDispatchContinue;
-        img->pixes[img->image_idx] = pix;
+
+    /* Evict the old pixmap before loading the new one */
+    if (img->current_pix) {
+        twin_pixmap_destroy(img->current_pix);
+        img->current_pix = NULL;
     }
+    img->current_pix = load_tvg(tvg_files[img->image_idx]);
+    if (!img->current_pix)
+        return TwinDispatchContinue;
     twin_custom_widget_queue_paint(custom);
     return TwinDispatchDone;
 }
@@ -109,10 +132,7 @@ static twin_custom_widget_t *_apps_image_init(twin_box_t *parent)
     apps_image_data_t *img =
         (apps_image_data_t *) twin_custom_widget_data(custom);
     img->image_idx = 0;
-    img->pixes = calloc(sizeof(tvg_files) / sizeof(tvg_files[0]),
-                        sizeof(twin_pixmap_t *));
-    img->pixes[0] = twin_tvg_to_pixmap_scale(tvg_files[0], TWIN_ARGB32,
-                                             APP_WIDTH, APP_HEIGHT);
+    img->current_pix = load_tvg(tvg_files[0]);
 
     twin_button_t *button =
         twin_button_create(parent, "Next Image", 0xFF482722, D(10),

apps/main.c

@@ -29,40 +29,43 @@
  * Load the background pixmap from storage.
  * Return a default pattern if the load of @path or image loader fails.
  */
+/*
+ * Load the background pixmap from storage.
+ * The screen compositor tiles backgrounds smaller than the screen,
+ * so scaling is only needed when the source is larger.  When the
+ * source fits, use it directly to avoid a full-screen allocation.
+ */
 static twin_pixmap_t *load_background(twin_screen_t *screen, const char *path)
 {
     twin_pixmap_t *raw_background = twin_pixmap_from_file(path, TWIN_ARGB32);
-    if (!raw_background) /* Fallback to a default pattern */
+    if (!raw_background)
         return twin_make_pattern();
 
-    if (screen->height == raw_background->height &&
-        screen->width == raw_background->width)
+    /* Source fits on screen -- use directly (tiles if smaller) */
+    if (raw_background->width <= screen->width &&
+        raw_background->height <= screen->height)
         return raw_background;
 
-    /* Scale as needed. */
-    twin_pixmap_t *scaled_background =
+    /* Source is larger -- scale down to screen size */
+    twin_pixmap_t *scaled =
         twin_pixmap_create(TWIN_ARGB32, screen->width, screen->height);
-    if (!scaled_background) {
+    if (!scaled) {
         twin_pixmap_destroy(raw_background);
         return twin_make_pattern();
     }
-    twin_fixed_t sx, sy;
-    sx = twin_fixed_div(twin_int_to_fixed(raw_background->width),
-                        twin_int_to_fixed(screen->width));
-    sy = twin_fixed_div(twin_int_to_fixed(raw_background->height),
-                        twin_int_to_fixed(screen->height));
-
+    twin_fixed_t sx = twin_fixed_div(twin_int_to_fixed(raw_background->width),
+                                     twin_int_to_fixed(screen->width));
+    twin_fixed_t sy = twin_fixed_div(twin_int_to_fixed(raw_background->height),
+                                     twin_int_to_fixed(screen->height));
     twin_matrix_scale(&raw_background->transform, sx, sy);
     twin_operand_t srcop = {
         .source_kind = TWIN_PIXMAP,
         .u.pixmap = raw_background,
     };
-    twin_composite(scaled_background, 0, 0, &srcop, 0, 0, NULL, 0, 0,
-                   TWIN_SOURCE, screen->width, screen->height);
-
+    twin_composite(scaled, 0, 0, &srcop, 0, 0, NULL, 0, 0, TWIN_SOURCE,
+                   screen->width, screen->height);
     twin_pixmap_destroy(raw_background);
-
-    return scaled_background;
+    return scaled;
 }
 
 static twin_context_t *tx = NULL;

configs/Kconfig

@@ -171,6 +171,15 @@ config LOGGING_CALLBACK
       Allow custom callback functions for log handling.
       Enables application-specific log processing.
 
+config MEMORY_STATS
+    bool "Enable memory usage tracking"
+    default y
+    help
+      Track heap allocation statistics including current usage,
+      peak usage, and allocation counts. Adds small overhead per
+      malloc/free call. Useful for profiling memory consumption
+      on constrained devices.
+
 comment "Logging is disabled"
     depends on !LOGGING
 
@@ -251,6 +260,16 @@ config LOADER_TVG
       Enable TinyVG vector graphics format support.
       Compact binary format for scalable graphics.
 
+config TVG_MEMORY_BUDGET
+    int "TVG rendering memory budget (KB)"
+    default 0
+    depends on LOADER_TVG
+    help
+      Maximum memory in kilobytes for a single TVG pixmap.
+      The renderer auto-scales the output to fit within this
+      budget while preserving aspect ratio.
+      Set to 0 for unlimited (use native document dimensions).
+
 endmenu
 
 menu "Demo Applications"

configs/defconfig

@@ -8,3 +8,4 @@ CONFIG_DEMO_CLOCK=y
 CONFIG_DEMO_CALCULATOR=y
 CONFIG_DEMO_SPLINE=y
 CONFIG_DEMO_ANIMATION=y
+CONFIG_MEMORY_STATS=y

include/twin.h

@@ -348,6 +348,21 @@ struct _twin_screen {
     twin_argb32_t *span_cache;     /**< Cached span buffer */
     twin_coord_t span_cache_width; /**< Cached span buffer width */
 
+    /* Scratch arena for per-frame temporary allocations */
+    void *scratch_buf;   /**< Scratch buffer (bump allocator) */
+    size_t scratch_size; /**< Scratch buffer capacity in bytes */
+
+    /* Reusable path object cache to avoid repeated alloc/free */
+#define TWIN_PATH_CACHE_SIZE 4
+    struct _twin_path *path_cache[TWIN_PATH_CACHE_SIZE];
+    int path_cache_count;
+
+    /* Cached A8 mask pixmap for twin_composite_path -- avoids
+     * per-composite malloc for masks larger than the scratch arena. */
+    twin_pixmap_t *mask_cache;
+    twin_coord_t mask_cache_width;
+    twin_coord_t mask_cache_height;
+
     /* Event processing: event filter callback */
     bool (*event_filter)(twin_screen_t *screen, twin_event_t *event);
 };
@@ -1582,6 +1597,28 @@ twin_pixmap_t *twin_tvg_to_pixmap_scale(const char *filepath,
                                         twin_coord_t w,
                                         twin_coord_t h);
 
+twin_pixmap_t *twin_tvg_to_pixmap_budget(const char *filepath,
+                                         twin_format_t fmt,
+                                         size_t memory_budget);
+
+twin_pixmap_t *twin_pixmap_create_budget(twin_format_t format,
+                                         twin_coord_t max_width,
+                                         twin_coord_t max_height,
+                                         size_t memory_budget);
+
+/**
+ * Memory usage statistics (requires CONFIG_MEMORY_STATS)
+ */
+typedef struct _twin_memory_info {
+    size_t current_bytes; /**< Currently allocated heap bytes */
+    size_t peak_bytes;    /**< High-water mark */
+    size_t total_allocs;  /**< Lifetime allocation count */
+    size_t total_frees;   /**< Lifetime free count */
+} twin_memory_info_t;
+
+void twin_memory_get_info(twin_memory_info_t *info);
+void twin_memory_reset_peak(void);
+
 twin_context_t *twin_create(int width, int height);
 
 void twin_destroy(twin_context_t *ctx);

src/animation.c

@@ -5,7 +5,7 @@
  */
 #include <stdlib.h>
 
-#include "twin.h"
+#include "twin_private.h"
 
 twin_time_t twin_animation_get_current_delay(const twin_animation_t *anim)
 {
@@ -33,18 +33,18 @@ void twin_animation_destroy(twin_animation_t *anim)
     if (!anim)
         return;
 
-    free(anim->iter);
+    twin_free(anim->iter);
     for (twin_count_t i = 0; i < anim->n_frames; i++) {
         twin_pixmap_destroy(anim->frames[i]);
     }
-    free(anim->frames);
-    free(anim->frame_delays);
-    free(anim);
+    twin_free(anim->frames);
+    twin_free(anim->frame_delays);
+    twin_free(anim);
 }
 
 twin_animation_iter_t *twin_animation_iter_init(twin_animation_t *anim)
 {
-    twin_animation_iter_t *iter = malloc(sizeof(twin_animation_iter_t));
+    twin_animation_iter_t *iter = twin_malloc(sizeof(twin_animation_iter_t));
     if (!iter || !anim)
         return NULL;
     iter->current_index = 0;

src/api.c

@@ -57,7 +57,25 @@ void twin_destroy(twin_context_t *ctx)
 
     assert(g_twin_backend.exit && "Backend not registered");
 
+    /* Screen teardown may emit damage callbacks through backend-owned closure.
+     */
+    if (ctx->screen) {
+        twin_screen_destroy(ctx->screen);
+        ctx->screen = NULL;
+    }
+
+    /* Backend frees its private data and ctx */
     g_twin_backend.exit(ctx);
+
+    /* Report memory statistics after all teardown */
+    twin_memory_info_t mem;
+    twin_memory_get_info(&mem);
+    if (mem.peak_bytes)
+        log_info(
+            "Memory: current %zu bytes, peak %zu bytes, "
+            "allocs %zu, frees %zu",
+            mem.current_bytes, mem.peak_bytes, mem.total_allocs,
+            mem.total_frees);
 }
 
 /**

src/box.c

@@ -228,7 +228,7 @@ twin_dispatch_result_t _twin_box_dispatch(twin_widget_t *widget,
 
 twin_box_t *twin_box_create(twin_box_t *parent, twin_box_dir_t dir)
 {
-    twin_box_t *box = malloc(sizeof(twin_box_t));
+    twin_box_t *box = twin_malloc(sizeof(twin_box_t));
     if (!box)
         return NULL;