@solidrt/3d 0.0.55 → 0.0.57

package/src/components/scene.tsx

@@ -0,0 +1,281 @@
+import { createEffect, displayScale, getBoundingBoxViewport, getLayoutBox, onCleanup, onLayout, untrack } from "@solidrt/core"
+import type { Element, ParentComponent, PointerFeed, TextureId } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { createScene } from "../scene.ts"
+import { feedPointer } from "../scene-pointer.ts"
+import type { EnvironmentOptions, FogOptions, Scene as SceneHandle, SkyboxOptions, ToneMapping } from "../scene.ts"
+import type { ScenePointerEvent, SceneTapEvent, SceneWheelEvent } from "../node.ts"
+import type { CameraUpdate } from "../camera.ts"
+
+/**
+ * The scene's own pointer events, the root of the walk: every event the
+ * nodes let through arrives here last - `event.mesh` is the hit it
+ * bubbled from, or null over empty space (a tap there with `mesh` null is
+ * "deselect"), `x`/`y` scene pixels. scene.listen as props; an
+ * `<OrbitCamera>` child's feed listens at the same root.
+ */
+export type ScenePointerProps = {
+  onPointerDown?: (event: ScenePointerEvent) => void
+  onPointerMove?: (event: ScenePointerEvent) => void
+  onPointerUp?: (event: ScenePointerEvent) => void
+  onWheel?: (event: SceneWheelEvent) => void
+  onTap?: (event: SceneTapEvent) => void
+}
+
+export type SceneProps = ScenePointerProps & {
+  /**
+   * Target pixels - give both, or neither. Omitted, the scene FILLS: the
+   * built-in leaf is laid out at 100% of its parent's box (give it a sized
+   * parent, as on the web) and the target tracks the leaf's on-screen size
+   * in device pixels - display scale, designSize fits and ancestor
+   * transforms included - so a bare `<Scene>` renders at native density on
+   * any display, and viewport-relative camera controls scale with the box.
+   * Fill or fixed is decided at mount. `output` needs explicit sizes (the
+   * target cannot follow a leaf it does not own); the leaf's own
+   * width/height are then layout, so render size and display size separate
+   * (supersampling).
+   */
+  width?: number
+  height?: number
+  clearColor?: [number, number, number, number]
+  /**
+   * Drive the scene camera declaratively (scene.setCamera as a prop): a
+   * partial CameraUpdate, absent keys keep their values - `ortho` included,
+   * which `<PerspectiveCamera>` by its name never sets. The prop and the
+   * `<PerspectiveCamera>` child write the same scene state, so use one
+   * form, not both (last write wins). The 2d layers' `camera` prop, one
+   * dimension up.
+   */
+  camera?: CameraUpdate
+  /** The background drawn behind the meshes, inside the scene's own pass
+   * (scene.setBackground): fragment GLSL (vUV/iResolution/fragColor plus
+   * the vRay view ray, so a createShaderTexture backdrop ports verbatim
+   * and a directional sky is a few lines) or a skybox `{ cube, intensity?,
+   * rotation? }`. Reactive - swapping the source replaces the background,
+   * a skybox's knobs update in place; undefined removes it. Three's
+   * `scene.background = color` is `clearColor` here. */
+  background?: string | SkyboxOptions
+  /** The cube map reflective `lit` materials mirror (scene.setEnvironment):
+   * `{ cube, intensity?, rotation? }`, typically the skybox's own cube
+   * turned with it. Reactive; undefined removes it. */
+  environment?: EnvironmentOptions
+  /** Scene-wide fog (scene.setFog): linear `{ color, near, far }` or exp2
+   * `{ color, density }`, optionally thinning above `height` by
+   * `heightFalloff`; every standard material fades toward `color` by
+   * distance from the camera. Reactive; undefined removes it. Match
+   * `color` to clearColor or the background, which is not fogged. */
+  fog?: FogOptions
+  /** Output tone mapping (scene.setToneMapping): "none" (default) or
+   * "aces". Reactive. */
+  toneMapping?: ToneMapping
+  /** Output exposure (scene.setExposure), default 1. Reactive. */
+  exposure?: number
+  /** The scene target's layer mask (scene.setLayers as a prop; default 1):
+   * the scene draws the meshes whose `layers` intersect it. Reactive. */
+  layers?: number
+  /** `"texture"` exposes the target's depth as `scene.depthTexture` (a
+   * depth-reading post effect's input). Fixed at creation; not with
+   * `samples`. */
+  depth?: true | "texture"
+  label?: string
+  /** Multisample count (1, 2, 4 or 8; default 1): anti-aliased mesh edges.
+   * Fixed at creation. */
+  samples?: 1 | 2 | 4 | 8
+  ref?: (scene: SceneHandle) => void
+  /**
+   * Compose the output yourself: called once (untracked) with the scene's
+   * texture id, and its return renders in place of the built-in `<texture>`
+   * leaf - a `<d-texture>`, a leaf carrying paint/pointer/layout props, or
+   * a post-effect chain (a shader target sampling the id; created in the
+   * callback it disposes with the Scene). Return null to render no leaf.
+   * Pointer events then need the scene's handlers on your leaf:
+   * `<texture src={texture} {...useScene().scene.handlers} />` - one
+   * spread carries the node events, the scene's own and the pointer
+   * feed, which listens at the scene's root.
+   */
+  output?: (texture: TextureId) => Element
+  /**
+   * Pointer events (default on): the built-in leaf carries scene.handlers,
+   * so nodes, the scene's own handlers and a camera control's feed
+   * receive input. `false` detaches them - the leaf then costs no pointer
+   * routing at all.
+   */
+  events?: boolean
+  /**
+   * The pointer feed of the scene's leaf (createPointerFeed), fed from
+   * the scene's root - the events the nodes let through: a mesh that
+   * claims its press (stopPropagation on its down) keeps a camera control
+   * bound to the feed out of that drag. The feed's gestures - drag,
+   * pinch, two-finger pan, wheel, mouse motion under lock - come from
+   * this scene, and an input map binds them to the camera controls
+   * inside; `useScene().pointer` is this feed. Fixed at creation. Without
+   * one the leaf feeds no gestures and the controls move only through
+   * their handles.
+   */
+  pointer?: PointerFeed
+}
+
+/**
+ * Owns a draw target and composites it as an ordinary `<texture>` leaf, so
+ * the output takes layout, transforms, blendMode, and pointer events like
+ * any element - or hand `output` the texture id and compose it yourself.
+ * Children (Mesh/Group/PerspectiveCamera) render nothing themselves - they
+ * populate the retained scene through context.
+ */
+// Creation size of a fill-mode target: the first onLayout replaces it
+// before the first paint, so it only has to be a valid texture size.
+const FILL_INITIAL_SIZE = 1
+
+export let Scene: ParentComponent<SceneProps> = props => {
+  // Fill vs fixed target is decided at mount, like `output`: both
+  // width and height (fixed pixels) or neither (fill).
+  let fill = untrack(() => {
+    if ((props.width === undefined) !== (props.height === undefined)) {
+      throw new Error("Scene: width and height come together - give both (fixed target) or neither (fill)")
+    }
+    if (props.width === undefined && props.output) {
+      throw new Error("Scene: fill needs the built-in leaf - with output, give width and height")
+    }
+    return props.width === undefined
+  })
+  // The initial props seed createScene, so `ref` (below) hands out a
+  // configured scene and the first frame draws it whole; the effects
+  // after this follow changes only (`defer`).
+  let scene = untrack(() => {
+    let s = createScene(props.width ?? FILL_INITIAL_SIZE, props.height ?? FILL_INITIAL_SIZE, {
+      clearColor: props.clearColor,
+      label: props.label,
+      samples: props.samples,
+      depth: props.depth,
+      background: props.background,
+      environment: props.environment,
+      fog: props.fog,
+      toneMapping: props.toneMapping,
+      exposure: props.exposure,
+      layers: props.layers,
+    })
+    if (props.camera) s.setCamera(props.camera)
+    return s
+  })
+  createEffect(
+    () => [props.width, props.height] as const,
+    ([w, h]) => {
+      if ((w === undefined) !== (h === undefined) || (w === undefined) !== fill) {
+        throw new Error("Scene: fill/fixed is mount-fixed - width/height cannot appear or disappear")
+      }
+      if (!fill) scene.setSize(w!, h!)
+    },
+  )
+  createEffect(
+    () => props.camera,
+    camera => {
+      if (camera) scene.setCamera(camera)
+    },
+    { defer: true },
+  )
+  createEffect(
+    () => props.background,
+    b => scene.setBackground(b ?? null),
+    { defer: true },
+  )
+  createEffect(
+    () => props.environment,
+    e => scene.setEnvironment(e ?? null),
+    { defer: true },
+  )
+  createEffect(
+    () => props.fog,
+    f => scene.setFog(f ?? null),
+    { defer: true },
+  )
+  createEffect(
+    () => props.toneMapping,
+    t => scene.setToneMapping(t ?? "none"),
+    { defer: true },
+  )
+  createEffect(
+    () => props.exposure,
+    e => scene.setExposure(e ?? 1),
+    { defer: true },
+  )
+  createEffect(
+    () => props.layers,
+    l => scene.setLayers(l ?? 1),
+    { defer: true },
+  )
+  untrack(() => props.ref)?.(scene)
+  // The pointer feed the app handed in listens at the scene's root, and
+  // children reach it through useScene().pointer. Fixed at creation, like
+  // output.
+  let pointer = untrack(() => props.pointer) ?? null
+  if (pointer) onCleanup(feedPointer(scene, pointer))
+  // The scene's own handlers at the root of the walk; the props are read
+  // per event, so a handler prop may change without re-registering.
+  onCleanup(
+    scene.listen({
+      onPointerDown: e => props.onPointerDown?.(e),
+      onPointerMove: e => props.onPointerMove?.(e),
+      onPointerUp: e => props.onPointerUp?.(e),
+      onWheel: e => props.onWheel?.(e),
+      onTap: e => props.onTap?.(e),
+    }),
+  )
+  let output = untrack(() => props.output)
+  let events = untrack(() => props.events) !== false
+  let leafNode: { id: number } | undefined
+  // The built-in leaf's laid-out box in ITS units - what pointer
+  // localX/localY report in and every handlersFor scales against. Fixed
+  // mode lays the leaf out at the target size; fill mode reads the box
+  // back (getLayoutBox, the untransformed read, so a designSize fit or
+  // ancestor transform never skews events). Zero before the first layout:
+  // no event can arrive before one, and a degenerate layout passes
+  // coordinates through unscaled. A custom output leaf registers its own
+  // layout via handlersFor.
+  let builtinLayout = fill
+    ? () => (leafNode && getLayoutBox(leafNode)) || { width: 0, height: 0 }
+    : () => ({ width: props.width!, height: props.height! })
+  if (fill) {
+    // Fill sizing: after every layout (and on display-scale changes, which
+    // lay nothing out) the target follows the leaf's on-screen box in
+    // device pixels - getBoundingBoxViewport composes designSize fits and
+    // ancestor transforms, so the scene renders at true density wherever
+    // it sits. onLayout runs before paint (no frame draws at a stale
+    // size); setSize no-ops when nothing changed. apply runs as an
+    // onLayout handler and as an effect apply, both untracked scopes, so
+    // its scale read is wrapped in an explicit untrack (the effect's
+    // compute is what tracks it).
+    let apply = () =>
+      untrack(() => {
+        if (!leafNode) return
+        let box = getBoundingBoxViewport(leafNode)
+        if (!box) return
+        let scale = displayScale()
+        scene.setSize(Math.max(1, Math.round(box.width * scale)), Math.max(1, Math.round(box.height * scale)))
+      })
+    onLayout(apply)
+    createEffect(() => displayScale(), apply)
+  }
+  // Pointer events on the built-in leaf: at target size the plain
+  // handlers, in fill mode scaled from the laid-out box.
+  let sceneHandlers = fill ? scene.handlersFor(builtinLayout) : scene.handlers
+  return (
+    <SceneContext value={{ scene, parent: scene.root, viewport: scene, pointer }}>
+      {output ? (
+        untrack(() => output(scene.texture))
+      ) : (
+        <texture
+          ref={(n: { id: number }) => (leafNode = n)}
+          src={scene.texture}
+          width={fill ? "100%" : props.width}
+          height={fill ? "100%" : props.height}
+          onPointerDown={events ? sceneHandlers.onPointerDown : undefined}
+          onPointerMove={events ? sceneHandlers.onPointerMove : undefined}
+          onPointerUp={events ? sceneHandlers.onPointerUp : undefined}
+          onPointerLeave={events ? sceneHandlers.onPointerLeave : undefined}
+          onWheel={events ? sceneHandlers.onWheel : undefined}
+        />
+      )}
+      {props.children}
+    </SceneContext>
+  )
+}

