doc(render): fix incorrectly transposed view matrix docs (#19317)

# Objective

- Mend incorrect docs

## Solution

- Mend them
- add example use
- clarify column major

## Testing

- No code changes
This commit is contained in:
atlv 2025-05-27 00:58:58 -04:00 committed by François Mockers
parent 4562bb484f
commit b14f94ec34
2 changed files with 36 additions and 30 deletions

View File

@ -262,34 +262,36 @@ impl RetainedViewEntity {
pub struct ExtractedView { pub struct ExtractedView {
/// The entity in the main world corresponding to this render world view. /// The entity in the main world corresponding to this render world view.
pub retained_view_entity: RetainedViewEntity, pub retained_view_entity: RetainedViewEntity,
/// Typically a right-handed projection matrix, one of either: /// Typically a column-major right-handed projection matrix, one of either:
/// ///
/// Perspective (infinite reverse z) /// Perspective (infinite reverse z)
/// ```text /// ```text
/// f = 1 / tan(fov_y_radians / 2) /// f = 1 / tan(fov_y_radians / 2)
/// ///
/// ⎡ f / aspect 0 0 0 ⎤ /// ⎡ f / aspect 0 0 0 ⎤
/// ⎢ 0 f 0 0 ⎥ /// ⎢ 0 f 0 0 ⎥
/// ⎢ 0 0 0 -1 /// ⎢ 0 0 0 near
/// ⎣ 0 0 near 0 ⎦ /// ⎣ 0 0 -1 0 ⎦
/// ``` /// ```
/// ///
/// Orthographic /// Orthographic
/// ```text /// ```text
/// w = right - left /// w = right - left
/// h = top - bottom /// h = top - bottom
/// d = near - far /// d = far - near
/// cw = -right - left /// cw = -right - left
/// ch = -top - bottom /// ch = -top - bottom
/// ///
/// ⎡ 2 / w 0 0 0 /// ⎡ 2 / w 0 0 cw / w
/// ⎢ 0 2 / h 0 0 /// ⎢ 0 2 / h 0 ch / h
/// ⎢ 0 0 1 / d 0 /// ⎢ 0 0 1 / d far / d
/// ⎣ cw / w ch / h near / d 1 ⎦ /// ⎣ 0 0 0 1 ⎦
/// ``` /// ```
/// ///
/// `clip_from_view[3][3] == 1.0` is the standard way to check if a projection is orthographic /// `clip_from_view[3][3] == 1.0` is the standard way to check if a projection is orthographic
/// ///
/// Glam matrices are column major, so for example getting the near plane of a perspective projection is `clip_from_view[3][2]`
///
/// Custom projections are also possible however. /// Custom projections are also possible however.
pub clip_from_view: Mat4, pub clip_from_view: Mat4,
pub world_from_view: GlobalTransform, pub world_from_view: GlobalTransform,
@ -529,34 +531,36 @@ pub struct ViewUniform {
pub world_from_clip: Mat4, pub world_from_clip: Mat4,
pub world_from_view: Mat4, pub world_from_view: Mat4,
pub view_from_world: Mat4, pub view_from_world: Mat4,
/// Typically a right-handed projection matrix, one of either: /// Typically a column-major right-handed projection matrix, one of either:
/// ///
/// Perspective (infinite reverse z) /// Perspective (infinite reverse z)
/// ```text /// ```text
/// f = 1 / tan(fov_y_radians / 2) /// f = 1 / tan(fov_y_radians / 2)
/// ///
/// ⎡ f / aspect 0 0 0 ⎤ /// ⎡ f / aspect 0 0 0 ⎤
/// ⎢ 0 f 0 0 ⎥ /// ⎢ 0 f 0 0 ⎥
/// ⎢ 0 0 0 -1 /// ⎢ 0 0 0 near
/// ⎣ 0 0 near 0 ⎦ /// ⎣ 0 0 -1 0 ⎦
/// ``` /// ```
/// ///
/// Orthographic /// Orthographic
/// ```text /// ```text
/// w = right - left /// w = right - left
/// h = top - bottom /// h = top - bottom
/// d = near - far /// d = far - near
/// cw = -right - left /// cw = -right - left
/// ch = -top - bottom /// ch = -top - bottom
/// ///
/// ⎡ 2 / w 0 0 0 /// ⎡ 2 / w 0 0 cw / w
/// ⎢ 0 2 / h 0 0 /// ⎢ 0 2 / h 0 ch / h
/// ⎢ 0 0 1 / d 0 /// ⎢ 0 0 1 / d far / d
/// ⎣ cw / w ch / h near / d 1 ⎦ /// ⎣ 0 0 0 1 ⎦
/// ``` /// ```
/// ///
/// `clip_from_view[3][3] == 1.0` is the standard way to check if a projection is orthographic /// `clip_from_view[3][3] == 1.0` is the standard way to check if a projection is orthographic
/// ///
/// Glam matrices are column major, so for example getting the near plane of a perspective projection is `clip_from_view[3][2]`
///
/// Custom projections are also possible however. /// Custom projections are also possible however.
pub clip_from_view: Mat4, pub clip_from_view: Mat4,
pub view_from_clip: Mat4, pub view_from_clip: Mat4,

View File

@ -19,33 +19,35 @@ struct View {
world_from_clip: mat4x4<f32>, world_from_clip: mat4x4<f32>,
world_from_view: mat4x4<f32>, world_from_view: mat4x4<f32>,
view_from_world: mat4x4<f32>, view_from_world: mat4x4<f32>,
// Typically a right-handed projection matrix, one of either: // Typically a column-major right-handed projection matrix, one of either:
// //
// Perspective (infinite reverse z) // Perspective (infinite reverse z)
// ``` // ```
// f = 1 / tan(fov_y_radians / 2) // f = 1 / tan(fov_y_radians / 2)
// //
// f / aspect 0 0 0 // f / aspect 0 0 0
// 0 f 0 0 // 0 f 0 0
// 0 0 0 -1 // 0 0 0 near
// 0 0 near 0 // 0 0 -1 0
// ``` // ```
// //
// Orthographic // Orthographic
// ``` // ```
// w = right - left // w = right - left
// h = top - bottom // h = top - bottom
// d = near - far // d = far - near
// cw = -right - left // cw = -right - left
// ch = -top - bottom // ch = -top - bottom
// //
// 2 / w 0 0 0 // 2 / w 0 0 cw / w
// 0 2 / h 0 0 // 0 2 / h 0 ch / h
// 0 0 1 / d 0 // 0 0 1 / d far / d
// cw / w ch / h near / d 1 // 0 0 0 1
// ``` // ```
// //
// `clip_from_view[3][3] == 1.0` is the standard way to check if a projection is orthographic // `clip_from_view[3][3] == 1.0` is the standard way to check if a projection is orthographic
//
// Wgsl matrices are column major, so for example getting the near plane of a perspective projection is `clip_from_view[3][2]`
// //
// Custom projections are also possible however. // Custom projections are also possible however.
clip_from_view: mat4x4<f32>, clip_from_view: mat4x4<f32>,