From 6bfabfee317887e678eed9cd6768df2ffd3b9704 Mon Sep 17 00:00:00 2001 From: Jay Kwak <82421531+jkwak-work@users.noreply.github.com> Date: Sat, 19 Apr 2025 03:29:15 -0700 Subject: Document matrix multiplication operators (#6852) * Document matrix multiplication operators This is to address one of cases where a user was confused about why Slang doesn't have operator overloading of multiplication for matrices. It is little confusing that glsl.meta.slang implemented `operator*()` for matrices but Slang/HLSL doesn't. It turned out that HLSL/Slang performs a component-wise multiplication with `operator*()` whereas GLSL performs a matrix multiplication. * Mentioning CUDA * Update based on the review feedback --- docs/language-reference/04-types.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/language-reference/04-types.md b/docs/language-reference/04-types.md index 3ccc7bdcb..a49efb490 100644 --- a/docs/language-reference/04-types.md +++ b/docs/language-reference/04-types.md @@ -153,6 +153,21 @@ typealias int64_t4x2 = matrix; > While it may seem that this choice of convention is confusing, it is necessary to ensure that subscripting with `[]` can be efficiently implemented on all target platforms. > This decision in the Slang language is consistent with the compilation of HLSL to SPIR-V performed by other compilers. + +### Matrix Operations + +Matrix types support several operations: + +* Element-wise operations (addition, subtraction, multiplication) using the standard operators (`+`, `-`, `*`). These operations require matrices of the same dimensions. +* Algebraic matrix-matrix multiplication using the `mul()` function, which supports matrices of compatible dimensions (e.g., `float2x3 * float3x4`). +* Matrix-vector multiplication using `mul()`, where the vector can be interpreted as either a row or column vector depending on the parameter order: + * `mul(v, m)` - v is interpreted as a row vector + * `mul(m, v)` - v is interpreted as a column vector + +For proper matrix multiplication, always use the `mul()` function. The `operator*` performs element-wise multiplication and should only be used when you want to multiply corresponding elements of same-sized matrices. + +> Note: This differs from GLSL, where the `*` operator performs matrix multiplication. When porting code from GLSL or CUDA to Slang, you'll need to replace matrix multiplications using `*` with calls to `mul()`. + ### Legacy Syntax For compatibility with older codebases, the generic `matrix` type includes default values for `T`, `R`, and `C`, being declared as: -- cgit v1.2.3