@ue-too/board 0.5.2 → 0.7.0

package/src/camera/camera-rig/pan-handler.ts

@@ -1,192 +0,0 @@
-import { Point, PointCal } from "@ue-too/math";
-import { BoardCamera } from "../interface";
-import { createHandlerChain } from "../../utils/handler-pipeline";
-import { clampPoint, clampPointEntireViewPort } from "../utils/position";
-
-/**
- * @description Configuration for the pan handler functions.
- * 
- * @category Camera
- */
-export type PanHandlerConfig = PanHandlerRestrictionConfig & PanHandlerClampConfig;
-
-export type PanHandlerClampConfig = {
-    /**
-     * @description Whether to limit the pan to the entire view port.
-     */
-    limitEntireViewPort: boolean;
-    /**
-     * @description Whether to clamp the translation.
-     */
-    clampTranslation: boolean;
-};
-
-export type PanHandlerRestrictionConfig = {
-    /**
-     * @description Whether to restrict the x translation.
-     */
-    restrictXTranslation: boolean;
-    /**
-     * @description Whether to restrict the y translation.
-     */
-    restrictYTranslation: boolean;
-    /**
-     * @description Whether to restrict the relative x translation. (because the camera can be rotated, the relative x translation is the horizontal direction of what the user sees on the screen)
-     */
-    restrictRelativeXTranslation: boolean;
-    /**
-     * @description Whether to restrict the relative y translation. (because the camera can be rotated, the relative y translation is the vertical direction of what the user sees on the screen)
-     */
-    restrictRelativeYTranslation: boolean;
-};
-
-/**
- * @description Function Type that is used to define the "pan to" handler.
- * The destination is in "stage/context/world" space.
- * This is structured as a handler pipeline. 
- * @see {@link createHandlerChain}
- * @category Camera
- */
-export type PanToHandlerFunction = (destination: Point, camera: BoardCamera, config: PanHandlerConfig) => Point;
-/**
- * @description Function Type that is used to define the "pan by" handler.
- * The delta is in "stage/context/world" space.
- * This is structured as a handler pipeline. 
- * @see {@link createHandlerChain}
- * @category Camera
- */
-export type PanByHandlerFunction = (delta: Point, camera: BoardCamera, config: PanHandlerConfig) => Point;
-
-/**
- * @description Helper function that creates a default "pan to" handler.
- * The default pan to handler will first restrict the pan to the view port, then clamp the pan to the boundaries, and then pan to the destination.
- * 
- * @see {@link createHandlerChain} to create your own custom pan handler pipeline. (you can also use this function as a part of your own custom pan handler pipeline)
- * @category Camera
- */
-export function createDefaultPanToHandler(): PanToHandlerFunction {
-    return createHandlerChain<Point, [BoardCamera, PanHandlerConfig]>(
-        restrictPanToHandler,
-        clampToHandler,
-    );
-}
-
-/**
- * @description Helper function that creates a default "pan by" handler.
- * The resulting pan by handler takes in a delta that is in "stage/context/world" space.
- * The default pan by handler will first restrict the pan by the view port, then clamp the pan by the boundaries, and then pan by the delta.
- * 
- * @see {@link createHandlerChain} to create your own custom pan handler pipeline. (you can also use this function as a part of your own custom pan handler pipeline)
- * @category Camera
- */
-export function createDefaultPanByHandler(): PanByHandlerFunction {
-    return createHandlerChain<Point, [BoardCamera, PanHandlerConfig]>(
-        restrictPanByHandler,
-        clampByHandler,
-    );
-}
-
-/**
- * @description Function that is part of the "pan to" handler pipeline. It restricts the "pan to" destination to within a single axis based on the config. (relative to the current camera position)
- * You can use this function standalone to restrict the "pan to" destination to within a single axis based on the config. 
- * But it is recommended to use this kind of function as part of the pan handler pipeline. (to include this function in your own custom pan handler pipeline)
- * 
- * @category Camera
- */
-export function restrictPanToHandler(destination: Point, camera: BoardCamera, config: PanHandlerRestrictionConfig): Point {
-    let delta = PointCal.subVector(destination, camera.position);
-    delta = convertDeltaToComplyWithRestriction(delta, camera, config);
-    if (delta.x === 0 && delta.y === 0) {
-        return destination;
-    }
-    const dest = PointCal.addVector(camera.position, delta);
-    return dest;
-}
-
-/**
- * @description Function that is part of the "pan by" handler pipeline. It restricts the pan delta to within a single axis based on the config. (relative to the current camera position)
- * You can use this function standalone to restrict the pan delta to within a single axis based on the config. 
- * But it is recommended to use this kind of function as part of the pan handler pipeline. (to include this function in your own custom pan handler pipeline)
- * 
- * @category Camera
- */
-export function restrictPanByHandler(delta: Point, camera: BoardCamera, config: PanHandlerRestrictionConfig): Point {
-    delta = convertDeltaToComplyWithRestriction(delta, camera, config);
-    return delta;
-}
-
-/**
- * @description Function that is part of the "pan to" handler pipeline. It clamps the pan destination within the boundaries of the view port.
- * You can use this function standalone to clamp the pan destination within the boundaries of the view port. 
- * But it is recommended to use this kind of function as part of the pan handler pipeline. (to include this function in your own custom pan handler pipeline)
- * 
- * @category Camera
- */
-export function clampToHandler(destination: Point, camera: BoardCamera, config: PanHandlerClampConfig): Point {
-    if(!config.clampTranslation){
-        return destination;
-    }
-    let actualDest = clampPoint(destination, camera.boundaries);
-    if(config.limitEntireViewPort){
-        actualDest = clampPointEntireViewPort(destination, camera.viewPortWidth, camera.viewPortHeight, camera.boundaries, camera.zoomLevel, camera.rotation);
-    }
-    return actualDest;
-}
-
-/**
- * @description Function that is part of the "pan by" handler pipeline. It clamps the pan delta within the boundaries of the view port.
- * You can use this function standalone to clamp the pan delta within the boundaries of the view port. 
- * But it is recommended to use this kind of function as part of the pan handler pipeline. (to include this function in your own custom pan handler pipeline)
- * 
- * @category Camera
- */
-export function clampByHandler(delta: Point, camera: BoardCamera, config: PanHandlerClampConfig): Point {
-    if(!config.clampTranslation){
-        return delta;
-    }
-    let actualDelta = PointCal.subVector(clampPoint(PointCal.addVector(camera.position, delta), camera.boundaries), camera.position);
-    if(config.limitEntireViewPort){
-        actualDelta = PointCal.subVector(clampPointEntireViewPort(PointCal.addVector(camera.position, delta), camera.viewPortWidth, camera.viewPortHeight, camera.boundaries, camera.zoomLevel, camera.rotation), camera.position);
-    }
-    return actualDelta;
-}
-
-/**
- * @description Helper function that converts the delta to comply with the restrictions of the config.
- * 
- * @category Camera
- */
-export function convertDeltaToComplyWithRestriction(delta: Point, camera: BoardCamera, config: PanHandlerRestrictionConfig): Point {
-    if(config.restrictXTranslation && config.restrictYTranslation){
-        return {x: 0, y: 0};
-    }
-    if(config.restrictRelativeXTranslation && config.restrictRelativeYTranslation){
-        return {x: 0, y: 0};
-    }
-    if(config.restrictXTranslation){
-        delta.x = 0;
-    }
-    if(config.restrictYTranslation){
-        delta.y = 0;
-    }
-    if(config.restrictRelativeXTranslation){
-        const upDirection =  PointCal.rotatePoint({x: 0, y: 1}, camera.rotation);
-        const value = PointCal.dotProduct(upDirection, delta);
-        delta = PointCal.multiplyVectorByScalar(upDirection, value);
-    }
-    if(config.restrictRelativeYTranslation){
-        const rightDirection =  PointCal.rotatePoint({x: 1, y: 0}, camera.rotation);
-        const value = PointCal.dotProduct(rightDirection, delta);
-        delta = PointCal.multiplyVectorByScalar(rightDirection, value);
-    }
-    return delta;
-}
-
-/**
- * @description Helper function that converts the user input delta to the camera delta.
- * 
- * @category Camera
- */
-export function convertUserInputDeltaToCameraDelta(delta: Point, camera: BoardCamera): Point {
-    return PointCal.multiplyVectorByScalar(PointCal.rotatePoint(delta, camera.rotation), 1 / camera.zoomLevel);
-}

