Commit8d1bfa18Recorded25 Sep 2026Repositorysigil-geometry

Update README and CHANGELOG for the widened allocation check

Message

123 checks covering all 80 ! forms; ELF numbers; the constructs the hot paths avoid (macros, named lets, case-lambda, rest arguments); NaN comparison semantics; predicates in the API tables.

Changed
 CHANGELOG.md |  6 +++++-
 README.md    | 60 +++++++++++++++++++++++++++++++++++++++---------------------
 2 files changed, 44 insertions(+), 22 deletions(-)
Diff
CHANGELOG.mdmodified
@@ -25,6 +25,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
25
weights for picking), plus plane and box helpers.
26
- Every operation that produces a value has an allocation-free `!` form
27
whose destination may alias its inputs. Measured at zero allocations
−28
per call for all 55 checked operations on wasm and on bytecode.
+28
per call on wasm and on bytecode, over 123 checks covering all 80
+29
`!` forms and their other branches.
30
- `scripts/check-targets`: the test suite and the allocation check on
31
bytecode, native ELF and wasm.
+32
- Tolerant comparisons (`vec3-approx=?`, `mat4-approx=?`,
+33
`quat-same-rotation?` and the rest) that never accept NaN, written
+34
around sigil 0.22.7's `<=`, `>=` and `=`, which answer #t for NaN.
README.mdmodified
@@ -110,8 +110,12 @@ contract is the bytes.
110
gives zero. Arguments that describe nothing (a perspective with
111
`near <= 0`, a plane with a zero normal) raise an error.
112
- **Tolerant comparison.** `vec3-approx=?`, `mat4-approx=?` and friends
−113
take an optional epsilon (default 1e-5, relative above magnitude 1).
−114
`quat-same-rotation?` treats `q` and `-q` as equal.
+113
take an optional epsilon (default 1e-5, relative above magnitude 1,
+114
must be positive). A NaN on either side is never approx=?.
+115
`quat-same-rotation?` compares components up to sign, so `q` and `-q`
+116
match and a non-unit quaternion does not match a unit one. Passing the
+117
epsilon explicitly allocates one list cell per call (it is a rest
+118
argument); the default allocates nothing.
119
120
## API
121
@@ -122,7 +126,7 @@ allocating twin without the `!`):
126
127
| | |
128
|---|---|
−125
| make | `vec3`, `make-vec3`, `vec3-copy`, `vec3-copy!`, `vec3-set!`, `vec3?` |
+129
| make | `vec3`, `make-vec3`, `vec3-copy`, `vec3-copy!`, `vec3-set!`, `vec3?` (size check) |
130
| access | `vec3-x`, `vec3-y`, `vec3-z` (`vec4-w`), `vec3->list` |
131
| arithmetic | `vec3-add!`, `vec3-sub!`, `vec3-mul!` (per component), `vec3-scale!`, `vec3-negate!`, `vec3-lerp!` |
132
| measure | `vec3-dot`, `vec3-length`, `vec3-length-squared`, `vec3-normalize!`, `vec2-distance`, `vec3-distance` |
@@ -134,7 +138,7 @@ allocating twin without the `!`):
138
139
| | mat4 | mat3 |
140
|---|---|---|
−137
| make | `mat4` (16 values), `make-mat4`, `mat4-identity!`, `list->mat4`, `mat4-copy!` | `mat3`, `make-mat3`, `mat3-identity!`, `list->mat3`, `mat3-copy!` |
+141
| make | `mat4` (16 values), `make-mat4`, `mat4-identity!`, `list->mat4`, `mat4-copy!`, `mat4?` | `mat3`, `make-mat3`, `mat3-identity!`, `list->mat3`, `mat3-copy!`, `mat3?` |
142
| access | `mat4-ref m col row`, `mat4-set!`, `mat4->list` | `mat3-ref`, `mat3-set!`, `mat3->list` |
143
| algebra | `mat4-mul!`, `mat4-transpose!`, `mat4-inverse!`, `mat4-determinant` | `mat3-mul!`, `mat3-transpose!`, `mat3-inverse!`, `mat3-determinant` |
144
| build | `mat4-translation!`, `mat4-scaling!`, `mat4-rotation-x!` / `-y!` / `-z!`, `mat4-rotation! axis angle`, `mat4-from-quat!`, `mat4-from-trs! t q s` | `mat3-from-mat4!`, `mat3-normal-matrix!`, `mat3-from-quat!` |
@@ -144,7 +148,7 @@ allocating twin without the `!`):
148
149
### Quaternions: `(sigil geometry quat)`
150
−147
`quat`, `make-quat`, `quat-identity!`, `quat-from-axis-angle!`,
+151
`quat`, `make-quat`, `quat?`, `quat-identity!`, `quat-from-axis-angle!`,
152
`quat-from-mat3!`, `quat-from-mat4!`, `quat-mul!`, `quat-conjugate!`,
153
`quat-inverse!`, `quat-normalize!`, `quat-dot`, `quat-length`,
154
`quat-slerp!`, `quat-nlerp!`, `quat-rotate-vec3!`, `quat-angle`,
@@ -189,27 +193,41 @@ That makes a sight line a ray with `dir = target - eye`, where a hit with
193
## Allocation, measured
194
195
`scripts/check-targets` counts GC allocations over 1000 calls of each of
−192
55 operations (every `!` form plus the scalar and ray functions),
−193
against an empty-loop baseline and a positive control. Results with
−194
sigil 0.22.7:
+196
123 checks, against an empty-loop baseline and a positive control. The
+197
checks cover all 80 exported `!` forms, the scalar, ray and comparison
+198
functions, and the other branches of the ops that have them (a
+199
projection's divide by w, a singular inverse, a degenerate look-at, each
+200
branch of the matrix-to-quaternion conversion, zero-length normalize, ray
+201
misses). The script refuses to run if an exported `!` form has no check.
+202
Results with sigil 0.22.7:
203
204
| target | allocations per call |
205
|---|---|
−198
| native wasm (the web) | 0 for all 55 |
−199
| bytecode | 0 for all 55 |
−200
| native ELF | 0 for 42; one per argument for the 13 that take 4 or more arguments (see below) |
+206
| native wasm (the web) | 0 for all 123 |
+207
| bytecode | 0 for all 123 |
+208
| native ELF | 0 for 87; the other 36 allocate where the call crosses from native code into bytecode (see below) |
209
210
On a native ELF build, sigil 0.22.7 loads a dependency package's
211
compiled bytecode rather than its native code, so an app's calls into
−204
sigil-geometry cross from native to bytecode, and that crossing
−205
allocates for calls with 4 or more arguments. It is a property of the
−206
toolchain's ELF bundles, not of this package, and the wasm build is not
−207
affected.
−208
−209
The package uses no `syntax-rules` macros in its hot paths, on purpose:
−210
under native codegen, each global a macro template introduces is looked
−211
up at run time through `%hygiene-ref`, which allocates on every call.
−212
Helper procedures cost nothing.
+212
sigil-geometry cross from native to bytecode. That crossing allocates one
+213
object per argument for calls with 4 or more arguments, and 2 for a call
+214
to a procedure with a rest argument (the `approx=?` family). It is a
+215
property of the toolchain's ELF bundles, not of this package, and the
+216
wasm build is not affected.
+217
+218
What the package avoids in its hot paths, and why (each measured to
+219
allocate on every call under native codegen):
+220
+221
- `syntax-rules` macros whose template names a global: native codegen
+222
looks the global up at run time through `%hygiene-ref`, which conses.
+223
Helper procedures cost nothing.
+224
- Named-let loops (3 to 5 objects per call) and `case-lambda` (2 to 4):
+225
loops are top-level recursive procedures instead.
+226
- Passing a rest argument (one list cell).
+227
+228
Sigil 0.22.7 also answers #t to `(<= x y)`, `(>= x y)` and `(= x y)` when
+229
an operand is NaN, so the comparisons here are written with `<` and `>`,
+230
which answer correctly.
231
232
## Development
233
@@ -225,7 +243,7 @@ guix shell -m manifest.scm -- scripts/check-targets
243
into the app in `harness/` with the allocation check, runs it on each
244
target (wasm under Node), and reports per target. A target passes when
245
every test ran and passed and, where the geometry code is native or all
−228
bytecode, no `!` form allocated.
+246
bytecode, none of the 123 checks allocated.
247
248
## License
249