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,7 +262,7 @@ impl RetainedViewEntity {
pub struct ExtractedView {
/// The entity in the main world corresponding to this render world view.
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)
/// ```text
@ -270,26 +270,28 @@ pub struct ExtractedView {
///
/// ⎡ f / aspect 0 0 0 ⎤
/// ⎢ 0 f 0 0 ⎥
/// ⎢ 0 0 0 -1
/// ⎣ 0 0 near 0 ⎦
/// ⎢ 0 0 0 near
/// ⎣ 0 0 -1 0 ⎦
/// ```
///
/// Orthographic
/// ```text
/// w = right - left
/// h = top - bottom
/// d = near - far
/// d = far - near
/// cw = -right - left
/// ch = -top - bottom
///
/// ⎡ 2 / w 0 0 0
/// ⎢ 0 2 / h 0 0
/// ⎢ 0 0 1 / d 0
/// ⎣ cw / w ch / h near / d 1 ⎦
/// ⎡ 2 / w 0 0 cw / w
/// ⎢ 0 2 / h 0 ch / h
/// ⎢ 0 0 1 / d far / d
/// ⎣ 0 0 0 1 ⎦
/// ```
///
/// `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.
pub clip_from_view: Mat4,
pub world_from_view: GlobalTransform,
@ -529,7 +531,7 @@ pub struct ViewUniform {
pub world_from_clip: Mat4,
pub world_from_view: 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)
/// ```text
@ -537,26 +539,28 @@ pub struct ViewUniform {
///
/// ⎡ f / aspect 0 0 0 ⎤
/// ⎢ 0 f 0 0 ⎥
/// ⎢ 0 0 0 -1
/// ⎣ 0 0 near 0 ⎦
/// ⎢ 0 0 0 near
/// ⎣ 0 0 -1 0 ⎦
/// ```
///
/// Orthographic
/// ```text
/// w = right - left
/// h = top - bottom
/// d = near - far
/// d = far - near
/// cw = -right - left
/// ch = -top - bottom
///
/// ⎡ 2 / w 0 0 0
/// ⎢ 0 2 / h 0 0
/// ⎢ 0 0 1 / d 0
/// ⎣ cw / w ch / h near / d 1 ⎦
/// ⎡ 2 / w 0 0 cw / w
/// ⎢ 0 2 / h 0 ch / h
/// ⎢ 0 0 1 / d far / d
/// ⎣ 0 0 0 1 ⎦
/// ```
///
/// `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.
pub clip_from_view: Mat4,
pub view_from_clip: Mat4,

View File

@ -19,7 +19,7 @@ struct View {
world_from_clip: mat4x4<f32>,
world_from_view: 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)
// ```
@ -27,26 +27,28 @@ struct View {
//
// f / aspect 0 0 0
// 0 f 0 0
// 0 0 0 -1
// 0 0 near 0
// 0 0 0 near
// 0 0 -1 0
// ```
//
// Orthographic
// ```
// w = right - left
// h = top - bottom
// d = near - far
// d = far - near
// cw = -right - left
// ch = -top - bottom
//
// 2 / w 0 0 0
// 0 2 / h 0 0
// 0 0 1 / d 0
// cw / w ch / h near / d 1
// 2 / w 0 0 cw / w
// 0 2 / h 0 ch / h
// 0 0 1 / d far / d
// 0 0 0 1
// ```
//
// `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.
clip_from_view: mat4x4<f32>,
view_from_clip: mat4x4<f32>,