Rendering API documentation

constant_buffer

constant_buffer = userdata

A mutable collection of shader constants created with render.constant_buffer. Assign constants by name using vector4 or matrix4 values, or arrays of those values, then pass the buffer in the constants option to render.draw. Constant buffers are Lua userdata and cannot be iterated with pairs() or ipairs().

EXAMPLES

local constants = render.constant_buffer()
constants.tint = vmath.vector4(1, 0.5, 0.5, 1)
render.draw(self.model_predicate, { constants = constants })

render.render_target_params

render.render_target_params = { sample_count?:integer, [graphics.BUFFER_TYPE]:render.render_target_buffer_params }

sample_count defaults to 1 and is normalized by the graphics adapter to a supported power-of-two value.

render_predicate

render_predicate = userdata

An opaque filter that selects renderable objects by material tag. Create a predicate with render.predicate and pass it to render.draw. When multiple tags are supplied, an object's material must contain all of them. Predicates are intended for use in render scripts.

EXAMPLES

local opaque = render.predicate({ "opaque" })
render.draw(opaque)

render_target

render_target = number

An opaque graphics handle identifying an off-screen render target. Create one with render.render_target, draw into it with render.set_render_target, and release dynamically created targets with render.delete_render_target. A render-target resource handle can also be obtained from resource.get_render_target_info.

EXAMPLES

function init(self)
    local color_params = {
        format = graphics.TEXTURE_FORMAT_RGBA,
        width = 320,
        height = 180,
    }
    self.target = render.render_target({
        [graphics.BUFFER_TYPE_COLOR0_BIT] = color_params,
    })
end

function update(self)
    if not self.target then
        return
    end
    render.set_render_target(self.target)
    -- Draw off-screen content here.
    render.set_render_target(render.RENDER_TARGET_DEFAULT)
end

function on_message(self, message_id)
    if message_id == hash("release_render_target") and self.target then
        render.delete_render_target(self.target)
        self.target = nil
    end
end

texture

texture = number

An opaque graphics handle identifying a texture. Texture handles are returned by APIs such as resource.get_texture_info, material.get_textures, and compute.get_textures. Pass a handle to render.enable_texture to bind the texture in a render script. The resource or render target that owns the texture controls its lifetime.

EXAMPLES

local texture_info = resource.get_texture_info("/assets/logo.texturec")
local texture_handle = texture_info.handle
render.enable_texture("texture_sampler", texture_handle)

render.camera_options

Render-camera options

FIELDS

render.debug_draw_options

Debug-draw options

FIELDS

render.dispatch_options

Compute-dispatch options

FIELDS

render.draw_options

Render draw options

FIELDS

render.render_target_buffer_params

Render-target attachment parameters

FIELDS

render.set_render_target_options

Render-target activation options

FIELDS

render.CONTEXT_EVENT

render.CONTEXT_EVENT: integer

Render context events

VALUES

render.FRUSTUM_PLANES

render.FRUSTUM_PLANES: integer

Frustum plane selections

VALUES

render.RENDER_TARGET_FLAG

render.RENDER_TARGET_FLAG: integer

Render-target creation flags

VALUES

render.SORT

render.SORT: integer

Render sort orders

VALUES

render.clear()

render.clear(buffers:table<graphics.BUFFER_TYPE, number|vector4>)

Clear buffers in the currently enabled render target with specified value. If the render target has been created with multiple color attachments, all buffers will be cleared with the same value.

PARAMETERS

EXAMPLES

render.clear({[graphics.BUFFER_TYPE_COLOR0_BIT] = vmath.vector4(0, 0, 0, 0), [graphics.BUFFER_TYPE_DEPTH_BIT] = 1})

render.constant_buffer()

render.constant_buffer()→buffer:constant_buffer

Constant buffers are used to set shader program variables and are optionally passed to the render.draw() function. The buffer's constant elements can be indexed like an ordinary Lua table, but you can't iterate over them with pairs() or ipairs().

PARAMETERS

None

RETURNS

EXAMPLES

local constants = render.constant_buffer()
constants.tint = vmath.vector4(1, 1, 1, 1)

render.draw(self.my_pred, {constants = constants})

local constants = render.constant_buffer()
constants.light_colors    = {}
constants.light_colors[1] = vmath.vector4(1, 0, 0, 1)
constants.light_colors[2] = vmath.vector4(0, 1, 0, 1)
constants.light_colors[3] = vmath.vector4(0, 0, 1, 1)

local constants = render.constant_buffer()
constants.light_colors    = {
     vmath.vector4(1, 0, 0, 1)
     vmath.vector4(0, 1, 0, 1)
     vmath.vector4(0, 0, 1, 1)
}

-- Add more constant to the array
constants.light_colors[4] = vmath.vector4(1, 1, 1, 1)

render.delete_render_target()

render.delete_render_target(render_target:render_target)

Deletes a render target created by a render script. You cannot delete a render target resource.

PARAMETERS

EXAMPLES

 render.delete_render_target(self.my_render_target)

render.disable_material()

render.disable_material()

If a material is currently enabled, disable it. The name of the material must be specified in the ".render" resource set in the "game.project" setting.

PARAMETERS

None

EXAMPLES

render.enable_material("glow")
render.draw(self.my_pred)
render.disable_material()

render.disable_state()

render.disable_state(state:graphics.STATE)

Disables a render state.

PARAMETERS

EXAMPLES

render.disable_state(graphics.STATE_CULL_FACE)
render.draw(self.tile_pred)

render.disable_texture()

render.disable_texture(binding:texture|string|hash)

Disables a texture that has previourly been enabled.

PARAMETERS

EXAMPLES

function update(self, dt)
    render.enable_texture(0, self.my_render_target, graphics.BUFFER_TYPE_COLOR0_BIT)
    -- draw a predicate with the render target available as texture 0 in the predicate
    -- material shader.
    render.draw(self.my_pred)
    -- done, disable the texture
    render.disable_texture(0)
end

render.dispatch_compute()

render.dispatch_compute(x:integer, y:integer, z:integer, [options:render.dispatch_options])

Dispatches the currently enabled compute program. The dispatch call takes three arguments x,y,z which constitutes the 'global working group' of the compute dispatch. Together with the 'local working group' specified in the compute shader as a layout qualifier, these two sets of parameters forms the number of invocations the compute shader will execute. An optional constant buffer can be provided to override the default constants. If no constants buffer is provided, a default system constants buffer is used containing constants as defined in the compute program.

PARAMETERS

EXAMPLES

function init(self)
    local color_params = { format = graphics.TEXTURE_FORMAT_RGBA,
                           width = render.get_window_width(),
                           height = render.get_window_height()}
    self.scene_rt = render.render_target({[graphics.BUFFER_TYPE_COLOR0_BIT] = color_params})
end

function update(self, dt)
    render.set_compute("bloom")
    render.enable_texture(0, self.backing_texture)
    render.enable_texture(1, self.scene_rt)
    render.dispatch_compute(128, 128, 1)
    render.set_compute()
end

local constants = render.constant_buffer()
constants.tint = vmath.vector4(1, 1, 1, 1)
render.dispatch_compute(32, 32, 32, {constants = constants})

render.draw()

render.draw(predicate:render_predicate, [options:render.draw_options])

Draws all objects that match a specified predicate. An optional constant buffer can be provided to override the default constants. If no constants buffer is provided, a default system constants buffer is used containing constants as defined in materials and set through go.set (or particlefx.set_constant) on visual components.

PARAMETERS

EXAMPLES

function init(self)
    -- define a predicate matching anything with material tag "my_tag"
    self.my_pred = render.predicate({hash("my_tag")})
end

