vgpu/scene31 symbolsView source ↗

Symbols in this topic

boxfunctionBoxOptionsoptionscapsulefunctionCapsuleOptionsoptionsconefunctionConeOptionsoptionscylinderfunctionCylinderOptionsoptionsdiskfunctionDiskOptionsoptionsdodecahedronfunctionfullscreenQuadfunctionFullscreenQuadOptionsoptionsgeometriesfunctionGeometryKindtypeicosahedronfunctionicospherefunctionIcosphereOptionsoptionsoctahedronfunctionplanefunctionPlaneOptionsoptionsPolyhedronOptionsoptionsringfunctionRingOptionsoptionsSceneGeometrytypeSceneGeometryOfKindtypespherefunctionSphereOptionsoptionstetrahedronfunctiontorusfunctionTorusOptionsoptions

box

Creates a pure cube descriptor for geometry(gpu). Descriptors are device-agnostic, so you can serialize or clone them freely and upload later.

Import

TypeScript
1
import { box } from "vgpu/scene";

Signature

TypeScript
1
declare function box(options?: import("vgpu/scene").BoxOptions): import("vgpu/scene").SceneGeometryOfKind<"box">;

Parameters

ParamTypeRequiredDefaultNotes
optionsBoxOptions✖{}Configuration bag for the cube descriptor.
options.sizenumber✖1Edge 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

TypeScript
1
2
3
4
import { box } from "vgpu/scene";
 
const tallCube = box({ size: 3 });
console.log(tallCube.kind); // "box"

Notes

BoxOptions

Shape configuration shared by box() descriptors.

Import

