From efc00c7912a7f1054e10f7dcf821a2284a12b7e0 Mon Sep 17 00:00:00 2001 From: YYBartT Date: Fri, 6 Dec 2024 13:28:58 +0100 Subject: [PATCH 01/15] docs(general): "Clear Display Buffer" is not working YoYoGames/GameMaker-Bugs#7456 Small changes to window_get_colour() & window_set_colour() manual pages --- .../The_Game_Window/window_get_colour.htm | 22 ++++++------ .../The_Game_Window/window_set_colour.htm | 34 ++++++++++--------- 2 files changed, 29 insertions(+), 27 deletions(-) diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Cameras_And_Display/The_Game_Window/window_get_colour.htm b/Manual/contents/GameMaker_Language/GML_Reference/Cameras_And_Display/The_Game_Window/window_get_colour.htm index 1004f516e..1d3a429bb 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Cameras_And_Display/The_Game_Window/window_get_colour.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Cameras_And_Display/The_Game_Window/window_get_colour.htm @@ -4,7 +4,7 @@ window_get_colour - + @@ -15,33 +15,33 @@ -

window_get_colour

-

This function returns the background colour of the game window. This colour represents that which will be used for those areas of the game window that are not occupied by any views. The following image illustrates this:

-

Windfow colour illustrationThe above image has two views with two view ports, each one drawn at different positions. This stretches the game window to accommodate both ports and uses the window colour to colour the background where no view is shown.

+

window_get_colour

+

This function returns the background colour of the game window.

+

This colour represents that which will be used for those areas of the game window that are not occupied by any views. The following image illustrates this:

+

Windfow colour illustrationThe above image has two views with two view ports, each one drawn at a different position. This stretches the game window to accommodate both ports and uses the window colour to colour the background where no view is shown.

 

Syntax:

-

window_get_colour();

+

window_get_colour();

 

Returns:

-

Colour Constant

+

Colour

 

Example:

-

if (window_get_colour() != c_black)
+

if (window_get_colour() != c_black)
{
    window_set_colour(c_black);
}

The above code will check the window colour to see if it is set as black or not, and if it is not it sets it to black.

 

 

-

 

-
Back: The Game Window
-
Next: window_get_fullscreen
+
Back: The Game Window
+
Next: window_get_fullscreen
-
© Copyright YoYo Games Ltd. 2022 All Rights Reserved
+
© Copyright YoYo Games Ltd. 2024 All Rights Reserved
-

window_set_colour

-

This function can set the background colour of the game window. This colour represents that which will be used for those areas of the game window that are not occupied by any views. The following image illustrates this:

-

Window colour exampleThe above image has two views with two view ports, each one drawn at different positions. This stretches the game window to accommodate both ports and uses the window colour to colour the background where no view is shown.

+

window_set_colour

+

This function sets the background colour of the game window.

+

This colour represents that which will be used for those areas of the game window that are not occupied by any views. The following image illustrates this:

+

Window colour exampleThe above image has two views with two view ports, each one drawn at a different position. This stretches the game window to accommodate both ports and uses the window colour to colour the background where no view is shown.

 

Syntax:

-

window_set_colour(colour);

+

window_set_colour(colour);

- + + - + - + + - +
ArgumentTypeArgumentType Description
colourcolourColour The colour to set the region.

 

Returns:

-

+

N/A

 

Example:

-

if (window_get_colour() != c_black)
+

if (window_get_colour() != c_black)
{
-     window_set_colour(c_black);
+     window_set_colour(c_black);
}

The above code will check the window colour to see if it is set as black or not, and if it is not it sets it to black.

 

 

-

 

-
Back: The Game Window
-
Next: window_set_fullscreen
+
Back: The Game Window
+
Next: window_set_fullscreen
-
© Copyright YoYo Games Ltd. 2021 All Rights Reserved
+
© Copyright YoYo Games Ltd. 2024 All Rights Reserved
+ + + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Debugging/debug_input_record.htm b/Manual/contents/GameMaker_Language/GML_Reference/Debugging/debug_input_record.htm new file mode 100644 index 000000000..a40f3c230 --- /dev/null +++ b/Manual/contents/GameMaker_Language/GML_Reference/Debugging/debug_input_record.htm @@ -0,0 +1,94 @@ + + + + + + debug_input_record + + + + + + + + + + +

debug_input_record

+

This function starts recording various types of input.

+

The types of input that you want to include are specified as a bitmask that can be a combination of the following constants: 

+ + + + + + + + + + + + + + + + + + + + + + + + +
Debug Input Filter Constant
ConstantDescription
debug_input_filter_keyboardInclude keyboard input
debug_input_filter_mouseInclude mouse input
debug_input_filter_touchInclude touch input
+

If you want to record, for example, keyboard and mouse input the value would be debug_input_filter_keyboard|debug_input_filter_mouse.

+
+

 

+

Syntax:

+

debug_input_record(filter);

+ + + + + + + + + + + + + + + + + + +
ArgumentTypeDescription
filterDebug Input Filter ConstantA bitmask combining the different types of input to record
+

 

+

Returns:

+

N/A

+

 

+

Example:

+

debug_input_record(debug_input_filter_keyboard|debug_input_filter_mouse);

+

The above code starts recording both keyboard and mouse input, which can be saved to a file using debug_input_save.

+

 

+

 

+
+
+
+
Back: Debugging
+
Next: debug_input_save
+
+
+
© Copyright YoYo Games Ltd. 2024 All Rights Reserved
+
+ + + + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Debugging/debug_input_save.htm b/Manual/contents/GameMaker_Language/GML_Reference/Debugging/debug_input_save.htm new file mode 100644 index 000000000..8f41a7925 --- /dev/null +++ b/Manual/contents/GameMaker_Language/GML_Reference/Debugging/debug_input_save.htm @@ -0,0 +1,69 @@ + + + + + + debug_input_save + + + + + + + + + + +

debug_input_save

+

This function stops recording input and saves it to the given file for later playback.

+

Recording of input must have previously been started with a call to debug_input_record.

+

 If you call this function in, e.g., a key press event this event will also be recorded (as the key press has already occurred at the time this function is called).

+
+

 

+

Syntax:

+

debug_input_save(filename);

+ + + + + + + + + + + + + + + + + + +
ArgumentTypeDescription
filenameStringThe path to the file to save the recorded input to
+

 

+

Returns:

+

N/A

+

 

+

Example:

+

debug_input_save("input.data");

+

The above code saves recorded debug input to a file named "input.data".

+

 

+

 

+
+
+
+
Back: Debugging
+
Next: debug_input_playback
+
+
+
© Copyright YoYo Games Ltd. 2024 All Rights Reserved
+
+ + + + \ No newline at end of file diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Debugging/fps_real.htm b/Manual/contents/GameMaker_Language/GML_Reference/Debugging/fps_real.htm index 98093f092..cf47e6245 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Debugging/fps_real.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Debugging/fps_real.htm @@ -20,28 +20,27 @@

fps_real

