--- title: box description: Creates a pure cube descriptor for `geometry(gpu)`. Descriptors are device-agnostic, so you can serialize or clone them freely and upload later. --- # box ## Import ```ts import { box } from "vgpu/scene"; ``` ## Signature ```ts declare function box(options?: import("vgpu/scene").BoxOptions): import("vgpu/scene").SceneGeometryOfKind<"box">; ``` ## Parameters | Param | Type | Required | Default | Notes | | ------------ | ------------ | -------- | ------- | ------------------------------------------------------------------- | | options | `BoxOptions` | ✖ | `{}` | Configuration bag for the cube descriptor. | | options.size | `number` | ✖ | `1` | Edge length used by the geometry factory. Any positive value works. | **Returns:** `SceneGeometryOfKind<"box">` — frozen descriptor with `kind: "box"` and the props you provided; omitted fields stay omitted until upload-time defaults are applied. **Throws:** None. Negative sizes do not throw but invert normals when uploaded. ## Examples ```ts import { box } from "vgpu/scene"; const tallCube = box({ size: 3 }); console.log(tallCube.kind); // "box" ``` ## Notes * Descriptors contain zero GPU state; call `geometry(gpu, descriptor)` per device. * **See also:** `BoxOptions`, `SceneGeometryOfKind`. *** # BoxOptions Shape configuration shared by `box()` descriptors. ## Import ```ts import type { BoxOptions } from "vgpu/scene"; ``` ## Signature ```ts interface BoxOptions { readonly size?: number; } ``` ## Parameters | Field | Type | Required | Default | Notes | | ----- | -------- | -------- | ------- | ------------------------------------ | | size | `number` | ✖ | `1` | Edge length measured in scene units. | **Returns:** Not applicable (type definition). **Throws:** None. ## Examples ```ts import type { BoxOptions } from "vgpu/scene"; const solid: BoxOptions = { size: 2 }; ``` ## Notes * Undefined fields are filled by the geometry factory when the descriptor is uploaded. * **See also:** `box`, `SceneGeometry`. *** # sphere Generates a UV sphere descriptor with configurable radius and tessellation. ## Import ```ts import { sphere } from "vgpu/scene"; ``` ## Signature ```ts declare function sphere(options?: import("vgpu/scene").SphereOptions): import("vgpu/scene").SceneGeometryOfKind<"sphere">; ``` ## Parameters | Param | Type | Required | Default | Notes | | ---------------------- | --------------- | -------- | ------- | --------------------------------------------- | | options | `SphereOptions` | ✖ | `{}` | Configure radius or segments before upload. | | options.radius | `number` | ✖ | `0.5` | Physical radius. Must be `> 0` once uploaded. | | options.widthSegments | `number` | ✖ | `32` | Meridians. Integer `>= 3`. | | options.heightSegments | `number` | ✖ | `16` | Latitudes. Integer `>= 2`. | **Returns:** `SceneGeometryOfKind<"sphere">`. **Throws:** None while creating the descriptor. `geometry(gpu, sphere(...))` throws `VGPU-CORE-INVALID-USAGE` if radius `<= 0`, segment counts drop below limits, or `(widthSegments + 1) * (heightSegments + 1)` exceeds the uint16 vertex cap (65 535). ## Examples ```ts import { sphere } from "vgpu/scene"; const globe = sphere({ radius: 1.2, widthSegments: 48, heightSegments: 32 }); ``` ## Notes * Higher segment counts increase vertex memory exponentially; use `icosphere()` for evenly distributed triangles. * **See also:** `SphereOptions`, `Geometry`. *** # SphereOptions Configuration interface for `sphere()`. ## Import ```ts import type { SphereOptions } from "vgpu/scene"; ``` ## Signature ```ts interface SphereOptions { readonly radius?: number; readonly widthSegments?: number; readonly heightSegments?: number; } ``` ## Parameters | Field | Type | Required | Default | Notes | | -------------- | -------- | -------- | ------- | --------------- | | radius | `number` | ✖ | `0.5` | Must be `> 0`. | | widthSegments | `number` | ✖ | `32` | Integer `>= 3`. | | heightSegments | `number` | ✖ | `16` | Integer `>= 2`. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { SphereOptions } from "vgpu/scene"; const detail: SphereOptions = { widthSegments: 96, heightSegments: 64 }; ``` ## Notes * Leave properties undefined to rely on the geometry factory defaults shown above. * **See also:** `sphere`, `IcosphereOptions`. *** # plane XZ-aligned quad descriptor centered at the origin with +Y normals. Use it for ground planes, decals, or full-quad geometry. ## Import ```ts import { plane } from "vgpu/scene"; ``` ## Signature ```ts declare function plane(options?: import("vgpu/scene").PlaneOptions): import("vgpu/scene").SceneGeometryOfKind<"plane">; ``` ## Parameters | Param | Type | Required | Default | Notes | | ---------------------- | -------------------- | -------- | -------- | -------------------------------------------- | | options | `PlaneOptions` | ✖ | `{}` | Width/height and tessellation controls. | | options.width | `number` | ✖ | `1` | Total X extent; must be `> 0`. | | options.height | `number` | ✖ | `1` | Total Z extent; must be `> 0`. | | options.widthSegments | `number` | ✖ | `1` | Integer `>= 1`. | | options.heightSegments | `number` | ✖ | `1` | Integer `>= 1`. | | options.shading | `"flat" \| "smooth"` | ✖ | `"flat"` | Present for parity; normals remain +Y today. | **Returns:** `SceneGeometryOfKind<"plane">`. **Throws:** None while creating the descriptor. `geometry(gpu, plane(...))` throws `VGPU-CORE-INVALID-USAGE` if width/height `<= 0`, segment counts `< 1`, or tessellation exceeds 65 535 vertices. ## Examples ```ts import { plane } from "vgpu/scene"; const tiled = plane({ width: 10, height: 10, widthSegments: 4, heightSegments: 4 }); ``` ## Notes * Use `plane()` when you need explicit vertex data instead of the implicit full-screen quad helper. * **See also:** `PlaneOptions`, `fullscreenQuad`. *** # PlaneOptions Options bag used by `plane()`. ## Import ```ts import type { PlaneOptions } from "vgpu/scene"; ``` ## Signature ```ts interface PlaneOptions { readonly width?: number; readonly height?: number; readonly widthSegments?: number; readonly heightSegments?: number; readonly shading?: "flat" | "smooth"; } ``` ## Parameters | Field | Type | Required | Default | Notes | | -------------- | -------------------- | -------- | -------- | --------------------------------------- | | width | `number` | ✖ | `1` | Must be `> 0`. | | height | `number` | ✖ | `1` | Must be `> 0`. | | widthSegments | `number` | ✖ | `1` | Integer `>= 1`. | | heightSegments | `number` | ✖ | `1` | Integer `>= 1`. | | shading | `"flat" \| "smooth"` | ✖ | `"flat"` | Smooth is reserved for future upgrades. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { PlaneOptions } from "vgpu/scene"; const quad: PlaneOptions = { width: 4, height: 2 }; ``` ## Notes * Leave fields undefined to inherit the defaults enforced at upload time. * **See also:** `plane`, `SceneGeometry`. *** # torus Donut descriptor with independent major/minor radii and optional arc slices. ## Import ```ts import { torus } from "vgpu/scene"; ``` ## Signature ```ts declare function torus(options?: import("vgpu/scene").TorusOptions): import("vgpu/scene").SceneGeometryOfKind<"torus">; ``` ## Parameters | Param | Type | Required | Default | Notes | | ----------------------- | -------------------- | -------- | ------------- | -------------------------------------------------------------- | | options | `TorusOptions` | ✖ | `{}` | Controls radii, arc, and tessellation. | | options.radius | `number` | ✖ | `0.5` | Distance from origin to tube center; must be `> options.tube`. | | options.tube | `number` | ✖ | `0.2` | Minor radius; must be `> 0`. | | options.radialSegments | `number` | ✖ | `16` | Around the tube. Integer `>= 3`. | | options.tubularSegments | `number` | ✖ | `32` | Around the ring. Integer `>= 3`. | | options.arc | `number` | ✖ | `Math.PI * 2` | Radians to sweep; must be `> 0`. | | options.shading | `"flat" \| "smooth"` | ✖ | `"smooth"` | Flat duplicates vertices for per-triangle normals. | **Returns:** `SceneGeometryOfKind<"torus">`. **Throws:** None while creating the descriptor. `geometry(gpu, torus(...))` throws `VGPU-CORE-INVALID-USAGE` if radii are invalid, segment counts fall below limits, `arc <= 0`, or vertex counts exceed 65 535. ## Examples ```ts import { torus } from "vgpu/scene"; const gauge = torus({ radius: 1, tube: 0.15, arc: Math.PI * 1.25 }); ``` ## Notes * Use partial arcs to build gauges or highlights without extra geometry. * **See also:** `RingOptions`, `TorusOptions`. *** # TorusOptions Configuration interface for `torus()`. ## Import ```ts import type { TorusOptions } from "vgpu/scene"; ``` ## Signature ```ts interface TorusOptions { readonly radius?: number; readonly tube?: number; readonly radialSegments?: number; readonly tubularSegments?: number; readonly arc?: number; readonly shading?: "flat" | "smooth"; } ``` ## Parameters | Field | Type | Required | Default | Notes | | --------------- | -------------------- | -------- | ------------- | ------------------------- | | radius | `number` | ✖ | `0.5` | Must be `> tube`. | | tube | `number` | ✖ | `0.2` | Minor radius `> 0`. | | radialSegments | `number` | ✖ | `16` | Integer `>= 3`. | | tubularSegments | `number` | ✖ | `32` | Integer `>= 3`. | | arc | `number` | ✖ | `Math.PI * 2` | Radians `> 0`. | | shading | `"flat" \| "smooth"` | ✖ | `"smooth"` | Flat duplicates vertices. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { TorusOptions } from "vgpu/scene"; const tight: TorusOptions = { radius: 0.75, tube: 0.3 }; ``` ## Notes * Keep `tube` significantly smaller than `radius` to avoid self-intersection. * **See also:** `torus`, `ring`. *** # fullscreenQuad Descriptor for a clip-space fullscreen quad (two triangles, six vertices). Use it for fragment-only passes recorded via `draw(gpu)`. ## Import ```ts import { fullscreenQuad } from "vgpu/scene"; ``` ## Signature ```ts declare function fullscreenQuad(options?: import("vgpu/scene").FullscreenQuadOptions): import("vgpu/scene").SceneGeometryOfKind<"fullscreenQuad">; ``` ## Parameters | Param | Type | Required | Default | Notes | | ------- | ----------------------- | -------- | ------- | ------------------------------------------------------- | | options | `FullscreenQuadOptions` | ✖ | `{}` | Reserved for future overrides; currently has no fields. | **Returns:** `SceneGeometryOfKind<"fullscreenQuad">`. **Throws:** None. ## Examples ```ts import { fullscreenQuad } from "vgpu/scene"; const descriptor = fullscreenQuad(); ``` ## Notes * Generated geometry exposes only position attributes (xy4). Add UVs in WGSL using built-in coordinates. * **See also:** `plane`, `Geometry`. *** # FullscreenQuadOptions Placeholder interface to keep API surface future-proof. ## Import ```ts import type { FullscreenQuadOptions } from "vgpu/scene"; ``` ## Signature ```ts interface FullscreenQuadOptions {} ``` ## Parameters No fields yet. **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { FullscreenQuadOptions } from "vgpu/scene"; const passthrough: FullscreenQuadOptions = {}; ``` ## Notes * Leave the argument undefined; future versions may add configurable fields. * **See also:** `fullscreenQuad`. *** # capsule Rounded capsule descriptor made of a cylinder body and two hemispherical caps. ## Import ```ts import { capsule } from "vgpu/scene"; ``` ## Signature ```ts declare function capsule(options?: import("vgpu/scene").CapsuleOptions): import("vgpu/scene").SceneGeometryOfKind<"capsule">; ``` ## Parameters | Param | Type | Required | Default | Notes | | ---------------------- | -------------------- | -------- | ---------- | -------------------------------------------------------------------- | | options | `CapsuleOptions` | ✖ | `{}` | Radius/height/tessellation overrides. | | options.radius | `number` | ✖ | `0.5` | Cap radius; must be `> 0`. | | options.height | `number` | ✖ | `1` | Cylinder length between caps; total height is `height + 2 * radius`. | | options.radialSegments | `number` | ✖ | `32` | Integer `>= 3`. | | options.heightSegments | `number` | ✖ | `8` | Integer `>= 2`. | | options.shading | `"flat" \| "smooth"` | ✖ | `"smooth"` | Flat duplicates vertices per triangle. | **Returns:** `SceneGeometryOfKind<"capsule">`. **Throws:** None while creating the descriptor. `geometry(gpu, capsule(...))` throws `VGPU-CORE-INVALID-USAGE` if radius `<= 0`, height `< 0`, segment counts fall below limits, or vertex counts exceed 65 535. ## Examples ```ts import { capsule } from "vgpu/scene"; const pillar = capsule({ radius: 0.3, height: 2, shading: "flat" }); ``` ## Notes * Increase `heightSegments` to reduce stretching along the cylinder body. * **See also:** `CapsuleOptions`, `cylinder`. *** # CapsuleOptions Configuration interface for `capsule()`. ## Import ```ts import type { CapsuleOptions } from "vgpu/scene"; ``` ## Signature ```ts interface CapsuleOptions { readonly radius?: number; readonly height?: number; readonly radialSegments?: number; readonly heightSegments?: number; readonly shading?: "flat" | "smooth"; } ``` ## Parameters | Field | Type | Required | Default | Notes | | -------------- | -------------------- | -------- | ---------- | -------------------------------- | | radius | `number` | ✖ | `0.5` | Must be `> 0`. | | height | `number` | ✖ | `1` | Can be zero for perfect spheres. | | radialSegments | `number` | ✖ | `32` | Integer `>= 3`. | | heightSegments | `number` | ✖ | `8` | Integer `>= 2`. | | shading | `"flat" \| "smooth"` | ✖ | `"smooth"` | Flat duplicates vertices. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { CapsuleOptions } from "vgpu/scene"; const short: CapsuleOptions = { height: 0.5 }; ``` ## Notes * Negative heights are rejected when uploading through `geometry(gpu)`. * **See also:** `capsule`, `SceneGeometry`. *** # cone Circular cone descriptor with optional base cap and angular slice control. ## Import ```ts import { cone } from "vgpu/scene"; ``` ## Signature ```ts declare function cone(options?: import("vgpu/scene").ConeOptions): import("vgpu/scene").SceneGeometryOfKind<"cone">; ``` ## Parameters | Param | Type | Required | Default | Notes | | ---------------------- | -------------------- | -------- | ------------- | -------------------------------------- | | options | `ConeOptions` | ✖ | `{}` | Controls size, caps, and tessellation. | | options.radius | `number` | ✖ | `0.5` | Base radius; must be `> 0`. | | options.height | `number` | ✖ | `1` | Must be `> 0`. | | options.radialSegments | `number` | ✖ | `32` | Integer `>= 3`. | | options.heightSegments | `number` | ✖ | `1` | Integer `>= 1`. | | options.openEnded | `boolean` | ✖ | `false` | Omits the base cap. | | options.thetaStart | `number` | ✖ | `0` | Start angle in radians. | | options.thetaLength | `number` | ✖ | `Math.PI * 2` | Sweep `> 0`. | | options.shading | `"flat" \| "smooth"` | ✖ | `"smooth"` | Flat duplicates vertices per face. | **Returns:** `SceneGeometryOfKind<"cone">`. **Throws:** None while creating the descriptor. `geometry(gpu, cone(...))` throws `VGPU-CORE-INVALID-USAGE` for invalid radius/height, low segment counts, zero sweep, or vertex counts above 65 535. ## Examples ```ts import { cone } from "vgpu/scene"; const spotlight = cone({ radius: 0.4, height: 1.2, openEnded: true, thetaLength: Math.PI }); ``` ## Notes * Use `openEnded: true` for beams or funnels where the cap would never be visible. * **See also:** `ConeOptions`, `cylinder`. *** # ConeOptions Configuration interface for `cone()`. ## Import ```ts import type { ConeOptions } from "vgpu/scene"; ``` ## Signature ```ts interface ConeOptions { readonly radius?: number; readonly height?: number; readonly radialSegments?: number; readonly heightSegments?: number; readonly openEnded?: boolean; readonly thetaStart?: number; readonly thetaLength?: number; readonly shading?: "flat" | "smooth"; } ``` ## Parameters | Field | Type | Required | Default | Notes | | -------------- | -------------------- | -------- | ------------- | ------------------------- | | radius | `number` | ✖ | `0.5` | Must be `> 0`. | | height | `number` | ✖ | `1` | Must be `> 0`. | | radialSegments | `number` | ✖ | `32` | Integer `>= 3`. | | heightSegments | `number` | ✖ | `1` | Integer `>= 1`. | | openEnded | `boolean` | ✖ | `false` | Omits the base cap. | | thetaStart | `number` | ✖ | `0` | Start angle in radians. | | thetaLength | `number` | ✖ | `Math.PI * 2` | Sweep `> 0`. | | shading | `"flat" \| "smooth"` | ✖ | `"smooth"` | Flat duplicates vertices. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { ConeOptions } from "vgpu/scene"; const halfCone: ConeOptions = { thetaLength: Math.PI }; ``` ## Notes * Upload-time validation enforces every invariant listed above. * **See also:** `cone`, `SceneGeometry`. *** # cylinder Pure descriptor for cylinders or frustums with independent top/bottom radii and optional caps. ## Import ```ts import { cylinder } from "vgpu/scene"; ``` ## Signature ```ts declare function cylinder(options?: import("vgpu/scene").CylinderOptions): import("vgpu/scene").SceneGeometryOfKind<"cylinder">; ``` ## Parameters | Param | Type | Required | Default | Notes | | ---------------------- | -------------------- | -------- | ---------------- | --------------------------------------------------------------- | | options | `CylinderOptions` | ✖ | `{}` | Provide either `radius` or both `radiusTop` and `radiusBottom`. | | options.radius | `number` | ✖ | `0.5` | Uniform radius fallback when per-end radii are omitted. | | options.radiusTop | `number` | ✖ | `options.radius` | Provide with `radiusBottom` for frustums. Must be `>= 0`. | | options.radiusBottom | `number` | ✖ | `options.radius` | Same as `radiusTop`. | | options.height | `number` | ✖ | `1` | Must be `> 0`. | | options.radialSegments | `number` | ✖ | `32` | Integer `>= 3`. | | options.heightSegments | `number` | ✖ | `1` | Integer `>= 1`. | | options.openEnded | `boolean` | ✖ | `false` | Omits caps (zero-radius caps are always skipped). | | options.thetaStart | `number` | ✖ | `0` | Start angle. | | options.thetaLength | `number` | ✖ | `Math.PI * 2` | Sweep `> 0`. | | options.shading | `"flat" \| "smooth"` | ✖ | `"smooth"` | Flat duplicates vertices. | **Returns:** `SceneGeometryOfKind<"cylinder">`. **Throws:** None while creating the descriptor. `geometry(gpu, cylinder(...))` throws `VGPU-CORE-INVALID-USAGE` if you provide both uniform and explicit radii, resolve radii below zero, keep both radii at zero, use low segment counts, or exceed the vertex limit. ## Examples ```ts import { cylinder } from "vgpu/scene"; const tapered = cylinder({ radiusTop: 0.2, radiusBottom: 0.4, height: 1.5, radialSegments: 48 }); ``` ## Notes * Zero-radius ends are automatically omitted to avoid degenerate caps. * **See also:** `CylinderOptions`, `capsule`. *** # CylinderOptions Configuration interface for `cylinder()`. ## Import ```ts import type { CylinderOptions } from "vgpu/scene"; ``` ## Signature ```ts interface CylinderOptions { readonly radius?: number; readonly radiusTop?: number; readonly radiusBottom?: number; readonly height?: number; readonly radialSegments?: number; readonly heightSegments?: number; readonly openEnded?: boolean; readonly thetaStart?: number; readonly thetaLength?: number; readonly shading?: "flat" | "smooth"; } ``` ## Parameters | Field | Type | Required | Default | Notes | | -------------- | -------------------- | -------- | ------------------------------- | ------------------------------------------------------------------------------------------ | | radius | `number` | ✖ | `0.5` | Uniform fallback radius. | | radiusTop | `number` | ✖ | omitted; resolved from `radius` | Provide with `radiusBottom` for frustums. If `radius` is set, omitting this uses `radius`. | | radiusBottom | `number` | ✖ | omitted; resolved from `radius` | Provide with `radiusTop`. If `radius` is set, omitting this uses `radius`. | | height | `number` | ✖ | `1` | Must be `> 0`. | | radialSegments | `number` | ✖ | `32` | Integer `>= 3`. | | heightSegments | `number` | ✖ | `1` | Integer `>= 1`. | | openEnded | `boolean` | ✖ | `false` | Skip caps when `true`. | | thetaStart | `number` | ✖ | `0` | Start angle. | | thetaLength | `number` | ✖ | `Math.PI * 2` | Sweep `> 0`. | | shading | `"flat" \| "smooth"` | ✖ | `"smooth"` | Flat duplicates vertices. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { CylinderOptions } from "vgpu/scene"; const frustum: CylinderOptions = { radiusTop: 0.25, radiusBottom: 0.6 }; ``` ## Notes * Validation occurs when `geometry(gpu)` uploads the descriptor. * **See also:** `cylinder`, `SceneGeometry`. *** # disk Flat disk descriptor oriented on the XZ plane with upward normals. ## Import ```ts import { disk } from "vgpu/scene"; ``` ## Signature ```ts declare function disk(options?: import("vgpu/scene").DiskOptions): import("vgpu/scene").SceneGeometryOfKind<"disk">; ``` ## Parameters | Param | Type | Required | Default | Notes | | ------------------- | ------------- | -------- | ------------- | --------------------------------- | | options | `DiskOptions` | ✖ | `{}` | Radius and polar slice overrides. | | options.radius | `number` | ✖ | `0.5` | Must be `> 0`. | | options.segments | `number` | ✖ | `32` | Integer `>= 3`. | | options.thetaStart | `number` | ✖ | `0` | Slice start angle. | | options.thetaLength | `number` | ✖ | `Math.PI * 2` | Sweep `> 0`. | **Returns:** `SceneGeometryOfKind<"disk">`. **Throws:** None while creating the descriptor. `geometry(gpu, disk(...))` throws `VGPU-CORE-INVALID-USAGE` if radius `<= 0`, segment counts `< 3`, sweep `<= 0`, or vertex counts exceed the uint16 limit. ## Examples ```ts import { disk } from "vgpu/scene"; const portal = disk({ radius: 1, segments: 64, thetaLength: Math.PI * 1.5 }); ``` ## Notes * Disk UVs map linearly from the center; combine with `ring()` for hollow shapes. * **See also:** `DiskOptions`, `ring`. *** # DiskOptions Configuration interface for `disk()`. ## Import ```ts import type { DiskOptions } from "vgpu/scene"; ``` ## Signature ```ts interface DiskOptions { readonly radius?: number; readonly segments?: number; readonly thetaStart?: number; readonly thetaLength?: number; } ``` ## Parameters | Field | Type | Required | Default | Notes | | ----------- | -------- | -------- | ------------- | ------------------ | | radius | `number` | ✖ | `0.5` | Must be `> 0`. | | segments | `number` | ✖ | `32` | Integer `>= 3`. | | thetaStart | `number` | ✖ | `0` | Slice start angle. | | thetaLength | `number` | ✖ | `Math.PI * 2` | Sweep `> 0`. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { DiskOptions } from "vgpu/scene"; const slice: DiskOptions = { thetaLength: Math.PI }; ``` ## Notes * Validation occurs when uploading through `geometry(gpu)`. * **See also:** `disk`, `ring`. *** # dodecahedron Regular dodecahedron descriptor backed by the polyhedron geometry builder. ## Import ```ts import { dodecahedron } from "vgpu/scene"; ``` ## Signature ```ts declare function dodecahedron(options?: import("vgpu/scene").PolyhedronOptions): import("vgpu/scene").SceneGeometryOfKind<"dodecahedron">; ``` ## Parameters | Param | Type | Required | Default | Notes | | -------------- | ------------------- | -------- | ------- | ------------------------------------ | | options | `PolyhedronOptions` | ✖ | `{}` | Provide a radius override. | | options.radius | `number` | ✖ | `0.5` | Circumscribed radius; must be `> 0`. | **Returns:** `SceneGeometryOfKind<"dodecahedron">`. **Throws:** None while creating the descriptor. Uploading this descriptor with `geometry(gpu, ...)` throws `VGPU-CORE-INVALID-USAGE` if radius `<= 0`. ## Examples ```ts import { dodecahedron } from "vgpu/scene"; const rock = dodecahedron({ radius: 0.8 }); ``` ## Notes * Polyhedra stay well under the uint16 vertex cap, making them ideal for stylized rocks. * **See also:** `PolyhedronOptions`, `icosahedron`. *** # PolyhedronOptions Shared options for `dodecahedron`, `icosahedron`, `octahedron`, and `tetrahedron`. ## Import ```ts import type { PolyhedronOptions } from "vgpu/scene"; ``` ## Signature ```ts interface PolyhedronOptions { readonly radius?: number; } ``` ## Parameters | Field | Type | Required | Default | Notes | | ------ | -------- | -------- | ------- | ------------------------------------ | | radius | `number` | ✖ | `0.5` | Circumscribed radius; must be `> 0`. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { PolyhedronOptions } from "vgpu/scene"; const hudIcon: PolyhedronOptions = { radius: 0.25 }; ``` ## Notes * All polyhedron helpers freeze the provided options before returning descriptors. * **See also:** `dodecahedron`, `tetrahedron`. *** # icosahedron Regular 20-faced polyhedron descriptor. ## Import ```ts import { icosahedron } from "vgpu/scene"; ``` ## Signature ```ts declare function icosahedron(options?: import("vgpu/scene").PolyhedronOptions): import("vgpu/scene").SceneGeometryOfKind<"icosahedron">; ``` ## Parameters Same as `dodecahedron`; omit or override `radius`. **Returns:** `SceneGeometryOfKind<"icosahedron">`. **Throws:** None while creating the descriptor. Uploading this descriptor with `geometry(gpu, ...)` throws `VGPU-CORE-INVALID-USAGE` if radius `<= 0`. ## Examples ```ts import { icosahedron } from "vgpu/scene"; const crystal = icosahedron({ radius: 0.6 }); ``` ## Notes * Acts as the seed geometry for `icosphere()` subdivisions. * **See also:** `PolyhedronOptions`, `icosphere`. *** # icosphere Geodesic sphere descriptor obtained by subdividing an icosahedron. ## Import ```ts import { icosphere } from "vgpu/scene"; ``` ## Signature ```ts declare function icosphere(options?: import("vgpu/scene").IcosphereOptions): import("vgpu/scene").SceneGeometryOfKind<"icosphere">; ``` ## Parameters | Param | Type | Required | Default | Notes | | -------------------- | -------------------- | -------- | ---------- | --------------------------------------------------------- | | options | `IcosphereOptions` | ✖ | `{}` | Radius and subdivision overrides. | | options.radius | `number` | ✖ | `0.5` | Must be `> 0`. | | options.subdivisions | `number` | ✖ | `2` | Integer in `[0, 6]`; each step quadruples triangle count. | | options.shading | `"flat" \| "smooth"` | ✖ | `"smooth"` | Flat duplicates vertices for per-face normals. | **Returns:** `SceneGeometryOfKind<"icosphere">`. **Throws:** None while creating the descriptor. `geometry(gpu, icosphere(...))` throws `VGPU-CORE-INVALID-USAGE` if radius/subdivision constraints are violated or vertex counts exceed 65 535. ## Examples ```ts import { icosphere } from "vgpu/scene"; const moon = icosphere({ radius: 1, subdivisions: 4, shading: "flat" }); ``` ## Notes * Prefer `icosphere()` over `sphere()` when you need evenly distributed triangles. * **See also:** `IcosphereOptions`, `sphere`. *** # IcosphereOptions Configuration interface for `icosphere()`. ## Import ```ts import type { IcosphereOptions } from "vgpu/scene"; ``` ## Signature ```ts interface IcosphereOptions { readonly radius?: number; readonly subdivisions?: number; readonly shading?: "flat" | "smooth"; } ``` ## Parameters | Field | Type | Required | Default | Notes | | ------------ | -------------------- | -------- | ---------- | ------------------------- | | radius | `number` | ✖ | `0.5` | Must be `> 0`. | | subdivisions | `number` | ✖ | `2` | Integer in `[0, 6]`. | | shading | `"flat" \| "smooth"` | ✖ | `"smooth"` | Flat duplicates vertices. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { IcosphereOptions } from "vgpu/scene"; const lowPoly: IcosphereOptions = { subdivisions: 1 }; ``` ## Notes * Higher subdivision counts grow vertex counts exponentially; stay at `<= 4` for most hardware. * **See also:** `icosphere`, `SphereOptions`. *** # octahedron Regular octahedron descriptor. ## Import ```ts import { octahedron } from "vgpu/scene"; ``` ## Signature ```ts declare function octahedron(options?: import("vgpu/scene").PolyhedronOptions): import("vgpu/scene").SceneGeometryOfKind<"octahedron">; ``` ## Parameters Same as `dodecahedron`. **Returns:** `SceneGeometryOfKind<"octahedron">`. **Throws:** None while creating the descriptor. Uploading this descriptor with `geometry(gpu, ...)` throws `VGPU-CORE-INVALID-USAGE` if radius `<= 0`. ## Examples ```ts import { octahedron } from "vgpu/scene"; const diamond = octahedron({ radius: 0.7 }); ``` ## Notes * Octahedra are useful for axis gizmos or debug visuals. * **See also:** `PolyhedronOptions`, `tetrahedron`. *** # ring Annulus descriptor with independent inner/outer radii and optional polar slices. ## Import ```ts import { ring } from "vgpu/scene"; ``` ## Signature ```ts declare function ring(options?: import("vgpu/scene").RingOptions): import("vgpu/scene").SceneGeometryOfKind<"ring">; ``` ## Parameters | Param | Type | Required | Default | Notes | | ------------------- | ------------- | -------- | ------------- | -------------------------- | | options | `RingOptions` | ✖ | `{}` | Controls radii and slices. | | options.innerRadius | `number` | ✖ | `0.25` | Must be `> 0`. | | options.outerRadius | `number` | ✖ | `0.5` | Must be `> innerRadius`. | | options.segments | `number` | ✖ | `32` | Integer `>= 3`. | | options.thetaStart | `number` | ✖ | `0` | Slice start. | | options.thetaLength | `number` | ✖ | `Math.PI * 2` | Sweep `> 0`. | **Returns:** `SceneGeometryOfKind<"ring">`. **Throws:** None while creating the descriptor. `geometry(gpu, ring(...))` throws `VGPU-CORE-INVALID-USAGE` if the radii relationship is invalid, segment counts `< 3`, or vertex counts exceed 65 535. ## Examples ```ts import { ring } from "vgpu/scene"; const halo = ring({ innerRadius: 0.9, outerRadius: 1, segments: 48 }); ``` ## Notes * Combine `ring()` with emissive materials for portals or HUD highlights. * **See also:** `RingOptions`, `disk`. *** # RingOptions Configuration interface for `ring()`. ## Import ```ts import type { RingOptions } from "vgpu/scene"; ``` ## Signature ```ts interface RingOptions { readonly innerRadius?: number; readonly outerRadius?: number; readonly segments?: number; readonly thetaStart?: number; readonly thetaLength?: number; } ``` ## Parameters | Field | Type | Required | Default | Notes | | ----------- | -------- | -------- | ------------- | ------------------------ | | innerRadius | `number` | ✖ | `0.25` | Must be `> 0`. | | outerRadius | `number` | ✖ | `0.5` | Must be `> innerRadius`. | | segments | `number` | ✖ | `32` | Integer `>= 3`. | | thetaStart | `number` | ✖ | `0` | Slice start. | | thetaLength | `number` | ✖ | `Math.PI * 2` | Sweep `> 0`. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { RingOptions } from "vgpu/scene"; const arc: RingOptions = { thetaLength: Math.PI * 0.75 }; ``` ## Notes * Upload-time validation enforces every constraint listed above. * **See also:** `ring`, `SceneGeometry`. *** # tetrahedron Regular tetrahedron descriptor. ## Import ```ts import { tetrahedron } from "vgpu/scene"; ``` ## Signature ```ts declare function tetrahedron(options?: import("vgpu/scene").PolyhedronOptions): import("vgpu/scene").SceneGeometryOfKind<"tetrahedron">; ``` ## Parameters Same as `dodecahedron`. **Returns:** `SceneGeometryOfKind<"tetrahedron">`. **Throws:** None while creating the descriptor. Uploading this descriptor with `geometry(gpu, ...)` throws `VGPU-CORE-INVALID-USAGE` if radius `<= 0`. ## Examples ```ts import { tetrahedron } from "vgpu/scene"; const marker = tetrahedron({ radius: 0.3 }); ``` ## Notes * Tetrahedra are handy for directional HUD markers or gizmos. * **See also:** `PolyhedronOptions`, `GeometryKind`. *** # geometries Frozen namespace exposing every primitive helper through properties, useful for UI pickers or serialization. ## Import ```ts import { geometries } from "vgpu/scene"; ``` ## Signature ```ts declare const geometries: { readonly box: typeof import("vgpu/scene")["box"]; readonly capsule: typeof import("vgpu/scene")["capsule"]; readonly cone: typeof import("vgpu/scene")["cone"]; readonly cylinder: typeof import("vgpu/scene")["cylinder"]; readonly disk: typeof import("vgpu/scene")["disk"]; readonly dodecahedron: typeof import("vgpu/scene")["dodecahedron"]; readonly fullscreenQuad: typeof import("vgpu/scene")["fullscreenQuad"]; readonly icosahedron: typeof import("vgpu/scene")["icosahedron"]; readonly icosphere: typeof import("vgpu/scene")["icosphere"]; readonly octahedron: typeof import("vgpu/scene")["octahedron"]; readonly plane: typeof import("vgpu/scene")["plane"]; readonly ring: typeof import("vgpu/scene")["ring"]; readonly sphere: typeof import("vgpu/scene")["sphere"]; readonly tetrahedron: typeof import("vgpu/scene")["tetrahedron"]; readonly torus: typeof import("vgpu/scene")["torus"]; }; ``` ## Parameters | Property | Type | Required | Default | Notes | | ------------------- | ---------- | -------- | ------- | -------------------------------------------- | | `geometries.` | `Function` | ✔ | — | Each property mirrors the standalone export. | **Returns:** Frozen object with the same helpers you can import individually. **Throws:** None. ## Examples ```ts import { geometries } from "vgpu/scene"; const primitiveNames = Object.keys(geometries); ``` ## Notes * Great for inspector tooling that needs to enumerate available primitives without hard-coding imports. * **See also:** `GeometryKind`, `SceneGeometry`. *** # GeometryKind String-literal union covering every built-in geometry kind. ## Import ```ts import type { GeometryKind } from "vgpu/scene"; ``` ## Signature ```ts type GeometryKind = | "box" | "capsule" | "cone" | "cylinder" | "disk" | "dodecahedron" | "fullscreenQuad" | "icosahedron" | "icosphere" | "octahedron" | "plane" | "ring" | "sphere" | "tetrahedron" | "torus"; ``` ## Parameters | Value | Type | Required | Default | Notes | | --------------- | -------------- | -------- | ------- | ----------------------------------------- | | listed literals | `GeometryKind` | ✔ | — | Each literal matches a descriptor `kind`. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import type { GeometryKind } from "vgpu/scene"; function isPolyhedron(kind: GeometryKind): boolean { return ["dodecahedron", "icosahedron", "octahedron", "tetrahedron"].includes(kind); } ``` ## Notes * Use `GeometryKind` when switching on `geometry.kind` to retain exhaustiveness checking. * **See also:** `SceneGeometry`, `SceneGeometryOfKind`. *** # SceneGeometry Union of every primitive descriptor returned by the geometry helpers. ## Import ```ts import type { SceneGeometry } from "vgpu/scene"; ``` ## Signature ```ts type SceneGeometry = import("vgpu/scene").SceneGeometry; ``` ## Parameters | Field | Type | Required | Default | Notes | | ----- | --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | | kind | `GeometryKind` | ✔ | — | Identifies the primitive helper that produced the descriptor. | | props | `Readonly<...>` | ✔ | — | Captured options exactly as provided and frozen; upload-time geometry factories apply the defaults listed on each option table. | **Returns:** Not applicable (type definition). **Throws:** None. ## Examples ```ts import { box } from "vgpu/scene"; import type { SceneGeometry } from "vgpu/scene"; const primitives: SceneGeometry[] = [box({ size: 2 })]; ``` ## Notes * `SceneGeometry` objects are fully serializable, making them ideal for editor save files. * **See also:** `SceneGeometryOfKind`, `Geometry`. *** # SceneGeometryOfKind Conditional helper that narrows a `SceneGeometry` union to a specific primitive. ## Import ```ts import type { SceneGeometryOfKind } from "vgpu/scene"; ``` ## Signature ```ts type SceneGeometryOfKind = Extract; ``` ## Parameters | Param | Type | Required | Default | Notes | | ----- | -------------- | -------- | ------- | ------------------------------------ | | K | `GeometryKind` | ✔ | — | Primitive to extract from the union. | **Returns:** Not applicable. **Throws:** None. ## Examples ```ts import { sphere } from "vgpu/scene"; import type { SceneGeometryOfKind } from "vgpu/scene"; const glossy: SceneGeometryOfKind<"sphere"> = sphere({ radius: 1 }); ``` ## Notes * Use this helper when writing utilities that only accept a single primitive while keeping props strongly typed. * **See also:** `SceneGeometry`, `GeometryKind`. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)