geomancy-0.4.0.0: ChangeLog.md

# Changelog for geomancy

## 0.4.0.0

A generally safe upgrade, but quite a bit of changes across the board.

- Added double-precision `DVec2`, `DVec3` (with `Packed`), `DVec4`, `DMat4` and `DQuaternion`.
  Includes SSE2/NEON kernels for `DMat4` products and `DMat4 !* DVec4`.
- Added `DTransform` (with `DTransform.Tree`), `Vulkan.DProjection` and `Vulkan.DView`.
  Compose in double and convert with `fromTransform`/`toTransform` to keep precision far from the origin.
- Added `DPoint2`, `DPoint3`, `DPoint3P` and `DPoint4`.
  `Point`'s `AffineSpace`, `qd`, `distance` and `lerp` now work over any scalar, not just `Float`.
- Added 64-bit integer vectors `I64Vec2`, `I64Vec3` (with `Packed`), `I64Vec4`,
  `U64Vec2`, `U64Vec3` (with `Packed`), `U64Vec4`.
- Added `fromVecN`/`toVecN`, `fromMat4`/`toMat4` and `fromQuaternion`/`toQuaternion`
  for single-precision conversions.
- Added `HasField` instances for the lanes of every vector type, for `v.x`, `v.y`, `v.z`, `v.w` with `OverloadedRecordDot`.
  * `Packed` vectors have them too, and a `Point` forwards each lane to the vector it wraps.
  * Optimized code is the same as with `withVecN`: one unpack, and only the lanes used get read.
- Added rewrite rules that fuse `Vec4` and `DVec4` producers into their consumers.
  * Intermediate vectors in expressions like `dot (a + b) c`, `lerp t a b` or `(a + b) * c - d` are no longer allocated.
  * Folds over such expressions got 20-30% faster.
  * When the rules fire, only the lanes the consumer uses are evaluated, so a fused expression may avoid forcing an undefined lane.
- Added `HasField` swizzles for every vector family, in `Geomancy.Swizzle.<Family>.Shuffle`, `.Down` and `.Up`
  (families: `Vec`, `DVec`, `IVec`, `UVec`, `I64Vec`, `U64Vec`).
  * `Shuffle` keeps the size (`v.zyx`, and the identity `v.xyz`), `Down` narrows (`v.xy` of a `Vec4`), `Up` widens (`v.xyxy` of a `Vec2`).
  * The instances are orphans. `import Geomancy.Swizzle ()` brings all of them,
    or import just the modules you need, like `import Geomancy.Swizzle.Vec.Down ()`.
  * Chains like `v.wzyx.zyx.yx.y` compile to a single lane read.
- Added `Extend` swizzles that widen a vector with constant lanes, in `Geomancy.Swizzle.<Family>.Extend`.
  * The source lanes stay in order and get `0` or `1` appended: `flatPos.xy01`, `pos.xyz1`, `uv.xy0`.
  * Masks compose from extending and narrowing: `white.xyz0.wyz` is `(0, y, z)`.
- Changed `Geomancy.Swizzle` labels to use the `HasField` swizzles, so `v .@ #xzy` works for every family.

- Modified Quaternion rotation to use a unit shortcut.
  * The contract was already "use normalized" quaternions for rotations.
  * Float got a modest speedup, Double is twice-ish as fast. Both are faster than Linear.

- Added `Eq` for `Mat4`, `DMat4`, `Transform` and `DTransform`.
  Elements are compared pointwise with IEEE semantics, like the derived `Eq` of `Vec3`:
  `0 == -0` and a matrix containing `NaN` is not equal to itself.
- Changed `Eq` and `Ord` for `Vec4` from bytewise to pointwise, matching `Vec3`.
  * `Ord` is now lexicographic over x, y, z, w. Previously it compared the raw bytes, which is not a numeric order.
  * `Map`/`Set` keyed by `Vec4` will order differently, and keys differing only in the sign of zero now collapse.
    + Keys containing `NaN` are no longer found by lookups, since `Ord` is no longer total for them.
    + Basically, don't use floats for keys.

- Fixed `abs` for `IVec3` and `IVec4`, which returned the vector unchanged.
- Fixed `Block` layout for `IVec3.Packed`, whose `alignment140` and `sizeOf140` were swapped in 0.3.1.0 (now 16 and 12).
- Fixed `peek` for `Vec4` and `Mat4` returning the wrong element under optimization.
  * `Data.Vector.Storable` indexing runs `peek` with a shared `realWorld#` token, which let GHC merge the
    buffer allocations of neighbouring reads, so every read in a strict context got the last element.
  * `peek` now loads on the caller's token and builds the value in a private buffer.
  * `Vec4` `peek` and `poke` are about twice as fast, since the 16-byte copies they replace were done bytewise.

- Changed `Vec4` and `Mat4` storage from aligned pinned to regular unpinned byte arrays, like the new `DVec4` and `DMat4`.
  * SIMD kernels now use unaligned loads and stores.
  * Code reaching into the exported constructors must not take `byteArrayContents#` or pass the array to `safe` foreign calls, since the GC may now move it.

## 0.3.1.0

- Fixed Block.sizeOf40 for Packed 3-vectors (was 16, now 12).

## 0.3.0.1

- Added Lift instances for data.
  Opt-out by disabling the `th-lift` flag.
- Added Serialise instances for data.
  Opt-out by disabling the `serialise` flag.

## 0.3.0.0

> `[0]` releases without row/col-major, handedness, and counter/clockwise confusion.

