Render

Rendering functions, messages and constants. The "render" namespace is accessible only from render scripts. The rendering API was originally built on top of OpenGL ES 2.0, and it uses a subset of the OpenGL computer graphics rendering API for rendering 2D and 3D computer graphics. Our current target is OpenGLES 3.0 with fallbacks to 2.0 on some 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.

draw_debug_text

draw a text on the screen

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

PARAMETERS

position - position of the text

text - the text to draw

color - color of the text

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

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

PARAMETERS

start_point - start point of the line

end_point - end point of the line

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


window_resized

reports a window size change

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

PARAMETERS

height - the new window height

width - 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


resize

resizes the window

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

PARAMETERS

height - the new window height

width - the new window width

EXAMPLES

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


clear_color

set clear color

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

PARAMETERS

color - color to use as clear color

EXAMPLES

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


render.constant_buffer()

create a new 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().

RETURN

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 = constants})
The constant buffer also supports array values by specifying constants in a table:
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)
You can also create the table by passing the vectors directly when creating the table:
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.STATE_DEPTH_TEST


render.STATE_STENCIL_TEST


render.STATE_BLEND


render.STATE_CULL_FACE


render.STATE_POLYGON_OFFSET_FILL


render.enable_state(state)

enables a render state

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

PARAMETERS

state - state to enable

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.disable_state(state)

disables a render state

Disables a render state.

PARAMETERS

state - state to disable

EXAMPLES

Disable face culling when drawing the tile predicate:

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


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

sets the render viewport

Set the render viewport to the specified rectangle.

PARAMETERS

x - left corner

y - bottom corner

width - viewport width

height - viewport height

EXAMPLES

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


render.FORMAT_LUMINANCE


render.FORMAT_RGB


render.FORMAT_RGBA


render.FORMAT_RGB16F

May be nil if the format isn't supported

May be nil if the format isn't supported


render.FORMAT_RGB32F

May be nil if the format isn't supported

May be nil if the format isn't supported


render.FORMAT_RGBA16F

May be nil if the format isn't supported

May be nil if the format isn't supported


render.FORMAT_RGBA32F

May be nil if the format isn't supported

May be nil if the format isn't supported


render.FORMAT_R16F

May be nil if the format isn't supported

May be nil if the format isn't supported


render.FORMAT_RG16F

May be nil if the format isn't supported

May be nil if the format isn't supported


render.FORMAT_R32F

May be nil if the format isn't supported

May be nil if the format isn't supported


render.FORMAT_RG32F

May be nil if the format isn't supported

May be nil if the format isn't supported


render.FORMAT_DEPTH


render.FORMAT_STENCIL


render.FILTER_LINEAR


render.FILTER_NEAREST


render.WRAP_CLAMP_TO_BORDER


render.WRAP_CLAMP_TO_EDGE


render.WRAP_MIRRORED_REPEAT


render.WRAP_REPEAT


render.render_target(name, parameters)

creates a new render target

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_DEPTH
render.FORMAT_STENCIL
render.FORMAT_RGBA32F
render.FORMAT_RGBA16F
width number
height number
min_filter (optional) render.FILTER_LINEAR
render.FILTER_NEAREST
mag_filter (optional) render.FILTER_LINEAR
render.FILTER_NEAREST
u_wrap (optional) render.WRAP_CLAMP_TO_BORDER
render.WRAP_CLAMP_TO_EDGE
render.WRAP_MIRRORED_REPEAT
render.WRAP_REPEAT
v_wrap (optional) render.WRAP_CLAMP_TO_BORDER
render.WRAP_CLAMP_TO_EDGE
render.WRAP_MIRRORED_REPEAT
render.WRAP_REPEAT
flags (optional) render.TEXTURE_BIT (only applicable to depth and stencil buffers)
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 render.BUFFER_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_COLOR1_BIT, BUFFER_COLOR2_BIT or BUFFER_COLOR3_BIT constants:

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

PARAMETERS

name - render target name

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