On the HTML5 target, this variable will instead return a multiple of the monitor refresh rate as GameMaker has to rely on the browser for timing and dispatch.

 

Syntax:

-

fps_real

+

fps_real

 

Returns:

-

Real

+

Real

 

Example:

-

if (debug_mode)
+

if (debug_mode)
{
    draw_text(32, 32, "FPS = " + string(fps_real));
}

The above code will check to see if the game is in debug mode and if it is it will display the current real fps on the screen.

 

 

-

 

-
Back: Debugging
-
Next: debug_mode
+
Back: Debugging
+
Next: debug_input_record
-
© Copyright YoYo Games Ltd. 2023 All Rights Reserved
+
© Copyright YoYo Games Ltd. 2024 All Rights Reserved
-

window_mouse_get_y

+

window_mouse_get_y

With this function you can get the y position of the mouse cursor (in pixels) within the browser if it is an HTML5 game or within the display if it is a Windows, Ubuntu (Linux) or macOS game.

 

Syntax:

-

window_mouse_get_y();

+

window_mouse_get_y();

 

Returns:

-

Real

+

Real

 

Example:

-

wy = window_mouse_get_y();

-

The above code stores the current y axis window position of the mouse in the variable "wy".

+

wy = window_mouse_get_y();

+

The above code stores the current y axis window position of the mouse in the variable wy.

 

 

-
Back: The Game Window
-
Next: window_mouse_get_delta_x
+
Back: The Game Window
+
Next: window_mouse_get_delta_x
-
© Copyright YoYo Games Ltd. 2023 All Rights Reserved
+
© Copyright YoYo Games Ltd. 2024 All Rights Reserved
-

Ini Files

-

INI files are small, lightweight files which are compatible with most platforms. They are ideal for storing small pieces of information, like interface preferences, local high scores, level data etc... and as such are a great and easy way for you to start saving information from your games. If you are looking for more advanced ways to save information to files, you may wish to look at some of the other file functions like Text Files, Binary Files and Buffers.

-

 All GameMaker projects have a file called "options.ini", so you cannot name any file with that name (you will get a uid failure when you try to compile your game project).

-

The following functions exist for ini files:

+

INI Files

+

INI files are small, lightweight files which are compatible with most platforms. They are ideal for storing small pieces of information, like interface preferences, local high scores, level data, etc., and as such are a great and easy way for you to start saving information from your games. If you are looking for more advanced ways to save information to files, you may wish to look at some of the other file functions like Text Files, Binary Files and Buffers.

+

 All GameMaker projects have a file called "options.ini", so you cannot name any file with that name (you will get a UID failure when you try to compile your game project).

+

Function Reference

+

Opening & Closing

+ +

Reading & Writing

 

 

-

 

-
Back: File Handling
-
Next: Text Files
+
Back: File Handling
+
Next: Text Files
© Copyright YoYo Games Ltd. 2024 All Rights Reserved
diff --git a/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_close.htm b/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_close.htm index 1d47026ed..6d4e98bd5 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_close.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_close.htm @@ -4,7 +4,7 @@ ini_close - + @@ -14,32 +14,32 @@ -

ini_close

-

This function should be called the moment you are finished reading or writing to any open ini file. If you do not use the function after you have used any of the ini write functions, then nothing will be written to disk, as the file information is held in memory until this function is called, which forces the write. If you try to open an ini without having previously closed another one (or the same one) you will get an error too.

-

The function will also return a string with the ini file encoded into it. This string can then be saved to a server and/or used again along with the function ini_open_from_string() to re-create the ini.

+

ini_close

+

This function should be called the moment you are finished reading from or writing to any open INI file.

+

If you do not use the function after you have used any of the INI write functions, then nothing will be written to disk, as the file information is held in memory until this function is called, which forces the write. Note that, even if you don't call this function, a  next call to ini_open will close the currently open INI file.

+

The function will also return a string with the INI file encoded into it. This string can then be saved to a server and/or used again along with the function ini_open_from_string to re-create the INI.

 

Syntax:

-

ini_close();

+

ini_close();

 

Returns:

-

String

+

String

 

Example:

ini_open("savedata.ini");
score = ini_read_real("save1", "score", 0);
ini_close();

-

This will open "savedata.ini" and read a value from the section "save1" with the key "score", then close the ini file. If there is no value under "save1" called "score" or there is no "savedata.ini" file present, 0 will be returned and a new ini file created.

-

 

+

This will open "savedata.ini" and read a value from the section "save1" with the key "score", then close the INI file. If there is no value under "save1" called "score" or there is no "savedata.ini" file present, 0 will be returned and a new INI file created.

 

 

-
Back: Ini Files
- +
Back: INI Files
+
-
© Copyright YoYo Games Ltd. 2022 All Rights Reserved
+
© Copyright YoYo Games Ltd. 2024 All Rights Reserved
-

ini_open

-

This opens an ini file for reading and/writing. If the ini file does not exist at the location you are checking, GameMaker may create one, but only if you write data to it. If you have only read information from the ini file, then the default values for the read function will be returned, but the ini file will not actually be created.

-

Please note that you can only have one ini file open at any one time and remember to use ini_close() once you're finished reading/writing from the .ini file as the information is not actually stored to disk until then (it is also stored in memory until the file is closed).

+

ini_open

+

This function opens a new INI file for reading/writing, closing the currently open INI file, if there is any.

+

If no INI file with the given name exists at the location you are checking, GameMaker may create it, but only if you write data to it. If you have only read information from the INI file, then the default values for the read function will be returned, but the INI file will not actually be created.

+

You can only have one INI file open at any one time and remember to use ini_close once you're finished reading from/writing to the INI file as the information is not actually saved to disk until then (it is also stored in memory until the file is closed). Note, however, that calling ini_open with an INI file still open will close that file.

 

Syntax:

-

ini_open(name);

+

ini_open(name);

@@ -31,7 +32,7 @@

Syntax:

- +
name StringThe filename for the .ini file.The filename for the INI file
@@ -43,15 +44,14 @@

Example:

ini_open("Settings/savedata.ini");
score = ini_read_real("save1", "score", 0);
ini_close();

-

This will open 'savedata.ini' and read the score value under the section "save1" with the key "score" in it, then close the .ini again. Should there be no value under "save1", "score" or there is no "savedata.ini" file present, score will be set to 0 (the default value). Note that the ini file has been placed in the sub-directory "Settings", which is the folder that holds the ini file in the Asset Browser included files.

-

 

+

This will open "savedata.ini" and read the score value under the section "save1" with the key "score" in it, then close the INI again. Should there be no value under "save1", "score" or there is no "savedata.ini" file present, score will be set to 0 (the default value). Note that the INI file has been placed in the sub-directory "Settings", which is the folder that holds the INI file in the Asset Browser included files.

 

 

-
Back: Ini Files
-
Next: ini_close
+
Back: Ini Files
+
© Copyright YoYo Games Ltd. 2024 All Rights Reserved
diff --git a/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_open_from_string.htm b/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_open_from_string.htm index c0356ce3e..0a270333a 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_open_from_string.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_open_from_string.htm @@ -4,7 +4,7 @@ ini_open_from_string - + @@ -15,21 +15,24 @@ -