package/src/camera/camera-rig/rotation-handler.ts

@@ -1,124 +0,0 @@
-import { BoardCamera } from "../interface";
-import { createHandlerChain } from "../../utils/handler-pipeline";
-import { normalizeAngleZero2TwoPI, angleSpan, clampRotation } from "../utils/rotation";
-
-/**
- * @description This is the configuration for the rotation handler functions.
- * This is the configuration object that is passed to the rotation handler functions.
- * 
- * @category Camera
- */
-export type RotationHandlerConfig = RotationHandlerRestrictConfig & RotationHandlerClampConfig;
-
-export type RotationHandlerRestrictConfig = {
-    /**
-     * @description Whether to restrict the rotation. (if true, rotation input will be ignored)
-     */
-    restrictRotation: boolean;
-}
-
-export type RotationHandlerClampConfig = {
-    /**
-     * @description Whether to clamp the rotation if the rotation is out of the rotation boundaries.
-     */
-    clampRotation: boolean;
-}
-
-/**
- * @description The function that is used to rotate the camera by a specific delta. 
- * The delta is in radians.
- * This is structured as a handler pipeline. 
- * 
- * @see {@link createHandlerChain}
- * @category Camera
- */
-export type RotateByHandlerFunction = (delta: number, camera: BoardCamera, config: RotationHandlerConfig) => number;
-/**
- * @description The function that is used to rotate the camera to a specific target rotation.
- * The target rotation is in radians.
- * This is structured as a handler pipeline. 
- * 
- * @see {@link createHandlerChain}
- * @category Camera
- */
-export type RotateToHandlerFunction = (targetRotation: number, camera: BoardCamera, config: RotationHandlerConfig) => number;
-
-/**
- * @description This is the clamp handler for the "rotate by" handler pipeline.
- * It clamps the delta to the range of the camera's rotation boundaries.
- * 
- * @category Camera
- */
-export function clampRotateByHandler(delta: number, camera: BoardCamera, config: RotationHandlerClampConfig): number {
-    if(!config.clampRotation){
-        return delta;
-    }
-    const targetRotation = normalizeAngleZero2TwoPI(camera.rotation + delta);
-    const clampedRotation = clampRotation(targetRotation, camera.rotationBoundaries);
-    const diff = angleSpan(camera.rotation, clampedRotation);
-    return diff;
-}
-
-/**
- * @description This is the restrict handler for the "rotate by" handler pipeline.
- * It restricts the delta to the range of the camera's rotation boundaries.
- * 
- * @category Camera
- */
-export function restrictRotateByHandler(delta: number, camera: BoardCamera, config: RotationHandlerRestrictConfig): number {
-    if(config.restrictRotation){
-        return 0;
-    }
-    return delta;
-}
-
-/**
- * @description This is the clamp handler for the "rotate to" handler pipeline.
- * It clamps the target rotation to the range of the camera's rotation boundaries.
- * 
- * @category Camera
- */
-export function clampRotateToHandler(targetRotation: number, camera: BoardCamera, config: RotationHandlerClampConfig): number {
-    if(!config.clampRotation){
-        return targetRotation;
-    }
-    const clampedRotation = clampRotation(targetRotation, camera.rotationBoundaries);
-    return clampedRotation;
-}
-
-/**
- * @description This is the restrict handler for the "rotate to" handler pipeline.
- * It restricts the target rotation to the range of the camera's rotation boundaries.
- * 
- * @category Camera
- */
-export function restrictRotateToHandler(targetRotation: number, camera: BoardCamera, config: RotationHandlerRestrictConfig): number {
-    if(config.restrictRotation){
-        return camera.rotation;
-    }
-    return targetRotation;
-}
-
-/**
- * @description This is the create default handler chain function for the "rotate by" handler pipeline.
- * 
- * @category Camera
- */
-export function createDefaultRotateByHandler(): RotateByHandlerFunction {
-    return createHandlerChain<number, [BoardCamera, RotationHandlerConfig]>(
-        restrictRotateByHandler,
-        clampRotateByHandler,
-    );
-}
-
-/**
- * @description This is the create default handler chain function for the "rotate to" handler pipeline.
- * 
- * @category Camera
- */
-export function createDefaultRotateToHandler(): RotateToHandlerFunction {
-    return createHandlerChain<number, [BoardCamera, RotationHandlerConfig]>(
-        restrictRotateToHandler,
-        clampRotateToHandler,
-    );
-}

