In certain situations you might want to paint not directly on the screen but on a canvas that can then later be used to paint things on the screen. Such a canvas is called a surface. For example, you want to let the user draw on the screen. The paint should not be drawn on the screen (because it will be removed each next step), but instead you want to draw it on a separate surface that is copied onto the screen in each step. Or you want to use a texture that changes over time.
Surfaces make this all possible. They are actually rather simple to use. You first create a surface. Next you indicate that further drawing should happen on this surface. From that moment on all drawing functions operate on the surface. Once you are done you reset the drawing target and further drawing happens on the screen again. You can draw the surface on the screen in many different ways or use it as a texture. There are though a few things you must be aware of. See the remarks at the end.
The following functions exist to deal with surfaces
surface_create(w,h) Creates a surface of the indicated width and height. Returns the id of the surface, which must be used in all further calls. Note that the surface will not be cleared. This is the responsibility of the user. (Set it as a target and call the appropriate clear function.)
surface_free(id) Frees the memory used by the surface.
surface_exists(id) Returns whether the surface with the indicated id exists.
surface_get_width(id) Returns the width of the surface.
surface_get_height(id) Returns the height of the surface.
surface_get_texture(id) Returns the texture corresponding to the surface. This can be used to draw textured objects with the image of the surface.
surface_set_target(id) Sets the indicated surface as the drawing target. All subsequent drawing happens on this surface. It resets the projection to simply cover the surface.
surface_reset_target() Resets the drawing target to the normal screen.
surface_getpixel(id,x,y) Returns the color of the pixel corresponding to position (x,y) in the surface. This is not very fast, so use with care.
surface_save(id,fname) Saves a bmp image of the surface in the given filename. Useful for making screenshots.
surface_save_part(id,fname,x,y,w,h) Saves part of the surface in the given filename.
draw_surface(id,x,y) Draws the surface at position (x,y). (Without color blending and no alpha transparency.)
draw_surface_stretched(id,x,y,w,h) Draws the surface stretched to the indicated region.
draw_surface_tiled(id,x,y) Draws the surface tiled so that it fills the entire room.
draw_surface_part(id,left,top,width,height,x,y) Draws the indicated part of the surface with its origin at position (x,y).
draw_surface_ext(id,x,y,xscale,yscale,rot,color,alpha) Draws the surface scaled and rotated with blending color (use c_white for no blending) and transparency alpha (0-1).
draw_surface_stretched_ext(id,x,y,w,h,color,alpha) Draws the surface stretched to the indicated region. color is the blending color and alpha indicates the transparency setting.
draw_surface_tiled_ext(id,x,y,xscale,yscale,color,alpha) Draws the surface tiled so that it fills the entire room but now with scale factors and a color and transparency setting.
draw_surface_part_ext(id,left,top,width,height,x,y,xscale,yscale,color,alpha) Draws the indicated part of the surface with its origin at position (x,y) but now with scale factors and a color and transparency setting.
draw_surface_general(id,left,top,width,height,x,y,xscale,yscale,rot,c1,c2,c3,c4,alpha) The most general drawing function. It draws the indicated part of the surface with its origin at position (x,y) but now with scale factors, a rotation angle, a color for each of the four vertices (top-left, top-right, bottom-right, and bottom-left), and an alpha transparency value.
surface_copy(destination,x,y,source) Copies the source surface at position (x,y) in the destination surface. (Without any form of blending.)
surface_copy_part(destination,x,y,source,xs,ys,ws,hs) Copies the indicated part of the source surface at position (x,y) in the destination surface. (Without any form of blending.)
Note that there are no functions to copy part of the screen to a surface. (This is impossible due to possible format differences between the screen and the surfaces.) If this is required you must set a surface as render target and next draw the room. You can then use the surface copying routines to get parts of it.
Note that you can also create sprites and backgrounds from surfaces. See the section on changing resources for more information.
Some care must be taken when using these functions. In particular please notice the following: