render5 new1 changed
Rendering API documentation
Functions
render.clear(buffers: LuaMap<render.ClearBufferKey, number | Vector4>): voidrender.constant_buffer():Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | ConstantArray<Vector4> | ConstantArray<Matrix4> }render.delete_render_target(render_target:Opaque<"render_target">): voidrender.disable_material(): voidrender.disable_state(state: Exclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>): voidrender.disable_texture(binding: string | Hash | number): voidrender.dispatch_compute(x: number, y: number, z: number, options?:render.DispatchOptions): voidrender.draw(2 overloads): voidrender.draw_debug3d(options?:render.DebugDrawOptions): voidrender.enable_material(material_id: string | Hash): voidrender.enable_state(state: Exclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>): voidrender.enable_texture(binding: number | string | Hash, handle_or_name:Opaque<"texture"> | string | Hash |Opaque<"render_target"> | number, buffer_type?:graphics.BufferType): voidrender.get_height(): numberrender.get_render_target_height(render_target:Opaque<"render_target"> | string | Hash, buffer_type:graphics.BufferType): numberrender.get_render_target_width(render_target:Opaque<"render_target"> | string | Hash, buffer_type:graphics.BufferType): numberrender.get_width(): numberrender.get_window_height(): numberrender.get_window_width(): numberrender.predicate(tags: (string | Hash)[]):Opaque<"render_predicate">render.render_target(2 overloads):Opaque<"render_target">Crender.set_blend_equation_separate(equation_color:graphics.BlendEquation, equation_alpha:graphics.BlendEquation): voidNrender.set_blend_func(source_factor:graphics.BlendFactor, destination_factor:graphics.BlendFactor): voidrender.set_blend_func_separate(source_factor_color:graphics.BlendFactor, destination_factor_color:graphics.BlendFactor, source_factor_alpha:graphics.BlendFactor, destination_factor_alpha:graphics.BlendFactor): voidNrender.set_camera(camera?: Url | number | string | Hash, options?:render.CameraOptions): voidrender.set_color_mask(red: boolean, green: boolean, blue: boolean, alpha: boolean): voidrender.set_compute(compute?: string | Hash): voidrender.set_cull_face(face_type:graphics.FaceType): voidrender.set_depth_func(func:graphics.CompareFunc): voidrender.set_depth_mask(depth: boolean): voidrender.set_listener(callback?: (self: unknown, event_type: render.ContextEvent) => void): voidrender.set_polygon_offset(factor: number, units: number): voidrender.set_projection(matrix: Matrix4): voidrender.set_render_target(2 overloads): voidrender.set_render_target_size(render_target:Opaque<"render_target"> | string | Hash, width: number, height: number): voidrender.set_stencil_func(func:graphics.CompareFunc, ref: number, mask: number): voidrender.set_stencil_mask(mask: number): voidrender.set_stencil_op(sfail:graphics.StencilOp, dpfail:graphics.StencilOp, dppass:graphics.StencilOp): voidrender.set_view(matrix: Matrix4): voidrender.set_viewport(x: number, y: number, width: number, height: number): void
render.clear(buffers: LuaMap<render.ClearBufferKey, number | Vector4>): void
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.
// Clear the color buffer and the depth buffer.
const buffers = new LuaMap<render.ClearBufferKey, number | Vector4>();
buffers.set(graphics.BUFFER_TYPE_COLOR0_BIT, vmath.vector4(0, 0, 0, 0));
buffers.set(graphics.BUFFER_TYPE_DEPTH_BIT, 1);
render.clear(buffers);render.clear({[graphics.BUFFER_TYPE_COLOR0_BIT] = vmath.vector4(0, 0, 0, 0), [graphics.BUFFER_TYPE_DEPTH_BIT] = 1})Parameters
buffers:LuaMap<render.ClearBufferKey, number | Vector4>— table with keys specifying which buffers to clear and values set to clear values. Available keys are:graphics.BUFFER_TYPE_COLOR0_BITgraphics.BUFFER_TYPE_DEPTH_BITgraphics.BUFFER_TYPE_STENCIL_BIT
render.constant_buffer(): Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | ConstantArray<Vector4> | ConstantArray<Matrix4> }
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().
Set a "tint" constant in a constant buffer in the render script:
const constants = render.constant_buffer();
constants.tint = vmath.vector4(1, 1, 1, 1);local constants = render.constant_buffer()
constants.tint = vmath.vector4(1, 1, 1, 1)Then use the constant buffer when drawing a predicate:
export default defineRenderScript({
init() {
return { my_pred: render.predicate([hash("my_tag")]) };
},
update(self, dt) {
const constants = render.constant_buffer();
render.draw(self.my_pred, { constants });
},
});render.draw(self.my_pred, {constants = constants})The constant buffer also supports array values by specifying constants in a table:
const constants = render.constant_buffer();
constants.light_colors = [];
constants.light_colors[0] = vmath.vector4(1, 0, 0, 1);
constants.light_colors[1] = vmath.vector4(0, 1, 0, 1);
constants.light_colors[2] = vmath.vector4(0, 0, 1, 1);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:
const 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 constants to the array
constants.light_colors[3] = vmath.vector4(1, 1, 1, 1);local constants = render.constant_buffer()
constants.light_colors = {
vmath.vector4(1, 0, 0, 1)
vmath.vector4(0, 1, 0, 1)
vmath.vector4(0, 0, 1, 1)
}
-- Add more constant to the array
constants.light_colors[4] = vmath.vector4(1, 1, 1, 1)Returns
buffer:Opaque<"constant_buffer"> & { [name: string]: Vector4 | Matrix4 | ConstantArray<Vector4> | ConstantArray<Matrix4> }— new constant buffer
render.delete_render_target(render_target: Opaque<"render_target">): void
Deletes a render target created by a render script. You cannot delete a render target resource.
export default defineRenderScript({
init() {
return { my_render_target: render.render_target("my_target", {}) };
},
// A render script has no final hook, so free the target on a message.
on_message(self, message_id) {
if (message_id === hash("release_target")) {
// How to delete a render target:
render.delete_render_target(self.my_render_target);
}
},
}); render.delete_render_target(self.my_render_target)Parameters
render_target:Opaque<"render_target">— render target to delete
render.disable_material(): void
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.
export default defineRenderScript({
init() {
return { my_pred: render.predicate([hash("my_tag")]) };
},
update(self, dt) {
// Enable material named "glow", then draw my_pred with it.
render.enable_material("glow");
render.draw(self.my_pred);
render.disable_material();
},
});render.enable_material("glow")
render.draw(self.my_pred)
render.disable_material()render.disable_state(state: Exclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>): void
Disables a render state.
export default defineRenderScript({
init() {
return { tile_pred: render.predicate([hash("tile")]) };
},
update(self, dt) {
// Disable face culling when drawing the tile predicate:
render.disable_state(graphics.STATE_CULL_FACE);
render.draw(self.tile_pred);
},
});render.disable_state(graphics.STATE_CULL_FACE)
render.draw(self.tile_pred)Parameters
state:Exclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>— state to disablegraphics.STATE_DEPTH_TESTgraphics.STATE_STENCIL_TESTgraphics.STATE_BLENDgraphics.STATE_ALPHA_TEST( not available on iOS and Android)graphics.STATE_CULL_FACEgraphics.STATE_POLYGON_OFFSET_FILL
render.disable_texture(binding: string | Hash | number): void
Disables a texture that has previourly been enabled.
export default defineRenderScript({
init() {
// the engine registers a texture format only when the driver supports it
const format = graphics.TEXTURE_FORMAT_RGBA;
if (format === undefined) return undefined;
const color_params = {
format,
width: render.get_window_width(),
height: render.get_window_height(),
};
return {
my_render_target: render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params }),
my_pred: render.predicate([hash("my_tag")]),
};
},
update(self, dt) {
if (self === undefined) return;
render.enable_texture(0, self.my_render_target, graphics.BUFFER_TYPE_COLOR0_BIT);
// draw a predicate with the render target available as texture 0 in the predicate
// material shader.
render.draw(self.my_pred);
// done, disable the texture
render.disable_texture(0);
},
});function update(self, dt)
render.enable_texture(0, self.my_render_target, graphics.BUFFER_TYPE_COLOR0_BIT)
-- draw a predicate with the render target available as texture 0 in the predicate
-- material shader.
render.draw(self.my_pred)
-- done, disable the texture
render.disable_texture(0)
endParameters
binding:string | Hash | number— texture binding, either by texture unit, string or hash that should be disabled
render.dispatch_compute(x: number, y: number, z: number, options?: render.DispatchOptions): void
Dispatches the currently enabled compute program. The dispatch call takes three arguments x,y,z which constitutes the 'global working group' of the compute dispatch. Together with the 'local working group' specified in the compute shader as a layout qualifier, these two sets of parameters forms the number of invocations the compute shader will execute. An optional constant buffer can be provided to override the default constants. If no constants buffer is provided, a default system constants buffer is used containing constants as defined in the compute program.
export default defineRenderScript({
init() {
// the engine registers a texture format only when the driver supports it
const format = graphics.TEXTURE_FORMAT_RGBA;
if (format === undefined) return undefined;
const color_params = {
format,
width: render.get_window_width(),
height: render.get_window_height(),
};
return {
backing_texture: resource.get_texture_info("/main/backing.texturec").handle,
scene_rt: render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params }),
};
},
update(self, dt) {
if (self === undefined) return;
render.set_compute("bloom");
render.enable_texture(0, self.backing_texture);
render.enable_texture(1, self.scene_rt);
render.dispatch_compute(128, 128, 1);
render.set_compute();
},
});function init(self)
local color_params = { format = graphics.TEXTURE_FORMAT_RGBA,
width = render.get_window_width(),
height = render.get_window_height()}
self.scene_rt = render.render_target({[graphics.BUFFER_TYPE_COLOR0_BIT] = color_params})
end
function update(self, dt)
render.set_compute("bloom")
render.enable_texture(0, self.backing_texture)
render.enable_texture(1, self.scene_rt)
render.dispatch_compute(128, 128, 1)
render.set_compute()
endDispatch a compute program with a constant buffer:
const constants = render.constant_buffer();
constants.tint = vmath.vector4(1, 1, 1, 1);
render.dispatch_compute(32, 32, 32, { constants });local constants = render.constant_buffer()
constants.tint = vmath.vector4(1, 1, 1, 1)
render.dispatch_compute(32, 32, 32, {constants = constants})Parameters
x:number— global work group size Xy:number— global work group size Yz:number— global work group size Zoptions?:render.DispatchOptions— optional compute-dispatch options
render.draw(2 overloads): void
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.
(predicate: Opaque<"render_predicate">)(predicate: Opaque<"render_predicate">, options: render.DrawOptions)Parameters
predicate:Opaque<"render_predicate">— predicate to draw foroptions:render.DrawOptions— optional draw options
export default defineRenderScript({
init() {
// define a predicate matching anything with material tag "my_tag"
return { my_pred: render.predicate([hash("my_tag")]) };
},
update(self, dt) {
// draw everything in the my_pred predicate
render.draw(self.my_pred);
},
});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)
endDraw predicate with constants:
function draw_tinted(self: { my_pred: Opaque<"render_predicate"> }) {
const constants = render.constant_buffer();
constants.tint = vmath.vector4(1, 1, 1, 1);
render.draw(self.my_pred, { 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):
function draw_culled(self: { my_pred: Opaque<"render_predicate">; proj: Matrix4; view: Matrix4 }) {
const frustum = self.proj.mul(self.view);
render.draw(self.my_pred, { frustum });
}local frustum = self.proj * self.view
render.draw(self.my_pred, {frustum = frustum})Draw with predicate and frustum culling (with near+far planes):
function draw_culled(self: { my_pred: Opaque<"render_predicate">; proj: Matrix4; view: Matrix4 }) {
const frustum = self.proj.mul(self.view);
render.draw(self.my_pred, { frustum, frustum_planes: render.FRUSTUM_PLANES_ALL });
}local frustum = self.proj * self.view
render.draw(self.my_pred, {frustum = frustum, frustum_planes = render.FRUSTUM_PLANES_ALL})render.draw_debug3d(options?: render.DebugDrawOptions): void
Draws all 3d debug graphics such as lines drawn with "draw_line" messages and physics visualization.
export default defineRenderScript({
update(self, dt) {
// draw debug visualization
render.draw_debug3d();
},
});function update(self, dt)
-- draw debug visualization
render.draw_debug3d()
endParameters
options?:render.DebugDrawOptions— optional debug-draw options
render.enable_material(material_id: string | Hash): void
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.
export default defineRenderScript({
init() {
return { my_pred: render.predicate([hash("my_tag")]) };
},
update(self, dt) {
// Enable material named "glow", then draw my_pred with it.
render.enable_material("glow");
render.draw(self.my_pred);
render.disable_material();
},
});render.enable_material("glow")
render.draw(self.my_pred)
render.disable_material()Parameters
material_id:string | Hash— material id to enable
render.enable_state(state: Exclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>): void
Enables a particular render state. The state will be enabled until disabled.
export default defineRenderScript({
init() {
return { gui_pred: render.predicate([hash("gui")]) };
},
update(self, dt) {
// Enable stencil test when drawing the gui predicate, then disable it:
render.enable_state(graphics.STATE_STENCIL_TEST);
render.draw(self.gui_pred);
render.disable_state(graphics.STATE_STENCIL_TEST);
},
});render.enable_state(graphics.STATE_STENCIL_TEST)
render.draw(self.gui_pred)
render.disable_state(graphics.STATE_STENCIL_TEST)Parameters
state:Exclude<graphics.State, typeof graphics.STATE_ALPHA_TEST_SUPPORTED | typeof graphics.STATE_SCISSOR_TEST>— state to enablegraphics.STATE_DEPTH_TESTgraphics.STATE_STENCIL_TESTgraphics.STATE_BLENDgraphics.STATE_ALPHA_TEST( not available on iOS and Android)graphics.STATE_CULL_FACEgraphics.STATE_POLYGON_OFFSET_FILL
render.enable_texture(binding: number | string | Hash, handle_or_name: Opaque<"texture"> | string | Hash | Opaque<"render_target"> | number, buffer_type?: graphics.BufferType): void
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.
export default defineRenderScript({
init() {
// the engine registers a texture format only when the driver supports it
const format = graphics.TEXTURE_FORMAT_RGBA;
if (format === undefined) return undefined;
const color_params = {
format,
width: render.get_window_width(),
height: render.get_window_height(),
};
return {
my_render_target: render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params }),
my_pred: render.predicate([hash("my_tag")]),
};
},
update(self, dt) {
if (self === undefined) return;
// enable target so all drawing is done to it
render.set_render_target(self.my_render_target);
// draw a predicate to the render target
render.draw(self.my_pred);
// disable target
render.set_render_target(render.RENDER_TARGET_DEFAULT);
render.enable_texture(0, self.my_render_target, graphics.BUFFER_TYPE_COLOR0_BIT);
// draw a predicate with the render target available as texture 0 in the predicate
// material shader.
render.draw(self.my_pred);
},
});function update(self, dt)
-- enable target so all drawing is done to it
render.set_render_target(self.my_render_target)
-- draw a predicate to the render target
render.draw(self.my_pred)
-- disable target
render.set_render_target(render.RENDER_TARGET_DEFAULT)
render.enable_texture(0, self.my_render_target, graphics.BUFFER_TYPE_COLOR0_BIT)
-- draw a predicate with the render target available as texture 0 in the predicate
-- material shader.
render.draw(self.my_pred)
endexport default defineRenderScript({
init() {
return { my_pred: render.predicate([hash("my_tag")]) };
},
update(self, dt) {
// enable render target by resource id
render.set_render_target("my_rt_resource");
render.draw(self.my_pred);
render.set_render_target(render.RENDER_TARGET_DEFAULT);
render.enable_texture(0, "my_rt_resource", graphics.BUFFER_TYPE_COLOR0_BIT);
// draw a predicate with the render target available as texture 0 in the predicate
// material shader.
render.draw(self.my_pred);
},
});function update(self, dt)
-- enable render target by resource id
render.set_render_target('my_rt_resource')
render.draw(self.my_pred)
render.set_render_target(render.RENDER_TARGET_DEFAULT)
render.enable_texture(0, 'my_rt_resource', graphics.BUFFER_TYPE_COLOR0_BIT)
-- draw a predicate with the render target available as texture 0 in the predicate
-- material shader.
render.draw(self.my_pred)
endexport default defineRenderScript({
init() {
return { my_texture_handle: resource.get_texture_info("/main/my_texture.texturec").handle };
},
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);
},
});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)
endParameters
binding:number | string | Hash— texture binding, either by texture unit, string or hash for the sampler name that the texture should be bound tohandle_or_name:Opaque<"texture"> | string | Hash | Opaque<"render_target"> | number— render target or texture handle that should be bound, or a named resource in the "Render Resource" table in the currently assigned .render filebuffer_type?:graphics.BufferType— optional render-target attachment. Defaults tographics.BUFFER_TYPE_COLOR0_BIT. Depth and stencil attachments must have been created as textures; color attachments beyond the first require a render target with multiple color attachments (up to four are supported).
render.get_height(): number
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.
// Get the height of the window
const h = render.get_height();local h = render.get_height()Returns
height:number— specified window height
render.get_render_target_height(render_target: Opaque<"render_target"> | string | Hash, buffer_type: graphics.BufferType): number
Returns the specified buffer height from a render target.
export default defineRenderScript({
init() {
// the engine registers a texture format only when the driver supports it
const format = graphics.TEXTURE_FORMAT_RGBA;
if (format === undefined) return undefined;
const color_params = {
format,
width: render.get_window_width(),
height: render.get_window_height(),
};
return {
target_right: render.render_target("right", {
[graphics.BUFFER_TYPE_COLOR0_BIT]: color_params,
}),
};
},
update(self, dt) {
if (self === undefined) return;
// get the height of the render target color buffer
const h = render.get_render_target_height(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT);
// get the height of a render target resource
const w = render.get_render_target_height("my_rt_resource", graphics.BUFFER_TYPE_COLOR0_BIT);
},
});-- get the height of the render target color buffer
local h = render.get_render_target_height(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT)
-- get the height of a render target resource
local w = render.get_render_target_height('my_rt_resource', graphics.BUFFER_TYPE_COLOR0_BIT)Parameters
render_target:Opaque<"render_target"> | string | Hash— render target from which to retrieve the buffer heightbuffer_type:graphics.BufferType— which type of buffer to retrieve the height fromgraphics.BUFFER_TYPE_COLOR0_BITgraphics.BUFFER_TYPE_DEPTH_BITgraphics.BUFFER_TYPE_STENCIL_BIT
Returns
height:number— the height of the render target buffer texture
render.get_render_target_width(render_target: Opaque<"render_target"> | string | Hash, buffer_type: graphics.BufferType): number
Returns the specified buffer width from a render target.
export default defineRenderScript({
init() {
// the engine registers a texture format only when the driver supports it
const format = graphics.TEXTURE_FORMAT_RGBA;
if (format === undefined) return undefined;
const color_params = {
format,
width: render.get_window_width(),
height: render.get_window_height(),
};
return {
target_right: render.render_target("right", {
[graphics.BUFFER_TYPE_COLOR0_BIT]: color_params,
}),
};
},
update(self, dt) {
if (self === undefined) return;
// get the width of the render target color buffer
const w = render.get_render_target_width(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT);
// get the width of a render target resource
const w2 = render.get_render_target_width("my_rt_resource", graphics.BUFFER_TYPE_COLOR0_BIT);
},
});-- get the width of the render target color buffer
local w = render.get_render_target_width(self.target_right, graphics.BUFFER_TYPE_COLOR0_BIT)
-- get the width of a render target resource
local w = render.get_render_target_width('my_rt_resource', graphics.BUFFER_TYPE_COLOR0_BIT)Parameters
render_target:Opaque<"render_target"> | string | Hash— render target from which to retrieve the buffer widthbuffer_type:graphics.BufferType— which type of buffer to retrieve the width fromgraphics.BUFFER_TYPE_COLOR0_BITgraphics.BUFFER_TYPE_COLOR[x]_BIT(x: [0..3], if supported!)graphics.BUFFER_TYPE_DEPTH_BITgraphics.BUFFER_TYPE_STENCIL_BIT
Returns
width:number— the width of the render target buffer texture
render.get_width(): number
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.
// Get the width of the window.
const w = render.get_width();local w = render.get_width()Returns
width:number— specified window width
render.get_window_height(): number
Returns the actual physical window height. Note that this value might differ from the logical height that is set in the "game.project" settings.
// Get the actual height of the window
const h = render.get_window_height();local h = render.get_window_height()Returns
height:number— actual window height
render.get_window_width(): number
Returns the actual physical window width. Note that this value might differ from the logical width that is set in the "game.project" settings.
// Get the actual width of the window
const w = render.get_window_width();local w = render.get_window_width()Returns
width:number— actual window width
render.predicate(tags: (string | Hash)[]): Opaque<"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.
// Create a new render predicate containing all visual objects that
// have a material with material tags "opaque" AND "smoke".
const p = render.predicate([hash("opaque"), hash("smoke")]);local p = render.predicate({hash("opaque"), hash("smoke")})Parameters
tags:(string | Hash)[]— table of tags that the predicate should match. The tags can be of either hash or string type
Returns
predicate:Opaque<"render_predicate">— new predicate
render.render_target(2 overloads): Opaque<"render_target">C
(parameters: render.RenderTargetParams)Creates a new render target according to the supplied specification table. The parameter table is keyed by buffer type, with one parameter table per attachment; see the reference for the available keys and values.
How to create a new render target and draw to it:
// How to create a new render target and draw to it: export default defineRenderScript({ init() { // the engine registers a texture format only when the driver supports it const format = graphics.TEXTURE_FORMAT_RGBA; if (format === undefined) return undefined; // render target buffer parameters const color_params = { format, width: render.get_window_width(), height: render.get_window_height(), min_filter: graphics.TEXTURE_FILTER_LINEAR, mag_filter: graphics.TEXTURE_FILTER_LINEAR, u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, }; const depth_params = { format: graphics.TEXTURE_FORMAT_DEPTH, width: render.get_window_width(), height: render.get_window_height(), u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, }; return { my_render_target: render.render_target({ sample_count: 4, [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params, [graphics.BUFFER_TYPE_DEPTH_BIT]: depth_params, }), my_pred: render.predicate([hash("my_tag")]), }; }, update(self, dt) { if (self === undefined) return; // 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); }, });function init(self) -- render target buffer parameters local color_params = { format = graphics.TEXTURE_FORMAT_RGBA, width = render.get_window_width(), height = render.get_window_height(), min_filter = graphics.TEXTURE_FILTER_LINEAR, mag_filter = graphics.TEXTURE_FILTER_LINEAR, u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE } local depth_params = { format = graphics.TEXTURE_FORMAT_DEPTH, width = render.get_window_width(), height = render.get_window_height(), u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE } self.my_render_target = render.render_target({sample_count = 4, [graphics.BUFFER_TYPE_COLOR0_BIT] = color_params, [graphics.BUFFER_TYPE_DEPTH_BIT] = depth_params }) end function update(self, dt) -- enable target so all drawing is done to it render.set_render_target(self.my_render_target) -- draw a predicate to the render target render.draw(self.my_pred) endHow to create a render target with multiple outputs:
// How to create a render target with multiple outputs: export default defineRenderScript({ init() { // the engine registers a texture format or an extra color attachment only when the driver supports it const format = graphics.TEXTURE_FORMAT_RGBA; const rg32f = graphics.TEXTURE_FORMAT_RG32F; const color1 = graphics.BUFFER_TYPE_COLOR1_BIT; const color2 = graphics.BUFFER_TYPE_COLOR2_BIT; if (format === undefined || rg32f === undefined || color1 === undefined || color2 === undefined) return undefined; // render target buffer parameters const color_params_rgba = { format, width: render.get_window_width(), height: render.get_window_height(), min_filter: graphics.TEXTURE_FILTER_LINEAR, mag_filter: graphics.TEXTURE_FILTER_LINEAR, u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, }; const color_params_float = { format: rg32f, width: render.get_window_width(), height: render.get_window_height(), min_filter: graphics.TEXTURE_FILTER_LINEAR, mag_filter: graphics.TEXTURE_FILTER_LINEAR, u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, }; // Create a render target with three color attachments // Note: No depth buffer is attached here return { my_render_target: render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params_rgba, [color1]: color_params_rgba, [color2]: color_params_float, }), my_pred: render.predicate([hash("my_tag")]), }; }, update(self, dt) { if (self === undefined) return; // set target so all drawing is done to it render.set_render_target(self.my_render_target); // draw a predicate to the render target render.draw(self.my_pred); }, });function init(self) -- render target buffer parameters local color_params_rgba = { format = graphics.TEXTURE_FORMAT_RGBA, width = render.get_window_width(), height = render.get_window_height(), min_filter = graphics.TEXTURE_FILTER_LINEAR, mag_filter = graphics.TEXTURE_FILTER_LINEAR, u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE } local color_params_float = { format = graphics.TEXTURE_FORMAT_RG32F, width = render.get_window_width(), height = render.get_window_height(), min_filter = graphics.TEXTURE_FILTER_LINEAR, mag_filter = graphics.TEXTURE_FILTER_LINEAR, u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE } -- Create a render target with three color attachments -- Note: No depth buffer is attached here self.my_render_target = render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT] = color_params_rgba, [graphics.BUFFER_TYPE_COLOR1_BIT] = color_params_rgba, [graphics.BUFFER_TYPE_COLOR2_BIT] = color_params_float, }) end function update(self, dt) -- set target so all drawing is done to it render.set_render_target(self.my_render_target) -- draw a predicate to the render target render.draw(self.my_pred) endParameters
parameters:render.render_target_params— render-target parameters
(name: string, parameters: render.RenderTargetParams)Creates a new named render target according to the supplied specification table. The name is used by the profiler and by render target lookups.
How to create a new render target and draw to it:
// How to create a new render target and draw to it: export default defineRenderScript({ init() { // the engine registers a texture format only when the driver supports it const format = graphics.TEXTURE_FORMAT_RGBA; if (format === undefined) return undefined; // render target buffer parameters const color_params = { format, width: render.get_window_width(), height: render.get_window_height(), min_filter: graphics.TEXTURE_FILTER_LINEAR, mag_filter: graphics.TEXTURE_FILTER_LINEAR, u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, }; const depth_params = { format: graphics.TEXTURE_FORMAT_DEPTH, width: render.get_window_width(), height: render.get_window_height(), u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, }; return { my_render_target: render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params, [graphics.BUFFER_TYPE_DEPTH_BIT]: depth_params, }), my_pred: render.predicate([hash("my_tag")]), }; }, update(self, dt) { if (self === undefined) return; // 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); }, });function init(self) -- render target buffer parameters local color_params = { format = graphics.TEXTURE_FORMAT_RGBA, width = render.get_window_width(), height = render.get_window_height(), min_filter = graphics.TEXTURE_FILTER_LINEAR, mag_filter = graphics.TEXTURE_FILTER_LINEAR, u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE } local depth_params = { format = graphics.TEXTURE_FORMAT_DEPTH, width = render.get_window_width(), height = render.get_window_height(), u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE } self.my_render_target = render.render_target({[graphics.BUFFER_TYPE_COLOR0_BIT] = color_params, [graphics.BUFFER_TYPE_DEPTH_BIT] = depth_params }) end function update(self, dt) -- enable target so all drawing is done to it render.set_render_target(self.my_render_target) -- draw a predicate to the render target render.draw(self.my_pred) endHow to create a render target with multiple outputs:
// How to create a render target with multiple outputs: export default defineRenderScript({ init() { // the engine registers a texture format or an extra color attachment only when the driver supports it const format = graphics.TEXTURE_FORMAT_RGBA; const rg32f = graphics.TEXTURE_FORMAT_RG32F; const color1 = graphics.BUFFER_TYPE_COLOR1_BIT; const color2 = graphics.BUFFER_TYPE_COLOR2_BIT; if (format === undefined || rg32f === undefined || color1 === undefined || color2 === undefined) return undefined; // render target buffer parameters const color_params_rgba = { format, width: render.get_window_width(), height: render.get_window_height(), min_filter: graphics.TEXTURE_FILTER_LINEAR, mag_filter: graphics.TEXTURE_FILTER_LINEAR, u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, }; const color_params_float = { format: rg32f, width: render.get_window_width(), height: render.get_window_height(), min_filter: graphics.TEXTURE_FILTER_LINEAR, mag_filter: graphics.TEXTURE_FILTER_LINEAR, u_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap: graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, }; // Create a render target with three color attachments // Note: No depth buffer is attached here return { my_render_target: render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params_rgba, [color1]: color_params_rgba, [color2]: color_params_float, }), my_pred: render.predicate([hash("my_tag")]), }; }, update(self, dt) { if (self === undefined) return; // set target so all drawing is done to it render.set_render_target(self.my_render_target); // draw a predicate to the render target render.draw(self.my_pred); }, });function init(self) -- render target buffer parameters local color_params_rgba = { format = graphics.TEXTURE_FORMAT_RGBA, width = render.get_window_width(), height = render.get_window_height(), min_filter = graphics.TEXTURE_FILTER_LINEAR, mag_filter = graphics.TEXTURE_FILTER_LINEAR, u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE } local color_params_float = { format = graphics.TEXTURE_FORMAT_RG32F, width = render.get_window_width(), height = render.get_window_height(), min_filter = graphics.TEXTURE_FILTER_LINEAR, mag_filter = graphics.TEXTURE_FILTER_LINEAR, u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE } -- Create a render target with three color attachments -- Note: No depth buffer is attached here self.my_render_target = render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT] = color_params_rgba, [graphics.BUFFER_TYPE_COLOR1_BIT] = color_params_rgba, [graphics.BUFFER_TYPE_COLOR2_BIT] = color_params_float, }) end function update(self, dt) -- set target so all drawing is done to it render.set_render_target(self.my_render_target) -- draw a predicate to the render target render.draw(self.my_pred) endParameters
name:string— render target nameparameters:Record<string | number, unknown>— table of buffer parameters, see the description for available keys and values
Returns
render_target:Opaque<"render_target">— new render target
render.set_blend_equation_separate(equation_color: graphics.BlendEquation, equation_alpha: graphics.BlendEquation): voidN
- Since Defold 1.13.0
Sets the blend equation with separate equations for the color and alpha channels.
render.set_blend_equation_separate(graphics.BLEND_EQUATION_ADD, graphics.BLEND_EQUATION_REVERSE_SUBTRACT);render.set_blend_equation_separate(graphics.BLEND_EQUATION_ADD,
graphics.BLEND_EQUATION_REVERSE_SUBTRACT)Parameters
equation_color:graphics.BlendEquation— color blend equationequation_alpha:graphics.BlendEquation— alpha blend equation
render.set_blend_func(source_factor: graphics.BlendFactor, destination_factor: graphics.BlendFactor): void
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.
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 (graphics.BLEND_FACTOR_SRC_ALPHA, graphics.BLEND_FACTOR_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.
// Set the blend func to the most common one:
render.set_blend_func(graphics.BLEND_FACTOR_SRC_ALPHA, graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA);render.set_blend_func(graphics.BLEND_FACTOR_SRC_ALPHA, graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA)Parameters
source_factor:graphics.BlendFactor— source factordestination_factor:graphics.BlendFactor— destination factor
render.set_blend_func_separate(source_factor_color: graphics.BlendFactor, destination_factor_color: graphics.BlendFactor, source_factor_alpha: graphics.BlendFactor, destination_factor_alpha: graphics.BlendFactor): voidN
- Since Defold 1.13.0
Sets the blend function with separate blend factors for the color and alpha channels.
render.set_blend_func_separate(graphics.BLEND_FACTOR_SRC_ALPHA, graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA, graphics.BLEND_FACTOR_ONE, graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA);render.set_blend_func_separate(graphics.BLEND_FACTOR_SRC_ALPHA,
graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA,
graphics.BLEND_FACTOR_ONE,
graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA)Parameters
source_factor_color:graphics.BlendFactor— source color blend factordestination_factor_color:graphics.BlendFactor— destination color blend factorsource_factor_alpha:graphics.BlendFactor— source alpha blend factordestination_factor_alpha:graphics.BlendFactor— destination alpha blend factor
render.set_camera(camera?: Url | number | string | Hash, options?: render.CameraOptions): void
Sets the current render camera to be used for rendering. If a render camera
has been set by the render script, the renderer will be using its projection and view matrix
during rendering. If a projection and/or view matrix has been set by the render script,
they will not be used until the current render camera has been reset by calling render.set_camera().
If the 'use_frustum' flag in the options table has been set to true, the renderer will automatically use the
camera frustum for frustum culling regardless of what frustum is being passed into the render.draw() function.
Note that the frustum plane option in render.draw can still be used together with the camera.
Set the current camera to be used for rendering
function draw_through_camera(self: { my_pred: Opaque<"render_predicate"> }) {
render.set_camera("main:/my_go#camera");
render.draw(self.my_pred);
render.set_camera(undefined);
}render.set_camera("main:/my_go#camera")
render.draw(self.my_pred)
render.set_camera(nil)Use the camera frustum for frustum culling together with a specific frustum plane option for the draw command
function draw_through_camera(self: { my_pred: Opaque<"render_predicate"> }) {
// The camera frustum will take precedence over the frustum plane option in render.draw
render.set_camera("main:/my_go#camera", { use_frustum: true });
// However, we can still customize the frustum planes regardless of the camera option!
render.draw(self.my_pred, { frustum_planes: render.FRUSTUM_PLANES_ALL });
render.set_camera();
}-- The camera frustum will take precedence over the frustum plane option in render.draw
render.set_camera("main:/my_go#camera", { use_frustum = true })
-- However, we can still customize the frustum planes regardless of the camera option!
render.draw(self.my_pred, { frustum_planes = render.FRUSTUM_PLANES_ALL })
render.set_camera()Parameters
camera?:Url | number | string | Hash— camera id to use, or nil to resetoptions?:render.CameraOptions— optional camera options
render.set_color_mask(red: boolean, green: boolean, blue: boolean, alpha: boolean): void
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.
// alpha cannot be written to frame buffer
render.set_color_mask(true, true, true, false);-- alpha cannot be written to frame buffer
render.set_color_mask(true, true, true, false)Parameters
red:boolean— red maskgreen:boolean— green maskblue:boolean— blue maskalpha:boolean— alpha mask
render.set_compute(compute?: string | Hash): void
The name of the compute program must be specified in the ".render" resource set in the "game.project" setting. If nil (or no arguments) are passed to this function, the current compute program will instead be disabled.
export default defineRenderScript({
init() {
return { backing_texture: "my_texture_resource" };
},
update(self, dt) {
// Enable compute program named "fractals", then dispatch it.
render.set_compute("fractals");
render.enable_texture(0, self.backing_texture);
render.dispatch_compute(128, 128, 1);
render.set_compute();
},
});render.set_compute("fractals")
render.enable_texture(0, self.backing_texture)
render.dispatch_compute(128, 128, 1)
render.set_compute()Parameters
compute?:string | Hash— compute id to use, or nil to disable
render.set_cull_face(face_type: graphics.FaceType): void
Specifies whether front- or back-facing polygons can be culled
when polygon culling is enabled. Polygon culling is initially disabled.
If mode is graphics.FACE_TYPE_FRONT_AND_BACK, no polygons are drawn, but other
primitives such as points and lines are drawn. The initial value for
face_type is graphics.FACE_TYPE_BACK.
// How to enable polygon culling and set front face culling:
render.enable_state(graphics.STATE_CULL_FACE);
render.set_cull_face(graphics.FACE_TYPE_FRONT);render.enable_state(graphics.STATE_CULL_FACE)
render.set_cull_face(graphics.FACE_TYPE_FRONT)Parameters
face_type:graphics.FaceType— face type
render.set_depth_func(func: graphics.CompareFunc): void
Specifies the function that should be used to compare each incoming pixel
depth value with the value present in the depth buffer.
The comparison is performed only if depth testing is enabled and specifies
the conditions under which a pixel will be drawn.
The depth function is initially set to graphics.COMPARE_FUNC_LESS.
// Enable depth test and set the depth test function to "not equal".
render.enable_state(graphics.STATE_DEPTH_TEST);
render.set_depth_func(graphics.COMPARE_FUNC_NOTEQUAL);render.enable_state(graphics.STATE_DEPTH_TEST)
render.set_depth_func(graphics.COMPARE_FUNC_NOTEQUAL)Parameters
func:graphics.CompareFunc— depth test function, see the description for available values
render.set_depth_mask(depth: boolean): void
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.
// How to turn off writing to the depth buffer:
render.set_depth_mask(false);render.set_depth_mask(false)Parameters
depth:boolean— depth mask
render.set_listener(callback?: (self: unknown, event_type: render.ContextEvent) => void): void
Set or remove the rendering-context event listener.
// Set listener and handle render context events.
// custom.render_script
export default defineRenderScript({
init() {
render.set_listener((self, event_type) => {
if (event_type === render.CONTEXT_EVENT_CONTEXT_LOST) {
// Some stuff when rendering context is lost
} else if (event_type === render.CONTEXT_EVENT_CONTEXT_RESTORED) {
// Start reload resources, reload game, etc.
}
});
},
});--- custom.render_script
function init(self)
render.set_listener(function(self, event_type)
if event_type == render.CONTEXT_EVENT_CONTEXT_LOST then
--- Some stuff when rendering context is lost
elseif event_type == render.CONTEXT_EVENT_CONTEXT_RESTORED then
--- Start reload resources, reload game, etc.
end
end)
endParameters
callback?:(self: unknown, event_type: render.ContextEvent) => void— A callback that receives all render related events. Passnilif want to remove listener.
render.set_polygon_offset(factor: number, units: number): void
Sets the scale and units used to calculate depth values.
If graphics.STATE_POLYGON_OFFSET_FILL is enabled, each fragment's depth value
is offset from its interpolated value (depending on the depth value of the
appropriate vertices). Polygon offset can be used when drawing decals, rendering
hidden-line images etc.
factor specifies a scale factor that is used to create a variable depth
offset for each polygon. The initial value is 0.
units is multiplied by an implementation-specific value to create a
constant depth offset. The initial value is 0.
The value of the offset is computed as factor × DZ + r × units
DZ is a measurement of the depth slope of the polygon which is the change in z (depth)
values divided by the change in either x or y coordinates, as you traverse a polygon.
The depth values are in window coordinates, clamped to the range [0, 1].
r is the smallest value that is guaranteed to produce a resolvable difference.
It's value is an implementation-specific constant.
The offset is added before the depth test is performed and before the
value is written into the depth buffer.
render.enable_state(graphics.STATE_POLYGON_OFFSET_FILL);
render.set_polygon_offset(1.0, 1.0);render.enable_state(graphics.STATE_POLYGON_OFFSET_FILL)
render.set_polygon_offset(1.0, 1.0)Parameters
factor:number— polygon offset factorunits:number— polygon offset units
render.set_projection(matrix: Matrix4): void
Sets the projection matrix to use when rendering.
// 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_projection(vmath.matrix4_orthographic(0, render.get_width(), 0, render.get_height(), -1, 1))Parameters
matrix:Matrix4— projection matrix
render.set_render_target(2 overloads): void
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.
(render_target?: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT)(render_target: Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT | undefined, options: render.SetRenderTargetOptions)Parameters
render_target:Opaque<"render_target"> | string | Hash | typeof render.RENDER_TARGET_DEFAULT | undefined— render target to set. Omit it, passnil, or use render.RENDER_TARGET_DEFAULT to set the default render targetoptions:render.SetRenderTargetOptions— optional render-target activation optionsfacenumber Cubemap face selected for rendering. This option is valid only for cubemap render targets and defaults tographics.CUBEMAP_FACE_POSITIVE_X.graphics.CUBEMAP_FACE_POSITIVE_Xgraphics.CUBEMAP_FACE_NEGATIVE_Xgraphics.CUBEMAP_FACE_POSITIVE_Ygraphics.CUBEMAP_FACE_NEGATIVE_Ygraphics.CUBEMAP_FACE_POSITIVE_Zgraphics.CUBEMAP_FACE_NEGATIVE_Z
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
// 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
export default defineRenderScript({
init() {
// the engine registers a texture format only when the driver supports it
const format = graphics.TEXTURE_FORMAT_RGBA;
if (format === undefined) return undefined;
const color_params = {
format,
width: render.get_window_width(),
height: render.get_window_height(),
};
return {
my_render_target: render.render_target({ [graphics.BUFFER_TYPE_COLOR0_BIT]: color_params }),
my_pred: render.predicate([hash("my_tag")]),
};
},
update(self, dt) {
if (self === undefined) return;
// set render target so all drawing is done to it
render.set_render_target(self.my_render_target, {
transient: [graphics.BUFFER_TYPE_DEPTH_BIT, graphics.BUFFER_TYPE_STENCIL_BIT],
});
// draw a predicate to the render target
render.draw(self.my_pred);
// set default render target. This also invalidates the depth and stencil buffers of the current target (self.my_render_target)
// which can be an optimisation on some hardware
render.set_render_target(render.RENDER_TARGET_DEFAULT);
},
});function update(self, dt)
-- set render target so all drawing is done to it
render.set_render_target(self.my_render_target, { transient = { graphics.BUFFER_TYPE_DEPTH_BIT, graphics.BUFFER_TYPE_STENCIL_BIT } } )
-- draw a predicate to the render target
render.draw(self.my_pred)
-- set default render target. This also invalidates the depth and stencil buffers of the current target (self.my_render_target)
-- which can be an optimisation on some hardware
render.set_render_target(render.RENDER_TARGET_DEFAULT)
endexport default defineRenderScript({
init() {
return { my_pred: render.predicate([hash("my_tag")]) };
},
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);
},
});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)
endrender.set_render_target_size(render_target: Opaque<"render_target"> | string | Hash, width: number, height: number): void
Sets the render target size for a render target created from either a render script, or from a render target resource. Cubemap render targets require equal width and height.
export default defineRenderScript({
init() {
return { my_render_target: render.render_target("my_target", {}) };
},
update(self, dt) {
// 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.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())Parameters
render_target:Opaque<"render_target"> | string | Hash— render target to set size forwidth:number— new render target widthheight:number— new render target height
render.set_stencil_func(func: graphics.CompareFunc, ref: number, mask: number): void
Stenciling is similar to depth-buffering as it enables and disables drawing on a
per-pixel basis. First, GL drawing primitives are drawn into the stencil planes.
Second, geometry and images are rendered but using the stencil planes to mask out
where to draw.
The stencil test discards a pixel based on the outcome of a comparison between the
reference value ref and the corresponding value in the stencil buffer.
func specifies the comparison function.
The initial value is graphics.COMPARE_FUNC_ALWAYS.
ref specifies the reference value for the stencil test. The value is clamped to
the range [0, 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.
// let only 0's pass the stencil test
render.set_stencil_func(graphics.COMPARE_FUNC_EQUAL, 0, 1);-- let only 0's pass the stencil test
render.set_stencil_func(graphics.COMPARE_FUNC_EQUAL, 0, 1)Parameters
func:graphics.CompareFunc— stencil test function, see the description for available valuesref:number— reference value for the stencil testmask:number— mask that is ANDed with both the reference value and the stored stencil value when the test is done
render.set_stencil_mask(mask: number): void
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.
// set the stencil mask to all 1:s
render.set_stencil_mask(0xff);-- set the stencil mask to all 1:s
render.set_stencil_mask(0xff)Parameters
mask:number— stencil mask
render.set_stencil_op(sfail: graphics.StencilOp, dpfail: graphics.StencilOp, dppass: graphics.StencilOp): void
The stencil test discards a pixel based on the outcome of a comparison between the
reference value ref and the corresponding value in the stencil buffer.
To control the test, call render.set_stencil_func.
This function takes three arguments that control what happens to the stored stencil
value while stenciling is enabled. If the stencil test fails, no change is made to the
pixel's color or depth buffers, and sfail specifies what happens to the stencil buffer
contents.
dppass and dpfail specify the stencil buffer actions depending on whether subsequent
depth buffer tests succeed (dppass) or fail (dpfail).
The initial value for all operators is graphics.STENCIL_OP_KEEP.
// Set the stencil function to never pass and operator to always draw 1's
// on test fail.
render.set_stencil_func(graphics.COMPARE_FUNC_NEVER, 1, 0xFF);
// always draw 1's on test fail
render.set_stencil_op(graphics.STENCIL_OP_REPLACE, graphics.STENCIL_OP_KEEP, graphics.STENCIL_OP_KEEP);render.set_stencil_func(graphics.COMPARE_FUNC_NEVER, 1, 0xFF)
-- always draw 1's on test fail
render.set_stencil_op(graphics.STENCIL_OP_REPLACE, graphics.STENCIL_OP_KEEP, graphics.STENCIL_OP_KEEP)Parameters
sfail:graphics.StencilOp— action to take when the stencil test failsdpfail:graphics.StencilOp— the stencil action when the stencil test passesdppass:graphics.StencilOp— 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
render.set_view(matrix: Matrix4): void
Sets the view matrix to use when rendering.
// How to set the view and projection matrices according to
// the values supplied by a camera.
export default defineRenderScript({
init() {
return {
view: vmath.matrix4(),
projection: vmath.matrix4(),
};
},
update(self, dt) {
// set the view to the stored view value
render.set_view(self.view);
// now we can draw with this view
},
on_message(self, message_id, message) {
if (
message_id === hash("set_view_projection") &&
types.is_matrix4(message.view) &&
types.is_matrix4(message.projection)
) {
// camera view and projection arrives here.
self.view = message.view;
self.projection = message.projection;
}
},
});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
endParameters
matrix:Matrix4— view matrix to set
render.set_viewport(x: number, y: number, width: number, height: number): void
Set the render viewport to the specified rectangle.
// Set the viewport to the window dimensions.
render.set_viewport(0, 0, render.get_window_width(), render.get_window_height());-- Set the viewport to the window dimensions.
render.set_viewport(0, 0, render.get_window_width(), render.get_window_height())Parameters
x:number— left cornery:number— bottom cornerwidth:number— viewport widthheight:number— viewport height
Constants
render.CONTEXT_EVENT_CONTEXT_LOST: number & { readonly __brand: "render.CONTEXT_EVENT_CONTEXT_LOST" }N
- Since Defold 1.13.2
rendering context was lost; rendering pauses and graphics resources become invalid
render.CONTEXT_EVENT_CONTEXT_RESTORED: number & { readonly __brand: "render.CONTEXT_EVENT_CONTEXT_RESTORED" }N
- Since Defold 1.13.2
rendering context was restored; rendering remains paused while resources can be reloaded
render.FRUSTUM_PLANES_ALL: number & { readonly __brand: "render.FRUSTUM_PLANES_ALL" }
All six frustum planes.
render.FRUSTUM_PLANES_SIDES: number & { readonly __brand: "render.FRUSTUM_PLANES_SIDES" }
Left, right, top, and bottom frustum planes.
render.RENDER_TARGET_DEFAULT: undefined
render.SORT_BACK_TO_FRONT: number & { readonly __brand: "render.SORT_BACK_TO_FRONT" }
Depth sort far-to-near (default; good for transparent passes).
render.SORT_FRONT_TO_BACK: number & { readonly __brand: "render.SORT_FRONT_TO_BACK" }
Depth sort near-to-far (good for opaque passes to reduce overdraw).
render.SORT_NONE: number & { readonly __brand: "render.SORT_NONE" }
No per-call sorting; draw entries in insertion order.
render.TEXTURE_BIT: number & { readonly __brand: "render.TEXTURE_BIT" }N
- Since Defold 1.13.2
Create a texture-backed depth or stencil attachment.