@forgeax/engine-picking 0.1.33 → 0.1.34

package/README.md

@@ -20,6 +20,23 @@ never the reverse.
 - **`viewportToWorld(world, cameraEntity, screenX, screenY, viewportWidth, viewportHeight)`**
   — exposes the same camera unprojection as a world-space `Ray` for cursor
   placement, gizmos, and custom plane/triangle queries.
+- **`pickDisplay` / `computeDisplayScreenRay`** — explicit display-space
+  entrypoints. They consume the effective `BarrelDistortionMapping` from the
+  submitted frame, map the displayed physical pixel once, then use the existing
+  unwarped camera math. The submitted mapping is mandatory, including its
+  identity case; absent, retired, lost, or zero-size frame contexts return a
+  miss. Legacy `pick` and `viewportToWorld` remain unwarped APIs.
+- **`pickVertexDisplay` / `pickVertexOnEntityDisplay`** — display-space vertex
+  queries. They project each candidate back through the same scene-to-display
+  inverse before applying the optional physical-pixel radius and sorting, so a
+  nonlinear warp cannot change which vertex is closest merely by correcting the
+  pointer.
+
+> [!WARNING]
+> An omitted `barrelDistortion` field means that no accepted submitted display
+> context is available. Treat it as a miss and wait for a new frame. An
+> identity query is valid only with an explicit submitted mapping whose
+> `strength` is `0`.
 - **`pickTriangle`** — exact static CPU triangle query for a screen ray. It
   transforms indexed or non-indexed triangle-list vertices into world space,
   returns the nearest world point, distance, barycentric weights, entity,
@@ -84,6 +101,37 @@ and `orthographic` camera projections are supported. Reads the resolved
 `GlobalTransform.world` mat4 directly (feat-20260601 D-3), so the camera + candidates
 must have propagated transforms for the current frame.
 
+### Display-space interaction
+
+```ts
+import { pickDisplay } from '@forgeax/engine-picking';
+
+const hit = pickDisplay(
+  world,
+  cameraEntity,
+  outputPixelX,
+  outputPixelY,
+  submittedReceipt.barrelDistortion,
+  outputWidth,
+  outputHeight,
+);
+```
+
+Coordinates are continuous physical output pixels. The host first converts the
+CSS pointer through the actual canvas/viewport rectangle and output extent; it
+does not add a half-pixel offset. Out-of-viewport and crop misses return
+`undefined` before the math layer's normal screen clamp. Reuse the same receipt
+mapping for labels, crosshairs, and display-space queries so a newer ECS camera
+component cannot disagree with the frame on screen. The App
+`subscribeBrowserFrameSubmitted(canvas, listener)` helper forwards the
+deep-frozen mapping and frame identity from the accepted browser submission;
+unsubscribe it when the canvas or renderer is retired. A lost or zero-size
+context must be discarded and reacquired through the existing App/Renderer
+recovery path. The width and height arguments are an explicit check against
+`mapping.width` and `mapping.height`; a mismatch, an undefined mapping, or an
+identity guess without a submitted mapping returns a miss. Display picking
+never falls back to the live World camera.
+
 ### Screen-to-world (`viewportToWorld`)
 
 | Function | Signature | Return |
@@ -132,10 +180,9 @@ Only `triangle-list` submeshes participate; skinned meshes report
 nearest `TriangleHit`; `miss` means every candidate was tested and no triangle
 intersects the ray; `unavailable` names intersecting entities whose CPU
 geometry, current skinned pose, or explicit instance transforms cannot be
-tested. For an entity carrying `Instances`, pass its renderer-owned
-`InstanceCollectionStore` as `options.instances`; a hit then includes the
-zero-based `instanceIndex`. The picker uses the store's non-consuming `peek`
-read, so inspection cannot consume a later render upload range. Pass
+tested. For an entity carrying `Instances`, the picker reads World-owned
+`Instances.transforms`; a hit includes the zero-based `instanceIndex`.
+No Renderer or collection resolver is needed. Pass
 `AssetRegistry.guidOf` as `assetGuidOf` when provenance is needed. The query
 does not mutate the World or own an asset registry.
 

package/dist/__tests__/display-picking.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=display-picking.unit.test.d.ts.map

package/dist/__tests__/display-picking.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-picking.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/display-picking.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/voxel-display-consumer.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=voxel-display-consumer.test-d.d.ts.map