package/src/components/spot-light.tsx

@@ -0,0 +1,65 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { syncNode } from "./node-props.ts"
+import type { TransformProps } from "./node-props.ts"
+import { add, remove } from "../node.ts"
+import { createSpotLight, setLight } from "../light.ts"
+import type { SpotLight as SpotLightNode, SpotShadowOptions } from "../light.ts"
+import type { Vec3 } from "../math.ts"
+
+export type SpotLightProps = TransformProps & {
+  /** Aim direction in the node's local space; default [0, -1, 0], a
+   * lamp pointing straight down. */
+  direction?: Vec3
+  color?: Vec3
+  intensity?: number
+  /** Falloff cutoff in world units (0 = no cutoff). */
+  distance?: number
+  /** Cone half-angle in DEGREES, (0, 90]; default 60 (degrees like
+   * camera fov; Three's radians convert as `angle * 180 / PI`). */
+  angle?: number
+  /** 0..1 fraction of the cone fading to the rim; default 0. */
+  penumbra?: number
+  /** Falloff exponent; default 2 (inverse square). */
+  decay?: number
+  /** Render a shadow map from this light (a perspective map of its
+   * cone; one shadow slot). */
+  castShadow?: boolean
+  /** Shadow-map options (mapSize, bias, normalBias, near), merged key
+   * by key. */
+  shadow?: SpotShadowOptions
+  ref?: (light: SpotLightNode) => void
+}
+
+/** A spot light node (createSpotLight): a cone from the node's world
+ * position along its local `direction` - give it a `position`, and aim
+ * it with `direction` or a parent's rotation. Counts against MAX_LIGHTS
+ * with the other non-ambient lights. */
+export let SpotLight: VoidComponent<SpotLightProps> = props => {
+  let ctx = useContext(SceneContext)
+  let light = untrack(() =>
+    createSpotLight({
+      direction: props.direction,
+      color: props.color,
+      intensity: props.intensity,
+      distance: props.distance,
+      angle: props.angle,
+      penumbra: props.penumbra,
+      decay: props.decay,
+      castShadow: props.castShadow,
+      shadow: props.shadow,
+    }),
+  )
+  add(ctx.parent, light)
+  syncNode(light, props)
+  createEffect(
+    () =>
+      [props.direction, props.color, props.intensity, props.distance, props.angle, props.penumbra, props.decay, props.castShadow, props.shadow] as const,
+    ([direction, color, intensity, distance, angle, penumbra, decay, castShadow, shadow]) =>
+      setLight(light, { direction, color, intensity, distance, angle, penumbra, decay, castShadow, shadow }),
+  )
+  untrack(() => props.ref)?.(light)
+  onCleanup(() => remove(light))
+  return null
+}