package/src/camera/camera-rig/update-batcher/index.ts

@@ -1,3 +0,0 @@
-export * from "./position-update-batcher";
-export * from "./rotation-update-batcher";
-export * from "./zoom-udpate-batcher";

package/src/camera/camera-rig/update-batcher/position-update-batcher.ts

@@ -1,133 +0,0 @@
-import { Observable, Observer, SubscriptionOptions } from "../../../utils/observable";
-
-export type Position = {
-    x: number;
-    y: number;
-};
-
-export type Velocity = {
-    vx: number;
-    vy: number;
-};
-
-export type DestinationUpdate = Position & {
-    type: 'destination';
-};
-
-export type DeltaUpdate = Position & {
-    type: 'delta';
-};
-
-export type PositionUpdate = DestinationUpdate | DeltaUpdate;
-
-export class CameraPositionUpdateBatcher {
-    private nextPosition: Position | null = null;
-    private delta: Position = { x: 0, y: 0 };
-    private observable: Observable<[PositionUpdate]>;
-    // Debug counters
-    private queuePositionUpdateCount: number = 0;
-    private queuePositionUpdateToCount: number = 0;
-    private queuePositionUpdateByCount: number = 0;
-    private lastUpdateCount: number = 0;
-    
-    constructor() {
-        this.observable = new Observable<[PositionUpdate]>();
-    }
-
-    /**
-     * Queue an absolute position update to be processed in the next animation frame
-     */
-    public queuePositionUpdate(x: number, y: number): void {
-        this.queuePositionUpdateCount++;
-        this.queuePositionUpdateTo({ x, y });
-    }
-
-    /**
-     * Queue a position update to a specific destination to be processed in the next animation frame
-     * This will override any pending delta updates
-     */
-    public queuePositionUpdateTo(destination: Position): void {
-        this.queuePositionUpdateToCount++;
-        this.nextPosition = { ...destination };
-        this.delta = { x: 0, y: 0 }; // Reset any pending deltas
-    }
-
-    /**
-     * Queue a position update by delta to be processed in the next animation frame
-     * This will be ignored if there's a pending destination update
-     */
-    public queuePositionUpdateBy(delta: Position): void {
-        this.queuePositionUpdateByCount++;
-        
-        // If we have a pending destination update, add the delta to it
-        if (this.nextPosition !== null) {
-            this.nextPosition = {
-                x: this.nextPosition.x + delta.x,
-                y: this.nextPosition.y + delta.y
-            };
-            return;
-        }
-        
-        this.delta = {
-            x: this.delta.x + delta.x,
-            y: this.delta.y + delta.y
-        };
-    }
-
-    /**
-     * Process and clear all queued position updates
-     * @returns the update to apply to the position, with type information
-     */
-    public processQueuedUpdates(): PositionUpdate | null {
-        this.lastUpdateCount = this.queuePositionUpdateCount + this.queuePositionUpdateToCount + this.queuePositionUpdateByCount;
-        // Reset counters after update
-        this.queuePositionUpdateCount = 0;
-        this.queuePositionUpdateToCount = 0;
-        this.queuePositionUpdateByCount = 0;
-        
-        if (this.nextPosition !== null) {
-            const update: DestinationUpdate = {
-                ...this.nextPosition,
-                type: 'destination'
-            };
-            this.nextPosition = null;
-            this.delta = { x: 0, y: 0 };
-            this.observable.notify(update);
-            return update;
-        } else if (this.delta.x !== 0 || this.delta.y !== 0) {
-            const update: DeltaUpdate = {
-                ...this.delta,
-                type: 'delta'
-            };
-            this.delta = { x: 0, y: 0 };
-            this.observable.notify(update);
-            return update;
-        }
-        
-        return null;
-    }
-
-    /**
-     * Subscribe to position updates
-     */
-    public subscribe(observer: Observer<[PositionUpdate]>, options?: SubscriptionOptions): () => void {
-        return this.observable.subscribe(observer, options);
-    }
-
-    /**
-     * Get debug information about queue method calls since last update
-     */
-    public getDebugInfo(): {
-        lastUpdateTotalCalls: number;
-        queuePositionUpdateCalls: number;
-        queuePositionUpdateToCalls: number;
-        queuePositionUpdateByCalls: number;
-    } {
-        return {
-            lastUpdateTotalCalls: this.lastUpdateCount,
-            queuePositionUpdateCalls: this.queuePositionUpdateCount,
-            queuePositionUpdateToCalls: this.queuePositionUpdateToCount,
-            queuePositionUpdateByCalls: this.queuePositionUpdateByCount
-        };
-    }
-}