function update(self, dt)
    -- draw everything in the my_pred predicate
    render.draw(self.my_pred)
end

local constants = render.constant_buffer()
constants.tint = vmath.vector4(1, 1, 1, 1)
render.draw(self.my_pred, {constants = constants})

local frustum = self.proj * self.view
render.draw(self.my_pred, {frustum = frustum})

local frustum = self.proj * self.view
render.draw(self.my_pred, {frustum = frustum, frustum_planes = render.FRUSTUM_PLANES_ALL})

render.draw_debug3d()

render.draw_debug3d([options:render.debug_draw_options])

Draws all 3d debug graphics such as lines drawn with "draw_line" messages and physics visualization.

PARAMETERS

EXAMPLES

function update(self, dt)
    -- draw debug visualization
    render.draw_debug3d()
end

render.enable_material()

render.enable_material(material_id:string|hash)

If another material was already enabled, it will be automatically disabled and the specified material is used instead. The name of the material must be specified in the ".render" resource set in the "game.project" setting.

PARAMETERS

EXAMPLES

render.enable_material("glow")
render.draw(self.my_pred)
render.disable_material()

render.enable_state()

render.enable_state(state:graphics.STATE)

Enables a particular render state. The state will be enabled until disabled.

PARAMETERS

EXAMPLES

render.enable_state(graphics.STATE_STENCIL_TEST)
render.draw(self.gui_pred)
render.disable_state(graphics.STATE_STENCIL_TEST)

render.enable_texture()

render.enable_texture(binding:number|string|hash, handle_or_name:texture|string|hash, [buffer_type:graphics.BUFFER_TYPE])

Sets the specified texture handle for a render target attachment or a regular texture that should be used for rendering. The texture can be bound to either a texture unit or to a sampler name by a hash or a string. A texture can be bound to multiple units and sampler names at the same time, the actual binding will be applied to the shaders when a shader program is bound. When mixing binding using both units and sampler names, you might end up in situations where two different textures will be applied to the same bind location in the shader. In this case, the texture set to the named sampler will take precedence over the unit. Note that you can bind multiple sampler names to the same texture, in case you want to reuse the same texture for differnt use-cases. It is however recommended that you use the same name everywhere for the textures that should be shared across different materials.

PARAMETERS

EXAMPLES

function update(self, dt)
    -- enable target so all drawing is done to it
    render.set_render_target(self.my_render_target)

    -- draw a predicate to the render target
    render.draw(self.my_pred)

    -- disable target
    render.set_render_target(render.RENDER_TARGET_DEFAULT)

    render.enable_texture(0, self.my_render_target, graphics.BUFFER_TYPE_COLOR0_BIT)
    -- draw a predicate with the render target available as texture 0 in the predicate
    -- material shader.
    render.draw(self.my_pred)
end

function update(self, dt)
    -- enable render target by resource id
    render.set_render_target('my_rt_resource')
    render.draw(self.my_pred)
    render.set_render_target(render.RENDER_TARGET_DEFAULT)

    render.enable_texture(0, 'my_rt_resource', graphics.BUFFER_TYPE_COLOR0_BIT)
    -- draw a predicate with the render target available as texture 0 in the predicate
    -- material shader.
    render.draw(self.my_pred)
end

function update(self, dt)
    -- bind a texture to the texture unit 0
    render.enable_texture(0, self.my_texture_handle)
    -- bind the same texture to a named sampler
    render.enable_texture("my_texture_sampler", self.my_texture_handle)
end

render.get_height()

render.get_height()→height:integer

Returns the logical window height that is set in the "game.project" settings. Note that the actual window pixel size can change, either by device constraints or user input.

PARAMETERS

None

RETURNS

EXAMPLES

local h = render.get_height()

render.get_render_target_height()

render.get_render_target_height(render_target:render_target|string|hash, buffer_type:graphics.BUFFER_TYPE)→height:integer

