Skip to content

Commit

Permalink
docs(feature): Add a new function matrix_inverse() for inverting a ma…
Browse files Browse the repository at this point in the history 
…trix

YoYoGames/GameMaker-Bugs#2960

* Added matrix_inverse() page
* Various other improvements to matrix function pages:
  * Changed the type "Matrix Array" to "Matrix", abstracting away the underlying type (similar to e.g. "Instance", "Surface", etc., which are stored in a "Handle")
  * Data Types: added a note under the "Arrays" section mentioning that matrices are stored in arrays
  * Matrix Functions page:
    * Grouped matrix functions according to their use, updated ToC accordingly
    * Documented that matrices are ordered column-major in arrays
    * Added a line to clarify that lines are the columns instead of the rows when splitting up an assignment over multiple lines
  * matrix_build() page: documented that matrices are ordered column-major in arrays, added note about matrices possibly ending up transposed in the shader
  * matrix_multiply() page: documented order of matrix multiplication on and added a second, copy-pastable example
  * matrix_set() page: listed the functions that can be used to create matrices of the various types, updated code example
  * matrix_get() and matrix_set() page: added proper short descriptions
  * Visual update of matrix function pages
  • Loading branch information
@YYBartT
YYBartT committed Nov 11, 2024
1 parent 84e25c0 commit 502f486
Show file tree
Hide file tree
Showing 18 changed files with 313 additions and 152 deletions.
18 changes: 10 additions & 8 deletions ..._Language/GML_Reference/Cameras_And_Display/Cameras_And_Viewports/camera_get_proj_mat.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>camera_get_proj_mat</title>
<meta name="generator" content="Adobe RoboHelp 2020" />
<meta name="generator" content="Adobe RoboHelp 2022" />
<link rel="stylesheet" href="../../../../assets/css/default.css" type="text/css" />
<script src="../../../../assets/scripts/main_script.js" type="module"></script>
<meta name="rh-authors" content="Mark Alexander" />
Expand All @@ -16,25 +16,27 @@
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1>camera_get_proj_mat</h1>
<p>This function can be used to retrieve the projection matrix. The function returns the matrix array which can then be used in other <a href="../../Maths_And_Numbers/Matrix_Functions/Matrix_Functions.htm">matrix functions</a> or to set the projection matrix of another camera (using <a href="camera_set_proj_mat.htm"><span class="inline">camera_set_proj_mat()</span></a>).</p>
<p>This function can be used to retrieve the projection matrix. The function returns the matrix which can then be used in other <a href="../../Maths_And_Numbers/Matrix_Functions/Matrix_Functions.htm">matrix functions</a> or to set the projection matrix of another camera (using <a href="camera_set_proj_mat.htm"><span class="inline">camera_set_proj_mat()</span></a>).</p>
<p> </p>
<h4>Syntax:</h4>
<p class="code">camera_get_proj_mat(camera_id)</p>
<table>
<tbody>
<tr>
<th>Argument</th><th>Type</th>
<th>Argument</th>
<th>Type</th>
<th>Description</th>
</tr>
</tr>
<tr>
<td>camera_id</td><td><span data-keyref="Type_ID_Camera"></span></td>
<td>camera_id</td>
<td><span data-keyref="Type_ID_Camera"><a href="camera_create.htm" target="_blank">Camera ID</a></span></td>
<td>The unique camera ID value returned when you created the camera</td>
</tr>
</tr>
</tbody>
</table>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_Array_Matrix">Matrix Array</span></p>
<p class="code"><span data-keyref="Type_Array_Matrix"><a href="../../Maths_And_Numbers/Matrix_Functions/Matrix_Functions.htm" target="_blank">Matrix</a></span></p>
<p> </p>
<h4>Example:</h4>
<p class="code">mat = camera_get_proj_mat(camera_view[0]);</p>
Expand All @@ -49,7 +51,7 @@ <h4>Example:</h4>
<div style="float:right">Next: <a href="camera_get_update_script.htm">camera_get_update_script</a></div>
</div>
</div>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2022 All Rights Reserved</span></h5>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
</div>
<!-- KEYWORDS
camera_get_proj_mat
Expand Down
18 changes: 10 additions & 8 deletions ..._Language/GML_Reference/Cameras_And_Display/Cameras_And_Viewports/camera_get_view_mat.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>camera_get_view_mat</title>
<meta name="generator" content="Adobe RoboHelp 2020" />
<meta name="generator" content="Adobe RoboHelp 2022" />
<link rel="stylesheet" href="../../../../assets/css/default.css" type="text/css" />
<script src="../../../../assets/scripts/main_script.js" type="module"></script>
<meta name="rh-authors" content="Mark Alexander" />
Expand All @@ -16,25 +16,27 @@
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1>camera_get_view_mat</h1>
<p>This function can be used to retrieve the view matrix. The function returns the matrix array which can then be used in other <a href="../../Maths_And_Numbers/Matrix_Functions/Matrix_Functions.htm">matrix functions</a> or to set the view matrix of another camera (using <a href="camera_set_view_mat.htm"><span class="inline">camera_set_view_mat()</span></a>). Note that this function is generally for use with cameras created using <a href="camera_create.htm"><span class="inline">camera_create()</span></a>, but it can also be used on those created in the room editor (or with <a href="camera_create_view.htm"><span class="inline">camera_create_view()</span></a>) - in which case the returned matrix will only be valid after the given camera is used in a view port for the first time.</p>
<p>This function can be used to retrieve the view matrix. The function returns the matrix which can then be used in other <a href="../../Maths_And_Numbers/Matrix_Functions/Matrix_Functions.htm">matrix functions</a> or to set the view matrix of another camera (using <a href="camera_set_view_mat.htm"><span class="inline">camera_set_view_mat()</span></a>). Note that this function is generally for use with cameras created using <a href="camera_create.htm"><span class="inline">camera_create()</span></a>, but it can also be used on those created in the room editor (or with <a href="camera_create_view.htm"><span class="inline">camera_create_view()</span></a>) - in which case the returned matrix will only be valid after the given camera is used in a view port for the first time.</p>
<p> </p>
<h4>Syntax:</h4>
<p class="code">camera_get_view_mat(camera_id)</p>
<table>
<tbody>
<tr>
<th>Argument</th><th>Type</th>
<th>Argument</th>
<th>Type</th>
<th>Description</th>
</tr>
</tr>
<tr>
<td>camera_id</td><td><span data-keyref="Type_ID_Camera"></span></td>
<td>camera_id</td>
<td><span data-keyref="Type_ID_Camera"><a href="camera_create.htm" target="_blank">Camera ID</a></span></td>
<td>The unique camera ID value returned when you created the camera</td>
</tr>
</tr>
</tbody>
</table>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_Array_Matrix">Matrix Array</span></p>
<p class="code"><span data-keyref="Type_Array_Matrix"><a href="../../Maths_And_Numbers/Matrix_Functions/Matrix_Functions.htm" target="_blank">Matrix</a></span></p>
<p> </p>
<h4>Example:</h4>
<p class="code">mat = camera_get_view_mat(camera_view[0]);</p>
Expand All @@ -49,7 +51,7 @@ <h4>Example:</h4>
<div style="float:right">Next: <a href="camera_get_proj_mat.htm">camera_get_proj_mat</a></div>
</div>
</div>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2022 All Rights Reserved</span></h5>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
</div>
<!-- KEYWORDS
camera_get_view_mat
Expand Down
58 changes: 38 additions & 20 deletions .../GameMaker_Language/GML_Reference/Maths_And_Numbers/Matrix_Functions/Matrix_Functions.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,33 +17,51 @@
<h1><span data-field="title" data-format="default">Matrix Functions</span></h1>
<p>A matrix is a collection of numbers arranged into a fixed number of rows and columns.</p>
<p>Usually the numbers are real numbers, but that doesn&#39;t always have to be the case. The following image shows in general how a matrix is constructed with four rows and four columns:</p>
<p><img alt="Matrix example image" class="center" height="178" src="../../../../assets/Images/Scripting_Reference/GML/Reference/Maths/Matrix_Example.png" width="309" />The top row is row 1, the leftmost column is column 1, and this matrix is a 4x4 matrix because it has four rows and four columns (other sized matrices can be constructed). In describing matrices, the format is always rows / columns, and each number that makes up a matrix is called an <i>element</i> of the matrix. The elements in a matrix have specific locations, described by their row and column position where the upper left corner of the matrix is row 1 column 1. In the above matrix example, the element at row 1 col 1 is the value &quot;1&quot;. The element at row 2 column 3 is the value &quot;4.8&quot;.</p>
<p class="note"><span data-conref="../../../../assets/snippets/Tag_important.hts"> </span> Matrices do not have their own datatype in <span data-keyref="GameMaker Name">GameMaker</span> and are always stored in <a data-xref="{title}" href="../../../GML_Overview/Arrays.htm">Arrays</a>.</p>
<p><img alt="Matrix example image" class="center" src="../../../../assets/Images/Scripting_Reference/GML/Reference/Maths/Matrix_Example.png" />The top row is row 1, the leftmost column is column 1, and this matrix is a 4x4 matrix because it has four rows and four columns (other sized matrices can be constructed). In describing matrices, the format is always rows / columns, and each number that makes up a matrix is called an <i>element</i> of the matrix. The elements in a matrix have specific locations, described by their row and column position where the upper left corner of the matrix is row 1 column 1. In the above matrix example, the element at row 1 col 1 is the value 1. The element at row 2 column 3 is the value 4.8.</p>
<p>Matrices are very important for many things but are used most in dealing with 3D space, for example they can be used for setting the camera view or for translating or transforming a model.</p>
<p><span data-keyref="GameMaker Name">GameMaker</span> has a number of functions that deal with matrices, including the <span class="inline3_func">matrix_build*</span> functions which create a matrix of a certain type, functions to perform matrix math and the functions <span class="inline3_func"><a data-xref="{title}" href="matrix_get.htm">matrix_get</a></span> and <span class="inline3_func"><a data-xref="{title}" href="matrix_set.htm">matrix_set</a></span> that allow you to get or set the matrix that&#39;s currently used for drawing. Finally, there are the matrix stack functions that can be used, for example, when working with hierarchical transformations (e.g. skeletal animation).</p>
<h3 id="storage">Storage</h3>
<p>Matrices do not have their own datatype in <span data-keyref="GameMaker Name">GameMaker</span> and are always stored in <a data-xref="{title}" href="../../../GML_Overview/Arrays.htm">Arrays</a>.</p>
<div data-conref="../../../../assets/snippets/Note_Matrix_Column_Major.hts"> </div>
<p>Alternatively, you can create a matrix yourself by creating a 16-element array. Note, however, that when splitting the initialisation of the matrix over multiple lines, every line represents a column rather than a row: </p>
<p class="code">the_matrix = <br />
[<br />
    1, 0, 0, 0,    // Col 1<br />
    0, 1, 0, 0,    // Col 2<br />
    0, 0, 1, 0,    // Col 3<br />
    x, y, z, 1     // Col 4<br />
];</p>
<h2 id="func_ref">Function Reference</h2>
<h3 id="func_ref_general">General Matrix Functions</h3>
<p>Matrices are very important for many things but are used most in dealing with 3D space, for example they can be used for setting the camera view or for translating or transforming a model. The following functions exist for dealing with matrices in <span data-keyref="GameMaker Name">GameMaker</span>:</p>
<h3 id="func_ref_modifying_builtin_matrices">Modifying Built-in Matrices</h3>
<ul class="colour">
<li><a href="matrix_get.htm">matrix_get</a></li>
<li><a href="matrix_set.htm">matrix_set</a></li>
<li><a href="matrix_build.htm">matrix_build</a></li>
<li><a href="matrix_multiply.htm">matrix_multiply</a></li>
<li><a href="matrix_build_identity.htm">matrix_build_identity</a></li>
<li><a href="matrix_build_lookat.htm">matrix_build_lookat</a></li>
<li><a href="matrix_build_projection_ortho.htm">matrix_build_projection_ortho</a></li>
<li><a href="matrix_build_projection_perspective.htm">matrix_build_projection_perspective</a></li>
<li><a href="matrix_build_projection_perspective_fov.htm">matrix_build_projection_perspective_fov</a></li>
<li><a href="matrix_transform_vertex.htm">matrix_transform_vertex</a></li>
<li><a data-xref="{title}" href="matrix_get.htm">matrix_get</a></li>
<li><a data-xref="{title}" href="matrix_set.htm">matrix_set</a></li>
</ul>
<h3 id="func_ref_matrix_math">Matrix Math</h3>
<ul class="colour">
<li><a data-xref="{title}" href="matrix_multiply.htm">matrix_multiply</a></li>
<li><a data-xref="{title}" href="matrix_inverse.htm">matrix_inverse</a></li>
<li><a data-xref="{title}" href="matrix_transform_vertex.htm">matrix_transform_vertex</a></li>
</ul>
<h3 id="func_ref_building_matrices">Building Matrices</h3>
<ul class="colour">
<li><a data-xref="{title}" href="matrix_build.htm">matrix_build</a></li>
<li><a data-xref="{title}" href="matrix_build_identity.htm">matrix_build_identity</a></li>
<li><a data-xref="{title}" href="matrix_build_lookat.htm">matrix_build_lookat</a></li>
<li><a data-xref="{title}" href="matrix_build_projection_ortho.htm">matrix_build_projection_ortho</a></li>
<li><a data-xref="{title}" href="matrix_build_projection_perspective.htm">matrix_build_projection_perspective</a></li>
<li><a data-xref="{title}" href="matrix_build_projection_perspective_fov.htm">matrix_build_projection_perspective_fov</a></li>
</ul>
<h3 id="func_ref_stack">Matrix Stack Functions</h3>
<p>The following functions are for using a matrix <strong>stack</strong>, which is similar to a <span data-keyref="Type_ID_DS_Stack"><a href="../../Data_Structures/DS_Stacks/ds_stack_create.htm" target="_blank">DS Stack</a></span>, but designed for use only with matrices. This is a handy way to apply multiple matrix operations (like transforms) one after another when creating a 3D scene.</p>
<div data-conref="../../../../assets/snippets/Note_Matrix_Stack_Size.hts"> </div>
<ul class="colour">
<li><a href="matrix_stack_is_empty.htm">matrix_stack_is_empty</a></li>
<li><a href="matrix_stack_clear.htm">matrix_stack_clear</a></li>
<li><a href="matrix_stack_set.htm">matrix_stack_set</a></li>
<li><a href="matrix_stack_push.htm">matrix_stack_push</a></li>
<li><a href="matrix_stack_pop.htm">matrix_stack_pop</a></li>
<li><a href="matrix_stack_top.htm">matrix_stack_top</a></li>
<li><a data-xref="{title}" href="matrix_stack_is_empty.htm">matrix_stack_is_empty</a></li>
<li><a data-xref="{title}" href="matrix_stack_clear.htm">matrix_stack_clear</a></li>
<li><a data-xref="{title}" href="matrix_stack_set.htm">matrix_stack_set</a></li>
<li><a data-xref="{title}" href="matrix_stack_push.htm">matrix_stack_push</a></li>
<li><a data-xref="{title}" href="matrix_stack_pop.htm">matrix_stack_pop</a></li>
<li><a data-xref="{title}" href="matrix_stack_top.htm">matrix_stack_top</a></li>
</ul>
<p> </p>
<p> </p>
Expand Down
19 changes: 10 additions & 9 deletions ...ents/GameMaker_Language/GML_Reference/Maths_And_Numbers/Matrix_Functions/matrix_build.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,9 @@
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1><span data-field="title" data-format="default">matrix_build</span></h1>
<p>This function can be used to create your own custom matrix and will return a matrix array, which should be stored in a variable for future reference and use. It accepts 3-dimensional (<span class="inline2">x, y, z</span>) translation, rotation and scale values, and uses them to build a matrix array.</p>
<p>The matrix array contains 16 values in total, where the initial 4 elements are <em><strong>row/column 1</strong></em>, the next 4 elements are <em><strong>row/column 2</strong></em> and so on, as part of a <a href="Matrix_Functions.htm">4x4 matrix</a>. Whether the array is ordered by rows or columns depends on the target platform, as the graphics renderer used by a platform may use row-major or column-major matrices.</p>
<p>This function creates a custom transformation matrix from 3-dimensional (<span class="inline2">x, y, z</span>) translation, rotation and scale values and returns it.</p>
<div data-conref="../../../../assets/snippets/Note_Matrix_Column_Major.hts"> </div>
<p class="note"><span data-conref="../../../../assets/snippets/Tag_note.hts"> </span> When you set this matrix in a shader using <span class="inline3_func"><a data-xref="{title}" href="../../Asset_Management/Shaders/shader_set_uniform_f_array.htm">shader_set_uniform_f_array</a></span>, <span class="inline3_func"><a data-xref="{title}" href="../../Asset_Management/Shaders/shader_set_uniform_matrix.htm">shader_set_uniform_matrix</a></span> or <span class="inline3_func"><a data-xref="{title}" href="../../Asset_Management/Shaders/shader_set_uniform_matrix_array.htm">shader_set_uniform_matrix_array</a></span>, depending on the shader type and the target platform, you may receive the matrix transposed in the shader.</p>
<p class="note"><span data-conref="../../../../assets/snippets/Tag_note.hts"> </span> When you build a new matrix in this way, the order of operation is YXZ.</p>
<p> </p>
<h4>Syntax:</h4>
Expand Down Expand Up @@ -47,17 +48,17 @@ <h4>Syntax:</h4>
<tr>
<td>xrotation</td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The angle to rotate around the x-axis (in degrees °).</td>
<td>The angle to rotate around the x-axis (in degrees).</td>
</tr>
<tr>
<td>yrotation</td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The angle to rotate around the y-axis (in degrees °).</td>
<td>The angle to rotate around the y-axis (in degrees).</td>
</tr>
<tr>
<td>zrotation</td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The angle to rotate around the z-axis (in degrees °).</td>
<td>The angle to rotate around the z-axis (in degrees).</td>
</tr>
<tr>
<td>xscale</td>
Expand All @@ -78,18 +79,18 @@ <h4>Syntax:</h4>
</table>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_Array_Matrix"><a href="Matrix_Functions.htm" target="_blank">Matrix Array</a></span></p>
<p class="code"><span data-keyref="Type_Array_Matrix"><a href="Matrix_Functions.htm" target="_blank">Matrix</a></span></p>
<p> </p>
<h4>Example:</h4>
<p class="code">t_matrix = matrix_build(x, y, 0, 0, 90, 0, 1, 2, 1);</p>
<p>The above code will build a new matrix transform and store the resulting matrix index in a variable <span class="inline2">t_matrix</span>.</p>
<p class="code">t_matrix = <span data-field="title" data-format="default">matrix_build</span>(x, y, 0, 0, 90, 0, 1, 2, 1);</p>
<p>The above code builds a new matrix transform and stores the resulting matrix index in a variable <span class="inline2">t_matrix</span>.</p>
<p> </p>
<p> </p>
<div class="footer">
<div class="buttons">
<div class="clear">
<div style="float:left">Back: <a data-xref="{title}" href="Matrix_Functions.htm">Matrix Functions</a></div>
<div style="float:right">Next: <a data-xref="{title}" href="matrix_multiply.htm">matrix_multiply</a></div>
<div style="float:right">Next: <a data-xref="{title}" href="matrix_build_identity.htm">matrix_build_identity</a></div>
</div>
</div>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
Expand Down
4 changes: 2 additions & 2 deletions ...Maker_Language/GML_Reference/Maths_And_Numbers/Matrix_Functions/matrix_build_identity.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,10 @@ <h4>Syntax:</h4>
<p class="code"><span data-field="title" data-format="default">matrix_build_identity</span>();</p>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_Array_Matrix"><a href="Matrix_Functions.htm" target="_blank">Matrix Array</a></span></p>
<p class="code"><span data-keyref="Type_Array_Matrix"><a href="Matrix_Functions.htm" target="_blank">Matrix</a></span></p>
<p> </p>
<h4>Example:</h4>
<p class="code">i_matrix = matrix_build_identity();</p>
<p class="code">i_matrix = <span data-field="title" data-format="default">matrix_build_identity</span>();</p>
<p>The above code will create an identity matrix and store its index in a variable for future use.</p>
<p> </p>
<p> </p>
Expand Down
Loading

0 comments on commit 502f486

Please sign in to comment.