package/src/camera/camera-rig/update-batcher/rotation-update-batcher.ts

@@ -1,123 +0,0 @@
-import { Observable, Observer, SubscriptionOptions } from "../../../utils/observable";
-
-export type Rotation = number; // in radians
-
-export type RotationVelocity = number; // in radians per millisecond
-
-export type RotationDestinationUpdate = {
-    type: 'destination';
-    destination: Rotation;
-};
-
-export type RotationDeltaUpdate = {
-    type: 'delta';
-    delta: Rotation;
-};
-
-export type RotationUpdate = RotationDestinationUpdate | RotationDeltaUpdate;
-
-export class CameraRotationUpdateBatcher {
-    private nextRotation: Rotation | null = null;
-    private delta: Rotation = 0;
-    private observable: Observable<[RotationUpdate]>;
-    // Debug counters
-    private queueRotationUpdateCount: number = 0;
-    private queueRotationUpdateToCount: number = 0;
-    private queueRotationUpdateByCount: number = 0;
-    private lastUpdateCount: number = 0;
-    
-    constructor() {
-        this.observable = new Observable<[RotationUpdate]>();
-    }
-
-    /**
-     * Queue an absolute rotation update to be processed in the next animation frame
-     */
-    public queueRotationUpdate(rotation: Rotation): void {
-        this.queueRotationUpdateCount++;
-        this.queueRotationUpdateTo(rotation);
-    }
-
-    /**
-     * Queue a rotation update to a specific destination to be processed in the next animation frame
-     * This will override any pending delta updates
-     */
-    public queueRotationUpdateTo(destination: Rotation): void {
-        this.queueRotationUpdateToCount++;
-        this.nextRotation = destination;
-        this.delta = 0; // Reset any pending deltas
-    }
-
-    /**
-     * Queue a rotation update by delta to be processed in the next animation frame
-     * This will be ignored if there's a pending destination update
-     */
-    public queueRotationUpdateBy(delta: Rotation): void {
-        this.queueRotationUpdateByCount++;
-        
-        // If we have a pending destination update, add the delta to it
-        if (this.nextRotation !== null) {
-            this.nextRotation = this.nextRotation + delta;
-            return;
-        }
-        
-        this.delta = this.delta + delta;
-    }
-
-    /**
-     * Process and clear all queued rotation updates
-     * @returns the update to apply to the rotation, with type information
-     */
-    public processQueuedUpdates(): RotationUpdate | null {
-        this.lastUpdateCount = this.queueRotationUpdateCount + this.queueRotationUpdateToCount + this.queueRotationUpdateByCount;
-        // Reset counters after update
-        this.queueRotationUpdateCount = 0;
-        this.queueRotationUpdateToCount = 0;
-        this.queueRotationUpdateByCount = 0;
-        
-        if (this.nextRotation !== null) {
-            const update: RotationDestinationUpdate = {
-                destination: this.nextRotation,
-                type: 'destination'
-            };
-            this.nextRotation = null;
-            this.delta = 0;
-            this.observable.notify(update);
-            return update;
-        } else if (this.delta !== 0) {
-            const update: RotationDeltaUpdate = {
-                delta: this.delta,
-                type: 'delta'
-            };
-            this.delta = 0;
-            this.observable.notify(update);
-            return update;
-        }
-        
-        return null;
-    }
-
-    /**
-     * Subscribe to rotation updates
-     */
-    public subscribe(observer: Observer<[RotationUpdate]>, options?: SubscriptionOptions): () => void {
-        return this.observable.subscribe(observer, options);
-    }
-
-    /**
-     * Get debug information about queue method calls since last update
-     */
-    public getDebugInfo(): {
-        lastUpdateTotalCalls: number;
-        queueRotationUpdateCalls: number;
-        queueRotationUpdateToCalls: number;
-        queueRotationUpdateByCalls: number;
-    } {
-        return {
-            lastUpdateTotalCalls: this.lastUpdateCount,
-            queueRotationUpdateCalls: this.queueRotationUpdateCount,
-            queueRotationUpdateToCalls: this.queueRotationUpdateToCount,
-            queueRotationUpdateByCalls: this.queueRotationUpdateByCount
-        };
-    }
-}