Returns the specified buffer height from a render target.

PARAMETERS

RETURNS

EXAMPLES

-- get the height of the render target color buffer
local h = render.get_render_target_height(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT)
-- get the height of a render target resource
local w = render.get_render_target_height('my_rt_resource', graphics.BUFFER_TYPE_COLOR0_BIT)

render.get_render_target_width()

render.get_render_target_width(render_target:render_target|string|hash, buffer_type:graphics.BUFFER_TYPE)→width:integer

Returns the specified buffer width from a render target.

PARAMETERS

RETURNS

EXAMPLES

-- get the width of the render target color buffer
local w = render.get_render_target_width(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT)
-- get the width of a render target resource
local w = render.get_render_target_width('my_rt_resource', graphics.BUFFER_TYPE_COLOR0_BIT)

render.get_width()

render.get_width()→width:integer

Returns the logical window width that is set in the "game.project" settings. Note that the actual window pixel size can change, either by device constraints or user input.

PARAMETERS

None

RETURNS

EXAMPLES

local w = render.get_width()

render.get_window_height()

render.get_window_height()→height:integer

Returns the actual physical window height. Note that this value might differ from the logical height that is set in the "game.project" settings.

PARAMETERS

None

RETURNS

EXAMPLES

local h = render.get_window_height()

render.get_window_width()

render.get_window_width()→width:integer

Returns the actual physical window width. Note that this value might differ from the logical width that is set in the "game.project" settings.

PARAMETERS

None

RETURNS

EXAMPLES

local w = render.get_window_width()

render.predicate()

render.predicate(tags:(string|hash)[])→predicate:render_predicate

This function returns a new render predicate for objects with materials matching the provided material tags. The provided tags are combined into a bit mask for the predicate. If multiple tags are provided, the predicate matches materials with all tags ANDed together. The current limit to the number of tags that can be defined is 64.

PARAMETERS

RETURNS

EXAMPLES

local p = render.predicate({hash("opaque"), hash("smoke")})

render.render_target()

render.render_target(parameters:render.render_target_params)→render_target:render_target

Creates a new render target according to the supplied specification table. The render target can be created to support multiple color attachments. Each attachment can have different format settings and texture filters, but attachments must be added in sequence, meaning you cannot create a render target at slot 0 and 3. Instead it has to be created with all four buffer types ranging from [0..3] (as denoted by graphics.BUFFER_TYPE_COLORX_BIT where 'X' is the attachment you want to create). It is not guaranteed that the device running the script can support creating render targets with multiple color attachments. To check if the device can support multiple attachments, you can check if the render table contains any of the BUFFER_TYPE_COLOR1_BIT, BUFFER_TYPE_COLOR2_BIT or BUFFER_TYPE_COLOR3_BIT constants:

function init(self)
    if graphics.BUFFER_TYPE_COLOR1_BIT == nil then
        -- this devices does not support multiple color attachments
    end
end

PARAMETERS

RETURNS

EXAMPLES

function init(self)
    -- render target buffer parameters
    local color_params = { format = graphics.TEXTURE_FORMAT_RGBA,
                           width = render.get_window_width(),
                           height = render.get_window_height(),
                           min_filter = graphics.TEXTURE_FILTER_LINEAR,
                           mag_filter = graphics.TEXTURE_FILTER_LINEAR,
                           u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
                           v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE }
    local depth_params = { format = graphics.TEXTURE_FORMAT_DEPTH,
                           width = render.get_window_width(),
                           height = render.get_window_height(),
                           u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
                           v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE }
    self.my_render_target = render.render_target({sample_count = 4, [graphics.BUFFER_TYPE_COLOR0_BIT] = color_params, [graphics.BUFFER_TYPE_DEPTH_BIT] = depth_params })
end

function update(self, dt)
    -- enable target so all drawing is done to it
    render.set_render_target(self.my_render_target)

    -- draw a predicate to the render target
    render.draw(self.my_pred)
