- Select ref document -

Rendering API documentation

version 1.2.149

Rendering functions, messages and constants. The "render" namespace is accessible only from render scripts.

The rendering API is built on top of OpenGL ES 2.0, is a subset of the OpenGL computer graphics rendering API for rendering 2D and 3D computer graphics. OpenGL ES 2.0 is supported on all our target platforms.

It is possible to create materials and write shaders that require features not in OpenGL ES 2.0, but those will not work cross platform.

Functions

render.clear

clears the active render target

render.constant_buffer

create a new constant buffer.

render.delete_render_target

deletes a render target

render.disable_material

disables the currently enabled material

render.disable_state

disables a render state

render.disable_texture

disables a texture for a render target

render.draw

draws all objects matching a predicate

render.draw_debug3d

draws all 3d debug graphics

render.enable_material

enables a material

render.enable_state

enables a render state

render.enable_texture

enables a texture for a render target

render.get_height

gets the window height, as specified for the project

render.get_render_target_height

retrieve a buffer height from a render target

render.get_render_target_width

retrieve the buffer width from a render target

render.get_width

gets the window width, as specified for the project

render.get_window_height

gets the actual window height

render.get_window_width

gets the actual window width

render.predicate

creates a new render predicate

render.render_target

creates a new render target

render.set_blend_func

sets the blending function

render.set_color_mask

sets the color mask

render.set_cull_face

sets the cull face

render.set_depth_func

sets the depth test function

render.set_depth_mask

sets the depth mask

render.set_polygon_offset

sets the polygon offset

render.set_projection

sets the projection matrix

render.set_render_target

sets a render target

render.set_render_target_size

sets the render target size

render.set_stencil_func

sets the stencil test function

render.set_stencil_mask

sets the stencil mask

render.set_stencil_op

sets the stencil operator

render.set_view

sets the view matrix

render.set_viewport

sets the render viewport

Messages

Constants

Functions

render.clear

render.clear(buffers)

Clear buffers in the currently enabled render target with specified value.

Parameters

buffers

table table with keys specifying which buffers to clear and values set to clear values. Available keys are:

  • render.BUFFER_COLOR_BIT
  • render.BUFFER_DEPTH_BIT
  • render.BUFFER_STENCIL_BIT
buffers

table table with keys specifying which buffers to clear and values set to clear values. Available keys are:

  • render.BUFFER_COLOR_BIT
  • render.BUFFER_DEPTH_BIT
  • render.BUFFER_STENCIL_BIT

Examples

Clear the color buffer and the depth buffer.

render.clear({[render.BUFFER_COLOR_BIT] = vmath.vector4(0, 0, 0, 0), [render.BUFFER_DEPTH_BIT] = 1})

render.constant_buffer

render.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().

Returns

buffer

constant_buffer new constant buffer

buffer

constant_buffer new constant buffer

Examples

Set a "tint" constant in a constant buffer in the render script:

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

Then use the constant buffer when drawing a predicate:

render.draw(self.my_pred, constants)

render.delete_render_target

render.delete_render_target(render_target)

Deletes a previously created render target.

Parameters

render_target

render_target render target to delete

render_target

render_target render target to delete

Examples

How to delete a render target:

 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.

Examples

Enable material named "glow", then draw my_pred with it.

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

render.disable_state

render.disable_state(state)

Disables a render state.

Parameters

state

constant state to disable

  • render.STATE_DEPTH_TEST
  • render.STATE_STENCIL_TEST
  • render.STATE_BLEND
  • render.STATE_ALPHA_TEST ( not available on iOS and Android)
  • render.STATE_CULL_FACE
  • render.STATE_POLYGON_OFFSET_FILL
state

constant state to disable

  • render.STATE_DEPTH_TEST
  • render.STATE_STENCIL_TEST
  • render.STATE_BLEND
  • render.STATE_ALPHA_TEST ( not available on iOS and Android)
  • render.STATE_CULL_FACE
  • render.STATE_POLYGON_OFFSET_FILL

Examples

Disable face culling when drawing the tile predicate:

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

render.disable_texture

render.disable_texture(unit)

Disables a texture unit for a render target that has previourly been enabled.

Parameters

unit

number texture unit to disable

unit

number texture unit to disable

Examples

