Skip to content

Commit

Permalink
Merge pull request #33 from YoYoGames/develop.bart
Browse files Browse the repository at this point in the history 
Various additions and bugfixes in the manual
  • Loading branch information
@gurpreetsinghmatharoo
gurpreetsinghmatharoo authored Oct 16, 2023
2 parents 5ee20f6 + c78c84b commit 1fe241f
Show file tree
Hide file tree
Showing 39 changed files with 2,303 additions and 314 deletions.
27 changes: 14 additions & 13 deletions Manual/contents/Additional_Information/Guide_To_Primitives_And_Vertex_Building.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>Guide To Primitives And Vertex Building</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,13 +16,15 @@
<!--<div class="body-scroll" style="top: 150px;">-->
<h1><span data-field="title" data-format="default">Guide To Primitives And Vertex Building</span></h1>
<p>This guide briefly covers how to build and use <a href="../GameMaker_Language/GML_Reference/Drawing/Primitives/Primitives_And_Vertex_Formats.htm">primitives</a> using custom <strong>vertex formats</strong> and <strong>vertex buffers</strong>. </p>
<p>In general when you start working with 3D, special effects, complex drawing processes or shaders you don&#39;t need to worry too much about the vertex format being used, since <span data-keyref="GameMaker Name">GameMaker</span> will automatically set up and pass through the <a class="glossterm" data-glossterm="vertex" href="#">vertex</a> data for you. However, sometimes it is necessary to create your own vertex data and format it to suit, especially when you need to boost speed, or wish to pass in extra information. For example the standard vertex format includes an x, y, z 3D position, colour (with alpha), and UV texture coordinates, which, if you were creating it yourself, would look something like:</p>
<p>In general when you start working with 3D, special effects, complex drawing processes or shaders you don&#39;t need to worry too much about the vertex format being used, since <span data-keyref="GameMaker Name">GameMaker</span> will automatically set up and pass through the <a class="glossterm" data-glossterm="vertex" href="#">vertex</a> data for you. However, sometimes it is necessary to create your own vertex data and format it to suit, especially when you need to boost speed, or wish to pass in extra information. For example the standard vertex format includes an x, y, z 3D position, colour (with alpha), and UV texture coordinates, which, if you were creating it yourself, would look something like this: </p>
<h4 id="passthrough_vertex_format">Passthrough Vertex Format:</h4>
<p class="code">vertex_format_begin();<br />
vertex_format_add_position_3d();<br />
vertex_format_add_colour();<br />
vertex_format_add_texcoord();<br />
my_format = vertex_format_end();</p>
<p>However, if you are only using (for example) a shader to manipulate the position of the vertex, then there would be no need to pass through colour or texture data. In this case you would create your own format as so:</p>
<p>However, if you are only using (for example) a shader to manipulate the position of the vertex, then there would be no need to pass through colour or texture data. In this case you would create your own format as follows: </p>
<h4>Custom Vertex Format:</h4>
<p class="code">vertex_format_begin();<br />
vertex_format_add_position_3d();<br />
my_format = vertex_format_end();</p>
Expand All @@ -38,8 +40,8 @@ <h1><span data-field="title" data-format="default">Guide To Primitives And Verte
<p>You should note that once you have created your vertex format, the order in which you have defined the vertex attributes <i>must be honoured</i> when building your <strong>primitives</strong>. So, if you have defined a vertex format as position, colour, and texture coordinate, then <b>you <i>must</i> add these attributes to the primitive in the same order otherwise you will get an error</b>. Also note that like any other dynamic resource, a vertex format requires memory and therefore should be removed when not needed using the function <span class="inline3_func"><a data-xref="{title}" href="../GameMaker_Language/GML_Reference/Drawing/Primitives/vertex_format_delete.htm">vertex_format_delete</a></span>.</p>
<p>Any primitives that you build are held in a <b>vertex buffer</b>. This must be created beforehand and then referenced by the functions that are used to build your primitive. The vertex buffer can be reused as many times as necessary to create different primitives, or it can be &quot;frozen&quot; to maintain a specific primitive type for the duration of your game or level (which is the fastest approach, so if you know that a primitive you build will not change then you should always use this option).</p>
<p>An example of a single triangle primitive being built is shown in the following code:</p>
<p class="code">// CREATE EVENT<br />
v_buff = vertex_create_buffer();<br />
<p class="code_heading">Create Event</p>
<p class="code">v_buff = vertex_create_buffer();<br />
vertex_begin(v_buff, global.my_format);<br />
vertex_position(v_buff, 10, 10);<br />
vertex_colour(v_buff, c_white, 1);<br />
Expand All @@ -50,20 +52,19 @@ <h1><span data-field="title" data-format="default">Guide To Primitives And Verte
vertex_position(v_buff, 110, 110);<br />
vertex_colour(v_buff, c_white, 1);<br />
vertex_texcoord(v_buff, 1, 1);<br />
vertex_end(v_buff);<br />
<br />
// DRAW EVENT<br />
vertex_end(v_buff);</p>
<p class="code_heading">Draw Event</p>
<p class="code"><br />
var tex = sprite_get_texture(spr_Background, 0);<br />
shader_set(shd_shimmer);<br />
vertex_submit(v_buff, pr_trianglelist, tex);<br />
shader_reset();
</p>
shader_reset();</p>
<p>Here we have first created our vertex buffer in the Create Event of the instance, then we begin the definition of the different vertices that make up our triangle primitive, giving the position, the colour, and the texture UV coordinate for each of the three points that we want to use. We then end the vertex definition, and we know that the vertex buffer with this vertex data is stored in the variable &quot;v_buff&quot;.  </p>
<p class="note"><span data-conref="../assets/snippets/Tag_note.hts"> </span> If the contents of the buffer are going to be updated constantly, the buffer would be created, given the vertex data, and then be destroyed again - after it&#39;s been drawn - all in the same step.</p>
<p>We then draw the contents of the vertex buffer in the Draw Event using a shader. This is a very simple example, and is basically how <span data-keyref="GameMaker Name">GameMaker</span> works internally, ie: When you draw a sprite, <span data-keyref="GameMaker Name">GameMaker</span> creates a vertex buffer with four vertices creating two triangles (which make a square, also called a &quot;quad&quot;), and textures these two triangles with the sprite image. When we draw this sprite, we are submitting the vertex buffer and its contents are drawn to the screen.</p>
<p>We then draw the contents of the vertex buffer in the Draw Event using a shader. This is a very simple example, and is basically how <span data-keyref="GameMaker Name">GameMaker</span> works internally, i.e.: When you draw a sprite, <span data-keyref="GameMaker Name">GameMaker</span> creates a vertex buffer with four vertices creating two triangles (which make a square, also called a &quot;quad&quot;), and textures these two triangles with the sprite image. When we draw this sprite, we are submitting the vertex buffer and its contents are drawn to the screen.</p>
<p>You&#39;ll notice when we submit the vertex buffer for drawing, we supply a primitive type. The type of primitive you use can be a point, a line list or strip, or a triangle list or strip, but you are <i>not</i> permitted triangle fans since most mobile hardware will not accept that primitive type. Don&#39;t forget to format your vertex buffer correctly for the type of primitive that is going to be used to draw it. For example, drawing a two triangle primitive as a triangle list requires 6 points, but as a triangle strip it only requires 4 points. Which type you use is up to you and will depend on what you are wanting to draw and the effect that you want to achieve.</p>
<p>One final important point to note when using your own vertex buffers in this way is how it affects the vertex batches that are sent to the GPU. When you create a vertex buffer you are creating the lowest level of graphics data, so when you draw all that happens is that <span data-keyref="GameMaker Name">GameMaker</span> sends your buffer directly to the graphics card. Because of this, if you want better batching, you must work it out yourself and store the things you want to batch inside the same buffer.</p>
<p>As we have already mentioned above, vertex formats are built up by using together the following 5 attribute types (added via the appropriate <span class="inline">vertex_format_add_*</span> function):</p>
<p>As we have already mentioned above, vertex formats are built up by using together the following 5 attribute types (added via the appropriate <span class="inline3_func">vertex_format_add_*</span> function):</p>
<ul class="colour">
<li>Colour</li>
<li>Normal</li>
Expand Down Expand Up @@ -110,7 +111,7 @@ <h1><span data-field="title" data-format="default">Guide To Primitives And Verte
attribute vec4 in_Colour1;       // (r,g,b,a)<br />
attribute vec2 in_TextureCoord;  // (u,v)</p>
<p>In this case <span class="inline">in_Colour0</span> maps to the first <span class="inline">vertex_format_add_colour()</span> and <span class="inline">in_Colour1</span> maps to the second.</p>
<p>Texture coordinates are handled slightly differently to colour. Basically, anything which isn&#39;t called <span class="inline">in_Position</span>, <span class="inline">in_Normal</span> or one of the <span class="inline">in_Colour[0 ... ]</span> attributes is treated as a texture coordinate. The order they are defined in, in the list of attributes in the shader, is what denotes which attribute in the vertex format they map to. See the following GML example:</p>
<p>Texture coordinates are handled slightly differently to colour. Basically, anything which isn&#39;t called <span class="inline">in_Position</span>, <span class="inline">in_Normal</span> or one of the <span class="inline">in_Colour[0 ... ]</span> attributes is treated as a texture coordinate. The order they are defined in, in the list of attributes in the shader, is what denotes which attribute in the vertex format they map to. See the following <span data-keyref="GML_Code">GML Code</span> example:</p>
<p class="code">vertex_format_begin();<br />
vertex_format_add_position_3d();<br />
vertex_format_add_colour();<br />
Expand Down
4 changes: 2 additions & 2 deletions Manual/contents/Additional_Information/Guide_To_Using_Buffers.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>Guide To Using Buffers</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 @@ -24,7 +24,7 @@ <h1><span data-field="title" data-format="default">Guide To Using Buffers</span>
<tbody>
<tr>
<th>Constant</th>
<th>description</th>
<th>Description</th>
</tr>
<tr>
<td><span class="inline">buffer_fixed</span></td>
Expand Down
46 changes: 22 additions & 24 deletions Manual/contents/GameMaker_Language/GML_Overview/Variables/Instance_Variables.htm
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,30 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Instance Variables</title>
<meta name="generator" content="Adobe RoboHelp 2020"/>
<link rel="stylesheet" href="../../../assets/css/default.css" type="text/css"/>
<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"/>
<meta name="topic-comment" content="Page explaining instance variables"/>
<meta name="rh-index-keywords" content="Instance Variables"/>
<meta name="search-keywords" content="instance variables"/>
<meta name="rh-authors" content="Mark Alexander" />
<meta name="topic-comment" content="Page explaining instance variables" />
<meta name="rh-index-keywords" content="Instance Variables" />
<meta name="search-keywords" content="instance variables" />
</head>
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1>Instance Variables</h1>
<p>An <strong>instance </strong>variable is created within an instance of an object and is considered unique to that instance - ie: many instances of the same object can have the same variable, but each variable can hold a different value as they are <em>unique </em>to
each instance. But <i>how</i> is an instance variable created? Well, you create new variables by simply assigning a value to them as shown in this small example (this is called <em>declaring</em> the variable):</p>
<p class="code">potions = 12;<br/> life = 100;<br/> name = &quot;Jock MacSweeney&quot;;<br/> strength = 5.5;<br/> armour = -2;</p>
<p>As you can see you just have to give the name and then a value (the value can be any <a href="../Data_Types.htm">data type</a>) to set that variable and have it ready for use within an instance of the object you are coding for (note that the value can
come from the return value of a function or the result of an operation between other variables, etc...). These variables can then be used and modified in a number of ways from within the instance, for example this code could be in a collision event
and used to take an amount off of the variable &quot;<span class="inline">life</span>&quot;:</p>
<h1><span data-field="title" data-format="default">Instance Variables</span></h1>
<p>An <strong>instance </strong>variable is created within an instance of an object and is considered unique to that instance - i.e.: many instances of the same object can have the same variable, but each variable can hold a different value as they are <em>unique </em>to each instance. But <i>how</i> is an instance variable created? Well, you create new variables by simply assigning a value to them as shown in this small example (this is called <em>declaring</em> the variable):</p>
<p class="code">potions = 12;<br />
life = 100;<br />
name = &quot;Jock MacSweeney&quot;;<br />
strength = 5.5;<br />
armour = -2;</p>
<p>As you can see you just have to give the name and then a value (the value can be any <a href="../Data_Types.htm">data type</a>) to set that variable and have it ready for use within an instance of the object you are coding for (note that the value can come from the return value of a function or the result of an operation between other variables, etc.). These variables can then be used and modified in a number of ways from within the instance, for example this code could be in a collision event and used to take an amount off of the variable &quot;<span class="inline">life</span>&quot;:</p>
<p class="code">life -= 5 + armour;</p>
<p>If &quot;<span class="inline">life</span>&quot; is at 100 it will now have a value of 97 (100 - (5 + -2) = 97). Now, that&#39;s a simple example, and you <i>could</i> replace &quot;<span class="inline">armour</span>&quot; for the actual value of -2,
but what happens if that value is <a class="glossterm" data-glossterm="hard-coded" href="#">hard-coded</a> in multiple places and then you decide to change it? You would have to go through ALL your code and change every -2 to whatever the new value
is, which is time consuming and very error prone! But if you use a variable, all you have to do is reassign it a new value and the code will automatically use that new value from then onwards, making things far more flexible and far easier to fix
should there be a problem. It should also be noted that even if a value is not going to change it is far easier to remember what a variable called &quot;<span class="inline">life</span>&quot; means rather than just looking at a number.</p>
<p><span data-keyref="GameMaker Name">GameMaker</span> has a collection of &quot;built in&quot; instance variables too, so you should be aware of them as you may name one of your own instance variables the same or wish to have your own global variable with the same name and wonder why
you are getting errors. They are easy to spot, however, as they are shown in a different colour in the code editor and also come up in auto-complete and are shown in bar at the bottom of the <a href="../../../The_Asset_Editors/Scripts.htm">code editor</a>.</p>
<p>If &quot;<span class="inline">life</span>&quot; is at 100 it will now have a value of 97 (100 - (5 + -2) = 97). Now, that&#39;s a simple example, and you <i>could</i> replace &quot;<span class="inline">armour</span>&quot; for the actual value of -2, but what happens if that value is <a class="glossterm" data-glossterm="hard-coded" href="#">hard-coded</a> in multiple places and then you decide to change it? You would have to go through ALL your code and change every -2 to whatever the new value is, which is time consuming and very error prone! But if you use a variable, all you have to do is reassign it a new value and the code will automatically use that new value from then onwards, making things far more flexible and far easier to fix should there be a problem. It should also be noted that even if a value is not going to change it is far easier to remember what a variable called &quot;<span class="inline">life</span>&quot; means rather than just looking at a number.</p>
<p><span data-keyref="GameMaker Name">GameMaker</span> has a collection of &quot;built in&quot; instance variables too, so you should be aware of them as you may name one of your own instance variables the same or wish to have your own global variable with the same name and wonder why you are getting errors. They are easy to spot, however, as they are shown in a different colour in the code editor and also come up in auto-complete and are shown in bar at the bottom of the <a href="../../../The_Asset_Editors/Scripts.htm">code editor</a>.</p>
<p>There are quite a few <a href="../Runtime_Functions.htm">runtime functions</a> designed to help you when dealing with instance variables, which are all listed in the following section:</p>
<ul class="colour">
<li><a href="../../GML_Reference/Variable_Functions/Variable_Functions.htm">Variable Functions</a></li>
Expand All @@ -41,13 +39,13 @@ <h1>Instance Variables</h1>
<div style="float:right">Next: <a href="Global_Variables.htm">Global Variables</a></div>
</div>
</div>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2021 All Rights Reserved</span></h5>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2023 All Rights Reserved</span></h5>
</div>
<!-- KEYWORDS
instance variables
-->
<!-- TAGS
instance_variables
-->

</body></html>
</body>
</html>
Loading

0 comments on commit 1fe241f

Please sign in to comment.