surface_set_target

Sets the drawing target to a specific surface.

Syntax:

GML Code Example

surface_set_target(surface_id);


Argument Description
surface_id The ID of the surface to set as the drawing target.


Returns: Boolean


Description

With this function you set all further drawing to the target surface rather than the screen and in this way you can tell GameMaker: Studio 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:

GML Code Example

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 as either this:

GML Code Example

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 as this:

GML Code Example

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

NOTE: When working with surfaces there is the possibility that they can cease to exist at any time due to them being stored in texture memory. You should ALWAYS check that a surface exists using surface_exists before referencing them directly. For further information see Surfaces.


Example:

GML Code 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 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.





No Examples Submitted

Does this page need better examples? Be the first to Submit

No Edits Suggested

Is this page unclear or not descriptive enough? Suggest an edit to the page and with enough upvotes your changes will be made.

No Questions Have Been Ask

Do you have a question about this page? Ask it Here