ianmackenzie / elm-3d-camera / WebGL.Matrices

These matrices can be used for rendering 3D WebGL scenes. For in-depth explanations of how they are used, check out:

Individual matrices

modelMatrix : Frame3d units coordinates defines -> Math.Matrix4.Mat4

Construct a WebGL model matrix given a Frame3d that defines the position and orientation of an object. Multiplying by this matrix transforms from local object coordinates (coordinates relative to the given frame) to world coordinates.

(This is an alias of Frame3d.toMat4, provided here for consistency/convenience.)

viewMatrix : Camera3d units coordinates -> Math.Matrix4.Mat4

Construct a WebGL view matrix for a given camera. Multiplying by this matrix transforms from world coordinates to view (eye) coordinates.

Note that to avoid accuracy/roundoff issues (especially if both the camera and rendered objects are far from the world origin point), it is often better to use modelViewMatrix instead of calling modelMatrix and viewMatrix separately.

projectionMatrix : Camera3d units coordinates -> { nearClipDepth : Quantity Basics.Float units, farClipDepth : Quantity Basics.Float units, aspectRatio : Basics.Float } -> Math.Matrix4.Mat4

Construct a WebGL projection matrix for a given camera, by supplying near and far clip depths as well as the aspect ratio (width over height) of the WebGL window being rendered to. Multiplying by this matrix converts from view coordinates to clip coordinates.

Using a value of Quantity.positiveInfinity for farClipDepth is supported, and this often works well for perspective cameras. However, for orthographic cameras, an infinite far clip depth means that depth testing will not work. For things like line drawings this might be fine, but if you are depending on closer objects being reliably drawn in front of further-away objects (at least when using an orthographic camera) then you will have to specify a finite far clip depth.

Combined matrices

modelViewMatrix : Frame3d units coordinates defines -> Camera3d units coordinates -> Math.Matrix4.Mat4

Construct a WebGL model-view matrix given a camera and a Frame3d that defines the position and orientation of an object.

Multiplying by this matrix transforms from local object coordinates (coordinates relative to the given frame) directly to view (eye) coordinates without first transforming to world coordinates. Avoiding this intermediate conversion to world coordinates improves accuracy, especially if both the object and camera are far from the world origin point.

viewProjectionMatrix : Camera3d units coordinates -> { nearClipDepth : Quantity Basics.Float units, farClipDepth : Quantity Basics.Float units, aspectRatio : Basics.Float } -> Math.Matrix4.Mat4

Construct a WebGL view-projection matrix for a given camera; this is the product of the projection and view matrices. Multiplying by this matrix converts from world coordinates to clip coordinates.

modelViewProjectionMatrix : Frame3d units coordinates defines -> Camera3d units coordinates -> { nearClipDepth : Quantity Basics.Float units, farClipDepth : Quantity Basics.Float units, aspectRatio : Basics.Float } -> Math.Matrix4.Mat4

Construct a WebGL model-view-projection matrix for a given camera; this is the product of the projection and model-view matrices. Multiplying by this matrix converts from local object coordinates to clip coordinates.