Skip to content

Commit

Permalink
docs(general): Document that draw_sprite_general gradients will not s…
Browse files Browse the repository at this point in the history 
…eamlessly span the whole rectangle

YoYoGames/GameMaker-Bugs#7394
  • Loading branch information
@gurpreetsinghmatharoo
gurpreetsinghmatharoo committed Aug 26, 2024
1 parent 9f0c3ef commit 6c2672b
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 21 deletions.
44 changes: 23 additions & 21 deletions ...ntents/GameMaker_Language/GML_Reference/Drawing/Sprites_And_Tiles/draw_sprite_general.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>draw_sprite_general</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 @@ -17,9 +17,11 @@
<!--<div class="body-scroll" style="top: 150px;">-->
<h1>draw_sprite_general</h1>
<p>This function combines the function <a href="draw_sprite_ext.htm"><span class="inline">draw_sprite_ext()</span></a> with the function <a href="draw_sprite_part.htm"><span class="inline">draw_sprite_part()</span></a>, adding in some additional blending options so that each corner of the final sprite part can be blended with an individual colour.</p>
<p class="note"><b>NOTE</b>: Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. if you do not wish to use WebGL, then you can set the font cache size to try and limit this should it be necessary using the function <span style="font-size:1px;"><a href="../../Asset_Management/Sprites/Sprite_Manipulation/sprite_set_cache_size_ext.htm"><span class="inline">sprite_set_cache_size()</span></a></span>.</p>
<p class="note"><b>NOTE</b>: This function may not work as expected when using skeleton animation sprites, and you may find that the function only draws the first frame of the default pose. You should be using the <span class="inline">draw_skeleton_*</span> functions instead.</p>
<p class="note"><b>NOTE</b>: When drawing with this function, the sprite <a href="../../Asset_Management/Sprites/Sprite_Instance_Variables/sprite_xoffset.htm">x offset</a> and <a href="../../Asset_Management/Sprites/Sprite_Instance_Variables/sprite_yoffset.htm">y offset</a> are ignored and the sprite part will be drawn with the top left corner at the specified x / y position in the room.</p>
<p>Note that applying colours to corners may not look exactly as you expect due to how sprites are drawn. See the following example, where the image on the left is drawn with a different bottom-left colour, and the image on the right is drawn with a different bottom-right colour:</p>
<p><img class="center" src="../../../../assets/Images/Scripting_Reference/GML/Reference/Drawing/draw_sprite_general_quirk.png" />In each image the gradients do not seamlessly span the whole rectangle and instead seem to be split into halves. This is due to a rectangle actually being made up of two triangles, where the corner colours supplied into this function are applied to each vertex of the two triangles (hence 6 vertices at 3 per triangle). This causes the colours between the vertices to be interpolated for each triangle separately.</p>
<p class="note"><b><span data-conref="../../../../assets/snippets/Tag_note.hts"> </span></b> Colour blending is only recommended for the HTML5 target when WebGL is enabled, although you can still set the blending colour if it is not enabled and it will blend the sprite as normal. However all blending in this way creates a duplicate sprite which is then stored in the cache and used when required. This is far from optimal and if you use multiple colour changes it will slow down your games performance unless you activate WebGL. If you do not wish to use WebGL, then you can set the sprite cache size to try and limit this should it be necessary using the function <span style="font-size:1px;"><a href="../../Asset_Management/Sprites/Sprite_Manipulation/sprite_set_cache_size_ext.htm"><span class="inline">sprite_set_cache_size()</span></a></span>.</p>
<p class="note"><b><span data-conref="../../../../assets/snippets/Tag_note.hts"> </span></b> This function may not work as expected when using skeleton animation sprites, and you may find that the function only draws the first frame of the default pose. You should be using the <span class="inline">draw_skeleton_*</span> functions instead.</p>
<p class="note"><b><span data-conref="../../../../assets/snippets/Tag_note.hts"> </span></b> When drawing with this function, the sprite <a href="../../Asset_Management/Sprites/Sprite_Instance_Variables/sprite_xoffset.htm">x offset</a> and <a href="../../Asset_Management/Sprites/Sprite_Instance_Variables/sprite_yoffset.htm">y offset</a> are ignored and the sprite part will be drawn with the top left corner at the specified x / y position in the room.</p>
<p> </p>
<h4>Syntax:</h4>
<p class="code">draw_sprite_general(sprite, subimg, left, top, width, height, x, y, xscale, yscale, rot, c1, c2, c3, c4, alpha);</p>
Expand All @@ -32,82 +34,82 @@ <h4>Syntax:</h4>
</tr>
<tr>
<td>sprite</td>
<td><span data-keyref="Type_Asset_Sprite"><a href="../../../../../The_Asset_Editors/Sprites.htm" target="_blank">Sprite Asset</a></span></td>
<td><span data-keyref="Type_Asset_Sprite"><a href="../../../../The_Asset_Editors/Sprites.htm" target="_blank">Sprite Asset</a></span></td>
<td>The index of the sprite to draw.</td>
</tr>
<tr>
<td>subimg</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The subimg (frame) of the sprite to draw (image_index or -1 correlate to the current frame of animation in the object).</td>
</tr>
<tr>
<td>left</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The x position on the sprite of the top left corner of the area to draw.</td>
</tr>
<tr>
<td>top</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The y position on the sprite of the top left corner of the area to draw.</td>
</tr>
<tr>
<td>width</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The width of the area to draw.</td>
</tr>
<tr>
<td>height</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The height of the area to draw.</td>
</tr>
<tr>
<td>x</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The x coordinate of where to draw the sprite.</td>
</tr>
<tr>
<td>y</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The y coordinate of where to draw the sprite.</td>
</tr>
<tr>
<td>xscale</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The horizontal scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...</td>
</tr>
<tr>
<td>yscale</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The vertical scaling of the sprite, as a multiplier: 1 = normal scaling, 0.5 is half etc...</td>
</tr>
<tr>
<td>rot</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The rotation of the sprite. 0=normal, 90=turned 90 degrees counter-clockwise etc.</td>
</tr>
<tr>
<td>c1</td>
<td><span data-keyref="Type_Constant_Colour"><a href="../../../../../GameMaker_Language/GML_Reference/Drawing/Colour_And_Alpha/Colour_And_Alpha.htm" target="_blank">Colour</a></span></td>
<td><span data-keyref="Type_Constant_Colour"><a href="../Colour_And_Alpha/Colour_And_Alpha.htm" target="_blank">Colour</a></span></td>
<td>The colour with which to blend the top left area of the sprite.</td>
</tr>
<tr>
<td>c2</td>
<td><span data-keyref="Type_Constant_Colour"><a href="../../../../../GameMaker_Language/GML_Reference/Drawing/Colour_And_Alpha/Colour_And_Alpha.htm" target="_blank">Colour</a></span></td>
<td><span data-keyref="Type_Constant_Colour"><a href="../Colour_And_Alpha/Colour_And_Alpha.htm" target="_blank">Colour</a></span></td>
<td>The colour with which to blend the top right area of the sprite.</td>
</tr>
<tr>
<td>c3</td>
<td><span data-keyref="Type_Constant_Colour"><a href="../../../../../GameMaker_Language/GML_Reference/Drawing/Colour_And_Alpha/Colour_And_Alpha.htm" target="_blank">Colour</a></span></td>
<td><span data-keyref="Type_Constant_Colour"><a href="../Colour_And_Alpha/Colour_And_Alpha.htm" target="_blank">Colour</a></span></td>
<td>The colour with which to blend the bottom right area of the sprite.</td>
</tr>
<tr>
<td>c4</td>
<td><span data-keyref="Type_Constant_Colour"><a href="../../../../../GameMaker_Language/GML_Reference/Drawing/Colour_And_Alpha/Colour_And_Alpha.htm" target="_blank">Colour</a></span></td>
<td><span data-keyref="Type_Constant_Colour"><a href="../Colour_And_Alpha/Colour_And_Alpha.htm" target="_blank">Colour</a></span></td>
<td>The colour with which to blend the bottom left area of the sprite.</td>
</tr>
<tr>
<td>alpha</td>
<td><span data-keyref="Type_Real"><a href="../../../../../GameMaker_Language/GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td><span data-keyref="Type_Real"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">Real</a></span></td>
<td>The alpha of the sprite (from 0 to 1 where 0 is transparent and 1 opaque).</td>
</tr>
</tbody>
Expand All @@ -129,7 +131,7 @@ <h4>Example:</h4>
<div style="float:right">Next: <a href="draw_sprite_part.htm">draw_sprite_part</a></div>
</div>
</div>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2023 All Rights Reserved</span></h5>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
</div>
<!-- KEYWORDS
draw_sprite_general
Expand Down
Binary file added .../Images/Scripting_Reference/GML/Reference/Drawing/draw_sprite_general_quirk.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 6c2672b

Please sign in to comment.