surface_set_target

With this function you set all further drawing to the target surface rather than the screen and in this way you can tell GameMaker to only draw specific things to the specified surface.

Please note that if you do not call surface_reset_target after you have finished, 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. You can check the return value of this function too as a debug tool to check whether the surface target was set or not, with a return value of 0 being a failure to set the target and any other positive value being a success.

One thing that should be noted is that surfaces are stacked so you cannot jump from target to target and then reset to the normal draw target at the end, but rather you must open and close rendering targets. For example, this will not work correctly:

surface_set_target(surf1);
draw_text(32, 32, "surface1");
surface_set_target(surf2);
draw_text(32, 64, "surface2");
surface_reset_target();

Instead, you must reset the target for each of the surfaces that you set, much like you must use opening and closing brackets {} for code blocks. So the above should be written either like this:

surface_set_target(surf1);
draw_text(32, 32, "surface1");
surface_reset_target();
surface_set_target(surf2);
draw_text(32, 64, "surface2");
surface_reset_target();

or like this:

surface_set_target(surf1);
draw_text(32, 32, "surface1");
surface_set_target(surf2);
draw_text(32, 64, "surface2");
surface_reset_target();
surface_reset_target();

Syntax:

surface_set_target(surface_id);

Returns:

Boolean Whether the render target was set successfully

Example:

if (view_current == 0)
{
    surface_set_target(surf);
    with (obj_Effect)
    {
        draw_self();
    }
    surface_reset_target();
}
else
{
    draw_surface(surf, 0, 0);
}

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.