function update(self, dt)
    render.enable_texture(0, self.my_render_target, render.BUFFER_COLOR_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.draw

render.draw(predicate, [constants])

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 *.set_constant() and *.reset_constant() on visual components.

Parameters

predicate

predicate predicate to draw for

[constants]

constant_buffer optional constants to use while rendering

predicate

predicate predicate to draw for

[constants]

constant_buffer optional constants to use while rendering

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

Draw predicate with constant:

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

render.draw_debug3d

render.draw_debug3d()

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

Examples

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

render.enable_material

render.enable_material(material_id)

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

material_id

string | hash material id to enable

material_id

string | hash material id to enable

Examples

Enable material named "glow", then draw my_pred with it.

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

render.enable_state

render.enable_state(state)

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

Parameters

state

constant state to enable

  • render.STATE_DEPTH_TEST
  • render.STATE_STENCIL_TEST
  • render.STATE_BLEND
  • render.STATE_ALPHA_TEST ( not available on iOS and Android)
  • render.STATE_CULL_FACE
  • render.STATE_POLYGON_OFFSET_FILL
state

constant state to enable

  • render.STATE_DEPTH_TEST
  • render.STATE_STENCIL_TEST
  • render.STATE_BLEND
  • render.STATE_ALPHA_TEST ( not available on iOS and Android)
  • render.STATE_CULL_FACE
  • render.STATE_POLYGON_OFFSET_FILL

Examples

Enable stencil test when drawing the gui predicate, then disable it:

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

render.enable_texture

render.enable_texture(unit, render_target, buffer_type)

Sets the specified render target's specified buffer to be used as texture with the specified unit. A material shader can then use the texture to sample from.

Parameters

unit

number texture unit to enable texture for

render_target

render_target render target from which to enable the specified texture unit

buffer_type

constant buffer type from which to enable the texture

  • render.BUFFER_COLOR_BIT
  • render.BUFFER_DEPTH_BIT
  • render.BUFFER_STENCIL_BIT
unit

number texture unit to enable texture for

render_target

render_target render target from which to enable the specified texture unit

buffer_type

constant buffer type from which to enable the texture

  • render.BUFFER_COLOR_BIT
  • render.BUFFER_DEPTH_BIT
  • render.BUFFER_STENCIL_BIT

Examples

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

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

    -- disable target
    render.disable_render_target(self.my_render_target)

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

render.get_height

render.get_height()

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.

Returns

height

number specified window height

height

number specified window height

Examples

Get the height of the window

local h = render.get_height()

render.get_render_target_height

render.get_render_target_height(render_target, buffer_type)

Returns the specified buffer height from a render target.

Parameters

render_target

render_target render target from which to retrieve the buffer height

buffer_type

constant which type of buffer to retrieve the height from

  • render.BUFFER_COLOR_BIT
  • render.BUFFER_DEPTH_BIT
  • render.BUFFER_STENCIL_BIT
render_target

render_target render target from which to retrieve the buffer height

buffer_type

constant which type of buffer to retrieve the height from

  • render.BUFFER_COLOR_BIT
  • render.BUFFER_DEPTH_BIT
  • render.BUFFER_STENCIL_BIT

Returns

height

number the height of the render target buffer texture

height

number the height of the render target buffer texture

Examples

-- get the height of the render target color buffer
local h = render.get_render_target_height(self.target_right, render.BUFFER_COLOR_BIT)

render.get_render_target_width

render.get_render_target_width(render_target, buffer_type)

Returns the specified buffer width from a render target.

Parameters

render_target

render_target render target from which to retrieve the buffer width

buffer_type

constant which type of buffer to retrieve the width from

  • render.BUFFER_COLOR_BIT
  • render.BUFFER_DEPTH_BIT
  • render.BUFFER_STENCIL_BIT
render_target

render_target render target from which to retrieve the buffer width

buffer_type

constant which type of buffer to retrieve the width from

  • render.BUFFER_COLOR_BIT
  • render.BUFFER_DEPTH_BIT
  • render.BUFFER_STENCIL_BIT

Returns

width

number the width of the render target buffer texture

width

number the width of the render target buffer texture

Examples

-- get the width of the render target color buffer
local w = render.get_render_target_width(self.target_right, render.BUFFER_COLOR_BIT)

render.get_width

render.get_width()

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.

Returns

width

number specified window width (number)

width

number specified window width (number)

Examples

Get the width of the window.

local w = render.get_width()

render.get_window_height

render.get_window_height()

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

Returns

height

number actual window height

height

number actual window height

Examples

Get the actual height of the window

local h = render.get_window_height()

render.get_window_width

render.get_window_width()

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

Returns

width

number actual window width

width

number actual window width

Examples

Get the actual width of the window

local w = render.get_window_width()

render.predicate

render.predicate(tags)

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

tags

table table of tags that the predicate should match. The tags can be of either hash or string type

tags

table table of tags that the predicate should match. The tags can be of either hash or string type

Returns

predicate

predicate new predicate

predicate

predicate new predicate

Examples

Create a new render predicate containing all visual objects that have a material with material tags "opaque" AND "smoke".

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

render.render_target

render.render_target(name, parameters)

Creates a new render target according to the supplied specification table.

The table should contain keys specifying which buffers should be created with what parameters. Each buffer key should have a table value consisting of parameters. The following parameter keys are available:

Key Values
format render.FORMAT_LUMINANCE
render.FORMAT_RGB
render.FORMAT_RGBA
render.FORMAT_RGB_DXT1
render.FORMAT_RGBA_DXT1
render.FORMAT_RGBA_DXT3
render.FORMAT_RGBA_DXT5
render.FORMAT_DEPTH
render.FORMAT_STENCIL
width number
height number
min_filter render.FILTER_LINEAR
render.FILTER_NEAREST
mag_filter render.FILTER_LINEAR
render.FILTER_NEAREST
u_wrap render.WRAP_CLAMP_TO_BORDER
render.WRAP_CLAMP_TO_EDGE
render.WRAP_MIRRORED_REPEAT
render.WRAP_REPEAT
v_wrap render.WRAP_CLAMP_TO_BORDER
render.WRAP_CLAMP_TO_EDGE
render.WRAP_MIRRORED_REPEAT
render.WRAP_REPEAT

Parameters

name

string render target name

parameters

table table of buffer parameters, see the description for available keys and values

name

string render target name

parameters

table table of buffer parameters, see the description for available keys and values

Returns

render_target

render_target new render target

render_target

render_target new render target

Examples

How to create a new render target and draw to it:

function init(self)
    -- render target buffer parameters
    local color_params = { format = render.FORMAT_RGBA,
                           width = render.get_window_width(),
                           height = render.get_window_height(),
                           min_filter = render.FILTER_LINEAR,
                           mag_filter = render.FILTER_LINEAR,
                           u_wrap = render.WRAP_CLAMP_TO_EDGE,
                           v_wrap = render.WRAP_CLAMP_TO_EDGE }
    local depth_params = { format = render.FORMAT_DEPTH,
                           width = render.get_window_width(),
                           height = render.get_window_height(),
                           u_wrap = render.WRAP_CLAMP_TO_EDGE,
                           v_wrap = render.WRAP_CLAMP_TO_EDGE }
    self.my_render_target = render.render_target("my_target", {[render.BUFFER_COLOR_BIT] = color_params, [render.BUFFER_DEPTH_BIT] = depth_params })
end

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

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

render.set_blend_func

render.set_blend_func(source_factor, destination_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 (Rs,Gs,Bs,As). Destination color components are referred to as (Rd,Gd,Bd,Ad). The color specified by setting the blendcolor is referred to as (Rc,Gc,Bc,Ac).

The source scale factor is referred to as (sR,sG,sB,sA). The destination scale factor is referred to as (dR,dG,dB,dA).

The color values have integer values between 0 and (kR,kG,kB,kA), where kc = 2mc - 1 and mc is the number of bitplanes for that color. I.e for 8 bit color depth, color values are between 0 and 255.

Available factor constants and corresponding scale factors:

Factor constant Scale factor (fR,fG,fB,fA)
render.BLEND_ZERO (0,0,0,0)
render.BLEND_ONE (1,1,1,1)
render.BLEND_SRC_COLOR (Rs/kR,Gs/kG,Bs/kB,As/kA)
render.BLEND_ONE_MINUS_SRC_COLOR (1,1,1,1) - (Rs/kR,Gs/kG,Bs/kB,As/kA)
render.BLEND_DST_COLOR (Rd/kR,Gd/kG,Bd/kB,Ad/kA)
render.BLEND_ONE_MINUS_DST_COLOR (1,1,1,1) - (Rd/kR,Gd/kG,Bd/kB,Ad/kA)
render.BLEND_SRC_ALPHA (As/kA,As/kA,As/kA,As/kA)
render.BLEND_ONE_MINUS_SRC_ALPHA (1,1,1,1) - (As/kA,As/kA,As/kA,As/kA)
render.BLEND_DST_ALPHA (Ad/kA,Ad/kA,Ad/kA,Ad/kA)
render.BLEND_ONE_MINUS_DST_ALPHA (1,1,1,1) - (Ad/kA,Ad/kA,Ad/kA,Ad/kA)
render.BLEND_CONSTANT_COLOR (Rc,Gc,Bc,Ac)
render.BLEND_ONE_MINUS_CONSTANT_COLOR (1,1,1,1) - (Rc,Gc,Bc,Ac)
render.BLEND_CONSTANT_ALPHA (Ac,Ac,Ac,Ac)
render.BLEND_ONE_MINUS_CONSTANT_ALPHA (1,1,1,1) - (Ac,Ac,Ac,Ac)
render.BLEND_SRC_ALPHA_SATURATE (i,i,i,1) where i = min(As, kA - Ad) /kA

The blended RGBA values of a pixel comes from the following equations:

  • Rd = min(kR, Rs * sR + Rd * dR)
  • Gd = min(kG, Gs * sG + Gd * dG)
  • Bd = min(kB, Bs * sB + Bd * dB)
  • Ad = min(kA, As * sA + Ad * dA)

Blend function (render.BLEND_SRC_ALPHA, render.BLEND_ONE_MINUS_SRC_ALPHA) is useful for drawing with transparency when the drawn objects are sorted from farthest to nearest. It is also useful for drawing antialiased points and lines in arbitrary order.

Parameters

source_factor

constant source factor

destination_factor

constant destination factor

source_factor

constant source factor

destination_factor

constant destination factor

Examples

Set the blend func to the most common one:

render.set_blend_func(render.BLEND_SRC_ALPHA, render.BLEND_ONE_MINUS_SRC_ALPHA)

render.set_color_mask

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

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

red

boolean red mask

green

boolean green mask

blue

boolean blue mask

alpha

boolean alpha mask

red

boolean red mask

green

boolean green mask

blue

boolean blue mask

alpha

boolean alpha mask

Examples

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

render.set_cull_face

render.set_cull_face(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 render.FACE_FRONT_AND_BACK, no polygons are drawn, but other primitives such as points and lines are drawn. The initial value for face_type is render.FACE_BACK.

Parameters

face_type

constant face type

  • render.FACE_FRONT
  • render.FACE_BACK
  • render.FACE_FRONT_AND_BACK
face_type

constant face type

  • render.FACE_FRONT
  • render.FACE_BACK
  • render.FACE_FRONT_AND_BACK

Examples

How to enable polygon culling and set front face culling:

render.enable_state(render.STATE_CULL_FACE)
render.set_cull_face(render.FACE_FRONT)

render.set_depth_func

render.set_depth_func(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.

Function constants:

  • render.COMPARE_FUNC_NEVER (never passes)
  • render.COMPARE_FUNC_LESS (passes if the incoming depth value is less than the stored value)
  • render.COMPARE_FUNC_LEQUAL (passes if the incoming depth value is less than or equal to the stored value)
  • render.COMPARE_FUNC_GREATER (passes if the incoming depth value is greater than the stored value)
  • render.COMPARE_FUNC_GEQUAL (passes if the incoming depth value is greater than or equal to the stored value)
  • render.COMPARE_FUNC_EQUAL (passes if the incoming depth value is equal to the stored value)
  • render.COMPARE_FUNC_NOTEQUAL (passes if the incoming depth value is not equal to the stored value)
  • render.COMPARE_FUNC_ALWAYS (always passes)

The depth function is initially set to render.COMPARE_FUNC_LESS.

Parameters

func

constant depth test function, see the description for available values

func

constant depth test function, see the description for available values

Examples

Enable depth test and set the depth test function to "not equal".

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

render.set_depth_mask

render.set_depth_mask(depth)

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

depth

boolean depth mask

depth

boolean depth mask

Examples

How to turn off writing to the depth buffer:

render.set_depth_mask(false)

render.set_polygon_offset

render.set_polygon_offset(factor, units)

Sets the scale and units used to calculate depth values. If render.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

factor

number polygon offset factor

units

number polygon offset units

factor

number polygon offset factor

units

number polygon offset units

Examples

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

render.set_projection

render.set_projection(matrix)

Sets the projection matrix to use when rendering.

Parameters

matrix

matrix4 projection matrix

matrix

matrix4 projection matrix

Examples

How to set the projection to orthographic with world origo at lower left, width and height as set in project settings and depth (z) between -1 and 1:

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, [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.

Parameters

render_target

render_target render target to set. render.RENDER_TARGET_DEFAULT to set the default render target

[options]

table optional table with behaviour parameters

transient
number Transient frame buffer types are only valid while the render target is active, i.e becomes undefined when a new target is set by a subsequent call to set_render_target. Default is all non-transient. Be aware that some hardware uses a combined depth stencil buffer and when this is the case both are considered non-transient if exclusively selected! A buffer type defined that doesn't exist in the render target is silently ignored.
  • render.BUFFER_COLOR_BIT
  • render.BUFFER_DEPTH_BIT
  • render.BUFFER_STENCIL_BIT
render_target

render_target render target to set. render.RENDER_TARGET_DEFAULT to set the default render target

[options]

table optional table with behaviour parameters

transient
number Transient frame buffer types are only valid while the render target is active, i.e becomes undefined when a new target is set by a subsequent call to set_render_target. Default is all non-transient. Be aware that some hardware uses a combined depth stencil buffer and when this is the case both are considered non-transient if exclusively selected! A buffer type defined that doesn't exist in the render target is silently ignored.
  • render.BUFFER_COLOR_BIT
  • render.BUFFER_DEPTH_BIT
  • render.BUFFER_STENCIL_BIT

Examples

How to set a render target and draw to it and then switch back to the default render target The render target defines the depth/stencil buffers as transient, when set_render_target is called the next time the buffers may be invalidated and allow for optimisations depending on driver support

function update(self, dt)
    -- set render target so all drawing is done to it
    render.set_render_target(self.my_render_target, { transient = [render.BUFFER_DEPTH_BIT, render.BUFFER_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

render.set_render_target_size

render.set_render_target_size(render_target, width, height)

Parameters

render_target

render_target render target to set size for

width

number new render target width

height

number new render target height

render_target

render_target render target to set size for

width

number new render target width

height

number new render target height

Examples

Set the render target size to the window size:

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

render.set_stencil_func

render.set_stencil_func(func, ref, mask)

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. See the table below for values. The initial value is render.COMPARE_FUNC_ALWAYS.

ref specifies the reference value for the stencil test. The value is clamped to the range [0, 2n-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.

Function constant:

  • render.COMPARE_FUNC_NEVER (never passes)
  • render.COMPARE_FUNC_LESS (passes if (ref & mask) < (stencil & mask))
  • render.COMPARE_FUNC_LEQUAL (passes if (ref & mask) <= (stencil & mask))
  • render.COMPARE_FUNC_GREATER (passes if (ref & mask) > (stencil & mask))
  • render.COMPARE_FUNC_GEQUAL (passes if (ref & mask) >= (stencil & mask))
  • render.COMPARE_FUNC_EQUAL (passes if (ref & mask) = (stencil & mask))
  • render.COMPARE_FUNC_NOTEQUAL (passes if (ref & mask) != (stencil & mask))
  • render.COMPARE_FUNC_ALWAYS (always passes)

Parameters

func

constant stencil test function, see the description for available values

ref

number reference value for the stencil test

mask

number mask that is ANDed with both the reference value and the stored stencil value when the test is done

func

constant stencil test function, see the description for available values

ref

number reference value for the stencil test

mask

number mask that is ANDed with both the reference value and the stored stencil value when the test is done

Examples

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

render.set_stencil_mask

render.set_stencil_mask(mask)

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

mask

number stencil mask

mask

number stencil mask

Examples

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

render.set_stencil_op

render.set_stencil_op(sfail, dpfail, dppass)

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.

Operator constants:

  • render.STENCIL_OP_KEEP (keeps the current value)
  • render.STENCIL_OP_ZERO (sets the stencil buffer value to 0)
  • render.STENCIL_OP_REPLACE (sets the stencil buffer value to ref, as specified by render.set_stencil_func)
  • render.STENCIL_OP_INCR (increments the stencil buffer value and clamp to the maximum representable unsigned value)
  • render.STENCIL_OP_INCR_WRAP (increments the stencil buffer value and wrap to zero when incrementing the maximum representable unsigned value)
  • render.STENCIL_OP_DECR (decrements the current stencil buffer value and clamp to 0)
  • render.STENCIL_OP_DECR_WRAP (decrements the current stencil buffer value and wrap to the maximum representable unsigned value when decrementing zero)
  • render.STENCIL_OP_INVERT (bitwise inverts the current stencil buffer value)

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 render.STENCIL_OP_KEEP.

Parameters

sfail

constant action to take when the stencil test fails

dpfail

constant the stencil action when the stencil test passes

dppass

constant the stencil action when both the stencil test and the depth test pass, or when the stencil test passes and either there is no depth buffer or depth testing is not enabled

sfail

constant action to take when the stencil test fails

dpfail

constant the stencil action when the stencil test passes

dppass

constant the stencil action when both the stencil test and the depth test pass, or when the stencil test passes and either there is no depth buffer or depth testing is not enabled

Examples

Set the stencil function to never pass and operator to always draw 1's on test fail.

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

render.set_view

render.set_view(matrix)

Sets the view matrix to use when rendering.

Parameters

matrix

matrix4 view matrix to set

matrix

matrix4 view matrix to set

Examples

How to set the view and projection matrices according to the values supplied by a camera.

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, y, width, height)

Set the render viewport to the specified rectangle.

Parameters

x

number left corner

y

number bottom corner

width

number viewport width

height

number viewport height

x

number left corner

y

number bottom corner

width

number viewport width

height

number viewport height

Examples

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

Messages

clear_color

"clear_color", { color=… }

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

Fields

color

vector4 color to use as clear color

color

vector4 color to use as clear color

Examples

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

draw_line

"draw_line", { start_point=…, end_point=…, color=… }

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

Fields

start_point

vector3 start point of the line

end_point

vector3 end point of the line

color

vector4 color of the line

start_point

vector3 start point of the line

end_point

vector3 end point of the line

color

vector4 color of the line

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) } )

draw_text

"draw_text", { position=…, text=… }

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

Fields

position

vector3 position of the text

text

string the text to draw

position

vector3 position of the text

text

string the text to draw

Examples

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

window_resized

"window_resized", { height=…, width=… }

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

Fields

height

number the new window height

width

number the new window width

height

number the new window height

width

number the new window width

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

Constants

render.BLEND_CONSTANT_ALPHA

render.BLEND_CONSTANT_COLOR

render.BLEND_DST_ALPHA

render.BLEND_DST_COLOR

render.BLEND_ONE

render.BLEND_ONE_MINUS_CONSTANT_ALPHA

render.BLEND_ONE_MINUS_CONSTANT_COLOR

render.BLEND_ONE_MINUS_DST_ALPHA

render.BLEND_ONE_MINUS_DST_COLOR

render.BLEND_ONE_MINUS_SRC_ALPHA

render.BLEND_ONE_MINUS_SRC_COLOR

render.BLEND_SRC_ALPHA

render.BLEND_SRC_ALPHA_SATURATE

render.BLEND_SRC_COLOR

render.BLEND_ZERO

render.BUFFER_COLOR_BIT

render.BUFFER_DEPTH_BIT

render.BUFFER_STENCIL_BIT

render.COMPARE_FUNC_ALWAYS

render.COMPARE_FUNC_EQUAL

render.COMPARE_FUNC_GEQUAL

render.COMPARE_FUNC_GREATER

render.COMPARE_FUNC_LEQUAL

render.COMPARE_FUNC_LESS

render.COMPARE_FUNC_NEVER

render.COMPARE_FUNC_NOTEQUAL

render.FACE_BACK

render.FACE_FRONT

render.FACE_FRONT_AND_BACK

render.FILTER_LINEAR

render.FILTER_NEAREST

render.FORMAT_DEPTH

render.FORMAT_LUMINANCE

render.FORMAT_RGB

render.FORMAT_RGBA

render.FORMAT_RGBA_DXT1

render.FORMAT_RGBA_DXT3

render.FORMAT_RGBA_DXT5

render.FORMAT_RGB_DXT1

render.FORMAT_STENCIL

render.RENDER_TARGET_DEFAULT

render.STATE_BLEND

render.STATE_CULL_FACE

render.STATE_DEPTH_TEST

render.STATE_POLYGON_OFFSET_FILL

render.STATE_STENCIL_TEST

render.STENCIL_OP_DECR

render.STENCIL_OP_DECR_WRAP

render.STENCIL_OP_INCR

render.STENCIL_OP_INCR_WRAP

render.STENCIL_OP_INVERT

render.STENCIL_OP_KEEP

render.STENCIL_OP_REPLACE

render.STENCIL_OP_ZERO

render.WRAP_CLAMP_TO_BORDER

render.WRAP_CLAMP_TO_EDGE

render.WRAP_MIRRORED_REPEAT

render.WRAP_REPEAT