package/src/components/sprite.tsx

@@ -0,0 +1,38 @@
+import { onCleanup, untrack, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import type { TransformProps, PointerEventProps } from "./node-props.ts"
+import { syncMesh } from "./mesh.tsx"
+import { add, remove } from "../node.ts"
+import { createSprite } from "../mesh.ts"
+import type { Mesh as MeshNode } from "../mesh.ts"
+import type { ShaderParams } from "@solidrt/core/gpu"
+import type { Material } from "../material.ts"
+
+export type SpriteProps = TransformProps & PointerEventProps & {
+  /** A `sprite()` material (any material draws, only a sprite one turns). */
+  material: Material
+  /** Per-mesh uniforms, merge semantics - as on Mesh. */
+  params?: ShaderParams
+  /** Explicit draw-order key (setRenderOrder as a prop); default 0. */
+  renderOrder?: number
+  /** Layer membership bitmask (setLayers as a prop; default 1). */
+  layers?: number
+  /** Frustum culling switch (setCulling as a prop; default true). */
+  frustumCulled?: boolean
+  /** World units the culled box grows by (setCulling as a prop; default 0). */
+  cullMargin?: number
+  ref?: (mesh: MeshNode) => void
+}
+
+/** A camera-facing unit quad (createSprite as a component): no geometry
+ * prop, `scale` is its world size, rotation is ignored. */
+export let Sprite: VoidComponent<SpriteProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() => createSprite(props.material))
+  add(ctx.parent, mesh)
+  syncMesh(mesh, props)
+  untrack(() => props.ref)?.(mesh)
+  onCleanup(() => remove(mesh))
+  return null
+}

