Wuss sharp

CLAUDE.md

@@ -51,6 +51,8 @@ Success prints `++ Tests completed in Ns: N of N tests passed.`
 
 New source/header files must be added by hand to the relevant `set(..._SOURCES ...)` list and, for public headers, to `PUBLIC_HEADERS`, in `CMakeLists.txt` — there is no globbing.
 
+**Internal naming (see `wuss`).** Functions declared in a private `impl.h` and not part of the public header use a double-underscore prefix, e.g. `wuss__titlebar_height_for`; internal-only enum constants still use the module's normal single-underscore style (e.g. `wuss_WINDOW_STATE_TOGGLED`), matching public enums. Per-instance internal state that isn't part of the public appearance API (e.g. `struct wuss_window`'s toggled/maximised state) is kept as a bitflags enum with `wuss__window_*` accessor helpers rather than loose `int`/`bool` fields, leaving room to add flags without growing the struct.
+
 **Error handling.** No exceptions; functions return `result_t` (`include/base/result.h`). Each module reserves a `result_BASE_<MODULE>` offset block and defines its own `result_<MODULE>_*` codes starting from that base. Common generic codes (`result_OK`, `result_OOM`, `result_BAD_ARG`, etc.) live at `result_BASE_GENERIC`. Callers typically check `rc != result_OK` and propagate.
 
 **Debug/logging.** `include/base/debug.h` provides `logf_info/warning/error/fatal/abort`, plus `check(err)` (log-and-`goto failure`) and `sentinel` (unreachable-code marker), both of which are compiled out entirely when `NDEBUG` is set — don't rely on their side effects in release builds.

CMakeLists.txt

@@ -14,7 +14,7 @@ endif()
 
 list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/Modules/)
 
-project(DPTLib VERSION 0.5.0 DESCRIPTION "DPT's C Library" LANGUAGES C)
+project(DPTLib VERSION 0.6.0 DESCRIPTION "DPT's C Library" LANGUAGES C)
 
 # The values set in the toolchain file aren't available until this point.
 if(TARGET_RISCOS)
@@ -28,6 +28,7 @@ if(CCACHE_FOUND)
 endif(CCACHE_FOUND)
 
 option(USE_FORTIFY "Use Fortify" OFF)
+option(USE_ASAN "Build with AddressSanitizer and UndefinedBehaviorSanitizer" OFF)
 option(DPTLIB_IMAGES_READ_ONLY "Remove libpng write support" OFF)
 
 # Referencing CMAKE_TOOLCHAIN_FILE avoids a warning on rebuilds.