package/dist/__tests__/voxel-display-consumer.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voxel-display-consumer.test-d.d.ts","sourceRoot":"","sources":["../../src/__tests__/voxel-display-consumer.test-d.ts"],"names":[],"mappings":""}

package/dist/display-picking.d.ts

@@ -0,0 +1,27 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { type BarrelDistortionMapping, type DisplayPoint } from '@forgeax/engine-render';
+import { type PickHit } from './pick';
+import { type ScreenRay } from './pick-core';
+import { type VertexHit } from './pick-vertex';
+export interface DisplayVertexPickOptions {
+    readonly limit?: number;
+    /** Maximum distance in displayed physical pixels; omitted keeps all ray hits. */
+    readonly radius?: number;
+}
+/**
+ * Convert a displayed output pixel to the matching unwarped scene pixel.
+ *
+ * `undefined` is the fail-closed signal that no accepted submitted frame is
+ * available. It is not an identity mapping; callers must wait for a new
+ * submitted frame (including an explicit zero-strength mapping).
+ */
+export declare function displayToScenePixel(out: DisplayPoint, mapping: BarrelDistortionMapping | undefined, displayX: number, displayY: number): boolean;
+/** Build a world ray from the physical pixel currently visible on screen. */
+export declare function computeDisplayScreenRay(world: World, cameraEntity: EntityHandle, displayX: number, displayY: number, mapping: BarrelDistortionMapping | undefined, viewportWidth: number, viewportHeight: number): ScreenRay | undefined;
+/** Explicit display-space entity pick; legacy `pick` remains unwarped. */
+export declare function pickDisplay(world: World, _cameraEntity: EntityHandle, displayX: number, displayY: number, mapping: BarrelDistortionMapping | undefined, viewportWidth: number, viewportHeight: number): PickHit | undefined;
+/** Pick vertices using displayed-pixel radius and ordering under the same mapping. */
+export declare function pickVertexDisplay(world: World, _cameraEntity: EntityHandle, displayX: number, displayY: number, mapping: BarrelDistortionMapping | undefined, viewportWidth: number, viewportHeight: number, options?: DisplayVertexPickOptions): VertexHit | VertexHit[] | undefined;
+/** Pick vertices on one entity using displayed-pixel radius and ordering. */
+export declare function pickVertexOnEntityDisplay(world: World, _cameraEntity: EntityHandle, displayX: number, displayY: number, mapping: BarrelDistortionMapping | undefined, viewportWidth: number, viewportHeight: number, entity: EntityHandle, options?: DisplayVertexPickOptions): VertexHit | VertexHit[] | undefined;
+//# sourceMappingURL=display-picking.d.ts.map

package/dist/display-picking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-picking.d.ts","sourceRoot":"","sources":["../src/display-picking.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EAGlB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,OAAO,EAAqB,MAAM,QAAQ,CAAC;AACzD,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,uBAAuB,GAAG,SAAS,EAC5C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAGT;AA8BD,6EAA6E;AAC7E,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,EAC1B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,uBAAuB,GAAG,SAAS,EAC5C,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,GACrB,SAAS,GAAG,SAAS,CAoBvB;AAqBD,0EAA0E;AAC1E,wBAAgB,WAAW,CACzB,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,YAAY,EAC3B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,uBAAuB,GAAG,SAAS,EAC5C,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,GACrB,OAAO,GAAG,SAAS,CAkBrB;AAiED,sFAAsF;AACtF,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,YAAY,EAC3B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,uBAAuB,GAAG,SAAS,EAC5C,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,wBAAwB,GACjC,SAAS,GAAG,SAAS,EAAE,GAAG,SAAS,CAmCrC;AAED,6EAA6E;AAC7E,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,YAAY,EAC3B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,uBAAuB,GAAG,SAAS,EAC5C,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,wBAAwB,GACjC,SAAS,GAAG,SAAS,EAAE,GAAG,SAAS,CAkCrC"}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export type { DisplayVertexPickOptions } from './display-picking';
+export { computeDisplayScreenRay, displayToScenePixel, pickDisplay, pickVertexDisplay, pickVertexOnEntityDisplay, } from './display-picking';
 export type { PickHit } from './pick';
 export { pick } from './pick';
 export type { PickErrorCode } from './pick-errors';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,YAAY,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAG9B,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EACL,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,6BAA6B,GACnC,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,YAAY,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,WAAW,EACX,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAG9B,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EACL,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,6BAA6B,GACnC,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC"}