EmuRenderSurface

Render surfaces are specialized Emu UI elements which can be used to draw any kind of visual content in a self-contained space in the UI. This may be used to quickly create custom UI elements, or serve as a "window" into the game through the UI.

A render surface displaying a 3D scene.

Constructor

Inheritance: EmuCore

EmuRenderSurface(name)

Parameter	Type	Description
x	real	The x coordinate where the render surface will be created
y	real	The y coordinate where the render surface will be created
w	real	The width of the render surface
h	real	The height of the render surface
render	function	The function invoked when the render surface is drawn
step	function	The function invoked before the render surface is drawn (useful for processing input)
create	function	The function invoked when the render surface is created
destroy	function	The function invoked when the render surface is destroyed

EmuRenderSurfaces take several callbacks (although they do not inherit from EmuCallback).

render is used as the Draw event. This is where content is drawn to the surface. Note that the framework takes care of surface targets for you but the surface is not cleared automatically, so you may wish to use draw_clear or draw_clear_alpha unless you want the content from the previous frame to remain. They are not required, but the render callback can the x and y position of the cursor relative to the render surface as parameters.

step is the Step event. It is called before the draw target is set to the render surface, and may be useful for separating input and game logic from the rendering code. They are not required, but the step callback can the x and y position of the cursor relative to the render surface as parameters.

create is invoked when the render surface is created. This is where one would create game objects, data structures, load data from a file, etc. if needed.

destroy is invoked when the render surface is destroyed. If you create game objects, data structures or any other data structures that need to be explicitly destroyed, they should be removed here or a memory leak will result.

Remember that code running in a callback (ie, its scope) belongs to the Emu element.

Relevant Methods

EmuRenderSurface::GetSurface()

Returns: surface

Returns the surface belonging to the render surface. Ideally this is not needed by the outside program, but may be useful for callbacks.

EmuRenderSurface::SetRecreate(recreate)

Returns: self

Parameter	Type	Description
recreate	function	The new function invoked when the render surface is recreated

On rare occasions, a render surface may need to be recreated on-the-fly. Certain operating system events such as the program window losing focus can result in GameMaker surfaces being removed from memory, and need to be recreated. Ordinarily the EmuRenderSurface will take care of recreating the surface for you, but in some specific situations you may wish for more granular control over how this is done.

Other Methods

EmuRenderSurfaces are intended to operate autonomously after creation, but if you wish to change the behavior of a render surface while it is running you may do that with the following methods.

EmuRenderSurface::SetRender(render)

Returns: self

Parameter	Type	Description
render	function	The new function invoked when the render surface is drawn

EmuRenderSurface::SetStep(step)

Returns: self

Parameter	Type	Description
step	function	The new function invoked before the render surface is drawn (useful for processing input)

Example

var render_surface = new EmuRenderSurface(32, 32, 256, 256,
    function(mx, my) {
        if (mouse_check_button(mb_left)) {
            draw_circle_colour(mx, my, 2, c_black, c_black, false);
            draw_line_width_colour(mx_previous, my_previous, mx, my, 4, c_black, c_black);
        }
        mx_previous = mx;
        my_previous = my;
    },
    function(mx, my) {
        buffer_seek(surface_buffer, buffer_seek_start, 0);
        buffer_get_surface(surface_buffer, GetSurface(), buffer_surface_copy, 0, 0);
    },
    function() {
        draw_clear(c_yellow);
        mx_previous = 0;
        my_previous = 0;
        surface_buffer = buffer_create(width * height * 4, buffer_fixed, 1);
    },
    function() {
        buffer_delete(surface_buffer);
    }
);

render_surface.SetRecreate(function() {
    buffer_set_surface(surface_buffer, GetSurface(), buffer_surface_copy, 0, 0);
});
container.AddContent(render_surface);

This will create an EmuRenderSurface. The surface background color is yellow, and the user can draw on it like a miniature painting application. The data on the surface is preserved in a buffer, meaning that losing the surface by taking away control from the program will not erase the picture.