AcademySoftwareFoundation / AcademySoftwareFoundation/OpenShadingLanguage

Matrix layout is only partially documented

Open
#1,895 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
2.3k
Forks
414
Avg merge
3d 1h
Merged PRs (30d)
10

Description

The documentation of `matrix()` points out that the 16-float constructor form accepts values in row major order, and the `[][]` operator accepts first a row and then a column. However that by itself is not meaningful, it also needs to specify if matrices have basis vectors in rows or columns. Depending on that choice:

- A translation matrix may be either `matrix(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, tx, ty, tz, 1)`, or\
`matrix(1, 0, 0, tx, 0, 1, 0, ty, 0, 0, 1, tz, 0, 0, 0, 1)`.
- The expression `point p3 = transform(M1 * M2, p1)` may be equivalent to either\
`point p2 = transform(M1, p1) ; point p3 = transform(M2, p2);`, or\
`point p2 = transform(M2, p1) ; point p3 = transform(M1, p2);`

In algebraic terms, that matrix multiplication would look like $\mathbf{p}\mathbf{M}_1\mathbf{M}_2$ (if vectors are rows), or $\mathbf{M}_2\mathbf{M}_1\mathbf{p}$ (if vectors are columns).

Contributor guide

Open the contributing guide

Research direction

Locate the documentation for matrix(), including its 16-float constructor and [][] operator. Document whether basis vectors are rows or columns and state the resulting matrix multiplication and transform order; done when both ambiguities are explicitly resolved.

Written by the indexing model from the issue text.

Assessment

Domain
computer-graphics, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.