Camera

Added because three callers had each derived this by hand and one of them got it wrong: a preview rig placed itself on a circle around its subject and computed a yaw that was exactly π out, so it rendered the inside of an empty box and the figure it was built to show was behind it. The trig is four lines and the sign conventions are this class's own — yaw 0 looks toward −Z, positive yaw turns toward +X — so leaving every caller to rediscover them is leaving them a trap.

Sets yaw and pitch only. Roll is a separate decision (it is a lean, not an aim), and updateMatrices still has to be called afterwards.

Because an XR eye cannot be described by this class, and this file already says why. updateMatrices derives the view from yaw and pitch and the projection from mat4.perspective, and the note above it records the corollary: only a centred crop of a symmetric frustum is itself a symmetric frustum; an off-centre one is sheared, which perspective cannot produce. A headset's eye projection is exactly that shear, off-axis by the distance from the pupil to the display's centre, and its view comes from a pose no pair of Euler angles was ever asked to describe.

So a supplied view is adopted rather than configured. Everything downstream reads view, projection, viewProjection and invViewProjection, so frustum culling, picking, the sky and every pass that samples the inverse keep working with nothing changed.

position and forward are decomposed back out, and that is not a convenience. A view matrix is the inverse of the camera's world transform, so the eye is -Rᵀt and the direction is the third row negated. A consumer reading camera.position to place a listener or to score a level of detail would otherwise get whatever the last non-XR frame left there, which is a defect that looks like an audio bug rather than a camera one.

yaw, pitch and roll are deliberately left alone, and reading them after this is reading the last angles somebody set. A supplied rotation may be one no Euler triple describes without a convention this class does not own, and inventing one here would put a second answer to "where is the camera looking" beside forward, which is derived from the matrix and is always right.

near and far are not read and not written: the supplied projection carries its own depth range, which the runtime chose.

For attaching DOM to a place in the world: a focus ring on a card, a label on a marker. The caller passes the CSS box rather than the drawing buffer, because the answer is for the document and the document does not know the device pixel ratio.

False rather than a coordinate when w <= 1e-6. The perspective divide by a negative w mirrors the point through the origin, so a thing behind the viewer reports a perfectly plausible position on the opposite side of the screen. A caller that placed an affordance there would be putting it on the wrong object, which is worse than putting it nowhere.

Two points are unprojected rather than one, because a direction cannot be recovered from a single unprojected point without knowing where the eye is in the same space — and for an orthographic camera there is no single eye at all. Unprojecting both ends of the depth range and subtracting is correct for either projection, which is why it is written this way for a camera that is currently only perspective.

cssX/cssY are in the canvas's CSS box, so a caller hands over event.clientX - rect.left and nothing has to know the device pixel ratio.