# gizlang/geometry

```gizlang
import * as Geometry from "gizlang/geometry";
```

## Types

### `Point3`

```gizlang
type Point3 = { x: f64; y: f64; z: f64; }
```

Three coordinates, in a right-handed space.

- `x`: `f64`
- `y`: `f64`
- `z`: `f64`

### `Point2`

```gizlang
type Point2 = { x: f64; y: f64; }
```

Two coordinates for mapping application content into a fitted canvas viewport.

- `x`: `f64`
- `y`: `f64`

### `Viewport2D`

```gizlang
type Viewport2D = { left: f64; top: f64; scale: f64; }
```

A shared letterbox transform. Content and pointer input use these same offsets and scale.

- `left`: `f64`
- `top`: `f64`
- `scale`: `f64`

### `Rotation`

```gizlang
type Rotation = { x: f64; y: f64; z: f64; w: f64; }
```

Quaternion in glTF order, x/y/z/w.

- `x`: `f64`
- `y`: `f64`
- `z`: `f64`
- `w`: `f64`

### `Bounds3`

```gizlang
type Bounds3 = { low: Point3; high: Point3; }
```

An axis-aligned bound, derived from a mesh or transformed instances.

- `low`: `gizlang_geometry.Point3`
- `high`: `gizlang_geometry.Point3`

### `Matrix4`

```gizlang
type Matrix4 = { values: Vec<f64>; }
```

A column-major 4 by 4 transform, compatible with WGSL and glTF.

- `values`: `Vec<f64>`

### `Ray`

```gizlang
type Ray = { origin: Point3; direction: Point3; }
```

A normalized world-space picking ray from a camera's near plane.

- `origin`: `gizlang_geometry.Point3`
- `direction`: `gizlang_geometry.Point3`

## Functions

### `fitted2D`

```gizlang
function fitted2D(width: f64, height: f64, logicalWidth: f64, logicalHeight: f64, pixelPerfect: bool = false): Viewport2D throws string
```

Fits a logical 2D surface into physical pixels. Pixel-perfect minification uses whole source pixels per output pixel.

Effects: fail, alloc.

### `pixel2D`

```gizlang
function pixel2D(viewport: Viewport2D, point: Point2): Point2
```

Logical content to physical canvas pixels, shared by render extraction and non-game viewers.

### `logical2D`

```gizlang
function logical2D(viewport: Viewport2D, point: Point2): Point2
```

Physical canvas pixels to logical content; callers choose how to treat points outside the content.

### `identity`

```gizlang
function identity(): Matrix4
```

The identity matrix.

Effects: fail, alloc.

### `dot`

```gizlang
function dot(a: Point3, b: Point3): f64
```

A dot product.

### `cross`

```gizlang
function cross(a: Point3, b: Point3): Point3
```

A right-handed cross product.

### `normalized`

```gizlang
function normalized(value: Point3): Point3 throws string
```

A unit direction; zero and non-finite vectors are refused.

Effects: fail.

### `multiply`

```gizlang
function multiply(left: Matrix4, right: Matrix4): Matrix4
```

LEFT * RIGHT: RIGHT is applied first.

Effects: fail, alloc.

### `inverse`

```gizlang
function inverse(matrix: Matrix4): Matrix4 throws string
```

Inverts a finite 4x4 matrix with partial pivoting. Singular camera/model transforms are explicit errors.

Effects: fail, alloc.

### `ray`

```gizlang
function ray(viewProjection: Matrix4, point: Point2): Ray throws string
```

A normalized top-left-origin surface point to a world-space ray, using WebGPU's [0,1] depth convention.

Effects: fail, alloc.

### `plane`

```gizlang
function plane(ray: Ray, normal: Point3, distance: f64): Point3 | undefined
```

Forward ray intersection with dot(NORMAL, point)+DISTANCE=0. Parallel or behind-camera planes have no hit.

Effects: fail.

### `normalMatrix`

```gizlang
function normalMatrix(matrix: Matrix4): Matrix4 throws string
```

The inverse-transpose linear transform for vertex normals. Singular transforms are refused.

Effects: fail, alloc.

### `transformed`

```gizlang
function transformed(matrix: Matrix4, point: Point3): Point3 throws string
```

Applies a homogeneous transform, including perspective division.

Effects: fail.

### `transform`

```gizlang
function transform(position: Point3, rotation: Rotation, scale: Point3): Matrix4 throws string
```

Translation, quaternion rotation and nonuniform scale. Normalizes the quaternion once.

Effects: fail, alloc.

### `perspective`

```gizlang
function perspective(verticalRadians: f64, aspect: f64, near: f64, far: f64): Matrix4 throws string
```

Right-handed projection, camera toward -Z, WebGPU depth in [0,1]. FAR must exceed NEAR.

Effects: fail, alloc.

### `lookAt`

```gizlang
function lookAt(eye: Point3, target: Point3, up: Point3 = { x: 0.0, y: 1.0, z: 0.0 }): Matrix4 throws string
```

A camera transform from EYE toward TARGET, with UP choosing its roll.

Effects: fail, alloc.

### `visible`

```gizlang
function visible(bounds: Bounds3, viewProjection: Matrix4): bool
```

Conservative clip-space test of all eight bound corners, using WebGPU's six clip planes.

Effects: fail, alloc.

### `orthographic`

```gizlang
function orthographic(left: f64, right: f64, bottom: f64, top: f64, near: f64, far: f64): Matrix4 throws string
```

Right-handed orthographic projection toward -Z, WebGPU depth in [0,1], as for a sun's shadow.

Effects: fail, alloc.

### `euler`

```gizlang
function euler(yaw: f64, pitch: f64, roll: f64): Rotation
```

The rotation of YAW about +Y, then PITCH about +X, then ROLL about +Z, in radians.

Effects: fail.