RETURN

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({[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.set_render_target(self.my_render_target)

    -- draw a predicate to the render target
    render.draw(self.my_pred)
end
How to create a render target with multiple outputs:
function init(self)
    -- render target buffer parameters
    local color_params_rgba = { 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 color_params_float = { format = render.FORMAT_RG32F,
                           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 }


    -- Create a render target with three color attachments
    -- Note: No depth buffer is attached here
    self.my_render_target = render.render_target({
           [render.BUFFER_COLOR0_BIT] = color_params_rgba,
           [render.BUFFER_COLOR1_BIT] = color_params_rgba,
           [render.BUFFER_COLOR2_BIT] = color_params_float, })
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.delete_render_target(render_target)

deletes a render target

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

PARAMETERS

render_target - render target to delete

EXAMPLES

How to delete a render target:

 render.delete_render_target(self.my_render_target)


render.RENDER_TARGET_DEFAULT


render.set_render_target(render_target, [options])

sets a render target

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

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

[options] - optional table with behaviour parameters

transient
table 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.

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

sets the render target size

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

PARAMETERS

render_target - render target to set size for

width - new render target width

height - new render target height

EXAMPLES

Resize render targets to the current window size:

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.enable_texture(binding, handle_or_name, [buffer_type])

sets a texture to the render state

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

binding - texture binding, either by texture unit, string or hash for the sampler name that the texture should be bound to

handle_or_name - render target or texture handle that should be bound, or a named resource in the "Render Resource" table in the currently assigned .render file

[buffer_type] - optional buffer type from which to enable the texture. Note that this argument only applies to render targets. Defaults to render.BUFFER_COLOR_BIT. These values are supported:

If The render target has been created as depth and/or stencil textures, these buffer types can be used: If the render target has been created with multiple color attachments, these buffer types can be used to enable those textures as well. Currently 4 color attachments are supported:

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, 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
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', 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
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.disable_texture(binding)

disables a texture on the render state

Disables a texture that has previourly been enabled.

PARAMETERS

binding - texture binding, either by texture unit, string or hash that should be disabled

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.get_render_target_width(render_target, buffer_type)

retrieve the buffer width from a render target

Returns the specified buffer width from a render target.

PARAMETERS

render_target - render target from which to retrieve the buffer width

buffer_type - which type of buffer to retrieve the width from

RETURN

width - 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)
-- get the width of a render target resource
local w = render.get_render_target_width('my_rt_resource', render.BUFFER_COLOR_BIT)


render.get_render_target_height(render_target, buffer_type)

retrieve a buffer height from a render target

Returns the specified buffer height from a render target.

PARAMETERS

render_target - render target from which to retrieve the buffer height

buffer_type - which type of buffer to retrieve the height from

RETURN

height - 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)
-- get the height of a render target resource
local w = render.get_render_target_height('my_rt_resource', render.BUFFER_COLOR_BIT)


render.BUFFER_COLOR_BIT


render.BUFFER_COLOR0_BIT


render.BUFFER_COLOR1_BIT


render.BUFFER_COLOR2_BIT


render.BUFFER_COLOR3_BIT


render.BUFFER_DEPTH_BIT


render.BUFFER_STENCIL_BIT


render.clear(buffers)

clears the active render target

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

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

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.draw(predicate, [options])

draws all objects matching a predicate

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

predicate - predicate to draw for

[options] - optional table with properties:

frustum
vmath.matrix4 A frustum matrix used to cull renderable items. (E.g. local frustum = proj * view). default=nil
frustum_planes
int Determines which sides of the frustum will be used. Default is render.FRUSTUM_PLANES_SIDES.
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 constants:
local constants = render.constant_buffer()
constants.tint = vmath.vector4(1, 1, 1, 1)
render.draw(self.my_pred, {constants = constants})
Draw with predicate and frustum culling (without near+far planes):
local frustum = self.proj * self.view
render.draw(self.my_pred, {frustum = frustum})
Draw with predicate and frustum culling (with near+far planes):
local frustum = self.proj * self.view
render.draw(self.my_pred, {frustum = frustum, frustum_planes = render.FRUSTUM_PLANES_ALL})


render.draw_debug3d([options])

draws all 3d debug graphics

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

PARAMETERS

[options] - optional table with properties:

frustum
vmath.matrix4 A frustum matrix used to cull renderable items. (E.g. local frustum = proj * view). May be nil.
frustum_planes
int Determines which sides of the frustum will be used. Default is render.FRUSTUM_PLANES_SIDES.

EXAMPLES

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


render.set_view(matrix)

sets the view matrix

Sets the view matrix to use when rendering.

PARAMETERS

matrix - 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_projection(matrix)

sets the projection matrix

Sets the projection matrix to use when rendering.

PARAMETERS

matrix - 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.FRUSTUM_PLANES_SIDES


render.FRUSTUM_PLANES_ALL


render.BLEND_ZERO


render.BLEND_ONE


render.BLEND_SRC_COLOR


render.BLEND_ONE_MINUS_SRC_COLOR


render.BLEND_DST_COLOR


render.BLEND_ONE_MINUS_DST_COLOR


render.BLEND_SRC_ALPHA


render.BLEND_ONE_MINUS_SRC_ALPHA


render.BLEND_DST_ALPHA


render.BLEND_ONE_MINUS_DST_ALPHA


render.BLEND_SRC_ALPHA_SATURATE


render.BLEND_CONSTANT_COLOR


render.BLEND_ONE_MINUS_CONSTANT_COLOR


render.BLEND_CONSTANT_ALPHA


render.BLEND_ONE_MINUS_CONSTANT_ALPHA


render.set_blend_func(source_factor, destination_factor)

sets the blending function

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:

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 - source factor

destination_factor - 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(red, green, blue, alpha)

sets the color mask

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 - red mask

green - green mask

blue - blue mask

alpha - alpha mask

EXAMPLES

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


render.set_depth_mask(depth)

sets the depth mask

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 - depth mask

EXAMPLES

How to turn off writing to the depth buffer:

render.set_depth_mask(false)


render.set_stencil_mask(mask)

sets the stencil 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 - stencil mask

EXAMPLES

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


render.COMPARE_FUNC_NEVER


render.COMPARE_FUNC_LESS


render.COMPARE_FUNC_LEQUAL


render.COMPARE_FUNC_GREATER


render.COMPARE_FUNC_GEQUAL


render.COMPARE_FUNC_EQUAL


render.COMPARE_FUNC_NOTEQUAL


render.COMPARE_FUNC_ALWAYS


render.set_depth_func(func)

sets the depth test function

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:

The depth function is initially set to render.COMPARE_FUNC_LESS.

PARAMETERS

func - 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_stencil_func(func, ref, mask)

sets the stencil test function

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:

PARAMETERS

func - stencil test function, see the description for available values

ref - reference value for the stencil test

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


render.STENCIL_OP_ZERO


render.STENCIL_OP_REPLACE


render.STENCIL_OP_INCR


render.STENCIL_OP_INCR_WRAP


render.STENCIL_OP_DECR


render.STENCIL_OP_DECR_WRAP


render.STENCIL_OP_INVERT


render.set_stencil_op(sfail, dpfail, dppass)

sets the stencil operator

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:

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 - action to take when the stencil test fails

dpfail - the stencil action when the stencil test passes

dppass - 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.FACE_FRONT


render.FACE_BACK


render.FACE_FRONT_AND_BACK


render.set_cull_face(face_type)

sets the cull face

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 - face type

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_polygon_offset(factor, units)

sets the polygon offset

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 - polygon offset factor

units - polygon offset units

EXAMPLES

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


render.get_width()

gets the window width, as specified for the project

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.

RETURN

width - specified window width (number)

EXAMPLES

Get the width of the window.

local w = render.get_width()


render.get_height()

gets the window height, as specified for the project

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.

RETURN

height - specified window height

EXAMPLES

Get the height of the window

local h = render.get_height()


render.get_window_width()

gets the actual 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.

RETURN

width - actual window width

EXAMPLES

Get the actual width of the window

local w = render.get_window_width()


render.get_window_height()

gets the actual 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.

RETURN

height - actual window height

EXAMPLES

Get the actual height of the window

local h = render.get_window_height()


render.predicate(tags)

creates a new 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

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

RETURN

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.enable_material(material_id)

enables a material

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

disables the currently enabled 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()