ini_open_from_string

-

This function will create a temporary ini file from a string and open it for reading/writing. The string should be correctly formatted as an ini file (ie: with sections, line breaks keys and values) otherwise the ini file will not be created correctly. Note that this ini file is temporary and will be removed from memory the moment it is closed, losing any information that was stored in it, however the ini_close() function returns a string of the full ini file which can then be saved to a server or to disk.

+

ini_open_from_string

+

This function creates a temporary INI file from a string and opens it for reading/writing. The string should be correctly formatted as an INI file (i.e.: with sections, line breaks, keys and values), otherwise the INI file will not be created correctly.

+

Note that this INI file is temporary and will be removed from memory the moment it is closed, losing any information that was stored in it, however the ini_close function returns a string of the full INI file which can then be saved to a server or to disk.

 

Syntax:

-

ini_open_from_string(string);

+

ini_open_from_string(string);

- + + - + - - - + + + +
ArgumentTypeArgumentType Description
stringThe string containing all the ini information.
stringStringThe string containing all the INI information

 

@@ -37,21 +40,20 @@

Returns:

N/A

 

Example:

-

ini_open_from_string(str)
+

ini_open_from_string(str);
global.sound = ini_read_string("Options", "Sound", true);
ini_close();

-

The above code sets a temporary ini to hold the information from the string "str", then reads from the ini before closing it again.

-

 

+

The above code sets a temporary INI to hold the information from the string str, then reads from the INI before closing it again.

 

 

-
Back: Ini Files
-
Next: ini_open
+
Back: Ini Files
+
Next: ini_close
-
© Copyright YoYo Games Ltd. 2022 All Rights Reserved
+
© Copyright YoYo Games Ltd. 2024 All Rights Reserved

surface_reset_target

-

This function resets all further drawing from the target surface back to the screen.

-

Please note that to start drawing to a surface you must first have called the function surface_set_target and then this one after you have finished, for each surface target that you have set or else nothing will be drawn on the screen as all further drawing (even in other instances) will be done on the surface. You should also realise that nothing will be seen if the surface itself is not drawn on the screen in the draw event of an instance.

+

This function resets all further drawing from the current surface back to the previous drawing target.

+

The previous drawing target can be one of the following:

+ +

Please note that to start drawing to a surface you must first have called the function surface_set_target and then this one after you have finished, for each surface target that you have set or else nothing will be drawn on the screen as all further drawing (even in other instances) will be done on the surface. You should also realise that nothing will be seen if the surface itself is not drawn on the screen in the Draw event of an instance.

 

Syntax:

@@ -40,7 +56,7 @@

Example:

if (view_current == 0)
{
    surface_set_target(surf);
-     with (obj_Effect)
+     with (obj_effect)
    {
        draw_self();
    }
@@ -50,14 +66,14 @@

Example:

{
    draw_surface(surf, 0, 0);
}

-

The above code will check to see which view is currently being drawn, and if it is view[0] it sets the draw target to a surface and draws all instances of the object obj_Effect before resetting the draw target again. If the view is not view[0] the surface is drawn to the screen.

+

The above code checks to see which view is currently being drawn, and if it is view[0] it sets the draw target to a surface and draws all instances of the object obj_effect before resetting the draw target again. If the view is not view[0] the surface is drawn to the screen.

 

 

-
Back: Surfaces
- +
Back: Surfaces
+
© Copyright YoYo Games Ltd. 2024 All Rights Reserved
diff --git a/Manual/contents/assets/snippets/Note_Surface_Function_Silently_Fails.hts b/Manual/contents/assets/snippets/Note_Surface_Function_Silently_Fails.hts index 7cde132ee..9d00bcb50 100644 --- a/Manual/contents/assets/snippets/Note_Surface_Function_Silently_Fails.hts +++ b/Manual/contents/assets/snippets/Note_Surface_Function_Silently_Fails.hts @@ -9,6 +9,6 @@ -

 If you have not previously set a render target with the function surface_set_target, calling this function will throw a fatal error.

+

 If you have not previously set a render target with the function surface_set_target, calling this function will throw a fatal error.

\ No newline at end of file From e06e6aef96f3331c031c50094664c56e2342e88c Mon Sep 17 00:00:00 2001 From: YYBartT Date: Wed, 11 Dec 2024 23:02:21 +0100 Subject: [PATCH 07/15] docs(general): minor changes to Shaders page --- Manual/contents/The_Asset_Editors/Shaders.htm | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Manual/contents/The_Asset_Editors/Shaders.htm b/Manual/contents/The_Asset_Editors/Shaders.htm index 929f44773..f59f53e49 100644 --- a/Manual/contents/The_Asset_Editors/Shaders.htm +++ b/Manual/contents/The_Asset_Editors/Shaders.htm @@ -28,9 +28,8 @@

The Shader Editor

 

A complete overview of how shaders really work and what place they have in the graphics pipeline is outside the scope of this, but you can find a brief guide here:

-

 

Language Support

GameMaker supports the following shader languages:

@@ -60,18 +59,18 @@

Language Support

When writing GLSL ES shaders, it is recommended to follow the official language specification as closely as possible to avoid errors as some target platforms can be stricter than others (such as the HTML5 and GX.games targets, which can be more restrictive than other platforms such as Windows, macOS, etc. when it comes to language limitations).

 

Creating a Shader

-

To create a shader resource, simply right click RMB Icon inside the Asset Browser and select Create -> Shader. Once you have created the base shader, you can then use the right mouse RMB Icon menu on the new resource to select the shader type before continuing to edit the code:

+

To create a shader asset, simply right-click RMB Icon inside The Asset Browser and select Create -> Shader. Once you have created the base shader, you can then use the right mouse RMB Icon menu on the new asset to select the shader type before continuing to edit the code:

Shader Editor RMB MenuThe code editor itself is split into two the "programs" - Vertex and Fragment - when you create a new shader, with each one being available from tabs at the top of the editor. Both are created at once because you cannot create a shader without both parts. Even if you wish to only use the fragment shader you will have to have created a "pass through" vertex shader first, which is why by default any new shader being created will have a vertex and fragment pass through shader already coded for you (in the screen shot at the top of the page, you can see that we have used the code editor pane view to show the two side by side... useful when working on both the shader programs together).

It is worth noting that you can use GLSL ES shaders on all target platforms, but for them to work on the HTML5 target platform you must have enabled WebGL in the HTML5 Game Options otherwise they will not work.

For further details relating to shader functions and how they can be used in GameMaker please see the following pages:

-

The Code Editor

+

The Code Editor (Beta)

The new Code Editor can be enabled from the preferences and is used to edit shader files when enabled. Both the vertex and fragment shaders will appear in the same editor one after another (unless the "Show all documents in single view" preference is disabled, in which case you can switch the opened shader file from the Navigation Bar).

 

 

From bbb21b975117cbf179b794ea0ea4b6fb3c5f0aa1 Mon Sep 17 00:00:00 2001 From: YYBartT Date: Wed, 11 Dec 2024 23:04:21 +0100 Subject: [PATCH 08/15] docs(general): capitalised Draw event --- .../The_Asset_Editors/Object_Properties/Draw_Events.htm | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Manual/contents/The_Asset_Editors/Object_Properties/Draw_Events.htm b/Manual/contents/The_Asset_Editors/Object_Properties/Draw_Events.htm index 7cee3c34d..c7762e8d5 100644 --- a/Manual/contents/The_Asset_Editors/Object_Properties/Draw_Events.htm +++ b/Manual/contents/The_Asset_Editors/Object_Properties/Draw_Events.htm @@ -27,7 +27,7 @@

Draw Events

Apart from the main Draw event, you also have a Draw Begin and a Draw End event too. These act exactly the same as a standard Draw event (i.e.: they will draw whatever you put in them every step of the game and for all viewports), but they do not "default draw" anything if they have not been explicitly added to an object, and they will always run before/after the standard Draw event. So, when the game is running you will always have the Draw Begin event for all instances, then the Draw event for all instances, then finally the Draw End event for all instances.

In this way, you can draw things or set draw properties in the Draw Begin step in one instance and be sure that all instances with a standard Draw event or Draw End event will use these properties or draw over what the first instance has drawn. Basically it's a sure fire way to guarantee that certain things are drawn at certain times, much like the Begin Step and End Step events do.

-

There are a few things to note when drawing things in GameMaker, whether it's a sprite you are drawing or a shader, or a 3D buffer:

+

There are a few things to note when drawing things in GameMaker, whether it's a sprite you are drawing or a shader, or a 3D model stored in a vertex buffer:

  • The Draw event is a very intensive event, in that it's one of the events that takes up most time and resources... To that end it is never a good idea to do anything in the Draw event other than drawing. So save your large code or complex actions for the Step event or Alarms or whatever other event fits, but leave the Draw event clear for the drawing as that's what it does best.
  • If your object has had the visible parameter set to off (so that the instances of the object are not drawn) then all Draw events are skipped (except for the Resize event). This means that making an instance invisible will stop all code placed in any of these events from running, so don't put essential code in the Draw events if they are not going to be visible.
    • @@ -41,7 +41,7 @@

    Draw Events

    When drawing in these events it is important that you understand that the draw coordinates do not change even when camera views are active and (0,0) is always the top left hand corner of either the application surface or the display (see the note at the bottom of this section), and the default width and height are 1:1 with the application surface. Depth ordering is still maintained between different instances on different layers (so an instance on a higher layer will be drawn under one at a lower layer) and also within the events themselves, as the Draw GUI Begin event will draw for all instances first, then the standard Draw GUI will draw for all instances over that, and finally the Draw GUI End event is triggered.

    In this way, you can draw things or set draw properties in the Draw GUI Begin in one instance and be sure that all instances with a standard Draw GUI or Draw GUI End event will use these properties or draw over what the first instance has drawn. Basically it's a sure fire way to guarantee that certain things are drawn at certain times, much like the Begin Step and End Step events do.

    These events can also be used in conjunction with the normal Draw events (which will be affected by the camera view position, scale and rotation as normal). If you have no Draw Event but you do have a Draw GUI Event, then GameMaker will still default draw the sprite for the instance (if it has one) as normal.

    -

    With relation to the other draw events, the Draw GUI events will always draw over anything drawn in the normal draw events. So, if you have an instance on a lower layer with a Draw GUI event, it will draw over the instance that is on a higher layer with a regular draw event. If both instances have a Draw GUI event, then the layer order will be respected.

    +

    With relation to the other draw events, the Draw GUI events will always draw over anything drawn in the normal draw events. So, if you have an instance on a lower layer with a Draw GUI event, it will draw over the instance that is on a higher layer with a regular Draw event. If both instances have a Draw GUI event, then the layer order will be respected.

     This event will, by default, draw 1:1 with the application surface size, which is normally the size of the room or the view port. This means that when you have Aspect Ratio Correction on in the Game Options the GUI is not going to be drawn over the black bars that "letterbox" the game. This behavior can be switched off using the display_set_gui_maximise function, and you can also lock the GUI event to a specific size which will then be scaled to fit the display or application surface dimensions automatically by using the function display_set_gui_size.

     

@@ -52,7 +52,7 @@

Draw Events

The Pre-Draw event is triggered before any other Draw event, and in it you can set values, set draw properties and even draw things without worrying about the viewports or the size of the GUI layer (the GUI layer size may be the same as the screen buffer, but it may not be since you can set the GUI resolution in code).

It is worth noting that this event happens before the display buffer is cleared for regular drawing, meaning that if you do not switch off view clearing in The Room Editor then nothing that is drawn in the Pre-Draw event will be seen, as the first viewport draw will clear it. If you want to be able to see through the viewports themselves, or you are not using viewports at all, then you should also have set the background colour to have an alpha of 0 in The Room Editor.

 If you switch off these options, you may notice unwanted artefacts being drawn on the screen when the game is tested (like "trails" from instances). This is because you are drawing directly over the previous frame of the display buffer without it being cleared. However you can use draw_clear_alpha to do this yourself.

-

The Post-Draw event is triggered after all the standard draw events, but before the Draw GUI events. Like the Pre-Draw event, it is based on the size of the display buffer, and is placed before the Draw GUI events to enable you to perform post-processing effects and other things on a full screen basis simply and easily without interfering with any HUD/ GUI elements that you may have in your game.

+

The Post-Draw event is triggered after all the standard Draw events, but before the Draw GUI events. Like the Pre-Draw event, it is based on the size of the display buffer, and is placed before the Draw GUI events to enable you to perform post-processing effects and other things on a full screen basis simply and easily without interfering with any HUD/ GUI elements that you may have in your game.

 

Window Resize HTML5

From f4c50da91ba316e4e85a6fb5309eaeeb5fdc4058 Mon Sep 17 00:00:00 2001 From: YYBartT Date: Thu, 12 Dec 2024 18:08:18 +0100 Subject: [PATCH 09/15] docs(general): surface_reset_target() page wording could be made more accurate YoYoGames/GameMaker-Bugs/issues/8573 * Moved information on the surface_reset_target() page to the Drawing page * Added an introduction on the Drawing page, describing when GameMaker draws things * Also added a section on "Drawing Targets" * Linked to the "Drawing Targets" section from the surface_reset_target() page --- .../GML_Reference/Drawing/Drawing.htm | 29 +++++++++++++++++-- .../Drawing/Surfaces/Surfaces.htm | 2 +- .../Drawing/Surfaces/surface_reset_target.htm | 17 +---------- 3 files changed, 29 insertions(+), 19 deletions(-) diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm index 64dbb5525..a66bd6d04 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm @@ -15,7 +15,33 @@

Drawing

-

This section contains all the functions related to drawing within the game room, as well as for controlling how things will be drawn (blending, alpha, culling, etc.). There are a great number of different functions for drawing, and they are split over the following categories to make it easier to find what you need:

+

This section contains all functions related to drawing within your game as well as for controlling how things will be drawn (blending, alpha, culling, etc.).

+

Drawing in GameMaker happens at the end of the frame, after all other events (see Event Order). In this draw cycle GameMaker performs a series of events in a specific order.

+

Everything that you draw eventually needs to be drawn to the display buffer in order to be visible on screen. By default, GameMaker does not directly draw to the display buffer, however, but rather to a surface: the Application Surface. This is the default drawing target when drawing in the regular Draw events (Draw, Draw Begin and Draw End).

+

 See the Draw Events page for detailed information on how GameMaker draws everything during a frame.

+

Drawing Targets

+

GameMaker always draws to a drawing target and changes it automatically at certain points in the draw cycle, resetting it afterwards. The drawing target can be one of the following:

+ +

GameMaker sets the drawing target to the application surface automatically after all instances have executed their Pre-Draw event and resets it to the display buffer before all instances execute their Post-Draw event.

+

At any point in a Draw event you can create your own custom surface with surface_create, set it as the drawing target with surface_set_target, draw to it and reset the target afterwards with surface_reset_target. See Surfaces for more information.

+

The Application Surface

+

This is the default drawing target that GameMaker draws to in the regular Draw events. You can choose to not draw it automatically with application_surface_draw_enable or disable it entirely with application_surface_enable. When the application surface is disabled, everything is drawn directly to the display buffer.

+

Reference

+

GameMaker comes with a great number of different functions for drawing. To make it easier to find what you need the functions are split over the following categories:

 

 

-

 

diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/Surfaces.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/Surfaces.htm index 7730c0f5e..4a207ef31 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/Surfaces.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/Surfaces.htm @@ -15,7 +15,7 @@

Surfaces

-

Application Surface

+

Application Surface

In the normal draw events, GameMaker doesn't actually draw directly to the screen, but rather draws to a surface called the application surface.

This surface is basically a blank "canvas" that can be manipulated before being drawn to the screen when needed, and in most cases GameMaker handles this for you (although you can also manipulate it yourself in code for shaders, scaling and many other things - further details are given below).

Custom Surfaces

diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm index 5dcd585f7..a965164f6 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm @@ -27,23 +27,8 @@

surface_reset_target

This function resets all further drawing from the current surface back to the previous drawing target.

-

The previous drawing target can be one of the following:

-

Please note that to start drawing to a surface you must first have called the function surface_set_target and then this one after you have finished, for each surface target that you have set or else nothing will be drawn on the screen as all further drawing (even in other instances) will be done on the surface. You should also realise that nothing will be seen if the surface itself is not drawn on the screen in the Draw event of an instance.

+

See Drawing Targets

 

Syntax:

From 2fa77a8892be0230b2711346d284734cc3b39b22 Mon Sep 17 00:00:00 2001 From: YYBartT Date: Fri, 13 Dec 2024 11:15:32 +0100 Subject: [PATCH 10/15] docs(general): surface_reset_target() page wording could be made more accurate YoYoGames/GameMaker-Bugs/issues/8573 Listed the possible draw targets on the surface_reset_target() page --- .../GML_Reference/Drawing/Drawing.htm | 12 ++++++------ .../Drawing/Surfaces/surface_reset_target.htm | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm index a66bd6d04..c2ffed16c 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm @@ -17,10 +17,10 @@

Drawing

This section contains all functions related to drawing within your game as well as for controlling how things will be drawn (blending, alpha, culling, etc.).

Drawing in GameMaker happens at the end of the frame, after all other events (see Event Order). In this draw cycle GameMaker performs a series of events in a specific order.

-

Everything that you draw eventually needs to be drawn to the display buffer in order to be visible on screen. By default, GameMaker does not directly draw to the display buffer, however, but rather to a surface: the Application Surface. This is the default drawing target when drawing in the regular Draw events (Draw, Draw Begin and Draw End).

+

Everything that you draw eventually needs to be drawn to the display buffer in order to be visible on screen. By default, GameMaker does not directly draw to the display buffer, however, but rather to a surface: the Application Surface. This is the default draw target when drawing in the regular Draw events (Draw, Draw Begin and Draw End).

 See the Draw Events page for detailed information on how GameMaker draws everything during a frame.

-

Drawing Targets

-

GameMaker always draws to a drawing target and changes it automatically at certain points in the draw cycle, resetting it afterwards. The drawing target can be one of the following:

+

Draw Targets

+

GameMaker always draws to a draw target and changes it automatically at certain points in the draw cycle, resetting it afterwards. The draw target can be one of the following:

  • The display buffer:
      @@ -36,10 +36,10 @@

      Drawing Targets

-

GameMaker sets the drawing target to the application surface automatically after all instances have executed their Pre-Draw event and resets it to the display buffer before all instances execute their Post-Draw event.

-

At any point in a Draw event you can create your own custom surface with surface_create, set it as the drawing target with surface_set_target, draw to it and reset the target afterwards with surface_reset_target. See Surfaces for more information.

+

GameMaker sets the draw target to the application surface automatically after all instances have executed their Pre-Draw event and resets it to the display buffer before all instances execute their Post-Draw event.

+

At any point in a Draw event you can create your own custom surface with surface_create, set it as the draw target with surface_set_target, draw to it and reset the target afterwards with surface_reset_target. See Surfaces for more information.

The Application Surface

-

This is the default drawing target that GameMaker draws to in the regular Draw events. You can choose to not draw it automatically with application_surface_draw_enable or disable it entirely with application_surface_enable. When the application surface is disabled, everything is drawn directly to the display buffer.

+

This is the default draw target that GameMaker draws to in the regular Draw events. You can choose to not draw it automatically with application_surface_draw_enable or disable it entirely with application_surface_enable. When the application surface is disabled, everything is drawn directly to the display buffer.

Reference

GameMaker comes with a great number of different functions for drawing. To make it easier to find what you need the functions are split over the following categories:

    diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm index a965164f6..5c3da23d8 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm @@ -26,9 +26,9 @@

    surface_reset_target

    -

    This function resets all further drawing from the current surface back to the previous drawing target.

    +

    This function resets all further drawing from the current surface back to the previous draw target.

    +

    This draw target can be another surface (the application surface, a view surface, a custom surface) or the display buffer, depending on where the call to the corresponding surface_set_target was made. See Draw Targets.

    Please note that to start drawing to a surface you must first have called the function surface_set_target and then this one after you have finished, for each surface target that you have set or else nothing will be drawn on the screen as all further drawing (even in other instances) will be done on the surface. You should also realise that nothing will be seen if the surface itself is not drawn on the screen in the Draw event of an instance.

    -

    See Drawing Targets

     

    Syntax:

    From 21ce4be49e1b7f4ab1e65b4434f8e2102ed16ecc Mon Sep 17 00:00:00 2001 From: YYBartT Date: Mon, 16 Dec 2024 18:06:56 +0100 Subject: [PATCH 11/15] docs(general): Small changes to webgl_enabled manual page https://github.com/YoYoGames/GameMaker-Bugs/issues/2238 --- .../Web_And_HTML5/webgl_enabled.htm | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Web_And_HTML5/webgl_enabled.htm b/Manual/contents/GameMaker_Language/GML_Reference/Web_And_HTML5/webgl_enabled.htm index 04971eb26..8ba20f27a 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Web_And_HTML5/webgl_enabled.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Web_And_HTML5/webgl_enabled.htm @@ -4,7 +4,7 @@ webgl_enabled - + @@ -14,33 +14,33 @@ -

    webgl_enabled

    -

    This read-only variable will return whether WebGL is enabled (true) or not (false) for your game. It will only work for those games running through a browser (ie: HTML5), and for all other platforms it will return true.

    +

    webgl_enabled

    +

    This read-only variable holds whether WebGL is enabled (true) or not (false) for your game.

    +

     This variable only contains a correct value for those games running through a browser (i.e.: HTML5), on all other platforms it will hold true.

     

    Syntax:

    -

    webgl_enabled

    +

    webgl_enabled

     

    Returns:

    -

    +

    Boolean

     

    Example:

    -

    if (webgl_enabled)
    +

    if (webgl_enabled)
    {
        global.quality = 1;
    }
    else global.quality = 0;

    -

    The above code checks the WebGL flag and then sets the global variable "quality" accordingly.

    -

     

    +

    The above code checks the WebGL flag and then sets the global variable quality accordingly.

     

     

    - - + +
    -
    © Copyright YoYo Games Ltd. 2022 All Rights Reserved
    +
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    -

    layer_shader

    -

    This function assigns a shader resource to any given layer and the layer will then be rendered using that shader.

    -

    You supply either The handle of the layer or the name of the layer (as a string - this will have a performance impact) , along with the ID of the shader to use. The shader must have been created previously in the Asset Browser and the shader index (the name of the shader resource) is then passed to this function. If the layer assigned has instances added to it, then the shader will be applied to all the draw events that the instance uses - for example if the instance has a Draw GUI Begin event, then the shader will be applied automatically to it. The shader will also affect any other graphic elements drawn on that layer, like sprite assets, tile maps or particle systems.

    -

    The function is not meant to be called in any draw events or step events, but rather only needs to be called at the start of the room in the Room Creation Code or in the Create Event / Room Start Event of an instance.

    -

    -

    Syntax:

    -

    layer_shader(layer_id, shader)

    -
- - - - - - - - - - - - - - - - - -
ArgumentTypeDescription
layer_idString or Layer IDThe handle of the layer to target (or the layer name as a string)
shaderShader AssetThe shader index to assign to the layer
-

-

Returns:

-

N/A

-

-

Example:

-

var lay_id = layer_get_id("Instances"); -
- layer_shader(lay_id, shd_Sepia);

-

The above code will assign the shader resource shd_Sepia to the given layer for all drawing.

-

-

-
-
-
- - -
+ + + layer_shader + + + + + + + + + + +

layer_shader

+

This function assigns a shader asset to any given layer and the layer will then be rendered using that shader.

+

You supply either the handle of the layer or the name of the layer (as a string - this will have a performance impact) , along with the shader to use. The shader must have been created previously in the Asset Browser and the shader asset is then passed to this function. If the layer assigned has instances added to it, then the shader will be applied to all the draw events that the instance uses - for example if the instance has a Draw GUI Begin event, then the shader will be applied automatically to it. The shader will also affect any other graphic elements drawn on that layer, like sprite assets, tile maps or particle systems.

+

The function is not meant to be called in any Draw events or Step events, but rather only needs to be called at the start of the room in the Room Creation Code or in the Create Event / Room Start Event of an instance.

+

 

+

Syntax:

+

layer_shader(layer_id, shader)

+ + + + + + + + + + + + + + + + + + +
ArgumentTypeDescription
layer_idString or LayerThe handle of the layer to target (or the layer name as a string)
shaderShader AssetThe shader to assign to the layer
+

 

+

Returns:

+

N/A

+

 

+

Example:

+

var _lay_id = layer_get_id("Instances");
+ layer_shader(_lay_id, shd_sepia); +

+

The above code will assign the shader asset shd_sepia to the given layer for all drawing.

+

 

+

 

+
+
+
+
Back: Layers
+
-
© Copyright YoYo Games Ltd. 2023 All Rights Reserved
- + +--> + \ No newline at end of file From 7cafe1e38b768100bf647e55b4e1299e13153442 Mon Sep 17 00:00:00 2001 From: YYBartT Date: Mon, 16 Dec 2024 18:44:29 +0100 Subject: [PATCH 13/15] docs(general): Several shader functions are not defined in autocomplete (or the manual) https://github.com/YoYoGames/GameMaker-Bugs/issues/8597 * Listed the functions on the Shaders page * Added a bit of structure to the Shaders page, adding headers and moving paragraphs under those --- .../Asset_Management/Shaders/Shaders.htm | 62 ++++++++++++------- 1 file changed, 39 insertions(+), 23 deletions(-) diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Asset_Management/Shaders/Shaders.htm b/Manual/contents/GameMaker_Language/GML_Reference/Asset_Management/Shaders/Shaders.htm index 6af7b4ce4..3735034df 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Asset_Management/Shaders/Shaders.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Asset_Management/Shaders/Shaders.htm @@ -17,14 +17,17 @@

Shaders

Shaders are an incredibly powerful tool for manipulating what and how things are rendered to the screen by the graphics card. Since these tiny programs are actually run on the graphics card itself, this means that they are extremely fast to process, freeing up valuable CPU cycles for more game logic.

To create a shader you will need to have written both a Vertex Shader and a Fragment Shader (also know as a Pixel Shader) using The Shader Editor, and even if (for example) you only wish to change the vertex positions for an instance being drawn, or if you only want to change the colour values for the pixels, you will still need both programs for a complete shader to work.

-

 Shaders do not permit you to change the value of any variables that you pass into them, and so these will be called shader constants (or uniforms) in all the documentation that refers to them.

-

For a complete overview of the language specification of GLSL ES that GameMaker currently uses, including the functions and variables that you can use to program the shaders themselves, please refer to the GLSL ES Specification 1.00. If you're looking for a quick overview of these functions and variables, the following link is useful as well as it contains some quick reference cards for the OpenGL ES API on the last two cards: OpenGL ES Reference Cards.

+

Note that shaders do not permit you to change the value of any variables that you pass into them, and so these will be called shader constants (or uniforms) in all the documentation that refers to them.

+

The default shader language is GLSL ES. For a complete overview of the language specification of GLSL ES that GameMaker currently uses, including the functions and variables that you can use to program the shaders themselves, please refer to the GLSL ES Specification 1.00. If you're looking for a quick overview of these functions and variables, the following link is useful as well as it contains some quick reference cards for the OpenGL ES API on the last two cards: OpenGL ES Reference Cards.

+

 If you are new to shaders or want a more complete guide to creating and using them in GameMaker, see Guide To Using Shaders.

+

Using Shaders

Using a shader in your projects is very simple, and only requires a couple of lines of code to get the most basic of use from it:

shader_set(myShader);
draw_self();
shader_reset();

-

As you can see, they are used in a similar manner to blend modes and surfaces, where you first select (set) the shader, draw what you want using it, then reset the draw target again afterwards. If you wish to render the entire screen through a shader, and not just a single sprite or background, you will need to set up a surface to catch the current view, and then pass that through to the shader (see Surfaces for more information).

+

As you can see, they are used in a similar manner to blend modes and surfaces, where you first select (set) the shader, draw what you want using it, then reset the shader again afterwards. If you wish to render the entire screen through a shader, and not just a single sprite or background, you will need to set up a surface to catch the current view, and then pass that through to the shader (see Surfaces for more information).

 Shaders, like anything related to drawing, can only be used in the Draw events. It is also worth noting that if you are trying to use a colour value in a shader and the object has no texture, the results will turn out black.

+

Uniforms

If the shader you are using has input values, these are set using the uniform functions. You would first get the uniform handle (which is essentially an ID value for the uniform to be set) using the function shader_get_uniform in the Create Event of the instance using the shader, and then store these handles in variables, something like this:

colour_to_find = shader_get_uniform(sShaderDemo5, "f_Colour1");
colour_to_set = shader_get_uniform(sShaderDemo5, "f_Colour2");

@@ -34,19 +37,23 @@

Shaders

shader_set_uniform_f(colour_to_set, 1, 0, 0);
draw_sprite(sprite_index, image_index, x + 24, y);
shader_reset();

-

One final thing to note is that although shaders are accepted across all platforms, they are still device specific and if the hardware or software of the device cannot use shaders then you will get an error. To check this you can call the function shaders_are_supported, which returns whether the hardware supports shaders.

-

Even though your game can be run specific shaders may not have been compiled for a variety of reasons. Therefore, you are recommended to check that the shader is compiled before setting uniforms or using the shader itself by using shader_is_compiled, like this:

+

Shader Compilation

+

Although shaders are accepted across all platforms, they are still device specific and if the hardware or software of the device cannot use shaders then you will get an error. To check this you can call the function shaders_are_supported, which returns whether the hardware supports shaders.

+

Even though your game runs fine, specific shaders may not have been compiled for a variety of reasons. Therefore, you are recommended to check that the shader is compiled before setting uniforms or using the shader itself by using shader_is_compiled, like this:

if (shader_is_compiled(myShader))
{
    shader_set(myShader);
    draw_self();
    shader_reset();
}
- else show_debug_message("Shader failed");

+ else
+ {
+     show_debug_message("Shader failed");
+ }

The reasons why a shader could not be compiled can vary, depending on the shader language used on the target platform and what that language supports or doesn't, according to its specification.

In general you'd do these checks on game start and store the results as a global variable to then check later.

-

It is important to note that GameMaker also supports some conditional compile Macros which can be used within GLSL ES shaders so they can perform alternative code on specific supported platforms. The macros and the platforms they will be generated on are shown in the table below:

-

 

+

Compile Macros

+

GameMaker supports some conditional compile macros which can be used within GLSL ES shaders so they can perform alternative code on specific supported platforms. The macros and the platforms they will be generated on are shown in the table below:

@@ -67,7 +74,7 @@

Shaders

- + @@ -76,20 +83,34 @@

Shaders

_YY_HLSL11_ 3Windows, XboxOneWindows, Xbox One
_YY_PSSL_
-

 

-

When you compile your GameMaker project on any one of the listed platforms using a GLSL ES format shader, one of the above macros will be generated which can then be used checked in the shader code like this:

+

When you compile your GameMaker project on any one of the listed platforms using a GLSL ES format shader, one of the above macros will be generated which can then be used for checks in the shader code like this:

#ifdef _YY_HLSL11_
// HLSL shader code here
#else
// GLSL shader code here
#endif

-

Shaders use a certain precision to store variables. By default, this may not be the highest precision. You can add the following line of code:

-

precision highp float;

-

at the top of any pixel shader that requires a higher degree of mathematical precision. This can be useful on e.g. some Android devices that run their shaders in low precision mode.

-

If you are new to shaders or want a more complete guide to creating and use them using GameMaker, then please see the following page of the manual:

+

Various

+

Built-in Functions, Uniforms and Constants

+

While this manual will not cover any of the OpenGL shader functions and variables, it does contain a list of the ones that are unique to GameMaker. These constants are not part of the OpenGL specification for shaders and are supplied to simplify the integration of shaders within your projects.

+ +

Also note that the following names are used for built-in functions and can therefore not be used:

+

Note that these names are not highlighted in the Shader Editor.

+
    +
+

Precision

+

Shaders use a certain precision to store variables. By default, this may not be the highest precision. You can add the following line of code:

+

precision highp float;

+

at the top of any pixel shader that requires a higher degree of mathematical precision. This can be useful on e.g. some Android devices that run their shaders in low precision mode.

Function Reference

The following functions are available for drawing and setting shaders:

 

-

While this manual will not cover any of the OpenGL shader functions and variables, it does contain a list of the ones that are unique to GameMaker. These constants are not part of the OpenGL specification for shaders and are supplied to simplify the integration of shaders within your projects.

- -

 

Finally, GameMaker permits you to define your own Vertex Formats from which you can create your own custom primitives. This can greatly speed up shader operations or can be used to extend their capabilities and create surprising effects. You can find information on this in the following sections:

  • Primitives And Vertex Formats
    • @@ -146,8 +162,8 @@

    Function Reference

    - -
    Next: Sequences
    + +
    Next: Sequences
    © Copyright YoYo Games Ltd. 2024 All Rights Reserved
    From b883425d4355eada8fbfa6060cee7a0f06b593cc Mon Sep 17 00:00:00 2001 From: YYBartT Date: Tue, 17 Dec 2024 12:01:28 +0100 Subject: [PATCH 14/15] docs(general): gl_FragData problem and shader not working when having loop functions on GX YoYoGames/GameMaker-Bugs#2238 * Clarified the note on the Shader Editor page, explaining that HTML5 and GX.games follow the WebGL standard, which is more strict * Added "WebGL Limitations" under "Creating a Shader" -> "GLSL ES 1.0 Specification" to make it clear that WebGL is GLSL ES 1.0 with some restrictions --- Manual/contents/The_Asset_Editors/Shaders.htm | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/Manual/contents/The_Asset_Editors/Shaders.htm b/Manual/contents/The_Asset_Editors/Shaders.htm index f59f53e49..0732ff23f 100644 --- a/Manual/contents/The_Asset_Editors/Shaders.htm +++ b/Manual/contents/The_Asset_Editors/Shaders.htm @@ -56,17 +56,21 @@

    Language Support

    -

    When writing GLSL ES shaders, it is recommended to follow the official language specification as closely as possible to avoid errors as some target platforms can be stricter than others (such as the HTML5 and GX.games targets, which can be more restrictive than other platforms such as Windows, macOS, etc. when it comes to language limitations).

    -

     

    +

    When writing GLSL ES shaders, it is recommended to follow the official language specification as closely as possible to avoid errors as some target platforms can be stricter than others.

    +

     The HTML5 and GX.games targets use WebGL, which follows the GLSL ES 1.0 spec but doesn't support any of its non-mandatory functionality. See the WebGL spec on Supported GLSL Constructs.

    Creating a Shader

    To create a shader asset, simply right-click RMB Icon inside The Asset Browser and select Create -> Shader. Once you have created the base shader, you can then use the right mouse RMB Icon menu on the new asset to select the shader type before continuing to edit the code:

    -

    Shader Editor RMB MenuThe code editor itself is split into two the "programs" - Vertex and Fragment - when you create a new shader, with each one being available from tabs at the top of the editor. Both are created at once because you cannot create a shader without both parts. Even if you wish to only use the fragment shader you will have to have created a "pass through" vertex shader first, which is why by default any new shader being created will have a vertex and fragment pass through shader already coded for you (in the screen shot at the top of the page, you can see that we have used the code editor pane view to show the two side by side... useful when working on both the shader programs together).

    -

    It is worth noting that you can use GLSL ES shaders on all target platforms, but for them to work on the HTML5 target platform you must have enabled WebGL in the HTML5 Game Options otherwise they will not work.

    +

    Shader Editor RMB MenuThe code editor itself is split into two "programs" - Vertex and Fragment - when you create a new shader, with each one being available from tabs at the top of the editor. Both are created at once because you cannot create a shader without both parts. Even if you wish to only use the fragment shader you will have to have created a "pass through" vertex shader first, which is why by default any new shader being created will have a vertex and fragment pass through shader already coded for you (in the screen shot at the top of the page, you can see that we have used the code editor pane view to show the two side by side... useful when working on both the shader programs together).

    +

    It is worth noting that you can use GLSL ES shaders on all target platforms, but for them to work on the HTML5 target platform you must have enabled WebGL in the HTML5 Game Options, otherwise they will not work.

    For further details relating to shader functions and how they can be used in GameMaker please see the following pages:

    From 547168a0ae5cc58ded686bb5bd7ee4eeca4e00d3 Mon Sep 17 00:00:00 2001 From: gurpreetsinghmatharoo Date: Fri, 20 Dec 2024 16:34:55 +0530 Subject: [PATCH 15/15] docs(general): Minor fixes to PR #227 --- .../GameMaker_Language/GML_Reference/Drawing/Drawing.htm | 6 +++--- .../GML_Reference/Drawing/Surfaces/surface_reset_target.htm | 2 +- .../GML_Reference/File_Handling/Ini_Files/ini_close.htm | 2 +- .../GameMaker_Language/GML_Reference/Strings/string.htm | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm index c2ffed16c..0f62ff889 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Drawing.htm @@ -32,12 +32,12 @@

    Draw Targets

    1. The Application Surface, if enabled
    2. A view surface, if set for a view with view_surface_id
      3. -
    3. A custom surface created with surface_create
      4. +
    4. A custom surface created with surface_create and set as the target with surface_set_target
-

GameMaker sets the draw target to the application surface automatically after all instances have executed their Pre-Draw event and resets it to the display buffer before all instances execute their Post-Draw event.

-

At any point in a Draw event you can create your own custom surface with surface_create, set it as the draw target with surface_set_target, draw to it and reset the target afterwards with surface_reset_target. See Surfaces for more information.

+

GameMaker sets the draw target to the application surface automatically (if enabled) after all instances have executed their Pre-Draw event and resets it to the display buffer before all instances execute their Post-Draw event.

+

At any point in a Draw event you can set a custom surface as the draw target with surface_set_target, draw to it and reset the target afterwards with surface_reset_target. See Surfaces for more information.

The Application Surface

This is the default draw target that GameMaker draws to in the regular Draw events. You can choose to not draw it automatically with application_surface_draw_enable or disable it entirely with application_surface_enable. When the application surface is disabled, everything is drawn directly to the display buffer.

Reference

diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm index 5c3da23d8..0472251e4 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Drawing/Surfaces/surface_reset_target.htm @@ -27,7 +27,7 @@

surface_reset_target

This function resets all further drawing from the current surface back to the previous draw target.

-

This draw target can be another surface (the application surface, a view surface, a custom surface) or the display buffer, depending on where the call to the corresponding surface_set_target was made. See Draw Targets.

+

The previous target can be another surface (the application surface, a view surface, a custom surface) or the display buffer, depending on where the call to the corresponding surface_set_target was made. See: Draw Targets

Please note that to start drawing to a surface you must first have called the function surface_set_target and then this one after you have finished, for each surface target that you have set or else nothing will be drawn on the screen as all further drawing (even in other instances) will be done on the surface. You should also realise that nothing will be seen if the surface itself is not drawn on the screen in the Draw event of an instance.

 

diff --git a/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_close.htm b/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_close.htm index 6d4e98bd5..49e775187 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_close.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/File_Handling/Ini_Files/ini_close.htm @@ -16,7 +16,7 @@

ini_close

This function should be called the moment you are finished reading from or writing to any open INI file.

-

If you do not use the function after you have used any of the INI write functions, then nothing will be written to disk, as the file information is held in memory until this function is called, which forces the write. Note that, even if you don't call this function, a  next call to ini_open will close the currently open INI file.

+

If you do not use the function after you have used any of the INI write functions, then nothing will be written to disk, as the file information is held in memory until this function is called, which forces the write. Note that, even if you don't call this function, a next call to ini_open will close the currently open INI file.

The function will also return a string with the INI file encoded into it. This string can then be saved to a server and/or used again along with the function ini_open_from_string to re-create the INI.

 

Syntax:

diff --git a/Manual/contents/GameMaker_Language/GML_Reference/Strings/string.htm b/Manual/contents/GameMaker_Language/GML_Reference/Strings/string.htm index 6d6d81ff7..95a4adc4e 100644 --- a/Manual/contents/GameMaker_Language/GML_Reference/Strings/string.htm +++ b/Manual/contents/GameMaker_Language/GML_Reference/Strings/string.htm @@ -28,7 +28,7 @@

Format String

// Results in:
// "This is a string with two placeholders that will be replaced. They are this and that."

-

Any curly braces { } with text written between them that doesn't refer to a valid argument index don't represent a placeholder and are preserved, for example string("{Not} {1} has been replaced.", "") becomes "{Not} {1} has been replaced.". Curly braces in a format string can be doubled to escape them: {{ and }}.

+

Any curly braces { } with text written between them that doesn't refer to a valid argument index won't represent a placeholder and are preserved, for example string("{Not} {1} has been replaced.", "") becomes "{Not} {1} has been replaced.". Curly braces in a format string can be doubled to escape them: {{ and }}.

If you only pass a single argument to the function, then this argument will not be considered a format string. If you add placeholders of the kind "{0}" in this case, then they will be output as normal text as there are no values to replace them with: 

string_variable = string("This is a string with two placeholders that won't be replaced. They are {0} and {1}.");