@@ -40,7 +41,7 @@ add_subdirectory(libraries/fortify)
 add_library(DPTLib)
 
 set_target_properties(DPTLib PROPERTIES
-    VERSION 0.5.0
+    VERSION 0.6.0
     DESCRIPTION "DPT's Portable C Library"
     C_STANDARD 99
     PREFIX ""  # remove 'lib' prefix
@@ -93,6 +94,7 @@ set(PUBLIC_HEADERS
     include/geom/line.h
     include/geom/packer.h
     include/geom/point.h
+    include/geom/size.h
     include/io/path.h
     include/io/stream-mem.h
     include/io/stream-mtfcomp.h
@@ -110,6 +112,7 @@ set(PUBLIC_HEADERS
     include/utils/maths.h
     include/utils/pack.h
     include/utils/primes.h
+    include/wuss/task.h
     include/wuss/window.h
     include/wuss/wuss.h)
 
@@ -253,6 +256,7 @@ set(GEOM_SOURCES
     libraries/geom/box/reset.c
     libraries/geom/box/round.c
     libraries/geom/box/round4.c
+    libraries/geom/box/size.c
     libraries/geom/box/translated.c
     libraries/geom/box/union.c
     libraries/geom/layout/layout.c
@@ -331,15 +335,16 @@ set(WUSS_SOURCES
     libraries/wuss/furniture/toggle-box.c
     libraries/wuss/furniture/vscroll-box.c
     libraries/wuss/furniture.h
+    libraries/wuss/get-font.c
     libraries/wuss/idle.c
     libraries/wuss/impl.h
     libraries/wuss/invalidate.c
     libraries/wuss/mouse-click.c
     libraries/wuss/mouse-move.c
     libraries/wuss/redraw.c
     libraries/wuss/scroll.c
-    libraries/wuss/task-start.c
-    libraries/wuss/task-stop.c
+    libraries/wuss/task/start.c
+    libraries/wuss/task/stop.c
     libraries/wuss/window/at.c
     libraries/wuss/window/create.c
     libraries/wuss/window/close.c
@@ -394,6 +399,11 @@ if(USE_FORTIFY)
     target_link_libraries(DPTLib PUBLIC Fortify)
 endif()
 
+if(USE_ASAN)
+    target_compile_options(DPTLib PUBLIC -fsanitize=address,undefined -g -O0)
+    target_link_options(DPTLib PUBLIC -fsanitize=address,undefined)
+endif()
+
 if(DPTLIB_IMAGES_READ_ONLY)
     target_compile_definitions(DPTLib PRIVATE DPTLIB_IMAGES_READ_ONLY)
 endif()
@@ -523,6 +533,7 @@ if(BUILD_TESTS)
         libraries/framebuf/bmfont/test/bmfont-test.c
         libraries/framebuf/composite/test/composite-test.c
         libraries/framebuf/curve/test/curve-test.c
+        libraries/framebuf/screen/test/screen-test.c
         libraries/geom/box/test/box-test.c
         libraries/geom/layout/test/layout-test.c
         libraries/geom/packer/test/packer-test.c
@@ -534,6 +545,7 @@ if(BUILD_TESTS)
         libraries/datastruct/vector/test/vector-test.c
         libraries/wuss/test/tasks/ball.c
         libraries/wuss/test/tasks/blank.c
+        libraries/wuss/test/tasks/chars.c
         libraries/wuss/test/tasks/checker.c
         libraries/wuss/test/tasks/curve.c
         libraries/wuss/test/tasks/gradient.c

README.md

@@ -1,6 +1,6 @@
 # DPTLib
 
-version 0.5.0
+version 0.6.0
 
 [![Build status](https://github.com/dpt/DPTLib/actions/workflows/ci.yml/badge.svg)](https://github.com/dpt/DPTLib/actions)
 

apps/test/main.c

@@ -54,6 +54,7 @@ static const test_t tests[] =
   { "bmfont",     bmfont_test     },
   { "composite",  composite_test  },
   { "curve",      curve_test      },
+  { "screen",     screen_test     },
 
   { "box",        box_test        },
   { "layout",     layout_test     },

docs/framebuf/bmfont.md

@@ -2,15 +2,15 @@
 
 "bmfont" is a sub-library of DPTLib for drawing proportionally spaced bitmap fonts. It reads font definitions from PNG files like this:
 
-![Henry Font](../resources/bmfonts/henry-font.png)
+![Henry Font](../resources/bmfonts/henry.png)
 
 or this:
 
-![Digits Font](../resources/bmfonts/digits-font.png)
+![Digits Font](../resources/bmfonts/digits.png)
 
 or even this:
 
-![Tiny Font](../resources/bmfonts/tiny-font.png)
+![Tiny Font](../resources/bmfonts/tiny.png)
 
 ...which have the glyphs laid out in a grid, with extra lines inserted, that define the advance widths.
 

docs/wuss.md

@@ -20,38 +20,40 @@ result_t wuss_create(screen_t             *scr,
                      wuss_t              **wuss);
 ```
 
-`font` and `palette` may both be NULL, for unlabelled titlebars and a built-in default palette respectively. `config` may be NULL for default titlebar height/colours.
+`font` and `palette` may both be NULL, for unlabelled titlebars and a built-in default palette respectively. `config` may be NULL for default titlebar height/colours. `config->backdrop` sets a desktop background colour painted behind windows on every redraw, or `wuss_NO_BACKGROUND` (the default when `config` is NULL) to leave the background untouched and require the caller to repaint it itself. `wuss_get_font` reads back the font passed in (or NULL), for a task that wants to draw its own content in the same face as titlebars.
 
 Destroy with `wuss_destroy`, which also destroys any windows still open on it.
 
 ## Windows
 
-Create a window with a content bounding box, optional title, appearance flags and a task delegate:
+Create a window with a content bounding box, optional title, appearance flags, a content background and a task delegate:
 
 ```C
 result_t wuss_window_create(wuss_t *wuss, const box_t *content, const char *title,
-                            wuss_window_flags_t flags, const wuss_task_t *task,
-                            int doc_width, int doc_height,
+                            wuss_window_flags_t flags, wuss_colour_t bg,
+                            const wuss_task_t *task,
+                            size2d_t doc,
                             wuss_window_t **window);
 ```
 
-`doc_width`/`doc_height` are the virtual document extent behind the horizontal/vertical scrollbars' sausage proportion; pass `content`'s own width/height for a window with nothing to scroll. Set once at creation, immutable thereafter.
+`bg` is filled in by wuss before each redraw event, or `wuss_NO_BACKGROUND` for the task to draw its own background (avoids a redundant fill behind an opaque task); changeable later via `wuss_window_set_background`.
+
+`doc` is the virtual document extent behind the horizontal/vertical scrollbars' sausage proportion; pass `content`'s own width/height for a window with nothing to scroll. Set once at creation, immutable thereafter.
 
 Furniture is additional to `content`, not carved out of it: the window's content area always ends up exactly the box requested, and its on-screen footprint (`wuss_window_get_visible_bounds`) is `content` expanded outward by whatever furniture flags request — a titlebar above, and/or a 1px outline around all four sides.
 
-`wuss_task_t` holds the task's event callback and its content background:
+`wuss_task_t` holds the task's event callback:
 
 ```C
 typedef struct wuss_task
 {
   wuss_event_fn_t *handle;       /* NULL => task receives no events */
   void            *task_data;
-  wuss_colour_t    bg;           /* filled by wuss before a redraw event, or wuss_NO_BACKGROUND */
 }
 wuss_task_t;
 ```
 
-`wuss_task_make` builds one from `handle`/`task_data`/`bg`.
+`wuss_task_start` builds one from `handle`/`task_data`.
 
 `flags` combines, by bitwise OR:
 
@@ -64,8 +66,9 @@ wuss_task_t;
 - `wuss_WINDOW_NO_VSCROLL` — no vertical scrollbar on the right edge.
 - `wuss_WINDOW_NO_HSCROLL` — no horizontal scrollbar on the bottom edge.
 - `wuss_WINDOW_NO_RESIZE` — no resize icon in the bottom-right corner.
+- `wuss_WINDOW_NO_RESIZE_BLIT` — a resize (drag or toggle-size) always fully redraws the window's content instead of blitting the preserved region; for a task whose rendering depends on window size in ways a partial redraw can't patch (e.g. a layout that spans the whole window).
 
-`wuss_WINDOW_NO_CLOSE`/`NO_BACK`/`NO_TOGGLE_SIZE` are ignored if `flags` includes `wuss_WINDOW_NO_TITLEBAR`; `NO_VSCROLL`/`NO_HSCROLL`/`NO_RESIZE` apply regardless.
+`wuss_WINDOW_NO_CLOSE`/`NO_BACK`/`NO_TOGGLE_SIZE` are ignored if `flags` includes `wuss_WINDOW_NO_TITLEBAR`; `NO_VSCROLL`/`NO_HSCROLL`/`NO_RESIZE`/`NO_RESIZE_BLIT` apply regardless.
 
 All furniture actions (back, toggle-size, resize-drag, scrollbar arrow/thumb) are handled entirely within Wuss via `wuss_mouse_click`/`wuss_mouse_move` — no new client events.
 
@@ -111,19 +114,19 @@ Feed mouse events in with `wuss_mouse_click` (action `wuss_MOUSE_DOWN` or `wuss_
 
 ## Scrolling
 
-Each window carries a scroll offset, `(0, 0)` by default: the point in the task's virtual content space that appears at the content area's top-left. `wuss_window_set_scroll(window, x, y)` moves it (invalidating the content area so the next redraw picks it up); `wuss_window_get_scroll` reads it back. `wuss_scroll` applies this offset itself as Wuss's default scroll action, clamped to `doc_width`/`doc_height` (set at window creation), before also delivering `wuss_EVENT_SCROLL` to the task if it has a handle:
+Each window carries a scroll offset, `(0, 0)` by default: the point in the task's virtual content space that appears at the content area's top-left. `wuss_window_set_scroll(window, x, y)` moves it (invalidating the content area so the next redraw picks it up); `wuss_window_get_scroll` reads it back. `wuss_scroll` applies this offset itself as Wuss's default scroll action, clamped to `doc` (set at window creation), before also delivering `wuss_EVENT_SCROLL` to the task if it has a handle:
 
 - window-local `x`/`y` delivered in mouse/scroll events (and expected in `wuss_window_invalidate`'s `local_box`) are in virtual content space, i.e. already shifted by the scroll offset.
 - a redraw event's `content` is still the on-screen (unscrolled) content box; a task reads the offset itself via `wuss_window_get_scroll` to work out which part of its content to paint there.
 
 ## Redrawing
 
-- `wuss_redraw` repaints every window, back-to-front, unconditionally.
+- `wuss_redraw` repaints every window, back-to-front, unconditionally, having first painted the configured backdrop colour (see Setup) behind them, if any.
 - `wuss_invalidate` / `wuss_window_invalidate` mark a screen-space or window-local region dirty; window management calls these automatically for its own changes, but a task must call one of them itself whenever its content changes on its own (e.g. an animation), passing the union of the old and new areas that need repainting.
-- `wuss_redraw_dirty` repaints only the accumulated dirty region, then clears it. Wuss only repaints windows, not the background between/behind them, so a caller whose invalidation can expose background (e.g. after a window move) should clear that region itself first.
-- `wuss_get_dirty` fetches the current accumulated dirty region without redrawing.
+- `wuss_redraw_dirty` repaints only the accumulated dirty region, then clears it, painting the backdrop colour into each dirty region first if one was configured. Without a configured backdrop, Wuss only repaints windows, not the background between/behind them, so a caller whose invalidation can expose background (e.g. after a window move) should clear that region itself first.
+- `wuss_get_dirty_count`/`wuss_get_dirty(wuss, index, out)` fetch the currently accumulated dirty regions (coalesced as they accumulate, up to a fixed cap after which further regions are merged into the last one) without redrawing.
+- A window move or resize is clipped, piece by piece, against whatever's above it in the z-order, and any pixels a move can preserve are blitted directly rather than queued dirty; only the genuinely-changed pieces end up in the dirty region. This is an internal optimisation with no effect on a task's own redraw handling.
 
 ## Limitations
 
 - No menus: `wuss_BUTTON_MENU` is defined and routed like any other button, but Wuss has no built-in menu widget.
-- No overlapping-window damage tracking finer than each window's own bounding box.

include/databases/digest-db.h

@@ -5,9 +5,9 @@
  *
  * Digest database.
  *
- * digestdb is a wrapper around an atom set specifically for holding
- * (128-bit) digests. It is used by tagdb and filenamedb to share the cost of
- * storing digest values by replacing 128-bit digests with smaller indices.
+ * digestdb is a wrapper around an atom set specifically for holding (128-bit)
+ * digests. It is used by tagdb and filenamedb to share the cost of storing
+ * digest values by replacing 128-bit digests with smaller indices.
  */
 
 #ifndef DATABASES_DIGEST_DB_H

include/databases/filename-db.h

@@ -5,8 +5,8 @@
  *
  * Filename database.
  *
- * The filenamedb is an associative array which maps keys (such as digests)
- * to filenames. The data is stored on disc.
+ * The filenamedb is an associative array which maps keys (such as digests) to
+ * filenames. The data is stored on disc.
  *
  * PrivateEye uses this to find out where an image lives given its digest.
  */

include/databases/pickle.h

@@ -6,12 +6,10 @@
  * Storage of associative arrays.
  *
  * Its name borrowed from Python, this module provides pickle_pickle() and
- * pickle_unpickle() which respectively serialise or deserialise an
- * associative array to a file of the form:
+ * pickle_unpickle() which respectively serialise or deserialise an associative
+ * array to a file of the form:
  *
- *   #<comments>
- *   <version>
- *   <key><separator><value>  (zero or more)
+ *   #<comments> <version> <key><separator><value>  (zero or more)
  *
  * When serialising, keys and values are read from through an abstract
  * pickle_reader_methods interface. They are then transformed into savable
@@ -242,9 +240,9 @@ pickle_unformat_methods_t;
 /* ----------------------------------------------------------------------- */
 
 /**
- * Serialise associative array 'assocarr' to the file 'filename'. Interpret
- * the contents of the associative array using the methods in 'reader'.
- * Format the keys and values for storage using the methods in 'format'.
+ * Serialise associative array 'assocarr' to the file 'filename'. Interpret the
+ * contents of the associative array using the methods in 'reader'. Format the
+ * keys and values for storage using the methods in 'format'.
  *
  * \param[in]   filename    Filename to save to.
  * \param[in]   assocarr    Associative array to pickle.
@@ -261,9 +259,9 @@ result_t pickle_pickle(const char                    *filename,
                        void                          *opaque);
 
 /**
- * Populate associative array 'assocarr' from the file 'filename'. Insert
- * into the associative array using the methods in 'writer'. Parse
- * the keys and values from storage using the methods in 'unformat'.
+ * Populate associative array 'assocarr' from the file 'filename'. Insert into
+ * the associative array using the methods in 'writer'. Parse the keys and
+ * values from storage using the methods in 'unformat'.
  *
  * \param[in]   filename    Filename to read from.
  * \param[in]   assocarr    Associative array to pickle.

include/datastruct/atom.h

@@ -6,16 +6,15 @@
  * Indexed data block store.
  *
  * Atoms are indices assigned to blocks of stored data. Identical data blocks
- * are assigned the same atom. Atoms belonging to the same set can be
- * directly compared avoiding the need to memcmp, strcmp, or otherwise
- * linearly compare the contents of the respective data blocks.
+ * are assigned the same atom. Atoms belonging to the same set can be directly
+ * compared avoiding the need to memcmp, strcmp, or otherwise linearly compare
+ * the contents of the respective data blocks.
  *
- * Data blocks can be retrieved by quoting an atom to atom_get. This returns
- * a pointer to the data block along with its length.
+ * Data blocks can be retrieved by quoting an atom to atom_get. This returns a
+ * pointer to the data block along with its length.
  *
- * To avoid heap overhead, atoms are stored in a series of fixed-size pools
- * of memory. The size of the pools may be specified when the set is first
- * created.
+ * To avoid heap overhead, atoms are stored in a series of fixed-size pools of
+ * memory. The size of the pools may be specified when the set is first created.
  */
 
 #ifndef DATASTRUCT_ATOM_H
@@ -57,15 +56,13 @@ atom_set_t *atom_create(void);
 /**
  * Create a new atom set using the specified data sizes.
  *
- * \param locpoolsz Size of a location pool, or zero for the default.
- *                  Set this to the number of entries you typically expect to
- *                  store.
- * \param blkpoolsz Size of a block pool, or zero for the default.
- *                  No inserted data block may be larger than this.
- *                  Increasing this value will use fewer individual block
- *                  pools, reducing heap overhead, at the expense of
- *                  potentially greater wasted space should the block pool
- *                  remain not fully allocated.
+ * \param locpoolsz Size of a location pool, or zero for the default. Set this
+ *                  to the number of entries you typically expect to store.
+ * \param blkpoolsz Size of a block pool, or zero for the default. No inserted
+ *                  data block may be larger than this. Increasing this value
+ *                  will use fewer individual block pools, reducing heap
+ *                  overhead, at the expense of potentially greater wasted space
+ *                  should the block pool remain not fully allocated.
  *
  * \return New atom set, or NULL if out of memory.
  */
@@ -117,8 +114,8 @@ void atom_delete(atom_set_t *set, atom_t atom);
  *
  * \param      set    Atom set.
  * \param      atom   Atom to retrieve.
- * \param[out] length Length of data block, in bytes.
- *                    NULL if length is not required.
+ * \param[out] length Length of data block, in bytes. NULL if length is not
+ *                    required.
  *
  * \return Data block.
  */
@@ -159,8 +156,8 @@ atom_t atom_for_block(atom_set_t          *set,
 /**
  * Delete an existing atom specified by data block.
  *
- * This is a convenience function equivalent to:
- *   atom_delete(set, atom_for_block(set, block, length)).
+ * This is a convenience function equivalent to: atom_delete(set,
+ * atom_for_block(set, block, length)).
  *
  * \param set    Atom set.
  * \param block  Data block to retrieve.