end

function init(self)
    -- render target buffer parameters
    local color_params_rgba = { format = graphics.TEXTURE_FORMAT_RGBA,
                                width = render.get_window_width(),
                                height = render.get_window_height(),
                                min_filter = graphics.TEXTURE_FILTER_LINEAR,
                                mag_filter = graphics.TEXTURE_FILTER_LINEAR,
                                u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
                                v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE }
    local color_params_float = { format = graphics.TEXTURE_FORMAT_RG32F,
                           width = render.get_window_width(),
                           height = render.get_window_height(),
                           min_filter = graphics.TEXTURE_FILTER_LINEAR,
                           mag_filter = graphics.TEXTURE_FILTER_LINEAR,
                           u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE,
                           v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE }


    -- Create a render target with three color attachments
    -- Note: No depth buffer is attached here
    self.my_render_target = render.render_target({
           [graphics.BUFFER_TYPE_COLOR0_BIT] = color_params_rgba,
           [graphics.BUFFER_TYPE_COLOR1_BIT] = color_params_rgba,
           [graphics.BUFFER_TYPE_COLOR2_BIT] = color_params_float, })
end

function update(self, dt)
    -- set target so all drawing is done to it
    render.set_render_target(self.my_render_target)

    -- draw a predicate to the render target
    render.draw(self.my_pred)
end

render.set_blend_equation_separate()

render.set_blend_equation_separate(equation_color:graphics.BLEND_EQUATION, equation_alpha:graphics.BLEND_EQUATION)

Sets the blend equation with separate equations for the color and alpha channels.

PARAMETERS

EXAMPLES

render.set_blend_equation_separate(graphics.BLEND_EQUATION_ADD,
                                   graphics.BLEND_EQUATION_REVERSE_SUBTRACT)

render.set_blend_func()

render.set_blend_func(source_factor:graphics.BLEND_FACTOR, destination_factor:graphics.BLEND_FACTOR)

Specifies the arithmetic used when computing pixel values that are written to the frame buffer. In RGBA mode, pixels can be drawn using a function that blends the source RGBA pixel values with the destination pixel values already in the frame buffer. Blending is initially disabled. source_factor specifies which method is used to scale the source color components. destination_factor specifies which method is used to scale the destination color components. Source color components are referred to as (R_s,G_s,B_s,A_s). Destination color components are referred to as (R_d,G_d,B_d,A_d). The color specified by setting the blendcolor is referred to as (R_c,G_c,B_c,A_c). The source scale factor is referred to as (s_R,s_G,s_B,s_A). The destination scale factor is referred to as (d_R,d_G,d_B,d_A). The color values have integer values between 0 and (k_R,k_G,k_B,k_A), where k_c = 2^m_c - 1 and m_c is the number of bitplanes for that color. I.e for 8 bit color depth, color values are between 0 and 255. The blended RGBA values of a pixel comes from the following equations:

• R_d = min(k_R, R_s * s_R + R_d * d_R)
• G_d = min(k_G, G_s * s_G + G_d * d_G)
• B_d = min(k_B, B_s * s_B + B_d * d_B)
• A_d = min(k_A, A_s * s_A + A_d * d_A)

PARAMETERS

EXAMPLES

render.set_blend_func(graphics.BLEND_FACTOR_SRC_ALPHA, graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA)

render.set_blend_func_separate()

render.set_blend_func_separate(source_factor_color:number, destination_factor_color:number, source_factor_alpha:number, destination_factor_alpha:number)

Sets the blend function with separate blend factors for the color and alpha channels.

PARAMETERS

EXAMPLES

render.set_blend_func_separate(graphics.BLEND_FACTOR_SRC_ALPHA,
                               graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA,
                               graphics.BLEND_FACTOR_ONE,
                               graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA)

render.set_camera()

render.set_camera(camera:url|number|nil, [options:render.camera_options])

