export type HandleGizmoTheme = { /** * - The color where the shapes are visible. */ base: Color; /** * - The color where the scene hides the shapes. */ occluded: Color; /** * - The color of filled volumes. An alpha of 0 skips the volumes. */ fill: Color; /** * - The color of a hovered or dragged radius, range, width or far clip * handle, and of its guide and readout label. */ primary: Color; /** * - The color of a hovered or dragged height, near clip or inner cone * angle handle, and of its guide and readout label. */ secondary: Color; /** * - The color of a hovered or dragged depth, field of view or outer cone * angle handle, and of its guide and readout label. */ tertiary: Color; /** * - The color of a hovered or dragged box corner handle. */ corner: Color; /** * - The color of the disc behind each icon, which is clicked to select it. */ backdrop: Color; }; /** * A handle placed this frame, or the one being dragged. */ export type GizmoHandle = { /** * - The handle shape. */ shape: Shape | null; /** * - The node the handle edits, or null for a shape gizmo. */ node: GraphNode | null; /** * - The value the handle edits. */ name: string; /** * - The index of the handle among those editing the value. */ index: number; /** * - The point the edit is measured from. */ origin: Vec3; /** * - The unit direction of the line, or the normal of the plane. */ dir: Vec3; /** * - Whether the handle moves in a plane rather than along a line. */ plane: boolean; }; /** * The handles of a box and how they resize it. */ export type BoxHandleOptions = { /** * - Whether to show handles at the center of each face. */ faceHandles: boolean; /** * - Whether to show handles at the corners. */ cornerHandles: boolean; /** * - Whether a resize keeps the center in place. */ centered: boolean; /** * - Whether a corner handle scales the box evenly. */ uniform: boolean; }; /** * The base class of gizmos that draw world-sized overlay shapes, such as a camera frustum or a * light shape, with handles that drag to edit them once large enough on screen. * * Use a layer that keeps the scene depth, so occluded parts use the `occluded` color, and sorts * transparent mesh instances manually, as {@link Gizmo.createLayer} makes with `depth` set. * * ```javascript * const layer = Gizmo.createLayer(app, 'Overlays', undefined, true); * ``` * * @category Gizmo */ export class HandleGizmo extends DragGizmo { /** * Fired when a handle starts being dragged. * * @event * @example * const gizmo = new pc.LightGizmo(camera, layer); * gizmo.on('handle:start', (node, name) => { * console.log(`Started editing ${name} of ${node.name}`); * }); */ static EVENT_HANDLESTART: string; /** * Fired when a dragged handle edits its value. * * @event * @example * const gizmo = new pc.LightGizmo(camera, layer); * gizmo.on('handle:move', (node, name) => { * console.log(`Edited ${name} of ${node.name}`); * }); */ static EVENT_HANDLEMOVE: string; /** * Fired when a handle stops being dragged. * * @event * @example * const gizmo = new pc.LightGizmo(camera, layer); * gizmo.on('handle:end', (node, name) => { * console.log(`Finished editing ${name} of ${node.name}`); * }); */ static EVENT_HANDLEEND: string; /** * Fired when the icon of a node is clicked. * * @event * @example * const gizmo = new pc.LightGizmo(camera, layer); * gizmo.on('icon:select', (node) => { * console.log(`Clicked the icon of ${node.name}`); * }); */ static EVENT_ICONSELECT: string; /** * Internal theme. * * @type {HandleGizmoTheme} * @protected */ protected _theme: HandleGizmoTheme; /** * The theme colors of the box faces along each axis, updated with the theme. * * @type {Color[]} * @private */ private _faceColors; /** * Whether to show handles that edit the shapes. Defaults to true. * * @type {boolean} */ handles: boolean; /** * Whether to show the value of a hovered or dragged handle. Defaults to true. * * @type {boolean} */ readout: boolean; /** * Whether to show an icon at each node. Defaults to true. * * @type {boolean} */ icon: boolean; /** * The overlay renderer. * * @type {OverlayRenderer} * @protected */ protected _renderer: OverlayRenderer; /** * The handles placed this frame. * * @type {Pool} * @private */ private _placed; /** * The hovered handle, matched by what it edits. * * @type {GizmoHandle} * @private */ private _hovered; /** * The dragged handle, as it was at the start of the drag. * * @type {GizmoHandle} * @protected */ protected _drag: GizmoHandle; /** * Whether a handle is being dragged. * * @protected */ protected _dragging: boolean; /** * The fade of the handles, set by {@link HandleGizmo#_detailed}. * * @private */ private _detailFade; /** * The offset from the pointer to the dragged handle, so it does not jump. * * @private */ private _dragOffset; /** * Sets the line thickness in CSS pixels; dashed lines space their dashes to match. Defaults * to 2. * * @type {number} */ set lineThickness(value: number); /** * Gets the line thickness in CSS pixels. * * @type {number} */ get lineThickness(): number; /** * Sets the handle size in CSS pixels. Defaults to 7. * * @type {number} */ set handleSize(value: number); /** * Gets the handle size in CSS pixels. * * @type {number} */ get handleSize(): number; /** * Sets the icon size in CSS pixels. Defaults to 24. * * @type {number} */ set iconSize(value: number); /** * Gets the icon size in CSS pixels. * * @type {number} */ get iconSize(): number; /** * Gets the current theme for the gizmo. * * @type {HandleGizmoTheme} */ get theme(): HandleGizmoTheme; /** * Sets the theme or partial theme for the gizmo. * * @param {Partial} partial - The partial theme to set. * @example * gizmo.setTheme({ occluded: new Color(1, 1, 1, 0.5) }); * @example * // accents told apart without red and green * gizmo.setTheme({ * primary: new Color(0.9, 0.6, 0), * secondary: new Color(0.35, 0.7, 0.9), * tertiary: new Color(0.8, 0.6, 0.7) * }); */ setTheme(partial: Partial): void; /** * @param {GizmoHandle} from - The handle to copy. * @param {GizmoHandle} to - The handle to copy into. * @private */ private _copy; /** * @param {GizmoHandle} a - A handle. * @param {GraphNode} node - The node the other handle edits. * @param {string} name - The value the other handle edits. * @param {number} index - The index of the other handle. * @returns {boolean} Whether the handles edit the same value. * @private */ private _matches; /** * @param {MeshInstance} [meshInstance] - The picked mesh instance. * @returns {GizmoHandle|null} The handle placed this frame that was picked. * @private */ private _find; /** * Gets the point of the dragged handle's line or plane under the pointer. * * @param {number} x - The canvas x coordinate. * @param {number} y - The canvas y coordinate. * @returns {Vec3|null} The point, or null when the line points at the camera. * @private */ private _pointerPoint; /** * @private */ private _endDrag; /** * Gets whether a shape is large enough on screen to show its handles. * * @param {Vec3} center - The center of the shape. * @param {number} radius - The radius of the shape. * @returns {boolean} Whether to show the details. * @protected */ protected _detailed(center: Vec3, radius: number): boolean; /** * Places a handle that drags along a line or in a plane, with a dashed guide from the origin * while hovered or dragged. * * @param {Vec3} position - The world position. * @param {Color} color - The color of the handle when hovered or dragged, and of its guide. * @param {GraphNode|null} node - The node the handle edits, or null for a shape gizmo. * @param {string} name - The value the handle edits. * @param {number} index - The index of the handle among those editing the value. * @param {Vec3} origin - A point the edit is measured from, on the line or plane. * @param {Vec3} dir - The unit direction of the line, or the normal of the plane. * @param {boolean} [inPlane] - Whether the handle moves in a plane. * @param {boolean} [guide] - Whether to show the dashed line. Defaults to true for a line. * @returns {boolean} Whether the handle is hovered or dragged. * @protected */ protected _handle(position: Vec3, color: Color, node: GraphNode | null, name: string, index: number, origin: Vec3, dir: Vec3, inPlane?: boolean, guide?: boolean): boolean; /** * Shows the value of a hovered or dragged handle below it. * * @param {Vec3} position - The handle position. * @param {string} label - The value label. * @param {Color} color - The label color. * @param {number} value - The value. * @param {string} [unit] - The unit after the value. * @protected */ protected _readoutAt(position: Vec3, label: string, color: Color, value: number, unit?: string): void; /** * Shows readout markup below a hovered or dragged handle. * * @param {Vec3} position - The handle position. * @param {string} html - The markup, as {@link HandleGizmo#_readoutValue} formats it. * @protected */ protected _readoutHtmlAt(position: Vec3, html: string): void; /** * Gets whether the handle editing a value is hovered or dragged. * * @param {GraphNode|null} node - The node the handle edits, or null for a shape gizmo. * @param {string} name - The value the handle edits. * @param {number} index - The index of the handle among those editing the value. * @returns {boolean} Whether the handle is active. * @protected */ protected _active(node: GraphNode | null, name: string, index: number): boolean; /** * Places three great circles of a sphere. * * @param {Vec3} center - The center of the sphere. * @param {Quat} rotation - The rotation of the sphere. * @param {number} radius - The radius of the sphere. * @param {number} [weight] - The thickness as a factor of the line thickness. * @param {number} [alpha] - The alpha factor. * @protected */ protected _sphereRings(center: Vec3, rotation: Quat, radius: number, weight?: number, alpha?: number): void; /** * Places the outline of a sphere, over faint great circles once large enough on screen, or * solid rings when the camera is inside it. * * @param {Vec3} center - The center of the sphere. * @param {Quat} rotation - The rotation of the great circles. * @param {number} radius - The radius of the sphere. * @protected */ protected _sphereOutline(center: Vec3, rotation: Quat, radius: number): void; /** * Gets the outline of a sphere as the camera sees it. * * @param {Vec3} center - The center of the sphere. * @param {number} radius - The radius of the sphere. * @param {Vec3} out - Receives the center of the outline. * @returns {number} The radius of the outline. * @protected */ protected _sphereSilhouette(center: Vec3, radius: number, out: Vec3): number; /** * Places handles at the ends of a sphere's axes, which drag its radius. * * @param {Vec3} center - The center of the sphere. * @param {Quat} rotation - The rotation of the axes. * @param {number} radius - The radius of the sphere. * @param {GraphNode|null} node - The node the handles edit, or null for a shape gizmo. * @param {string} name - The value the handles edit. * @protected */ protected _sphereHandles(center: Vec3, rotation: Quat, radius: number, node: GraphNode | null, name: string): void; /** * Gets the corners of a box, indexed by their x, y and z bits. * * @param {Vec3} center - The center of the box. * @param {Quat} rotation - The rotation of the box. * @param {Vec3} halfExtents - The half extents along the axes of the rotation. * @returns {Vec3[]} The world corners, valid until the next call. * @protected */ protected _boxCorners(center: Vec3, rotation: Quat, halfExtents: Vec3): Vec3[]; /** * Places the face and corner handles of the box last passed to * {@link HandleGizmo#_boxCorners}, once large enough on screen. * * @param {Vec3} center - The center of the box. * @param {Vec3} halfExtents - The half extents. * @param {BoxHandleOptions} options - The handles to show. * @param {number} [pad] - The padding on each side, left out of the readout extents. * @protected */ protected _boxHandles(center: Vec3, halfExtents: Vec3, options: BoxHandleOptions, pad?: number): void; /** * Resizes one axis of a box to a dragged face or corner. * * @param {number} axis - The axis index. * @param {number} sign - The side of the dragged face or corner, -1 or 1. * @param {Vec3} local - The dragged point relative to the start position, along the box axes. * @param {Vec3} start - The half extents at the start of the resize. * @param {boolean} centered - Whether the resize keeps the center in place. * @param {number} pad - The padding on each side, left out of the snapped extent. * @param {Vec3} half - The half extents to set. * @param {Vec3} mid - The offset of the center to set, along the box axes. * @private */ private _resizeBoxAxis; /** * Snaps a half extent so the extent without padding is a multiple of * {@link DragGizmo#snapIncrement}. * * @param {number} half - The half extent, padding included. * @param {number} pad - The padding on each side. * @returns {number} The half extent. * @private */ private _snapBoxHalf; /** * Resizes a box to a dragged {@link HandleGizmo#_boxHandles} handle, keeping the opposite face * or corner in place, or the center for a centered box. * * @param {GizmoHandle} handle - The dragged handle. * @param {Vec3} point - Where the handle is dragged to. * @param {Quat} rotation - The rotation of the box. * @param {Vec3} startPosition - The center at the start of the resize. * @param {Vec3} startHalfExtents - The half extents at the start of the resize. * @param {BoxHandleOptions} options - How the handles resize the box. * @param {number} pad - The padding on each side, left out of the snapped extents. * @param {Vec3} position - Receives the center. * @param {Vec3} halfExtents - Receives the half extents. * @protected */ protected _resizeBox(handle: GizmoHandle, point: Vec3, rotation: Quat, startPosition: Vec3, startHalfExtents: Vec3, options: BoxHandleOptions, pad: number, position: Vec3, halfExtents: Vec3): void; /** * Places the icon of a node, which fires {@link HandleGizmo.EVENT_ICONSELECT} when clicked. * * @param {OverlayIcon} kind - The icon. * @param {Vec3} position - The world position. * @param {GraphNode} node - The node the icon marks. * @protected */ protected _icon(kind: OverlayIcon, position: Vec3, node: GraphNode): void; /** * Formats a value with two decimals after a colored label. * * @param {string} label - The label. * @param {Color} color - The label color. * @param {number} value - The value. * @param {string} [unit] - The unit after the value. * @returns {string} The markup. * @protected */ protected _readoutValue(label: string, color: Color, value: number, unit?: string): string; /** * Places the shapes of the attached nodes. Implemented by the subclass. * * @protected */ protected _drawShapes(): void; /** * Stores the values a handle edits at the start of a drag. Implemented by the subclass. * * @param {GizmoHandle} handle - The dragged handle. * @protected */ protected _startHandle(handle: GizmoHandle): void; /** * Edits the value of the dragged handle. Implemented by the subclass. * * @param {GizmoHandle} handle - The dragged handle. * @param {Vec3} point - Where the handle is dragged to, on its line. * @protected */ protected _moveHandle(handle: GizmoHandle, point: Vec3): void; } import { Color } from '../../../core/math/color.js'; import type { Shape } from '../shape/shape.js'; import type { GraphNode } from '../../../scene/graph-node.js'; import { Vec3 } from '../../../core/math/vec3.js'; import { DragGizmo } from '../drag-gizmo.js'; import { OverlayRenderer } from '../overlay/overlay-renderer.js'; import { Quat } from '../../../core/math/quat.js'; import type { OverlayIcon } from '../overlay/icon-glyphs.js';