This release brings sanity and consistency around the transform stack.
- `Transform`s have proper *col-major* definitions.
- Operation ordering follows the GLSL convention.
  * The composition order is `(p <> v <> m <> ...)` (from global to local).
    Reverse your transforms to adjust.
  * The application order is `m !* v` (with the operators becoming infixr 5, just under the `<>`).
    It will do `Mᵀ * v` inside for SIMD reasons and to match what GLSL does for its `M * v` ops.
- `Geomancy.Vulkan.Projection` is right-handed, BUT produces *reverse-depth* range ([1; 0], In 3D infinite-Z converges to 0).
  * Replace your depth tests with `OP_GREATER` and clear to `0.0` - get better precision for your migration troubles.
- `Geomancy.Vulkan.View` is *right-handed*, with +Z being forward.
  * The intended up vector is still `vec3 0 (-1) 0` -- +Y down.
    Silly as it sounds, this matches the XY plane of the window with XY plane in front of a "first person" camera.
- Axis rotations (using `rotateQ`) will appear clockwise when looking along the axis.
- Angle rotations follow Tait-Bryan angles (heading/elevation/bank or yaw/pitch/roll) in the y-x-z frame.
  * `rotateZ (time * rate)` will follow the clock hands in 2D scenes and roll in 3D.
  * `rotateX` will follow the sun from sunrise to sunset, pitching UP / increasing elevation.
  * `rotateY` will turn you right, increasing yaw / heading eastwards.
- You're of course free to define your own transforms, just copy the modules and tune to your liking.
  Just make sure that you use matching row/column constructors and the math layer will do the rest, fast.
- Added `webcolor-labels` instances for UVec3/Vec3/Vec4.

## 0.2.6.0

* `Geomancy.Gl.Block` extract to `gl-block` package as `Graphics.Gl.Block`.
* Added `convert` function to vector modules to facilitate type-changing operations like rounding.
* Added `Ix` instances for integral vectors.
* Added `dot` for integral vectors.

## 0.2.5.0

* Added Geomancy.Gl.Block to derive packed/std140/std430 layouts generically.
  Originally a part of the unpublished `glow` package in the `codex` project by Edward Kmett.
  Add `ptrdiff-0` to your stack resolvers.

## 0.2.4.2

* Support ARM/aarch64 SIMD.

## 0.2.4.1

* Support simple-affine-space-0.2

## 0.2.4.0

A bunch of experimental code to see what sticks.

+ Added `simple-affine-space` instances.
  * The classes are re-exported from `Geomancy`, bringing stuff like `dot` and `normalize`.
+ Added `mono-traversable` instances and `Geomancy.Elementwise` wrapper.
+ Added `Point` wrapper and `PointN` aliases.
+ Added `Geomancy.Interpolate` with generic linear, quadratic and cubic functions.
  - ⚠️ `VecN.lerp` has wrong (flipped) order of vector arguments. This is fixed in `linear`.
+ Added `Geomancy.Swizzle` overloaded labels.
+ Added `Geomancy.Gl.Funs` with kinda-GLSL math functions, appropriately overloaded.

## 0.2.3.0

- Vec4 moved to ByteArray#.
- Mat4 !* Vec4 is now SIMD too.

## 0.2.2.4

+ Add Transform trees.

## 0.2.2.3

+ Add IVec and UVec 32-bit integer vectors.

## 0.2.2.2

+ Fixed using Transform.apply with projection inverses.

## 0.2.2.1

+ Add Vec2.
+ Add pattern synonyms to `Geomancy` re-exports.
+ Add Fractional instances.
+ Add conversions from tuples and lower-dimension vecs.

## 0.2.2.0

+ Add pattern synonym alternatives to `withVecN`.
+ Add Mat4 converstion from `Linear.M44`.
- Hide `toList` and `toListTrans`.
+ Add `toList2d` and publish its element-order wrappers.

## 0.2.1.0

Transform rewrite

* Change perspective FoV to radians.
+ Add `infinitePerspective`.
+ Add `Transform.inverse`.
- Hide `mat4`, `withMat4`.

## 0.2.0.0

Mat4 rewrite

+ Add `rowMajor`, `withRowMajor`, `toListRowMajor`.
+ Add `colMajor`, `withColMajor`, `toListColMajor`.
+ Add `Mat4.inverse`.
* Expose `matrixProduct`.
+ Add `scalarMultiply`.
+ Add `Mat4.(!*)` to use with `Vec4`.
* Extract transformations to `Geomancy.Transform` and use column notation.
+ Add `Transform.(!.)` and `apply` to use with `Vec3`.
* Rename `scale` to `scale3`.
+ Add uniform `scale`.
+ Add `scaleXY` for flat meshes.
* Rename `mkTransformation` to `dirPos`.
+ Add `rotateQ` via `dirPos` with empty translation.
+ Add `Vec3.Packed` newtype without extra padding.

## 0.1.3.0

* Update tests
+ Add `zipWith`
* Rename `elementwise` to `pointwise`
* Rename `colMajor` to `toList`
* Rename `rowMajor` to `toListTrans`

## 0.1.2.1

+ Add Mat4 multiplication test via `linear`
+ Add `elementwise`, `colMajor`, `rowMajor`

## 0.1.2.0

* Move projections and views to Vulkan namespace.

## 0.1.1.2

* Fix bug in quaternion rotationBetween.

## 0.1.1.1

* Add lookAtUp and rotationBetween.