Sets the current render camera to be used for rendering. If a render camera has been set by the render script, the renderer will be using its projection and view matrix during rendering. If a projection and/or view matrix has been set by the render script, they will not be used until the current render camera has been reset by calling render.set_camera(). If the 'use_frustum' flag in the options table has been set to true, the renderer will automatically use the camera frustum for frustum culling regardless of what frustum is being passed into the render.draw() function. Note that the frustum plane option in render.draw can still be used together with the camera.

PARAMETERS

EXAMPLES

render.set_camera("main:/my_go#camera")
render.draw(self.my_pred)
render.set_camera(nil)

-- The camera frustum will take precedence over the frustum plane option in render.draw
render.set_camera("main:/my_go#camera", { use_frustum = true })
-- However, we can still customize the frustum planes regardless of the camera option!
render.draw(self.my_pred, { frustum_planes = render.FRUSTUM_PLANES_ALL })
render.set_camera()

render.set_color_mask()

render.set_color_mask(red:boolean, green:boolean, blue:boolean, alpha:boolean)

Specifies whether the individual color components in the frame buffer is enabled for writing (true) or disabled (false). For example, if blue is false, nothing is written to the blue component of any pixel in any of the color buffers, regardless of the drawing operation attempted. Note that writing are either enabled or disabled for entire color components, not the individual bits of a component. The component masks are all initially true.

PARAMETERS

EXAMPLES

-- alpha cannot be written to frame buffer
render.set_color_mask(true, true, true, false)

render.set_compute()

render.set_compute(compute:string|hash|nil)

The name of the compute program must be specified in the ".render" resource set in the "game.project" setting. If nil (or no arguments) are passed to this function, the current compute program will instead be disabled.

PARAMETERS

EXAMPLES

render.set_compute("fractals")
render.enable_texture(0, self.backing_texture)
render.dispatch_compute(128, 128, 1)
render.set_compute()

render.set_cull_face()

render.set_cull_face(face_type:graphics.FACE_TYPE)

Specifies whether front- or back-facing polygons can be culled when polygon culling is enabled. Polygon culling is initially disabled. If mode is graphics.FACE_TYPE_FRONT_AND_BACK, no polygons are drawn, but other primitives such as points and lines are drawn. The initial value for face_type is graphics.FACE_TYPE_BACK.

PARAMETERS

EXAMPLES

render.enable_state(graphics.STATE_CULL_FACE)
render.set_cull_face(graphics.FACE_TYPE_FRONT)

render.set_depth_func()

render.set_depth_func(func:graphics.COMPARE_FUNC)

Specifies the function that should be used to compare each incoming pixel depth value with the value present in the depth buffer. The comparison is performed only if depth testing is enabled and specifies the conditions under which a pixel will be drawn. The depth function is initially set to graphics.COMPARE_FUNC_LESS.

PARAMETERS

EXAMPLES

render.enable_state(graphics.STATE_DEPTH_TEST)
render.set_depth_func(graphics.COMPARE_FUNC_NOTEQUAL)

render.set_depth_mask()

render.set_depth_mask(depth:boolean)

Specifies whether the depth buffer is enabled for writing. The supplied mask governs if depth buffer writing is enabled (true) or disabled (false). The mask is initially true.

PARAMETERS

EXAMPLES

render.set_depth_mask(false)

render.set_listener()

render.set_listener(callback:fun(self:script_instance, event_type:render.CONTEXT_EVENT)|nil)

Set or remove the rendering-context event listener.

PARAMETERS

EXAMPLES

--- custom.render_script
function init(self)
   render.set_listener(function(self, event_type)
       if event_type == render.CONTEXT_EVENT_CONTEXT_LOST then
           --- Some stuff when rendering context is lost
       elseif event_type == render.CONTEXT_EVENT_CONTEXT_RESTORED then
           --- Start reload resources, reload game, etc.
       end
   end)
