bplinejs 0.0.101-beta.10 → 0.0.102

package/lib/Camera/index.d.ts

@@ -1,7 +1,8 @@
 import ObjectNode from "../Object";
 import type { ObjectNodeLike } from "../Object";
 import { Mat3 } from "bpmatrixjs/Math/Mat3";
-import type { VersionedMath } from "bpmatrixjs/Math";
+import { Vec2, type VersionedMath } from "bpmatrixjs/Math";
+import type { RenderLike } from "../Render";
 interface CameraBuffersLike {
     uniform?: number;
 }
@@ -16,11 +17,113 @@ interface CameraLike extends ObjectNodeLike {
     readonly left: number;
     readonly bottom: number;
     readonly right: number;
+    /**
+     * 同时更新相机视口宽高，通知投影矩阵在下一次使用前更新。
+     * @param width 新视口宽度
+     * @param height 新视口高度
+     * @example
+     * camera.setViewport(width, height);
+     * @returns 无返回值。
+     */
     setViewport(width: number, height: number): void;
+    /**
+     * 在渲染前更新版本落后的矩阵；支持相机挂在 Group/Mesh 内以及独立相机。
+     * @example
+     * camera.ensureCameraMatrix();
+     * @returns 无返回值。
+     */
     ensureCameraMatrix(): void;
+    /**
+     * 强制计算投影矩阵，保持 Y 正方向向上。
+     * @example
+     * camera.updateOrthogonalMatrix();
+     * @returns 计算得到的 Mat3 结果。
+     */
     updateOrthogonalMatrix(): Mat3;
+    /**
+     * 先确保父级与自身世界矩阵有效，再计算逆矩阵。
+     * @example
+     * camera.updateViewMatrix();
+     * @returns 计算得到的 Mat3 结果。
+     */
     updateViewMatrix(): Mat3;
+    /**
+     * 强制更新投影矩阵和视图矩阵。
+     * @example
+     * camera.updateCameraMatrix();
+     * @returns 无返回值。
+     */
     updateCameraMatrix(): void;
+    /**
+     * 世界坐标转归一化NDC坐标。
+     * @param position 世界坐标。
+     * @example
+     * camera.worldToNdc(position);
+     * @returns 归一化NDC坐标。
+     */
+    worldToNdc(position: Vec2): Vec2;
+    /**
+     * 归一化ndc坐标转世界坐标
+     * @param position 归一化NDC坐标。
+     * @example
+     * camera.ndcToWorld(position);
+     * @returns 世界坐标。
+     */
+    ndcToWorld(position: Vec2): Vec2;
+    /**
+     * 归一化NDC坐标转画布坐标。
+     * @param position 归一化NDC坐标。
+     * @param render 可选渲染器，按画布实际 CSS 尺寸换算；省略时使用相机宽高 / DPR
+     * @example
+     * camera.ndcToScreen(position, render);
+     * @returns 相对画布左上角的 CSS 像素坐标。
+     */
+    ndcToScreen(position: Vec2, render?: RenderLike): Vec2;
+    /**
+     * 画布坐标转归一化NDC坐标。
+     * @param position 相对画布左上角的 CSS 像素坐标
+     * @param render 可选渲染器，省略时使用相机宽高 / DPR
+     * @example
+     * camera.screenToNdc(position, render);
+     * @returns 归一化NDC坐标。
+     */
+    screenToNdc(position: Vec2, render?: RenderLike): Vec2;
+    /**
+     * 世界坐标转画布坐标。
+     * @param position 世界坐标。
+     * @param render 可选渲染器，支持 resize 延迟期间的 CSS 拉伸
+     * @example
+     * camera.worldToScreen(position, render);
+     * @returns 相对画布左上角的 CSS 像素坐标。
+     */
+    worldToScreen(position: Vec2, render?: RenderLike): Vec2;
+    /**
+     * 画布坐标转世界坐标
+     * @param position 相对画布左上角的 CSS 像素坐标
+     * @param render 可选渲染器，按画布实际 CSS 尺寸换算
+     * @example
+     * camera.screenToWorld(position, render);
+     * @returns 世界坐标。
+     */
+    screenToWorld(position: Vec2, render?: RenderLike): Vec2;
+    /**
+     * 世界坐标转浏览器视口坐标，适用于 DOM 定位；支持 CSS 平移/轴向缩放，不含旋转/倾斜。
+     * @param position 世界坐标。
+     * @param render 提供实际画布位置和尺寸的渲染器
+     * @example
+     * camera.worldToWindow(position, render);
+     * @returns clientX/clientY 坐标，不含页面滚动偏移。
+     */
+    worldToWindow(position: Vec2, render: RenderLike): Vec2;
+    /**
+     * 浏览器视口坐标转世界坐标。
+     * @param position MouseEvent.clientX/clientY，不是 pageX/pageY
+     * @param render 提供实际画布位置和尺寸的渲染器
+     * @example
+     * camera.windowToWorld(position, render);
+     * @returns 世界坐标。
+     */
+    windowToWorld(position: Vec2, render: RenderLike): Vec2;
 }
 /** 正交相机：输入沿用节点单一版本，矩阵与每个 Render 独立保存处理快照。 */
 declare class Camera extends ObjectNode implements CameraLike {
@@ -37,52 +140,249 @@ declare class Camera extends ObjectNode implements CameraLike {
     private _writingCamera;
     /** 保留的缓冲描述；实际 GPUBuffer 仍由 Render 持有。 */
     buffers: CameraBuffersLike;
-    /** @param width 视口宽度 @param height 视口高度 @param zoom 缩放值 */
+    /**
+     * 创建对象并建立初始状态及依赖关联。
+     * @param width 视口宽度
+     * @param height 视口高度
+     * @param zoom 缩放值
+     * @example
+     * const camera = new Camera(width, height, zoom);
+     * @returns 创建的 Camera 对象。
+     */
     constructor(width?: number, height?: number, zoom?: number);
-    /** 视口宽度。 */
+    /**
+     * 视口宽度。
+     * @example
+     * const value = camera.width;
+     * @returns 视口宽度。
+     */
     get width(): number;
-    /** @param value 新宽度 */
+    /**
+     * 视口宽度。
+     * @param value 新宽度
+     * @example
+     * camera.width = value;
+     * @returns 无返回值。
+     */
     set width(value: number);
-    /** 视口高度。 */
+    /**
+     * 视口高度。
+     * @example
+     * const value = camera.height;
+     * @returns 视口高度。
+     */
     get height(): number;
-    /** @param value 新高度 */
+    /**
+     * 视口高度。
+     * @param value 新高度
+     * @example
+     * camera.height = value;
+     * @returns 无返回值。
+     */
     set height(value: number);
-    /** 相机缩放。 */
+    /**
+     * 相机缩放。
+     * @example
+     * const value = camera.zoom;
+     * @returns 相机缩放。
+     */
     get zoom(): number;
-    /** @param value 新缩放 */
+    /**
+     * 相机缩放。
+     * @param value 新缩放
+     * @example
+     * camera.zoom = value;
+     * @returns 无返回值。
+     */
     set zoom(value: number);
-    /** 正交视口上边界。 */
+    /**
+     * 正交视口上边界。
+     * @example
+     * const value = camera.top;
+     * @returns 正交视口上边界。
+     */
     get top(): number;
-    /** 正交视口下边界。 */
+    /**
+     * 正交视口下边界。
+     * @example
+     * const value = camera.bottom;
+     * @returns 正交视口下边界。
+     */
     get bottom(): number;
-    /** 正交视口左边界。 */
+    /**
+     * 正交视口左边界。
+     * @example
+     * const value = camera.left;
+     * @returns 正交视口左边界。
+     */
     get left(): number;
-    /** 正交视口右边界。 */
+    /**
+     * 正交视口右边界。
+     * @example
+     * const value = camera.right;
+     * @returns 正交视口右边界。
+     */
     get right(): number;
-    /** 投影矩阵，GPU 上传比较矩阵版本。 */
+    /**
+     * 投影矩阵，GPU 上传比较矩阵版本。
+     * @example
+     * const value = camera.orthogonalMatrix;
+     * @returns 投影矩阵，GPU 上传比较矩阵版本。
+     */
     get orthogonalMatrix(): Mat3;
-    /** @param value 新投影矩阵，替换引用也使 Render 缓存失效 */
+    /**
+     * 投影矩阵，GPU 上传比较矩阵版本。
+     * @param value 新投影矩阵，替换引用也使 Render 缓存失效
+     * @example
+     * camera.orthogonalMatrix = value;
+     * @returns 无返回值。
+     */
     set orthogonalMatrix(value: Mat3);
-    /** 视图矩阵，通常为世界矩阵的逆。 */
+    /**
+     * 视图矩阵，通常为世界矩阵的逆。
+     * @example
+     * const value = camera.viewMatrix;
+     * @returns 视图矩阵，通常为世界矩阵的逆。
+     */
     get viewMatrix(): Mat3;
-    /** @param value 新视图矩阵 */
+    /**
+     * 视图矩阵，通常为世界矩阵的逆。
+     * @param value 新视图矩阵
+     * @example
+     * camera.viewMatrix = value;
+     * @returns 无返回值。
+     */
     set viewMatrix(value: Mat3);
-    /** @param source 数学对象 @param field 关联字段 */
+    /**
+     * 接收数学对象的变化通知，更新对应字段的消费者版本。
+     * @param source 数学对象
+     * @param field 关联字段
+     * @example
+     * camera.onMathChange(source, field);
+     * @returns 无返回值。
+     */
     onMathChange(source: VersionedMath, field: string): void;
-    /** @param width 新视口宽度 @param height 新视口高度 */
+    /**
+     * 同时更新相机视口宽高，通知投影矩阵在下一次使用前更新。
+     * @param width 新视口宽度
+     * @param height 新视口高度
+     * @example
+     * camera.setViewport(width, height);
+     * @returns 无返回值。
+     */
     setViewport(width?: number, height?: number): void;
-    /** 相机不提供子节点容器。 */
+    /**
+     * 相机不提供子节点容器。
+     * @example
+     * camera.add();
+     * @returns 无返回值。
+     */
     add(): void;
-    /** 在渲染前更新版本落后的矩阵；支持相机挂在 Group/Mesh 内以及独立相机。 */
+    /**
+     * 在渲染前更新版本落后的矩阵；支持相机挂在 Group/Mesh 内以及独立相机。
+     * @example
+     * camera.ensureCameraMatrix();
+     * @returns 无返回值。
+     */
     ensureCameraMatrix(): void;
-    /** 强制计算投影矩阵，保持 Y 正方向向上。 */
+    /**
+     * 强制计算投影矩阵，保持 Y 正方向向上。
+     * @example
+     * camera.updateOrthogonalMatrix();
+     * @returns 计算得到的 Mat3 结果。
+     */
     updateOrthogonalMatrix(): Mat3;
-    /** 先确保父级与自身世界矩阵有效，再计算逆矩阵。 */
+    /**
+     * 先确保父级与自身世界矩阵有效，再计算逆矩阵。
+     * @example
+     * camera.updateViewMatrix();
+     * @returns 计算得到的 Mat3 结果。
+     */
     updateViewMatrix(): Mat3;
-    /** 强制更新投影矩阵和视图矩阵。 */
+    /**
+     * 强制更新投影矩阵和视图矩阵。
+     * @example
+     * camera.updateCameraMatrix();
+     * @returns 无返回值。
+     */
     updateCameraMatrix(): void;
-    /** 最终释放相机对所有数学对象的订阅，不销毁共享矩阵。 */
+    /**
+     * 最终释放相机对所有数学对象的订阅，不销毁共享矩阵。
+     * @example
+     * camera.dispose();
+     * @returns 无返回值。
+     */
     dispose(): void;
+    /**
+     * 世界坐标转归一化NDC坐标。
+     * @param position 世界坐标。
+     * @example
+     * camera.worldToNdc(position);
+     * @returns 归一化NDC坐标。
+     */
+    worldToNdc(position: Vec2): Vec2;
+    /**
+     * 归一化NDC坐标转画布坐标。
+     * @param position 归一化NDC坐标。
+     * @param render 可选渲染器，按画布实际 CSS 尺寸换算；省略时使用相机宽高 / DPR
+     * @example
+     * camera.ndcToScreen(position, render);
+     * @returns 相对画布左上角的 CSS 像素坐标。
+     */
+    ndcToScreen(position: Vec2, render?: RenderLike): Vec2;
+    /**
+     * 世界坐标转画布坐标。
+     * @param position 世界坐标。
+     * @param render 可选渲染器，支持 resize 延迟期间的 CSS 拉伸
+     * @example
+     * camera.worldToScreen(position, render);
+     * @returns 相对画布左上角的 CSS 像素坐标。
+     */
+    worldToScreen(position: Vec2, render?: RenderLike): Vec2;
+    /**
+     * 画布坐标转归一化NDC坐标。
+     * @param position 相对画布左上角的 CSS 像素坐标
+     * @param render 可选渲染器，省略时使用相机宽高 / DPR
+     * @example
+     * camera.screenToNdc(position, render);
+     * @returns 归一化NDC坐标。
+     */
+    screenToNdc(position: Vec2, render?: RenderLike): Vec2;
+    /**
+     * 归一化ndc坐标转世界坐标
+     * @param position 归一化NDC坐标。
+     * @example
+     * camera.ndcToWorld(position);
+     * @returns 世界坐标。
+     */
+    ndcToWorld(position: Vec2): Vec2;
+    /**
+     * 画布坐标转世界坐标
+     * @param position 相对画布左上角的 CSS 像素坐标
+     * @param render 可选渲染器，按画布实际 CSS 尺寸换算
+     * @example
+     * camera.screenToWorld(position, render);
+     * @returns 世界坐标。
+     */
+    screenToWorld(position: Vec2, render?: RenderLike): Vec2;
+    /**
+     * 世界坐标转浏览器视口坐标，适用于 DOM 定位；支持 CSS 平移/轴向缩放，不含旋转/倾斜。
+     * @param position 世界坐标。
+     * @param render 提供实际画布位置和尺寸的渲染器
+     * @example
+     * camera.worldToWindow(position, render);
+     * @returns clientX/clientY 坐标，不含页面滚动偏移。
+     */
+    worldToWindow(position: Vec2, render: RenderLike): Vec2;
+    /**
+     * 浏览器视口坐标转世界坐标。
+     * @param position MouseEvent.clientX/clientY，不是 pageX/pageY
+     * @param render 提供实际画布位置和尺寸的渲染器
+     * @example
+     * camera.windowToWorld(position, render);
+     * @returns 世界坐标。
+     */
+    windowToWorld(position: Vec2, render: RenderLike): Vec2;
 }
 export default Camera;
 export type { CameraBuffersLike, CameraLike };