# packages/three/src/lib/types.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/types.ts#L78). [Back to reference](/reference/types/three/)
1 import type { defineThreeLayer } from './define-three-layer.js';
2 import type * as THREE from "three";
3 import type {
4   PibblEventHandlers,
5   PibblPointerEvents,
6   PibblRenderLayerContext,
7   PibblRenderLayerFrame,
8   PibblRenderLayerHit,
9   PibblRenderLayerSize,
10   LayoutBox,
11 } from "@pibbl/core";
12 
13 /**
14  * Application-owned scene and camera required by a Three layer; additional resources may be stored
15  * alongside them.
16  *
17  * @see {@link PibblThreeLayerDefinition}
18  * @see {@link defineThreeLayer}
19  * @see {@link THREE.Scene}
20  * @see {@link THREE.Camera}
21  */
22 export interface PibblThreeLayerResources {
23   /** Application-owned scene rendered by the layer. See {@link THREE.Scene}. */
24   readonly scene: THREE.Scene;
25   /** Application-owned camera used for rendering and picking. See {@link THREE.Camera}. */
26   readonly camera: THREE.Camera;
27 }
28 
29 /**
30  * A Three object registered as a Pibbl logical event and keyboard-focus target.
31  *
32  * @see {@link PibblEventHandlers}
33  * @see {@link PibblPointerEvents}
34  * @see {@link LayoutBox}
35  * @see {@link PibblThreeLayerDefinition}
36  * @see {@link THREE.Object3D}
37  */
38 export interface PibblThreeTarget {
39   /** Three object registered as a Pibbl logical target. See {@link THREE.Object3D}. */
40   readonly object: THREE.Object3D;
41   /** Event handlers dispatched for this logical target. See {@link PibblEventHandlers}. */
42   readonly handlers?: PibblEventHandlers;
43   /** Whether this content participates in pointer targeting. See {@link PibblPointerEvents}. */
44   readonly pointerEvents?: PibblPointerEvents;
45   /** Cursor shown while this target owns pointer presentation. See {@link PibblThreeTarget}. */
46   readonly cursor?: string;
47   /** Whether the target may receive keyboard focus. See {@link PibblThreeTarget}. */
48   readonly keyboardFocusable?: boolean;
49   /** Logical rectangle used for directional keyboard navigation. See {@link LayoutBox}. */
50   readonly keyboardNavigationBounds?: Readonly<LayoutBox>;
51 }
52 
53 /**
54  * The target, block, or miss result of picking in a Three layer.
55  *
56  * @see {@link PibblRenderLayerHit}
57  * @see {@link PibblThreePicker}
58  * @see {@link THREE.Object3D}
59  */
60 export type PibblThreePickResult = PibblRenderLayerHit<THREE.Object3D>;
61 
62 /**
63  * Three renderer construction options, excluding the canvas and transparency owned by the adapter.
64  *
65  * @see {@link PibblThreeLayerDefinition}
66  * @see {@link THREE.WebGLRendererParameters}
67  */
68 export type PibblThreeRendererOptions = Omit<
69   THREE.WebGLRendererParameters,
70   "canvas" | "alpha"
71 >;
72 
73 /**
74  * Connects Three controls to Pibbl-routed input through an element-compatible bridge.
75  *
76  * @see {@link PibblThreeLayerContext}
77  */
78 export interface PibblThreeInputBridge {
79   /**
80    * Creates controls against the Pibbl input bridge and returns the created control instance. See
81    * {@link PibblThreeInputBridge}.
82    * @param create - Factory that constructs controls using Pibbl's routed-input element.
83    * @returns The control object returned by the factory.
84    */
85   connect<Control>(create: (element: HTMLElement) => Control): Control;
86 }
87 
88 /**
89  * Hit-tests a layer-local logical point against a settled Three scene.
90  *
91  * @param point - Pointer position in layer-local logical coordinates.
92  * @returns A Three object target, a blocking hit, or a miss. See {@link PibblThreePickResult}.
93  *
94  * @see {@link PibblThreePickResult}
95  * @see {@link PibblThreeLayerDefinition}
96  */
97 export type PibblThreePicker = (
98   point: Readonly<{
99     /**
100      * Horizontal coordinate or displacement in the containing coordinate system. See
101      * {@link PibblThreePicker}.
102      */
103     x: number;
104     /**
105      * Vertical coordinate or displacement in the containing coordinate system. See
106      * {@link PibblThreePicker}.
107      */
108     y: number;
109   }>,
110 ) => PibblThreePickResult;
111 
112 /**
113  * Pibbl surface context extended with the adapter-owned renderer and controls-input bridge.
114  *
115  * @see {@link PibblRenderLayerContext}
116  * @see {@link PibblThreeInputBridge}
117  * @see {@link PibblThreeLayerDefinition}
118  * @see {@link THREE.WebGLRenderer}
119  */
120 export interface PibblThreeLayerContext extends PibblRenderLayerContext {
121   /** The transparent renderer owned by this mounted adapter. See {@link PibblThreeLayerContext}. */
122   readonly renderer: THREE.WebGLRenderer;
123   /**
124    * Bridge used to connect Three controls to Pibbl-routed events. See {@link PibblThreeInputBridge}.
125    */
126   readonly input: PibblThreeInputBridge;
127 }
128 
129 /**
130  * Three scene resource lifecycle, optional rendering overrides, and Pibbl interaction integration.
131  *
132  * @see {@link PibblThreeLayerResources}
133  * @see {@link PibblThreeRendererOptions}
134  * @see {@link PibblThreeLayerContext}
135  * @see {@link PibblRenderLayerSize}
136  * @see {@link PibblRenderLayerFrame}
137  * @see {@link PibblThreeTarget}
138  * @see {@link PibblThreePicker}
139  * @see {@link defineThreeLayer}
140  */
141 export interface PibblThreeLayerDefinition<
142   Props,
143   Resources extends PibblThreeLayerResources,
144 > {
145   /**
146    * Three renderer construction options; Pibbl supplies the canvas and enables transparency. See
147    * {@link PibblThreeRendererOptions}.
148    */
149   readonly renderer?: PibblThreeRendererOptions;
150   /**
151    * Creates the application's scene, camera, and other explicitly owned resources. See
152    * {@link PibblThreeLayerDefinition}.
153    * @param context - Adapter-owned renderer, surface, input bridge, and invalidation services. See
154    * {@link PibblThreeLayerContext} .
155    * @param initialProps - Props from the first mounted render.
156    * @returns Application-owned scene, camera, and additional resources retained for this mount.
157    */
158   create(context: PibblThreeLayerContext, initialProps: Readonly<Props>): Resources;
159   /**
160    * Applies current props to the persistent Three resources. See {@link PibblThreeLayerDefinition}.
161    * @param resources - Resources returned by create.
162    * @param props - Latest layer props.
163    * @param context - Adapter-owned renderer, surface, input bridge, and invalidation services. See
164    * {@link PibblThreeLayerContext} .
165    */
166   update?(
167     resources: Resources,
168     props: Readonly<Props>,
169     context: PibblThreeLayerContext,
170   ): void;
171   /**
172    * Updates camera or application render targets after the layer size changes. See
173    * {@link PibblThreeLayerDefinition}.
174    * @param resources - Resources returned by create.
175    * @param size - New logical and backing dimensions. See {@link PibblRenderLayerSize}.
176    * @param context - Adapter-owned renderer, surface, input bridge, and invalidation services. See
177    * {@link PibblThreeLayerContext} .
178    */
179   resize?(
180     resources: Resources,
181     size: PibblRenderLayerSize,
182     context: PibblThreeLayerContext,
183   ): void;
184   /**
185    * Overrides rendering for custom effects; omitted callbacks use ordinary scene/camera rendering.
186    * See {@link PibblThreeLayerDefinition}.
187    * @param resources - Resources returned by create.
188    * @param frame - Shared Pibbl frame timing and invalidation service. See
189    * {@link PibblRenderLayerFrame} .
190    * @param context - Adapter-owned renderer, surface, input bridge, and invalidation services. See
191    * {@link PibblThreeLayerContext} .
192    */
193   render?(
194     resources: Resources,
195     frame: PibblRenderLayerFrame,
196     context: PibblThreeLayerContext,
197   ): void;
198   /**
199    * Returns the Three objects exposed as Pibbl interaction and focus targets. See
200    * {@link PibblThreeTarget}.
201    * @param resources - Resources returned by create.
202    * @param props - Props used by this interaction generation.
203    * @returns Object targets and their Pibbl event/focus metadata. See {@link PibblThreeTarget}.
204    */
205   targets?(resources: Resources, props: Readonly<Props>): Iterable<PibblThreeTarget>;
206   /**
207    * Creates a custom picker for the settled generation; omission uses the adapter's raycasting.
208    * See {@link PibblThreePicker}.
209    * @param resources - Resources returned by create.
210    * @param context - Adapter-owned renderer, surface, input bridge, and invalidation services. See
211    * {@link PibblThreeLayerContext} .
212    * @returns A picker for the current scene resources. See {@link PibblThreePicker}.
213    */
214   pick?(resources: Resources, context: PibblThreeLayerContext): PibblThreePicker;
215   /**
216    * Disposes application-created Three resources; the adapter disposes its own renderer. See
217    * {@link PibblThreeLayerDefinition}.
218    * @param resources - Application-owned resources returned by create; release geometries,
219    * materials, and other owned resources here.
220    * @param context - Adapter context; the adapter releases its renderer and bridge after this
221    * callback. See {@link PibblThreeLayerContext} .
222    */
223   dispose?(resources: Resources, context: PibblThreeLayerContext): void;
224 }
225
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.