diff options
| -rw-r--r-- | docs/_includes/user-guide-toc.html | 5 | ||||
| -rw-r--r-- | docs/user-guide/a1-01-matrix-layout.md | 56 | ||||
| -rw-r--r-- | docs/user-guide/a1-special-topics.md | 11 |
3 files changed, 72 insertions, 0 deletions
diff --git a/docs/_includes/user-guide-toc.html b/docs/_includes/user-guide-toc.html index ec6f60d05..a761fe3fd 100644 --- a/docs/_includes/user-guide-toc.html +++ b/docs/_includes/user-guide-toc.html @@ -7,4 +7,9 @@ <li><a href="/slang/user-guide/04-interfaces-generics.html">Interfaces and Generics</a></li> <li><a href="/slang/user-guide/05-compiling.html">Compiling Code with Slang</a></li> <li><a href="/slang/user-guide/06-targets.html">Supported Compilation Targets</a></li> + <li><a href="/slang/user-guide/a1-special-topics.html">Special Topics</a></li> + <ol style="list-style-type:circle"> + <li><a href="/slang/user-guide/a1-01-matrix-layout.html">Matrix Layout</a></li> + </ol> + </ol> diff --git a/docs/user-guide/a1-01-matrix-layout.md b/docs/user-guide/a1-01-matrix-layout.md new file mode 100644 index 000000000..f8e4edd78 --- /dev/null +++ b/docs/user-guide/a1-01-matrix-layout.md @@ -0,0 +1,56 @@ +--- +layout: user-guide +--- + +Handling Matrix Layout Differences on Different Platforms +============================ + +The differences on default matrix layout or storage conventions between GLSL (OpenGL/Vulkan) and HLSL has been an issue that frequently causes confusion among developers. When writing applications that work on different targets, one important goal that developers frequently seek is to make it possible to pass the same matrix generated by host code to the same shader code, regardless of what graphics API is being used (e.g. Vulkan, OpenGL or Direct3D). As a solution to shader cross-compilation, Slang provides necessary tools for developers navigate around the differences between GLSL and HLSL targets. + +Row-major vs Column-major storage layouts +------------------------- +In this article, the term matrix layouts or storage layouts refers to the order of matrix elements in memory. Specifically, we use the following umambiguous technique to determine whether a matrix is in `row-major` and `column-major` layout: if we have a 4x4 matrix defined as `float m[16]`, and the translation terms are stored at `m[12], m[13], m[14]`, then we say this matrix is in `column-major` layout. If the translation terms are stored at `m[3], m[7], m[11]`, then we say this matrix is in `row-major` layout. + +Using this technique, it should be easy to know the layout that your host math library is using. For example, the `glm` library uses `column-major` layout by default under the definition of this article. + +If the host code generates a `column-major` matrix, then a vertex shader written in GLSL should be like this: +``` +gl_Position = modelViewProjectionMatrix * vertexPosition; +``` +The same vertex shader written in HLSL should be: +``` +float4 result = mul(vertexPosition, modelViewProjectionMatrix); +``` + +If the host code generates a `row-major` matrix, the correct GLSL code should be: +``` +gl_Position = vertexPosition * modelViewProjectionMatrix; +``` +The correct HLSL code should be: +``` +float4 result = mul(modelViewProjectionMatrix, vertexPosition); +``` + +As you can see, the ordering of matrix multiplication is always reversed between GLSL and HLSL. +Slang will always translate `mul(a, b)` to `b * a` when generating GLSL code. By default, Slang assumes all matrices to be in `row-major` layout, so a shader code written in Slang should be written as `mul(modelViewProjectionMatrix, vertexPosition)`, and the host application should always make sure to pass matrices in row-major layout to shaders. However, the user can always override this behavior with a compiler flag to make Slang compiler assume `column-major` matrix layout by default. This compiler flag can be specified during the creation of a `Session`: +``` +slang::IGlobalSession* globalSession; +... +slang::SessionDesc slangSessionDesc = {}; +slangSessionDesc.defaultMatrixLayoutMode = SLANG_MATRIX_LAYOUT_COLUMN_MAJOR; +... +slang::ISession* session; +globalSession->createSession(slangSessionDesc, &session); +``` + +In summary, to make sure your application works correctly on all platforms, you need to make sure the application does the following things consistently: +###Using row-major matrix layout +- Make sure the host code fills in matrices in row-major layout, i.e. translation terms are specified in `m[3], m[7], m[11]` elements. +- Leave `defaultMatrixLayoutMode` as default value when creating a Slang session, or specify `SLANG_MATRIX_LAYOUT_ROW_MAJOR`. +- Write `mul(Matrix, Vector)` in shader code to transform `Vector` by `Matrix`. +###Using column-major matrix layout +- Make sure the host code fills in matrices in column-major layout, i.e. translations terms are specified in `m[12], m[13], m[14]` elements. +- Set `defaultMatrixLayoutMode` to `SLANG_MATRIX_LAYOUT_COLUMN_MAJOR` when creating a Slang session. +- Write `mul(Vector, Matrix)` in shader code. + +And that's it! Slang will make sure the remaining details are correctly handled when generating target HLSL/GLSL code.
\ No newline at end of file diff --git a/docs/user-guide/a1-special-topics.md b/docs/user-guide/a1-special-topics.md new file mode 100644 index 000000000..3091621ea --- /dev/null +++ b/docs/user-guide/a1-special-topics.md @@ -0,0 +1,11 @@ +--- +layout: user-guide +--- + +Special Topics +============================ + +This chapter covers several additional topics on using Slang. These topics do not belong to any categories covered in previous chapters, but they address specific issues that developers may frequently encounter. + +In this chapter: +1. [Handling matrix layout differences on different platforms](a1-01-matrix-layout.md)
\ No newline at end of file |