This project is part of the @thi.ng/umbrella monorepo.
- Usage examples
- How it works
- SVG conversion
- Supported shape types
@thi.ng/hdom component wrapper for declarative canvas scenegraphs.
This package provides a re-usable canvas component, which accepts child nodes defining a scene tree of different shape types in standard @thi.ng/hiccup syntax/format (i.e. nested arrays) and then translates these into canvas API draw calls during the hdom update process / cycle.
STABLE - used in production
BREAKING CHANGES 3.0.0
The actual tree traversal & drawing has been extracted to the new @thi.ng/hiccup-canvas package for better re-usability, also outside without hdom.
- @thi.ng/geom - Functional, polymorphic API for 2D geometry types & SVG generation
- @thi.ng/hdom - Lightweight vanilla ES6 UI component trees with customizable branch-local behaviors
- @thi.ng/hiccup-canvas - Hiccup shape tree renderer for vanilla Canvas 2D contexts
- @thi.ng/hiccup-svg - SVG element functions for @thi.ng/hiccup & @thi.ng/hdom
yarn add @thi.ng/hdom-canvas
// ES module// UMD
Package sizes (gzipped, pre-treeshake): ESM: 913 bytes / CJS: 982 bytes / UMD: 1.06 KB
Several demos in this repo's /examples directory are using this package.
|Interactive inverse FFT toy synth||Demo||Source|
|Doodle w/ K-nearest neighbor search result visualization||Demo||Source|
|Poisson-disk shape-aware sampling, Voronoi & Minimum Spanning Tree visualization||Demo||Source|
|Realtime analog clock demo||Demo||Source|
|Interactive pattern drawing demo using transducers||Demo||Source|
|2D Bezier curve-guided particle system||Demo||Source|
|Various hdom-canvas shape drawing examples & SVG conversion / export||Demo||Source|
|Canvas based Immediate Mode GUI components||Demo||Source|
|Animated sine plasma effect visualized using contour lines||Demo||Source|
|Basic rstream-gestures multi-touch demo||Demo||Source|
|Unison wavetable synth with waveform editor||Demo||Source|
|Animated Voronoi diagram, cubic splines & SVG download||Demo||Source|
|2D scenegraph & shape picking||Demo||Source|
|2D scenegraph & image map based geometry manipulation||Demo||Source|
|Fork-join worker-based raymarch renderer||Demo||Source|
Usage with @thi.ng/geom shape primitives:
How it works
The package provides a
canvas component which uses the branch-local
behavior implementation feature of
v5.0.0 to support virtual SVG-like shape elements / components. These
are defined as part of the main UI component tree just like any other
component, but are then translated into canvas API draw commands during
the hdom update process. Any embedded shape component functions receive
the user context object as first arg, just like normal hdom components.
Shape components are expressed in standard hiccup syntax (or as objects
IToHiccup() interface, like the shape types provided
and with the following...
Restrictions & behavior controls
- Shape component objects with life cycle methods are only partially
supported, i.e. only the
releasemethods are used.
- For performance reasons
releasemethods are disabled by default. If your shape tree contains stateful components which use the
releaselife cycle method, you'll need to explicitly enable the canvas component's
__releasecontrol attribute by setting it to
- Currently no event listeners can be assigned to shapes (ignored), though this is planned for a future version. The canvas element itself can of course have event handlers as usual.
For best performance it's recommended to ensure all resulting shapes elements are provided in already normalized hiccup format, i.e.
That way the
__normalize: false control attribute can be added either
to the canvas component itself (or to individual shapes / groups), and
if present, will skip normalization of that element's children.
Likewise, for animated scenes, the
__diff control attribute should be
false to skip unnecessary diffing and force redraws.
To disable the automatic background clearing of the canvas, set the
__clear attribute to
The canvas component automatically adjusts its size for HDPI displays by
height properties and pre-scaling the drawing
context accordingly before any shapes are processed. For fullscreen
canvases simply set the
height attribs to:
Even though the element names & syntax are very similar to SVG
elements, for performance reasons all geometry data given to each shape
remains un-stringified (only styling attributes are). However, the
package provides a
convertTree() function which takes the arguably
more "raw" shape format used by hdom-canvas and converts an entire shape
tree into SVG compatible & serializable format. Note: the tree MUST
first be normalized (if not already) using hdom-canvas'
;;;serializesvg,convertTreenormalizeTree, // default normalization options;
Supported shape types
Please see the @thi.ng/hiccup-canvas README for the full list of supported shapes, gradients, attributes, colors and transformations.
- Karsten Schmidt (@postspectacular)
- Arthur Carabott (@acarabott)
© 2018 - 2020 Karsten Schmidt // Apache Software License 2.0