gpu_set_depth

This function sets the depth (i.e. the z coordinate) for GameMaker's 2D drawing functions (sprites, shapes, primitives, text, etc.)

By default, GameMaker uses the layer's depth when drawing flat graphics, but this function allows you to use your own. This can be used to draw at a different depth, or draw individual sprites/primitives at their own depths.

IMPORTANT This function doesn't change the depth of the layer when called in a layer begin script (see layer_script_begin). If you need to change the depth of a specific layer in the layer begin script you should do so using layer_force_draw_depth instead.

NOTE GameMaker only changes the depth when it starts drawing a new layer, so you may want to restore the original depth (saved previously from gpu_get_depth) after you're done drawing, so any subsequent calls will not be affected by your depth change.

Syntax:

gpu_set_depth(depth);

Returns:

N/A

Example 1: "depth = -y"

Draw Event

var _zwrite = gpu_get_zwriteenable();
var _ztest = gpu_get_ztestenable();
gpu_set_zwriteenable(true);
gpu_set_ztestenable(true);
var _depth = gpu_get_depth();

gpu_set_depth(-y);

draw_self();

gpu_set_depth(_depth);
gpu_set_zwriteenable(_zwrite);
gpu_set_ztestenable(_ztest);

The above code sets the depth used for drawing to the current instance's -y. This gives an easy way to draw instances behind other instances once they move "behind" them, if those instances also have their depth set to -y.

First, z-writing and z-testing are enabled on the GPU using gpu_set_zwriteenable and gpu_set_ztestenable. Their current values are stored in temporary variables _zwrite and _ztest respectively, as well as the current depth, which is stored in a temporary variable _depth. The depth is then set to the instance's -y using gpu_set_depth and the instance is drawn normally using draw_self.

Finally, depth, z-writing and z-testing are all set to their previous value in order to not affect further drawing.

Example 2: Drawing an Hourglass Shape using Circles

Draw Event

gpu_set_zwriteenable(true);
gpu_set_ztestenable(true);
matrix_set(matrix_view, matrix_build_lookat(220, 0, 90, 0, 0, 90, 0, 0, 1));
matrix_set(matrix_projection, matrix_build_projection_perspective_fov(60, room_width/room_height, 1, 10000));

var _depth = gpu_get_depth(); // store previous depth
var _col = draw_get_colour();

var n = 180;
for (var z = 0; z <= n; z += 10)
{
    gpu_set_depth(z);
    draw_set_colour(make_color_hsv(z / n * 255, 150, 250));
    draw_circle(0, 0, 40 + lengthdir_x(20, z / n * 360), false);
}

draw_set_colour(_col);
gpu_set_depth(_depth);        // restore previous depth

The code above draws a coloured hourglass-like shape in the Draw event.

First, z-writing and z-testing are enabled (gpu_set_zwriteenable and gpu_set_ztestenable) and an appropriate projection (matrix_build_projection_perspective_fov) and view matrix (matrix_build_lookat) are built and set using matrix_set. Next, the current depth value and draw colour are stored so they can be restored later.

After this, a couple of circles are drawn in a for loop using draw_circle. The depth used to draw each circle is set to the value of the loop variable z, which is increased by 10 every iteration. The radius of the circle varies in a way that the final shape looks like an hourglass shape. The draw colour is changed to bring variation in the colours of the circles.

Finally, the draw colour and depth are set back to the values they had before, in order to not affect further drawing on the instance's layer.