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.

IMPORTANT! Shaders are not
available with the Trial Licence of the product.

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.

NOTE: 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 in all the
documentation that refers to them.

For a complete overview of the available GLSL ES functions and
variables that you can use to program the shaders themselves,
please refer to the OpenGL ES Shading Language (GLSL ES) Reference
Pages. The following link is also useful as it contains some
quick reference cards for the OpenGL ES Api (note that only the
last two cards shown are applicable to GameMaker Studio 2):
OpenGL ES Reference Cards.

Using Shaders

Once you have your shader created, using it 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 full 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).

NOTES: Shaders, like anything related to
drawing, can only be used in the draw event. 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.

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:

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. Therefore you are recommended to check that the
shader has been compiled before setting uniforms or using the
shader itself, like this:

As an extra check you can also call the function shaders_are_supported to
see if the hardware even supports shaders. 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 Studio 2 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:

Shader Macro

Value

Target Platform

_YY_GLSLES_

1

All target platforms

_YY_GLSL_

1

Mac and Ubuntu (Linux)

_YY_HLSL11_

1

Windows, UWP, XboxOne

_YY_PSSL_

1

PS4

When you compile your GameMaker Studio 2 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:

GameMaker Studio 2 Shader Constants

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

Vertex Formats and Custom Primitives

Finally, GameMaker Studio 2 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: