Vital.sandbox

core.engine.draw_material

Client

Draws an image, SVG, rendertarget, or shader on the canvas


Syntax

local status = core.engine.draw_material(
    position, 
    size, 
    material, 
    rotation = 0, 
    pivot = {0, 0}, 
    color = {1, 1, 1, 1}
)

Must be called within the "sandbox:draw" util.event. Invoking this function outside of that event will have no effect.

  • Inside the event — executes as expected, rendering the material to the canvas each frame.
  • Outside the event — the call will be silently ignored and nothing will be drawn.
  • Recommended usage — register a handler via util.event.on("sandbox:draw", ...) and place all draw calls inside it.

Custom fragment() shaders may ignore color. It's set as the vertex color and passed in as uniform vec4 modulate.

  • Honored — fragment() never touches COLOR, or uses COLOR *= modulate;.
  • Ignored — fragment() bare-assigns COLOR, e.g. COLOR = vec4(...);.

Parameters

TypeNameDescription
vector2positionTop-left position to draw the material
vector2sizeWidth and height to render the material at
string | image | svg | rendertarget | shadermaterialDraw source:
• string - file path to an image asset
• image - pre-loaded image instance
• svg - svg instance
• rendertarget - rendertarget instance
• shader - shader instance
floatrotationRotation angle in degrees
vector2pivotPivot point for rotation, relative to the material's position
colorcolorTint color to multiply over the material

Returns

TypeNameDescription
boolstatustrue on successful execution, false otherwise

Examples

Draw an image from a file path
local resolution = core.engine.get_resolution()
local center = {resolution[1]*0.5, resolution[2]*0.5}

util.event.on("sandbox:draw", function()
    core.engine.draw_material(
        {center[1] - 128, center[2] - 128},
        {256, 256},
        "assets/logo.png"
    )
end)
Draw a tinted image
local resolution = core.engine.get_resolution()
local center = {resolution[1]*0.5, resolution[2]*0.5}

util.event.on("sandbox:draw", function()
    core.engine.draw_material(
        {center[1] - 128, center[2] - 128},
        {256, 256},
        "assets/icon.png",
        0,
        {0, 0},
        {1, 0.5, 0.5, 1}
    )
end)
Draw an image rotated around its center
local resolution = core.engine.get_resolution()
local center = {resolution[1]*0.5, resolution[2]*0.5}

util.event.on("sandbox:draw", function()
    core.engine.draw_material(
        {center[1] - 64, center[2] - 64},
        {128, 128},
        "assets/arrow.png",
        90,
        {64, 64}
    )
end)
Draw from an image instance
local resolution = core.engine.get_resolution()
local center = {resolution[1]*0.5, resolution[2]*0.5}
local image = core.image.create("assets/logo.png")

util.event.on("sandbox:draw", function()
    core.engine.draw_material(
        {center[1] - 128, center[2] - 128},
        {256, 256},
        image
    )
end)
Draw from an SVG instance
local resolution = core.engine.get_resolution()
local center = {resolution[1]*0.5, resolution[2]*0.5}
local svg = core.svg.create("assets/icon.svg")

util.event.on("sandbox:draw", function()
    core.engine.draw_material(
        {center[1] - 128, center[2] - 128},
        {256, 256},
        svg
    )
end)
Draw from a rendertarget instance
local resolution = core.engine.get_resolution()
local center = {resolution[1]*0.5, resolution[2]*0.5}
local rendertarget = core.rendertarget.create(1920, 1080)

util.event.on("sandbox:draw", function()
    core.engine.draw_material(
        {center[1] - 200, center[2] - 113},
        {400, 225},
        rendertarget
    )
end)
Draw a fullscreen shader
local entity = core.shader.create("assets/shaders/ripple.glsl", core.shader.shader_mode.CANVAS_ITEM)

util.event.on("sandbox:draw", function()
    core.engine.draw_material(
        {0, 0}, 
        core.engine.get_resolution(), 
        entity
    )
end)

On this page

SyntaxParametersReturnsExamples