# packages/three/src/lib/define-three-layer.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/three/src/lib/define-three-layer.ts#L45). [Back to reference](/reference/functions/define-three-layer/)
1 import { Raycaster, WebGLRenderer, type Object3D } from "three";
2 import {
3   defineRenderLayer,
4   type PibblRenderLayerContext,
5   type PibblRenderLayerTarget,
6 } from "@pibbl/core";
7 import { createDefaultPicker } from "./default-picker.js";
8 import { projectObjectBounds } from "./project-bounds.js";
9 import {
10   createThreeInputBridge,
11   type ThreeInputBridgeController,
12 } from "./three-input-bridge.js";
13 import type {
14   PibblThreeLayerContext,
15   PibblThreeLayerDefinition,
16   PibblThreeLayerResources,
17   PibblThreeTarget,
18 } from "./types.js";
19 
20 interface ThreeAdapterResources<
21   Props,
22   Resources extends PibblThreeLayerResources,
23 > {
24   readonly renderer: WebGLRenderer;
25   readonly input: ThreeInputBridgeController;
26   readonly threeContext: PibblThreeLayerContext;
27   readonly resources: Resources;
28   readonly raycaster: Raycaster;
29   props: Readonly<Props>;
30 }
31 
32 /**
33  * Defines a Pibbl external layer using ordinary Three.js scenes and resources. Each mount owns one
34  * transparent renderer; dispose must release application-created resources, and animation uses
35  * Pibbl's supplied frame and invalidation.
36  *
37  * @param definition - Resource lifecycle, rendering overrides, targets, and picking configuration.
38  * See {@link PibblThreeLayerDefinition} .
39  * @returns A Pibbl component mounting a persistent Three.js scene boundary with an adapter-owned
40  * renderer.
41  *
42  * @see {@link PibblThreeLayerDefinition}
43  * @see {@link PibblThreeLayerResources}
44  */
45 export function defineThreeLayer<
46   Props,
47   Resources extends PibblThreeLayerResources,
48 >(definition: PibblThreeLayerDefinition<Props, Resources>) {
49   const immutableDefinition = snapshotDefinition(definition);
50   return defineRenderLayer<
51     Props,
52     ThreeAdapterResources<Props, Resources>,
53     Object3D
54   >({
55     create(context, initialProps) {
56       const renderer = new WebGLRenderer({
57         ...immutableDefinition.renderer,
58         canvas: context.canvas,
59         alpha: true,
60       });
61       const input = createThreeInputBridge(context);
62       const threeContext = createThreeContext(context, renderer, input);
63       try {
64         const resources = immutableDefinition.create(
65           threeContext,
66           initialProps,
67         );
68         assertSynchronous(resources, "create");
69         assertThreeResources(resources);
70         input.finishCreate();
71         return {
72           renderer,
73           input,
74           threeContext,
75           resources,
76           raycaster: new Raycaster(),
77           props: initialProps,
78         };
79       } catch (error) {
80         try {
81           input.dispose();
82         } finally {
83           renderer.dispose();
84         }
85         throw error;
86       }
87     },
88     update(adapter, props) {
89       assertSynchronous(
90         immutableDefinition.update?.(
91           adapter.resources,
92           props,
93           adapter.threeContext,
94         ),
95         "update",
96       );
97       adapter.props = props;
98     },
99     resize(adapter, size) {
100       adapter.renderer.setPixelRatio(1);
101       adapter.renderer.setSize(size.backingWidth, size.backingHeight, false);
102       assertSynchronous(
103         immutableDefinition.resize?.(
104           adapter.resources,
105           size,
106           adapter.threeContext,
107         ),
108         "resize",
109       );
110     },
111     render(adapter, frame) {
112       if (immutableDefinition.render) {
113         assertSynchronous(
114           immutableDefinition.render(
115             adapter.resources,
116             frame,
117             adapter.threeContext,
118           ),
119           "render",
120         );
121       } else {
122         adapter.renderer.render(
123           adapter.resources.scene,
124           adapter.resources.camera,
125         );
126       }
127     },
128     dispose(adapter) {
129       try {
130         assertSynchronous(
131           immutableDefinition.dispose?.(
132             adapter.resources,
133             adapter.threeContext,
134           ),
135           "dispose",
136         );
137       } finally {
138         try {
139           adapter.input.dispose();
140         } finally {
141           adapter.renderer.dispose();
142         }
143       }
144     },
145     interaction: {
146       settle(adapter, props, size) {
147         const declaredTargets =
148           immutableDefinition.targets?.(adapter.resources, props) ?? [];
149         assertSynchronous(declaredTargets, "targets");
150         const declarations = Array.from(declaredTargets);
151         const targetMap = new Map<Object3D, PibblThreeTarget>();
152         const disabledRoots = new Set<Object3D>();
153         const targets: PibblRenderLayerTarget<Object3D>[] = [];
154         for (const declaration of declarations) {
155           targetMap.set(declaration.object, declaration);
156           if (declaration.pointerEvents === "none") {
157             disabledRoots.add(declaration.object);
158           }
159           const projectedBounds =
160             declaration.keyboardFocusable &&
161             !declaration.keyboardNavigationBounds
162               ? projectObjectBounds(
163                   declaration.object,
164                   adapter.resources.camera,
165                   size,
166                 )
167               : declaration.keyboardNavigationBounds;
168           targets.push({
169             target: declaration.object,
170             handlers: declaration.handlers,
171             pointerEvents: declaration.pointerEvents,
172             cursor: declaration.cursor,
173             keyboardFocusable:
174               declaration.keyboardFocusable && projectedBounds !== undefined,
175             keyboardNavigationBounds: projectedBounds,
176           });
177         }
178         let hitTest;
179         if (immutableDefinition.pick) {
180           const picker = immutableDefinition.pick(
181             adapter.resources,
182             adapter.threeContext,
183           );
184           assertSynchronous(picker, "pick");
185           hitTest = (point: Readonly<{ x: number; y: number }>) => {
186             const result = picker(point);
187             assertSynchronous(result, "picker");
188             return result;
189           };
190         } else {
191           hitTest = createDefaultPicker(
192             adapter.resources.scene,
193             adapter.resources.camera,
194             adapter.raycaster,
195             size,
196             targetMap,
197             disabledRoots,
198           );
199         }
200         return {
201           targets,
202           hitTest,
203           onInput: adapter.input.connected
204             ? (input) => adapter.input.deliver(input)
205             : undefined,
206         };
207       },
208     },
209   });
210 }
211 
212 function assertSynchronous(value: unknown, callback: string): void {
213   if (value && typeof (value as { then?: unknown }).then === "function") {
214     throw new TypeError(`defineThreeLayer ${callback}() must be synchronous.`);
215   }
216 }
217 
218 function createThreeContext(
219   context: Readonly<PibblRenderLayerContext>,
220   renderer: WebGLRenderer,
221   input: ThreeInputBridgeController,
222 ): PibblThreeLayerContext {
223   return Object.freeze({
224     canvas: context.canvas,
225     get size() {
226       return context.size;
227     },
228     invalidate: () => context.invalidate(),
229     renderer,
230     input,
231   });
232 }
233 
234 function assertThreeResources(
235   resources: PibblThreeLayerResources,
236 ): asserts resources is PibblThreeLayerResources {
237   if (!resources?.scene?.isScene || !resources?.camera?.isCamera) {
238     throw new TypeError(
239       "defineThreeLayer create() must return Three scene and camera resources.",
240     );
241   }
242 }
243 
244 function snapshotDefinition<Props, Resources extends PibblThreeLayerResources>(
245   definition: PibblThreeLayerDefinition<Props, Resources>,
246 ): PibblThreeLayerDefinition<Props, Resources> {
247   return Object.freeze({
248     renderer: definition.renderer
249       ? Object.freeze({ ...definition.renderer })
250       : undefined,
251     create: definition.create,
252     update: definition.update,
253     resize: definition.resize,
254     render: definition.render,
255     targets: definition.targets,
256     pick: definition.pick,
257     dispose: definition.dispose,
258   });
259 }
260
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.