end

render.set_polygon_offset()

render.set_polygon_offset(factor:number, units:number)

Sets the scale and units used to calculate depth values. If graphics.STATE_POLYGON_OFFSET_FILL is enabled, each fragment's depth value is offset from its interpolated value (depending on the depth value of the appropriate vertices). Polygon offset can be used when drawing decals, rendering hidden-line images etc. factor specifies a scale factor that is used to create a variable depth offset for each polygon. The initial value is 0. units is multiplied by an implementation-specific value to create a constant depth offset. The initial value is 0. The value of the offset is computed as factor × DZ + r × units DZ is a measurement of the depth slope of the polygon which is the change in z (depth) values divided by the change in either x or y coordinates, as you traverse a polygon. The depth values are in window coordinates, clamped to the range [0, 1]. r is the smallest value that is guaranteed to produce a resolvable difference. It's value is an implementation-specific constant. The offset is added before the depth test is performed and before the value is written into the depth buffer.

PARAMETERS

EXAMPLES

render.enable_state(graphics.STATE_POLYGON_OFFSET_FILL)
render.set_polygon_offset(1.0, 1.0)

render.set_projection()

render.set_projection(matrix:matrix4)

Sets the projection matrix to use when rendering.

PARAMETERS

EXAMPLES

render.set_projection(vmath.matrix4_orthographic(0, render.get_width(), 0, render.get_height(), -1, 1))

render.set_render_target()

render.set_render_target([render_target:render_target|string|hash|nil], [options:render.set_render_target_options])

Sets a render target. Subsequent draw operations will be to the render target until it is replaced by a subsequent call to set_render_target. This function supports render targets created by a render script, or a render target resource.

PARAMETERS

EXAMPLES

function update(self, dt)
    -- set render target so all drawing is done to it
    render.set_render_target(self.my_render_target, { transient = { graphics.BUFFER_TYPE_DEPTH_BIT, graphics.BUFFER_TYPE_STENCIL_BIT } } )

    -- draw a predicate to the render target
    render.draw(self.my_pred)

    -- set default render target. This also invalidates the depth and stencil buffers of the current target (self.my_render_target)
    --  which can be an optimisation on some hardware
    render.set_render_target(render.RENDER_TARGET_DEFAULT)

end

function update(self, dt)
    -- set render target by a render target resource identifier
    render.set_render_target('my_rt_resource')

    -- draw a predicate to the render target
    render.draw(self.my_pred)

    -- reset the render target to the default backbuffer
    render.set_render_target(render.RENDER_TARGET_DEFAULT)

end

render.set_render_target_size()

render.set_render_target_size(render_target:render_target|string|hash, width:integer, height:integer)

Sets the render target size for a render target created from either a render script, or from a render target resource.

PARAMETERS

EXAMPLES

render.set_render_target_size(self.my_render_target, render.get_window_width(), render.get_window_height())
render.set_render_target_size('my_rt_resource', render.get_window_width(), render.get_window_height())

render.set_stencil_func()

render.set_stencil_func(func:graphics.COMPARE_FUNC, ref:number, mask:number)

Stenciling is similar to depth-buffering as it enables and disables drawing on a per-pixel basis. First, GL drawing primitives are drawn into the stencil planes. Second, geometry and images are rendered but using the stencil planes to mask out where to draw. The stencil test discards a pixel based on the outcome of a comparison between the reference value ref and the corresponding value in the stencil buffer. func specifies the comparison function. The initial value is graphics.COMPARE_FUNC_ALWAYS. ref specifies the reference value for the stencil test. The value is clamped to the range [0, 2ⁿ-1], where n is the number of bitplanes in the stencil buffer. The initial value is 0. mask is ANDed with both the reference value and the stored stencil value when the test is done. The initial value is all 1's.

PARAMETERS

EXAMPLES

