API conventions
A few conventions hold across the whole datumhue.* API. Once you know
them, most entries of the reference read at a glance.
Values and handles
| Convention | In practice |
|---|---|
Colors are Color values. | datumhue.color("#e67e80"), datumhue.color(1, 0.5, 0) with channels from 0 to 1, or a named form such as color.hsl. Programs usually start with local color = datumhue.color. |
| Small values do not change. | A Vec2, Vec3, Quat or Color has read-only fields. Make a new one with arithmetic or a method such as Vec2:with_x. |
| Everything else is a handle. | A call that makes something returns a typed handle: a DrawCanvas, a UiElement, a Scene. A handle has its own methods and properties, compares with == and prints with tostring; it is not a number or a table. |
| State is a property; an action is a method. | Assigning a label's UiElement.text changes it, and calling DrawCanvas:circle draws on a canvas. The reference marks the properties you can only read. |
Calls
| Convention | In practice |
|---|---|
| Settings go in one option table. | datumhue.draw.new({ width = 320, height = 240 }). A key you leave out takes the default the reference lists, and a key the call does not know raises, naming the keys it takes. Drawing on a Picture is the exception: Picture:circfill, Picture:line and its other drawing calls take their arguments in order. |
| Making is not showing. | datumhue.draw.new, datumhue.image.new and datumhue.scene.new make something to draw on. DrawCanvas:mount and the other mount methods show it, as often as you like. |
| Angles are radians. | A 2D rotation is a number of radians, a 3D one a Quat. A color's hue, in color.hsl and color.oklch, is the one angle in degrees, as in CSS. |
| Errors raise. | A call that fails raises an error rather than returning one. Wrap a call that may fail in pcall. A call returns nil only where its entry says when. |
| Lists count from 1; fixed layouts from 0. | A position in a Lua list you pass or receive starts at 1, so # and ipairs work. An address into a fixed layout, such as a grid cell or an atlas cell, starts at 0. Each entry says which it takes. |
The units and directions of positions are on Coordinates and units, and calls that wait on Waiting.
See also
Reference used on this page: datumhue.color datumhue.color.hsl Vec2:with_x UiElement.text DrawCanvas:circle datumhue.draw.new Picture:circfill Picture:line datumhue.image.new datumhue.scene.new DrawCanvas:mount datumhue.color.oklch