package/src/components/view3d.tsx

@@ -0,0 +1,152 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { Element, ParentComponent, PointerFeed, TextureId } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { feedPointer } from "../scene-pointer.ts"
+import type { ViewHandle, ViewOptions } from "../scene.ts"
+import type { CameraUpdate } from "../camera.ts"
+import type { ScenePointerProps } from "./scene.tsx"
+
+export type View3dProps = Pick<ViewOptions, "clearColor" | "label" | "overrideMaterial" | "fog" | "depth" | "samples" | "filter" | "wrap" | "into"> &
+  ScenePointerProps & {
+  /** Target pixels, live: the view resizes, or its tile moves. Fixed
+   * only, for now: a fill mode like Scene's is a later, additive step. */
+  width: number
+  height: number
+  /** The tile's top-left in `into` (view.setRect as props), live; without
+   * `into` they mean nothing. */
+  x?: number
+  y?: number
+  /** The view's layer mask (view.setLayers as a prop; default 1). Live. */
+  layers?: number
+  /** Partial camera update on the view's own camera (view.setCamera):
+   * absent keys keep their values. Live. The `<PerspectiveCamera>` child
+   * writes the same state - use one form, not both. */
+  camera?: CameraUpdate
+  /**
+   * Compose the leaf yourself: called once (untracked) with view.texture,
+   * and its return renders in place of the built-in `<texture>` leaf.
+   * Pointer events through the view then need its handlers on your leaf:
+   * `<texture src={texture} {...view.handlers} />` (the view from `ref`);
+   * the view's pointer feed listens at its root. A tiled view's id is a
+   * draw target, not a texture: show `into` with srcX/srcY, as the
+   * built-in leaf does.
+   */
+  output?: (texture: TextureId) => Element
+  /** Pointer events (default on): the built-in leaf carries the view's
+   * handlers. `false` detaches them. */
+  events?: boolean
+  /** The pointer feed of this view's leaf (see Scene's `pointer`), fed
+   * from the view's root - the events the nodes let through - so a map
+   * bound to it drives the camera controls inside this view and no other;
+   * inside, `useScene().pointer` is this feed. Fixed at creation. */
+  pointer?: PointerFeed
+  ref?: (view: ViewHandle) => void
+}
+
+/**
+ * A second rendering of the enclosing scene from a camera of its own
+ * (scene.createView as a component): the same meshes, materials, lights
+ * and shadow maps, another target and one entry per mesh, so it costs no
+ * per-frame JS. Composites as an ordinary `<texture>` leaf at the target
+ * size (a tile of `into` shown through srcX/srcY), or through `output`.
+ * Camera-control children (`<OrbitCamera>`, `<FirstPersonCamera>`,
+ * `<PerspectiveCamera>`) drive the VIEW's camera: inside, `useScene()`
+ * reports the view as `viewport` and the view leaf's feed as `pointer`,
+ * so a map over that feed moves this view alone. Node children (`<Mesh>`) mount
+ * to the scene as they would outside - a view mirrors the scene's meshes,
+ * it has none of its own. Nodes under the view's leaf get their ordinary
+ * pointer handlers, picked through the view's camera; the view's own
+ * `onPointer*`/`onWheel`/`onTap` are the last stop of that walk
+ * (`event.mesh` null over empty space).
+ */
+export let View3d: ParentComponent<View3dProps> = props => {
+  let ctx = useContext(SceneContext)
+  // A tile of `into` or a target of its own is decided at mount, like
+  // Scene's fill/fixed: `into` cannot appear or disappear.
+  let tiled = untrack(() => props.into !== undefined)
+  // The initial props seed createView, so `ref` hands out a configured
+  // view and the first frame draws it whole; the effects follow changes
+  // only (`defer`).
+  let view = untrack(() => {
+    let v = ctx.scene.createView({
+      width: props.width,
+      height: props.height,
+      x: props.x,
+      y: props.y,
+      layers: props.layers,
+      clearColor: props.clearColor,
+      label: props.label,
+      overrideMaterial: props.overrideMaterial,
+      fog: props.fog,
+      depth: props.depth,
+      samples: props.samples,
+      filter: props.filter,
+      wrap: props.wrap,
+      into: props.into,
+    })
+    if (props.camera) v.setCamera(props.camera)
+    return v
+  })
+  createEffect(
+    () => props.camera,
+    camera => {
+      if (camera) view.setCamera(camera)
+    },
+    { defer: true },
+  )
+  createEffect(
+    () => [props.x, props.y, props.width, props.height] as const,
+    ([x, y, width, height]) => {
+      if (tiled) view.setRect({ x: x ?? 0, y: y ?? 0, width, height })
+      else view.setSize(width, height)
+    },
+    { defer: true },
+  )
+  createEffect(
+    () => props.layers,
+    l => view.setLayers(l ?? 1),
+    { defer: true },
+  )
+  untrack(() => props.ref)?.(view)
+  onCleanup(() => view.dispose())
+  // The pointer feed the app handed in (see Scene) listens at the view's
+  // root; children reach it through useScene().pointer.
+  let pointer = untrack(() => props.pointer) ?? null
+  if (pointer) onCleanup(feedPointer(view, pointer))
+  // The view's own handlers at the root of the walk; the props are read
+  // per event, so a handler prop may change without re-registering.
+  onCleanup(
+    view.listen({
+      onPointerDown: e => props.onPointerDown?.(e),
+      onPointerMove: e => props.onPointerMove?.(e),
+      onPointerUp: e => props.onPointerUp?.(e),
+      onWheel: e => props.onWheel?.(e),
+      onTap: e => props.onTap?.(e),
+    }),
+  )
+  let output = untrack(() => props.output)
+  let events = untrack(() => props.events) !== false
+  return (
+    <SceneContext value={{ scene: ctx.scene, parent: ctx.parent, viewport: view, pointer }}>
+      {output ? (
+        untrack(() => output(view.texture))
+      ) : (
+        <texture
+          src={tiled ? props.into : view.texture}
+          width={props.width}
+          height={props.height}
+          srcX={tiled ? (props.x ?? 0) : undefined}
+          srcY={tiled ? (props.y ?? 0) : undefined}
+          srcW={tiled ? props.width : undefined}
+          srcH={tiled ? props.height : undefined}
+          onPointerDown={events ? view.handlers.onPointerDown : undefined}
+          onPointerMove={events ? view.handlers.onPointerMove : undefined}
+          onPointerUp={events ? view.handlers.onPointerUp : undefined}
+          onPointerLeave={events ? view.handlers.onPointerLeave : undefined}
+          onWheel={events ? view.handlers.onWheel : undefined}
+        />
+      )}
+      {props.children}
+    </SceneContext>
+  )
+}