-- let only 0's pass the stencil test
render.set_stencil_func(graphics.COMPARE_FUNC_EQUAL, 0, 1)

render.set_stencil_mask()

render.set_stencil_mask(mask:number)

The stencil mask controls the writing of individual bits in the stencil buffer. The least significant n bits of the parameter mask, where n is the number of bits in the stencil buffer, specify the mask. Where a 1 bit appears in the mask, the corresponding bit in the stencil buffer can be written. Where a 0 bit appears in the mask, the corresponding bit in the stencil buffer is never written. The mask is initially all 1's.

PARAMETERS

EXAMPLES

-- set the stencil mask to all 1:s
render.set_stencil_mask(0xff)

render.set_stencil_op()

render.set_stencil_op(sfail:graphics.STENCIL_OP, dpfail:graphics.STENCIL_OP, dppass:graphics.STENCIL_OP)

The stencil test discards a pixel based on the outcome of a comparison between the reference value ref and the corresponding value in the stencil buffer. To control the test, call render.set_stencil_func. This function takes three arguments that control what happens to the stored stencil value while stenciling is enabled. If the stencil test fails, no change is made to the pixel's color or depth buffers, and sfail specifies what happens to the stencil buffer contents. dppass and dpfail specify the stencil buffer actions depending on whether subsequent depth buffer tests succeed (dppass) or fail (dpfail). The initial value for all operators is graphics.STENCIL_OP_KEEP.

PARAMETERS

EXAMPLES

render.set_stencil_func(graphics.COMPARE_FUNC_NEVER, 1, 0xFF)
-- always draw 1's on test fail
render.set_stencil_op(graphics.STENCIL_OP_REPLACE, graphics.STENCIL_OP_KEEP, graphics.STENCIL_OP_KEEP)

render.set_view()

render.set_view(matrix:matrix4)

Sets the view matrix to use when rendering.

PARAMETERS

EXAMPLES

function init(self)
  self.view = vmath.matrix4()
  self.projection = vmath.matrix4()
end

function update(self, dt)
  -- set the view to the stored view value
  render.set_view(self.view)
  -- now we can draw with this view
end

function on_message(self, message_id, message)
  if message_id == hash("set_view_projection") then
     -- camera view and projection arrives here.
     self.view = message.view
     self.projection = message.projection
  end
end

render.set_viewport()

render.set_viewport(x:integer, y:integer, width:integer, height:integer)

Set the render viewport to the specified rectangle.

PARAMETERS

EXAMPLES

-- Set the viewport to the window dimensions.
render.set_viewport(0, 0, render.get_window_width(), render.get_window_height())

render.RENDER_TARGET_DEFAULT

clear_color

Set render clear color. This is the color that appears on the screen where nothing is rendered, i.e. background.

EXAMPLES

msg.post("@render:", "clear_color", { color = vmath.vector4(1, 0, 0, 0) } )

draw_debug_text

Draw a text on the screen. This should be used for debugging purposes only.

EXAMPLES

msg.post("@render:", "draw_debug_text", { text = "Hello world!", position = vmath.vector3(200, 200, 0), color = vmath.vector4(1, 0, 0, 1) } )

draw_line

Draw a line on the screen. This should mostly be used for debugging purposes.

EXAMPLES

-- draw a white line from (200, 200) to (200, 300)
msg.post("@render:", "draw_line", { start_point = vmath.vector3(200, 200, 0), end_point = vmath.vector3(200, 300, 0), color = vmath.vector4(1, 1, 1, 1) } )

resize

Set the size of the game window. Only works on desktop platforms.

EXAMPLES

msg.post("@render:", "resize", { width = 1024, height = 768 } )

window_resized

Reports a change in window size. This is initiated on window resize on desktop or by orientation changes on mobile devices.

EXAMPLES

function on_message(self, message_id, message)
    -- check for the message
    if message_id == hash("window_resized") then
        -- the window was resized.
    end
end