Version: stable
FUNCTION | |
---|---|
render.constant_buffer() | create a new constant buffer. |
render.enable_state() | enables a render state |
render.disable_state() | disables a render state |
render.set_viewport() | sets the render viewport |
render.render_target() | creates a new render target |
render.delete_render_target() | deletes a render target |
render.set_render_target() | sets a render target |
render.set_render_target_size() | sets the render target size |
render.enable_texture() | enables a texture for a render target |
render.disable_texture() | disables a texture for a render target |
render.get_render_target_width() | retrieve the buffer width from a render target |
render.get_render_target_height() | retrieve a buffer height from a render target |
render.clear() | clears the active render target |
render.draw() | draws all objects matching a predicate |
render.draw_debug3d() | draws all 3d debug graphics |
render.set_view() | sets the view matrix |
render.set_projection() | sets the projection matrix |
render.set_blend_func() | sets the blending function |
render.set_color_mask() | sets the color mask |
render.set_depth_mask() | sets the depth mask |
render.set_stencil_mask() | sets the stencil mask |
render.set_depth_func() | sets the depth test function |
render.set_stencil_func() | sets the stencil test function |
render.set_stencil_op() | sets the stencil operator |
render.set_cull_face() | sets the cull face |
render.set_polygon_offset() | sets the polygon offset |
render.get_width() | gets the window width, as specified for the project |
render.get_height() | gets the window height, as specified for the project |
render.get_window_width() | gets the actual window width |
render.get_window_height() | gets the actual window height |
render.predicate() | creates a new render predicate |
render.enable_material() | enables a material |
render.disable_material() | disables the currently enabled material |
MESSAGE | |
---|---|
draw_debug_text | draw a text on the screen |
draw_line | draw a line on the screen |
window_resized | reports a window size change |
resize | resizes the window |
clear_color | set clear color |
render.constant_buffer()
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
RETURNS
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)
render.draw(self.my_pred, constants)
render.enable_state(state)
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)
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)
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.render_target(name,parameters)
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 |
render target name |
parameters |
table of buffer parameters, see the description for available keys and values |
RETURNS
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.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)
PARAMETERS
render_target |
render target to delete |
EXAMPLES
How to delete a render target:render.delete_render_target(self.my_render_target)
render.set_render_target(render_target,[options])
PARAMETERS
render_target |
render target to set. render.RENDER_TARGET_DEFAULT to set the default render target |
[options] |
optional table with behaviour parameters
|
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 supportfunction 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_target,width,height)
PARAMETERS
render_target |
render target to set size for |
width |
new render target width |
height |
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.enable_texture(unit,render_target,buffer_type)
PARAMETERS
unit |
texture unit to enable texture for |
render_target |
render target from which to enable the specified texture unit |
buffer_type |
buffer type from which to enable the texture
|
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.disable_texture(unit)
PARAMETERS
unit |
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.get_render_target_width(render_target,buffer_type)
PARAMETERS
render_target |
render target from which to retrieve the buffer width |
buffer_type |
which type of buffer to retrieve the width from
|
RETURNS
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)
render.get_render_target_height(render_target,buffer_type)
PARAMETERS
render_target |
render target from which to retrieve the buffer height |
buffer_type |
which type of buffer to retrieve the height from
|
RETURNS
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)
render.clear(buffers)
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,[constants])
PARAMETERS
predicate |
predicate to draw for |
[constants] |
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
local constants = render.constant_buffer() constants.tint = vmath.vector4(1, 1, 1, 1) render.draw(self.my_pred, constants)
render.draw_debug3d()
PARAMETERS
EXAMPLES
function update(self, dt) -- draw debug visualization render.draw_debug3d() end
render.set_view(matrix)
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)
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.set_blend_func(source_factor,destination_factor)
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 |
(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)
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)
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)
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.set_depth_func(func)
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)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)
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 |
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.set_stencil_op(sfail,dpfail,dppass)
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 |
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.set_cull_face(face_type)
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)
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()
PARAMETERS
RETURNS
width |
specified window width (number) |
EXAMPLES
Get the width of the window.local w = render.get_width()
render.get_height()
PARAMETERS
RETURNS
height |
specified window height |
EXAMPLES
Get the height of the windowlocal h = render.get_height()
render.get_window_width()
PARAMETERS
RETURNS
width |
actual window width |
EXAMPLES
Get the actual width of the windowlocal w = render.get_window_width()
render.get_window_height()
PARAMETERS
RETURNS
height |
actual window height |
EXAMPLES
Get the actual height of the windowlocal h = render.get_window_height()
render.predicate(tags)
64
.
PARAMETERS
tags |
table of tags that the predicate should match. The tags can be of either hash or string type |
RETURNS
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)
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()
PARAMETERS
EXAMPLES
Enable material named "glow", then draw my_pred with it.render.enable_material("glow") render.draw(self.my_pred) render.disable_material()
draw a text on the screen
Draw a text on the screen. This should be used for debugging purposes only.
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 a line on the screen
Draw a line on the screen. This should mostly be used for debugging purposes.
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) } )
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.
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
resizes the window
Set the size of the game window. Only works on desktop platforms.
height |
the new window height |
width |
the new window width |
EXAMPLES
msg.post("@render:", "resize", { width = 1024, height = 768 } )
set clear color
Set render clear color. This is the color that appears on the screen where nothing is rendered, i.e. background.
color |
color to use as clear color |
EXAMPLES
msg.post("@render:", "clear_color", { color = vmath.vector4(1, 0, 0, 0) } )