With this variable you can set the contents of a given view port to draw to a surface, or get the current surface id if one has been assigned to a view port. When working with surfaces, it is often required that you capture the whole visible region of the screen to the surface, and so you would assign it to a view port using this variable. This means that everything that is shown in the chosen view will now be drawn to the assigned surface. The view will now not be drawn to the screen, meaning that you will need to either:
- Enable a new view and draw the surface only in that view (using view_current to check which view is being drawn)
- Draw the surface in the Draw GUI event of an instance, since the GUI layer is independent of views.
You can also read this variable to get the index of the surface that has been assigned to the chosen view or it will return -1 if no surface has been assigned, and generally the surface used for this function should be the size of the view camera itself (not the view port). The extended example below shows a basic setup for capturing a view and drawing it in the Draw GUI event, and for more information on surfaces see the section Surfaces.
Note that you can also set a view port to a surface using the function view_set_surface_id().
Real (surface index or -1 if no surface has been assigned)
In this extended example, we will create a surface and assign it to view port so it captures the camera view assigned to that port, then draw that to the screen in the Draw GUI event. To start with we need to initialise our surface variable in the Create Event of a controller instance:
surf = -1;
We set the surface variable to -1, as all surface functions should really be used in the Draw events to prevent odd errors or undefined behaviours. So, with that done, we would then have this in the main Draw event:
surf = surface_create(camera_get_view_width(view_camera), camera_get_view_height(view_camera));
view_surface_id = surf;
Surfaces are volatile meaning that they could be removed from memory at any time due to OS memory management and other things, so here we check to see if our surface exists and if it doesn't we create it and assign it to the view 0. With that done, everything that would appear in view 0 will now be drawn to the surface we have created instead. If you do nothing else at this point, when you run your game you will simply get a blank screen as all drawing is being done on the surface, but the surface itself is not being drawn anywhere. Therefore we now need to draw the surface to the screen in the Draw GUI event like this:
draw_surface_stretched(surf, 0, 0, display_get_gui_width(), display_get_gui_height());
This code will now draw the surface that we have created from the view camera stretched to fill the entire GUI layer.