The HTML canvas element that defines the coordinate space
The pointer event containing screen coordinates (offsetX, offsetY)
Optional viewport definition for multi-viewport applications
Optionalmouse: Vector2Optional Vector2 to reuse for the result (prevents object allocation)
Vector2 containing normalized device coordinates (x: -1 to 1, y: -1 to 1)
Transforms DOM pointer event coordinates into Three.js normalized device coordinates, which are required for raycasting and 3D object intersection detection. This function is the core coordinate conversion utility that bridges pointer interactions with Three.js 3D scene queries.
Conversion Process: Converts DOM pixel coordinates to Three.js normalized device coordinates (NDC). Supports both full-canvas and viewport-specific coordinate systems.
Performance Optimization:
The optional mouse parameter allows reusing Vector2 instances to prevent
object allocation during high-frequency pointer events.
// Basic usage
const ndcCoords = convertToMousePosition(canvas, event, undefined);
// With viewport
const viewport = new Vector4(100, 50, 400, 300);
const ndcCoords = convertToMousePosition(canvas, event, viewport);
// Performance-optimized with vector reuse
const reusableVector = new Vector2();
convertToMousePosition(canvas, event, viewport, reusableVector);
Essential for Three.js raycasting operations. Used extensively by MouseEventManager for interactive object detection in both full-canvas and multi-viewport applications.
Converts DOM pointer event coordinates to Three.js normalized device coordinates (NDC).