From e2cea247a87c3d6ce49a4544b589dfd5243c30c1 Mon Sep 17 00:00:00 2001 From: Nathan Bierema Date: Sun, 25 Aug 2024 15:53:52 -0400 Subject: [PATCH] OrbitControls: Derive from Controls. (#1193) --- .../jsm/controls/ArcballControls.d.ts | 2 + .../examples/jsm/controls/OrbitControls.d.ts | 221 +++++++----------- 2 files changed, 86 insertions(+), 137 deletions(-) diff --git a/types/three/examples/jsm/controls/ArcballControls.d.ts b/types/three/examples/jsm/controls/ArcballControls.d.ts index e152be5a4..4da2164ea 100644 --- a/types/three/examples/jsm/controls/ArcballControls.d.ts +++ b/types/three/examples/jsm/controls/ArcballControls.d.ts @@ -196,6 +196,8 @@ declare class ArcballControls extends Controls { * {@link Raycaster} with a matching value, or else the {@link ArcballControls} won't work as expected. */ getRaycaster(): Raycaster; + + update(): void; } export { ArcballControls }; diff --git a/types/three/examples/jsm/controls/OrbitControls.d.ts b/types/three/examples/jsm/controls/OrbitControls.d.ts index 2de07d615..0348f0c26 100644 --- a/types/three/examples/jsm/controls/OrbitControls.d.ts +++ b/types/three/examples/jsm/controls/OrbitControls.d.ts @@ -1,49 +1,32 @@ -import { Camera, EventDispatcher, MOUSE, TOUCH, Vector3 } from "three"; +import { Camera, Controls, MOUSE, TOUCH, Vector3 } from "three"; export interface OrbitControlsEventMap { - change: {}; - start: {}; - end: {}; -} - -/** - * Orbit controls allow the camera to orbit around a target. - * @param object - The camera to be controlled. The camera must not - * be a child of another object, unless that object is the scene itself. - * @param domElement - The HTML element used for - * event listeners. - */ -export class OrbitControls extends EventDispatcher { - constructor(object: Camera, domElement: HTMLElement); - /** - * The camera being controlled. + * Fires when the camera has been transformed by the controls. */ - object: Camera; + change: {}; /** - * The HTMLElement used to listen for mouse / touch events. - * This must be passed in the constructor; - * changing it here will not set up new event listeners. + * Fires when an interaction was initiated. */ - domElement: HTMLElement | Document; + start: {}; /** - * When set to `false`, the controls will not respond to user input. - * @default true + * Fires when an interaction has finished. */ - enabled: boolean; + end: {}; +} +/** + * Orbit controls allow the camera to orbit around a target. + */ +declare class OrbitControls extends Controls { /** - * The focus point of the controls, the .object orbits around this. - * It can be updated manually at any point to change the focus - * of the controls. + * The focus point of the controls, the {@link .object} orbits around this. It can be updated manually at any point + * to change the focus of the controls. */ target: Vector3; - /** @deprecated */ - center: Vector3; - /** * The focus point of the {@link .minTargetRadius} and {@link .maxTargetRadius} limits. It can be updated manually * at any point to change the center of interest for the {@link .target}. @@ -51,178 +34,141 @@ export class OrbitControls extends EventDispatcher { cursor: Vector3; /** - * How far you can dolly in ( PerspectiveCamera only ). - * @default 0 + * How far you can dolly in ( {@link PerspectiveCamera} only ). Default is 0. */ minDistance: number; /** - * How far you can dolly out ( PerspectiveCamera only ). - * @default Infinity + * How far you can dolly out ( {@link PerspectiveCamera} only ). Default is Infinity. */ maxDistance: number; /** - * How far you can zoom in ( OrthographicCamera only ). - * @default 0 + * How far you can zoom in ( {@link OrthographicCamera} only ). Default is 0. */ minZoom: number; /** - * How far you can zoom out ( OrthographicCamera only ). - * @default Infinity + * How far you can zoom out ( {@link OrthographicCamera} only ). Default is Infinity. */ maxZoom: number; /** - * How close you can get the target to the 3D {@link .cursor}. - * @default 0 + * How close you can get the target to the 3D {@link .cursor}. Default is 0. */ minTargetRadius: number; /** - * How far you can move the target from the 3D {@link .cursor}. - * @default Infinity + * How far you can move the target from the 3D {@link .cursor}. Default is Infinity. */ maxTargetRadius: number; /** - * How far you can orbit vertically, lower limit. - * Range is 0 to Math.PI radians. - * @default 0 + * How far you can orbit vertically, lower limit. Range is 0 to Math.PI radians, and default is 0. */ minPolarAngle: number; /** - * How far you can orbit vertically, upper limit. - * Range is 0 to Math.PI radians. - * @default Math.PI. + * How far you can orbit vertically, upper limit. Range is 0 to Math.PI radians, and default is Math.PI. */ maxPolarAngle: number; /** - * How far you can orbit horizontally, lower limit. - * If set, the interval [ min, max ] - * must be a sub-interval of [ - 2 PI, 2 PI ], - * with ( max - min < 2 PI ). - * @default Infinity + * How far you can orbit horizontally, lower limit. If set, the interval [ min, max ] must be a sub-interval of + * [ - 2 PI, 2 PI ], with ( max - min < 2 PI ). Default is Infinity. */ minAzimuthAngle: number; /** - * How far you can orbit horizontally, upper limit. - * If set, the interval [ min, max ] must be a sub-interval - * of [ - 2 PI, 2 PI ], with ( max - min < 2 PI ). - * @default Infinity + * How far you can orbit horizontally, upper limit. If set, the interval [ min, max ] must be a sub-interval of + * [ - 2 PI, 2 PI ], with ( max - min < 2 PI ). Default is Infinity. */ maxAzimuthAngle: number; /** - * Set to true to enable damping (inertia), which can - * be used to give a sense of weight to the controls. - * Note that if this is enabled, you must call - * .update () in your animation loop. - * @default false + * Set to true to enable damping (inertia), which can be used to give a sense of weight to the controls. Default is + * false. + * Note that if this is enabled, you must call {@link .update}() in your animation loop. */ enableDamping: boolean; /** - * The damping inertia used if .enableDamping is set to true. - * Note that for this to work, - * you must call .update () in your animation loop. - * @default 0.05 + * The damping inertia used if .enableDamping is set to true. Default is `0.05`. + * Note that for this to work, you must call {@link .update}() in your animation loop. */ dampingFactor: number; /** * Enable or disable zooming (dollying) of the camera. - * @default true */ enableZoom: boolean; /** - * Speed of zooming / dollying. - * @default 1 + * Speed of zooming / dollying. Default is 1. */ zoomSpeed: number; /** - * Setting this property to `true` allows to zoom to the cursor's position. - * @default false - */ - zoomToCursor: boolean; - - /** - * Enable or disable horizontal and - * vertical rotation of the camera. - * Note that it is possible to disable a single axis - * by setting the min and max of the polar angle or - * azimuth angle to the same value, which will cause - * the vertical or horizontal rotation to be fixed at that value. - * @default true + * Enable or disable horizontal and vertical rotation of the camera. Default is true. + * Note that it is possible to disable a single axis by setting the min and max of the + * [polar angle]{@link .minPolarAngle} or [azimuth angle]{@link .minAzimuthAngle} to the same value, which will + * cause the vertical or horizontal rotation to be fixed at that value. */ enableRotate: boolean; /** - * Speed of rotation. - * @default 1 + * Speed of rotation. Default is 1. */ rotateSpeed: number; /** - * Enable or disable camera panning. - * @default true + * Enable or disable camera panning. Default is true. */ enablePan: boolean; /** - * Speed of panning. - * @default 1 + * Speed of panning. Default is 1. */ panSpeed: number; /** - * Defines how the camera's position is translated when panning. - * If true, the camera pans in screen space. Otherwise, - * the camera pans in the plane orthogonal to the camera's - * up direction. Default is true for OrbitControls; false for MapControls. - * @default true + * Defines how the camera's position is translated when panning. If true, the camera pans in screen space. + * Otherwise, the camera pans in the plane orthogonal to the camera's up direction. Default is `true`. */ screenSpacePanning: boolean; /** - * How fast to pan the camera when the keyboard is used. - * Default is 7.0 pixels per keypress. - * @default 7 + * How fast to pan the camera when the keyboard is used. Default is 7.0 pixels per keypress. */ keyPanSpeed: number; + /** + * Setting this property to `true` allows to zoom to the cursor's position. Default is `false`. + */ + zoomToCursor: boolean; + /** * Set to true to automatically rotate around the target. - * Note that if this is enabled, you must call .update() in your animation loop. If you want the auto-rotate speed + * Note that if this is enabled, you must call {@link .update}() in your animation loop. If you want the auto-rotate speed * to be independent of the frame rate (the refresh rate of the display), you must pass the time `deltaTime`, in - * seconds, to .update(). + * seconds, to {@link .update}(). */ autoRotate: boolean; /** - * How fast to rotate around the target if .autoRotate is true. - * Default is 2.0, which equates to 30 seconds per orbit at 60fps. - * Note that if .autoRotate is enabled, you must call - * .update () in your animation loop. - * @default 2 + * How fast to rotate around the target if {@link .autoRotate} is true. Default is 2.0, which equates to 30 seconds + * per orbit at 60fps. + * Note that if {@link .autoRotate} is enabled, you must call {@link .update}() in your animation loop. */ autoRotateSpeed: number; /** - * This object contains references to the keycodes for controlling - * camera panning. Default is the 4 arrow keys. + * This object contains references to the keycodes for controlling camera panning. Default is the 4 arrow keys. */ keys: { LEFT: string; UP: string; RIGHT: string; BOTTOM: string }; /** - * This object contains references to the mouse actions used - * by the controls. + * This object contains references to the mouse actions used by the controls. */ mouseButtons: { LEFT?: MOUSE | null | undefined; @@ -231,74 +177,75 @@ export class OrbitControls extends EventDispatcher { }; /** - * This object contains references to the touch actions used by - * the controls. + * This object contains references to the touch actions used by the controls. */ touches: { ONE?: TOUCH | null | undefined; TWO?: TOUCH | null | undefined }; /** - * Used internally by the .saveState and .reset methods. + * Used internally by the {@link .saveState} and {@link .reset} methods. */ target0: Vector3; /** - * Used internally by the .saveState and .reset methods. + * Used internally by the {@link .saveState} and {@link .reset} methods. */ position0: Vector3; /** - * Used internally by the .saveState and .reset methods. + * Used internally by the {@link .saveState} and {@link .reset} methods. */ zoom0: number; /** - * Update the controls. Must be called after any manual changes to the camera's transform, or in the update loop if - * .autoRotate or .enableDamping are set. `deltaTime`, in seconds, is optional, and is only required if you want the - * auto-rotate speed to be independent of the frame rate (the refresh rate of the display). + * @param object The camera to be controlled. The camera must not be a child of another object, unless that object + * is the scene itself. + * @param domElement The HTML element used for event listeners. (optional) */ - update(deltaTime?: number): boolean; + constructor(object: Camera, domElement?: HTMLElement | null); /** - * Adds key event listeners to the given DOM element. `window` - * is a recommended argument for using this method. - * @param domElement + * Get the current vertical rotation, in radians. */ - listenToKeyEvents(domElement: HTMLElement | Window): void; + getPolarAngle(): number; /** - * Removes the key event listener previously defined with {@link listenToKeyEvents}. + * Get the current horizontal rotation, in radians. */ - stopListenToKeyEvents(): void; + getAzimuthalAngle(): number; /** - * Save the current state of the controls. This can later be - * recovered with .reset. + * Returns the distance from the camera to the target. */ - saveState(): void; + getDistance(): number; /** - * Reset the controls to their state from either the last time - * the .saveState was called, or the initial state. + * Adds key event listeners to the given DOM element. `window` is a recommended argument for using this method. + * @param domElement */ - reset(): void; + listenToKeyEvents(domElement: HTMLElement | Window): void; /** - * Remove all the event listeners. + * Removes the key event listener previously defined with {@link .listenToKeyEvents}(). */ - dispose(): void; + stopListenToKeyEvents(): void; /** - * Get the current vertical rotation, in radians. + * Save the current state of the controls. This can later be recovered with {@link .reset}. */ - getPolarAngle(): number; + saveState(): void; /** - * Get the current horizontal rotation, in radians. + * Reset the controls to their state from either the last time the {@link .saveState} was called, or the initial + * state. */ - getAzimuthalAngle(): number; + reset(): void; /** - * Returns the distance from the camera to the target. + * Update the controls. Must be called after any manual changes to the camera's transform, or in the update loop if + * {@link .autoRotate} or {@link .enableDamping} are set. `deltaTime`, in seconds, is optional, and is only required + * if you want the auto-rotate speed to be independent of the frame rate (the refresh rate of the display). */ - getDistance(): number; + update(deltaTime?: number | null): boolean; } + +export { OrbitControls };