TypeScript
1
import type { BoxOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
interface BoxOptions {
  readonly size?: number;
}

Parameters

FieldTypeRequiredDefaultNotes
sizenumber✖1Edge length measured in scene units.

Returns: Not applicable (type definition).

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import { sphere } from "vgpu/scene";

Signature

TypeScript
1
declare function sphere(options?: import("vgpu/scene").SphereOptions): import("vgpu/scene").SceneGeometryOfKind<"sphere">;

Parameters

ParamTypeRequiredDefaultNotes
optionsSphereOptions✖{}Configure radius or segments before upload.
options.radiusnumber✖0.5Physical radius. Must be > 0 once uploaded.
options.widthSegmentsnumber✖32Meridians. Integer >= 3.
options.heightSegmentsnumber✖16Latitudes. 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

TypeScript
1
2
3
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

TypeScript
1
import type { SphereOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
interface SphereOptions {
  readonly radius?: number;
  readonly widthSegments?: number;
  readonly heightSegments?: number;
}

Parameters

FieldTypeRequiredDefaultNotes
radiusnumber✖0.5Must be > 0.
widthSegmentsnumber✖32Integer >= 3.
heightSegmentsnumber✖16Integer >= 2.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import { plane } from "vgpu/scene";

Signature

TypeScript
1
declare function plane(options?: import("vgpu/scene").PlaneOptions): import("vgpu/scene").SceneGeometryOfKind<"plane">;

Parameters

ParamTypeRequiredDefaultNotes
optionsPlaneOptions✖{}Width/height and tessellation controls.
options.widthnumber✖1Total X extent; must be > 0.
options.heightnumber✖1Total Z extent; must be > 0.
options.widthSegmentsnumber✖1Integer >= 1.
options.heightSegmentsnumber✖1Integer >= 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

TypeScript
1
2
3
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

TypeScript
1
import type { PlaneOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
interface PlaneOptions {
  readonly width?: number;
  readonly height?: number;
  readonly widthSegments?: number;
  readonly heightSegments?: number;
  readonly shading?: "flat" | "smooth";
}

Parameters

FieldTypeRequiredDefaultNotes
widthnumber✖1Must be > 0.
heightnumber✖1Must be > 0.
widthSegmentsnumber✖1Integer >= 1.
heightSegmentsnumber✖1Integer >= 1.
shading"flat" | "smooth"✖"flat"Smooth is reserved for future upgrades.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import { torus } from "vgpu/scene";

Signature

TypeScript
1
declare function torus(options?: import("vgpu/scene").TorusOptions): import("vgpu/scene").SceneGeometryOfKind<"torus">;

Parameters

ParamTypeRequiredDefaultNotes
optionsTorusOptions✖{}Controls radii, arc, and tessellation.
options.radiusnumber✖0.5Distance from origin to tube center; must be > options.tube.
options.tubenumber✖0.2Minor radius; must be > 0.
options.radialSegmentsnumber✖16Around the tube. Integer >= 3.
options.tubularSegmentsnumber✖32Around the ring. Integer >= 3.
options.arcnumber✖Math.PI * 2Radians 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

TypeScript
1
2
3
import { torus } from "vgpu/scene";
 
const gauge = torus({ radius: 1, tube: 0.15, arc: Math.PI * 1.25 });

Notes

TorusOptions

Configuration interface for torus().

Import

TypeScript
1
import type { TorusOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
8
interface TorusOptions {
  readonly radius?: number;
  readonly tube?: number;
  readonly radialSegments?: number;
  readonly tubularSegments?: number;
  readonly arc?: number;
  readonly shading?: "flat" | "smooth";
}

Parameters

FieldTypeRequiredDefaultNotes
radiusnumber✖0.5Must be > tube.
tubenumber✖0.2Minor radius > 0.
radialSegmentsnumber✖16Integer >= 3.
tubularSegmentsnumber✖32Integer >= 3.
arcnumber✖Math.PI * 2Radians > 0.
shading"flat" | "smooth"✖"smooth"Flat duplicates vertices.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import { fullscreenQuad } from "vgpu/scene";

Signature

TypeScript
1
declare function fullscreenQuad(options?: import("vgpu/scene").FullscreenQuadOptions): import("vgpu/scene").SceneGeometryOfKind<"fullscreenQuad">;

Parameters

ParamTypeRequiredDefaultNotes
optionsFullscreenQuadOptions✖{}Reserved for future overrides; currently has no fields.

Returns: SceneGeometryOfKind<"fullscreenQuad">.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import type { FullscreenQuadOptions } from "vgpu/scene";

Signature

TypeScript
1
interface FullscreenQuadOptions {}

Parameters

No fields yet.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import { capsule } from "vgpu/scene";

Signature

TypeScript
1
declare function capsule(options?: import("vgpu/scene").CapsuleOptions): import("vgpu/scene").SceneGeometryOfKind<"capsule">;

Parameters

ParamTypeRequiredDefaultNotes
optionsCapsuleOptions✖{}Radius/height/tessellation overrides.
options.radiusnumber✖0.5Cap radius; must be > 0.
options.heightnumber✖1Cylinder length between caps; total height is height + 2 * radius.
options.radialSegmentsnumber✖32Integer >= 3.
options.heightSegmentsnumber✖8Integer >= 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

TypeScript
1
2
3
import { capsule } from "vgpu/scene";
 
const pillar = capsule({ radius: 0.3, height: 2, shading: "flat" });

Notes

CapsuleOptions

Configuration interface for capsule().

Import

TypeScript
1
import type { CapsuleOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
interface CapsuleOptions {
  readonly radius?: number;
  readonly height?: number;
  readonly radialSegments?: number;
  readonly heightSegments?: number;
  readonly shading?: "flat" | "smooth";
}

Parameters

FieldTypeRequiredDefaultNotes
radiusnumber✖0.5Must be > 0.
heightnumber✖1Can be zero for perfect spheres.
radialSegmentsnumber✖32Integer >= 3.
heightSegmentsnumber✖8Integer >= 2.
shading"flat" | "smooth"✖"smooth"Flat duplicates vertices.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import { cone } from "vgpu/scene";

Signature

TypeScript
1
declare function cone(options?: import("vgpu/scene").ConeOptions): import("vgpu/scene").SceneGeometryOfKind<"cone">;

Parameters

ParamTypeRequiredDefaultNotes
optionsConeOptions✖{}Controls size, caps, and tessellation.
options.radiusnumber✖0.5Base radius; must be > 0.
options.heightnumber✖1Must be > 0.
options.radialSegmentsnumber✖32Integer >= 3.
options.heightSegmentsnumber✖1Integer >= 1.
options.openEndedboolean✖falseOmits the base cap.
options.thetaStartnumber✖0Start angle in radians.
options.thetaLengthnumber✖Math.PI * 2Sweep > 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

TypeScript
1
2
3
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

TypeScript
1
import type { ConeOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
8
9
10
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

FieldTypeRequiredDefaultNotes
radiusnumber✖0.5Must be > 0.
heightnumber✖1Must be > 0.
radialSegmentsnumber✖32Integer >= 3.
heightSegmentsnumber✖1Integer >= 1.
openEndedboolean✖falseOmits the base cap.
thetaStartnumber✖0Start angle in radians.
thetaLengthnumber✖Math.PI * 2Sweep > 0.
shading"flat" | "smooth"✖"smooth"Flat duplicates vertices.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import { cylinder } from "vgpu/scene";

Signature

TypeScript
1
declare function cylinder(options?: import("vgpu/scene").CylinderOptions): import("vgpu/scene").SceneGeometryOfKind<"cylinder">;

Parameters

ParamTypeRequiredDefaultNotes
optionsCylinderOptions✖{}Provide either radius or both radiusTop and radiusBottom.
options.radiusnumber✖0.5Uniform radius fallback when per-end radii are omitted.
options.radiusTopnumber✖options.radiusProvide with radiusBottom for frustums. Must be >= 0.
options.radiusBottomnumber✖options.radiusSame as radiusTop.
options.heightnumber✖1Must be > 0.
options.radialSegmentsnumber✖32Integer >= 3.
options.heightSegmentsnumber✖1Integer >= 1.
options.openEndedboolean✖falseOmits caps (zero-radius caps are always skipped).
options.thetaStartnumber✖0Start angle.
options.thetaLengthnumber✖Math.PI * 2Sweep > 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

TypeScript
1
2
3
import { cylinder } from "vgpu/scene";
 
const tapered = cylinder({ radiusTop: 0.2, radiusBottom: 0.4, height: 1.5, radialSegments: 48 });

Notes

CylinderOptions

Configuration interface for cylinder().

Import

TypeScript
1
import type { CylinderOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
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

FieldTypeRequiredDefaultNotes
radiusnumber✖0.5Uniform fallback radius.
radiusTopnumber✖omitted; resolved from radiusProvide with radiusBottom for frustums. If radius is set, omitting this uses radius.
radiusBottomnumber✖omitted; resolved from radiusProvide with radiusTop. If radius is set, omitting this uses radius.
heightnumber✖1Must be > 0.
radialSegmentsnumber✖32Integer >= 3.
heightSegmentsnumber✖1Integer >= 1.
openEndedboolean✖falseSkip caps when true.
thetaStartnumber✖0Start angle.
thetaLengthnumber✖Math.PI * 2Sweep > 0.
shading"flat" | "smooth"✖"smooth"Flat duplicates vertices.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
import type { CylinderOptions } from "vgpu/scene";
 
const frustum: CylinderOptions = { radiusTop: 0.25, radiusBottom: 0.6 };

Notes

disk

Flat disk descriptor oriented on the XZ plane with upward normals.

Import

TypeScript
1
import { disk } from "vgpu/scene";

Signature

TypeScript
1
declare function disk(options?: import("vgpu/scene").DiskOptions): import("vgpu/scene").SceneGeometryOfKind<"disk">;

Parameters

ParamTypeRequiredDefaultNotes
optionsDiskOptions✖{}Radius and polar slice overrides.
options.radiusnumber✖0.5Must be > 0.
options.segmentsnumber✖32Integer >= 3.
options.thetaStartnumber✖0Slice start angle.
options.thetaLengthnumber✖Math.PI * 2Sweep > 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

TypeScript
1
2
3
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

TypeScript
1
import type { DiskOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
interface DiskOptions {
  readonly radius?: number;
  readonly segments?: number;
  readonly thetaStart?: number;
  readonly thetaLength?: number;
}

Parameters

FieldTypeRequiredDefaultNotes
radiusnumber✖0.5Must be > 0.
segmentsnumber✖32Integer >= 3.
thetaStartnumber✖0Slice start angle.
thetaLengthnumber✖Math.PI * 2Sweep > 0.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import { dodecahedron } from "vgpu/scene";

Signature

TypeScript
1
declare function dodecahedron(options?: import("vgpu/scene").PolyhedronOptions): import("vgpu/scene").SceneGeometryOfKind<"dodecahedron">;

Parameters

ParamTypeRequiredDefaultNotes
optionsPolyhedronOptions✖{}Provide a radius override.
options.radiusnumber✖0.5Circumscribed 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

TypeScript
1
2
3
import { dodecahedron } from "vgpu/scene";
 
const rock = dodecahedron({ radius: 0.8 });

Notes

PolyhedronOptions

Shared options for dodecahedron, icosahedron, octahedron, and tetrahedron.

Import

TypeScript
1
import type { PolyhedronOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
interface PolyhedronOptions {
  readonly radius?: number;
}

Parameters

FieldTypeRequiredDefaultNotes
radiusnumber✖0.5Circumscribed radius; must be > 0.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import { icosahedron } from "vgpu/scene";

Signature

TypeScript
1
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

TypeScript
1
2
3
import { icosahedron } from "vgpu/scene";
 
const crystal = icosahedron({ radius: 0.6 });

Notes

icosphere

Geodesic sphere descriptor obtained by subdividing an icosahedron.

Import

TypeScript
1
import { icosphere } from "vgpu/scene";

Signature

TypeScript
1
declare function icosphere(options?: import("vgpu/scene").IcosphereOptions): import("vgpu/scene").SceneGeometryOfKind<"icosphere">;

Parameters

ParamTypeRequiredDefaultNotes
optionsIcosphereOptions✖{}Radius and subdivision overrides.
options.radiusnumber✖0.5Must be > 0.
options.subdivisionsnumber✖2Integer 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

TypeScript
1
2
3
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

TypeScript
1
import type { IcosphereOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
interface IcosphereOptions {
  readonly radius?: number;
  readonly subdivisions?: number;
  readonly shading?: "flat" | "smooth";
}

Parameters

FieldTypeRequiredDefaultNotes
radiusnumber✖0.5Must be > 0.
subdivisionsnumber✖2Integer in [0, 6].
shading"flat" | "smooth"✖"smooth"Flat duplicates vertices.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import { octahedron } from "vgpu/scene";

Signature

TypeScript
1
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

TypeScript
1
2
3
import { octahedron } from "vgpu/scene";
 
const diamond = octahedron({ radius: 0.7 });

Notes

ring

Annulus descriptor with independent inner/outer radii and optional polar slices.

Import

TypeScript
1
import { ring } from "vgpu/scene";

Signature

TypeScript
1
declare function ring(options?: import("vgpu/scene").RingOptions): import("vgpu/scene").SceneGeometryOfKind<"ring">;

Parameters

ParamTypeRequiredDefaultNotes
optionsRingOptions✖{}Controls radii and slices.
options.innerRadiusnumber✖0.25Must be > 0.
options.outerRadiusnumber✖0.5Must be > innerRadius.
options.segmentsnumber✖32Integer >= 3.
options.thetaStartnumber✖0Slice start.
options.thetaLengthnumber✖Math.PI * 2Sweep > 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

TypeScript
1
2
3
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

TypeScript
1
import type { RingOptions } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
interface RingOptions {
  readonly innerRadius?: number;
  readonly outerRadius?: number;
  readonly segments?: number;
  readonly thetaStart?: number;
  readonly thetaLength?: number;
}

Parameters

FieldTypeRequiredDefaultNotes
innerRadiusnumber✖0.25Must be > 0.
outerRadiusnumber✖0.5Must be > innerRadius.
segmentsnumber✖32Integer >= 3.
thetaStartnumber✖0Slice start.
thetaLengthnumber✖Math.PI * 2Sweep > 0.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import { tetrahedron } from "vgpu/scene";

Signature

TypeScript
1
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

TypeScript
1
2
3
import { tetrahedron } from "vgpu/scene";
 
const marker = tetrahedron({ radius: 0.3 });

Notes

geometries

Frozen namespace exposing every primitive helper through properties, useful for UI pickers or serialization.

Import

TypeScript
1
import { geometries } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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

PropertyTypeRequiredDefaultNotes
geometries.<name>Function✔—Each property mirrors the standalone export.

Returns: Frozen object with the same helpers you can import individually.

Throws: None.

Examples

TypeScript
1
2
3
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

TypeScript
1
import type { GeometryKind } from "vgpu/scene";

Signature

TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
type GeometryKind =
  | "box"
  | "capsule"
  | "cone"
  | "cylinder"
  | "disk"
  | "dodecahedron"
  | "fullscreenQuad"
  | "icosahedron"
  | "icosphere"
  | "octahedron"
  | "plane"
  | "ring"
  | "sphere"
  | "tetrahedron"
  | "torus";

Parameters

ValueTypeRequiredDefaultNotes
listed literalsGeometryKind✔—Each literal matches a descriptor kind.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
4
5
import type { GeometryKind } from "vgpu/scene";
 
function isPolyhedron(kind: GeometryKind): boolean {
  return ["dodecahedron", "icosahedron", "octahedron", "tetrahedron"].includes(kind);
}

Notes

SceneGeometry

Union of every primitive descriptor returned by the geometry helpers.

Import

TypeScript
1
import type { SceneGeometry } from "vgpu/scene";

Signature

TypeScript
1
type SceneGeometry = import("vgpu/scene").SceneGeometry;

Parameters

FieldTypeRequiredDefaultNotes
kindGeometryKind✔—Identifies the primitive helper that produced the descriptor.
propsReadonly<...>✔—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

TypeScript
1
2
3
4
import { box } from "vgpu/scene";
import type { SceneGeometry } from "vgpu/scene";
 
const primitives: SceneGeometry[] = [box({ size: 2 })];

Notes

SceneGeometryOfKind

Conditional helper that narrows a SceneGeometry union to a specific primitive.

Import

TypeScript
1
import type { SceneGeometryOfKind } from "vgpu/scene";

Signature

TypeScript
1
type SceneGeometryOfKind<K extends import("vgpu/scene").GeometryKind> = Extract<import("vgpu/scene").SceneGeometry, { readonly kind: K }>;

Parameters

ParamTypeRequiredDefaultNotes
KGeometryKind✔—Primitive to extract from the union.

Returns: Not applicable.

Throws: None.

Examples

TypeScript
1
2
3
4
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.