packages/three/src/lib/types.ts
This is the source snapshot used to build these API details. View this revision on GitHub.
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
Section titled “Documentation version”Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.