@weasel-js/kernel3d 1.6.1 → 1.7.1

package/dist/index.d.ts

@@ -9,6 +9,9 @@ import { SceneNode, Scene, NodeId, AreaSelectDep, InsertExtras, InsertDep, NodeA
  * `camera3d` dep of its own rather than reusing the kit's `view`.
  */
 
+/** An orbit camera. The eye sits `distance` world units from `target` at
+ *  `yaw`/`pitch`; `fov` is the vertical field of view in radians, and
+ *  `near`/`far` the clip distances. */
 interface Camera3d {
     target: Vec3;
     /** Radians about +y, measured from +z. */
@@ -22,11 +25,19 @@ interface Camera3d {
 }
 /** Short of vertical: at exactly ±π/2 the eye lands on the up axis and `lookAt` degenerates. */
 declare const MAX_PITCH: number;
+/** A camera with defaults for every field not given: origin target, level at
+ *  yaw 0, distance 10, fov π/4, near 0.1, far 1000. */
 declare function createCamera(init: Partial<Camera3d>): Camera3d;
+/** The eye's world position. */
 declare function cameraEye(camera: Camera3d): Vec3;
+/** World-to-view matrix, with +y up. */
 declare function cameraView(camera: Camera3d): Mat4;
+/** World-to-clip matrix for a pane of the given width/height `aspect`. */
 declare function cameraViewProjection(camera: Camera3d, aspect: number): Mat4;
+/** The camera turned about its target by the given radians. Pitch is clamped
+ *  to ±`MAX_PITCH`; yaw is not wrapped. */
 declare function orbitBy(camera: Camera3d, deltaYaw: number, deltaPitch: number): Camera3d;
+/** The camera with its distance multiplied by `factor`, clamped to 0.5..500. */
 declare function dollyBy(camera: Camera3d, factor: number): Camera3d;
 
 /**
@@ -38,6 +49,7 @@ declare function dollyBy(camera: Camera3d, factor: number): Camera3d;
  * subclass and no special case.
  */
 
+/** Position, rotation and scale of a 3D node. */
 interface Pose3 {
     position: Vec3;
     rotation: Quat;
@@ -47,7 +59,10 @@ interface Pose3 {
  *  its own origin — which is what the kernel assumes nothing about — is
  *  `UNIT_CUBE`. */
 declare const UNIT_CUBE: Aabb;
+/** A pose at `position`, unscaled and unrotated unless given. */
 declare function pose3(position: Vec3, scale?: Vec3, rotation?: Quat): Pose3;
+/** The pose as a matrix: scale, then rotation, then translation to
+ *  `position`. */
 declare function poseMatrix(pose: Pose3): Mat4;
 /**
  * The world box a posed primitive occupies, given the box it occupies in its
@@ -88,6 +103,8 @@ declare function screenToNdc(point: {
     x: number;
     y: number;
 };
+/** Inverse of `screenToNdc`: normalized device coordinates (y up) to a point
+ *  in `rect`'s space (y down). */
 declare function ndcToScreen(ndc: {
     x: number;
     y: number;
@@ -133,6 +150,8 @@ declare function projectAabbToScreen(box: Aabb, viewProjection: Mat4, rect: Scre
  * guessing. A guess would report a fit the kernel does not have.
  */
 
+/** The camera and the pane it draws into; `width`/`height` are the pane's
+ *  size in the same units as the pointer points. */
 interface Viewport3d {
     camera: Camera3d;
     width: number;
@@ -145,9 +164,11 @@ interface Viewport3d {
     originX?: number;
     originY?: number;
 }
+/** Read on every dep call, so a dep always sees the current camera and pane. */
 type ViewportSource = () => Viewport3d;
 /** A 3D scene is core's scene with a `Pose3`. Nothing wraps it. */
 type Scene3d<TData, TLayer extends string> = Scene<TData, TLayer, Pose3>;
+/** A node of a `Scene3d`. */
 type Node3d<TData, TLayer extends string> = SceneNode<TData, TLayer, Pose3>;
 /**
  * The world box a node occupies. The kernel cannot answer this, and the reason
@@ -159,6 +180,8 @@ type Node3d<TData, TLayer extends string> = SceneNode<TData, TLayer, Pose3>;
  * Omitted, a node is a unit cube carried by its pose.
  */
 type NodeBounds<TData, TLayer extends string> = (node: Node3d<TData, TLayer>) => Aabb;
+/** What every 3D dep is built from: the scene, the viewport, and optionally
+ *  each node's world box. */
 interface World3d<TData, TLayer extends string> {
     scene: Scene3d<TData, TLayer>;
     viewport: ViewportSource;
@@ -256,8 +279,14 @@ declare function collectOverlayBoxes(handles: Iterable<OngoingHandle>, origin: {
  * `viewport.dragPan`, and that wants the 2D `view`.
  */
 
+/** `camera.orbit`: an ongoing drag that turns the `camera3d` dep about its
+ *  target, relative to the camera as it was when the drag began. */
 declare const orbitAction: Action;
+/** `camera.dolly`: moves the `camera3d` dep toward or away from its target by
+ *  the wheel's `deltaY`. Bound to the wheel by default, in every tool. */
 declare const dollyAction: Action;
+/** A tool that binds drag to `camera.orbit`. Register `orbitAction` alongside
+ *  it; the tool only declares the binding. */
 declare function useOrbitTool(): Tool<null>;
 
 /**
@@ -269,6 +298,8 @@ declare function useOrbitTool(): Tool<null>;
  * anything core does not already offer.
  */
 
+/** The `camera3d` dep: the orbit camera a 3D host owns, which the camera
+ *  actions read and replace. */
 interface Camera3dDep {
     get(): Camera3d;
     set(camera: Camera3d): void;