stingray.ShadingEnvironment object reference

Description

NOTE: This object and its API are considered deprecated in favor of the workflow based on entities.

See The Shading environment and post effects in the Stingray Help.

A shading environment specifies a set of variables used for lighting and post processing when rendering a game world. Typically it includes data such as sun direction, sun color, shadow settings etc.

The contents of a shading environment are defined from data files with the .shading_environment_template extension, and are set up on a per-project basis. You can use the Lighting Editor tool to author shading environments.

The following example shows how to use this interface:

function render()
stingray.ShadingEnvironment.blend(self.shading_environment, {"default", 1.0, "dense_fog", 0.5})
stingray.ShadingEnvironment.set_vector3(self.shading_environment, "sun_direction", stingray.Vector3(0,0,-1))
stingray.ShadingEnvironment.apply(self.shading_environment)

stingray.Application.render_world(self.world, self.camera, self.viewport, self.shading_environment)
end

Constructors and accessors

stingray.World.create_shading_environment()

Related sample code

Appkit: /level_wrapper.lua Appkit: /world_wrapper.lua Minimal template: /boot.lua

Other related reference items

	stingray.Application.render_world() stingray.World.create_shading_environment() stingray.World.destroy_shading_environment() stingray.World.set_shading_environment()
	Core

Functions

apply ( self ) Writes the blended result to the materials global shader variables specified in the .shading_environment_template data file.

Parameters

self :

stingray.ShadingEnvironment

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

This function does not return any values.

Other related reference items

stingray.ShadingEnvironment.blend()

array_elements ( self, variable ) : integer Returns the number of elements in the specified array variable in the shading environment.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the array variable whose value you want to retrieve.

Returns

integer

The number of elements in the array.

array_scalar ( self, variable, n ) : number Returns the scalar value stored at the specified index of the specified array variable in the shading environment.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the array whose value you want to retrieve.
n :	integer	The index of the value to retrieve from the array.

Returns

number

The value stored at the specified index of the array.

array_vector2 ( self, variable, n ) : stingray.Vector3 Returns the two-dimensional vector value stored at the specified index of the specified array variable in the shading environment.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the array whose value you want to retrieve.
n :	integer	The index of the value to retrieve from the array.

Returns

stingray.Vector3

The value stored at the specified index of the array. The Z-axis component will be 0.

array_vector3 ( self, variable, n ) : stingray.Vector3 Returns the three-dimensional vector value stored at the specified index of the specified array variable in the shading environment.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the array whose value you want to retrieve.
n :	integer	The index of the value to retrieve from the array.

Returns

stingray.Vector3

The value stored at the specified index of the array.

blend ( self, settings ) Blends between shading environment settings authored in the Lighting Editor.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
settings :	any(string, number)+	The names of the settings you want to set, each followed by a numeric weight to assign for that setting. The + notation indicates that there may be one or more instances of the specified type. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

This function does not return any values.

The blend happens in the order the settings and weights are declared (similar to how layered blends works in Photoshop). You need to provide at least one setting for the shading environment to be valid.

For example:

stingray.ShadingEnvironment.blend(self.shading_environment, {"default", 1.0, "dense_fog", 0.5})

Note: You must call apply() after calling blend() in order for the results to be visible.

material ( self, material_name ) : stingray.Material Returns the specified material associated with the shading environment.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
material_name :	stingray.Material	The name of the material to retrieve.

Returns

stingray.Material

The material with the specified name.

scalar ( self, variable ) : number Returns the value of the specified scalar variable in the shading environment.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the scalar variable whose value you want to retrieve.

Returns

number

The value set for the variable.

set_array_scalar ( self, variable, n, value ) Sets the value at the specified index in the specified array in the shading environment to the specified scalar value.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the array variable whose value you want to set.
n :	integer	The index at which to store the value in the array.
value :	number	The value to set for the variable.

Returns

This function does not return any values.

set_array_vector2 ( self, variable, n, vector2 ) Sets the value at the specified index in the specified array in the shading environment to the specified two-dimensional vector value.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the array variable whose value you want to set.
n :	integer	The index at which to store the value in the array.
vector2 :	stingray.Vector3	The value to set for the variable. Only the X and Y components are used.

Returns

This function does not return any values.

set_array_vector3 ( self, variable, n, vector3 ) Sets the value at the specified index in the specified array in the shading environment to the specified three-dimensional vector value.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the array variable whose value you want to set.
n :	integer	The index at which to store the value in the array.
vector3 :	stingray.Vector3	The value to set for the variable.

Returns

This function does not return any values.

set_scalar ( self, variable, scalar ) Sets a scalar variable in the shading environment to the specified value.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the scalar variable whose value you want to set.
scalar :	number	The new value value to set for the variable.

Returns

This function does not return any values.

set_vector2 ( self, variable, vector2 ) Sets a two-dimensional vector variable in the shading environment to the specified value.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the vector variable whose value you want to set.
vector2 :	stingray.Vector3	The new value value to set for the variable.

Returns

This function does not return any values.

set_vector3 ( self, variable, vector3 ) Sets a three-dimensional vector variable in the shading environment to the specified value.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the vector variable whose value you want to set.
vector3 :	stingray.Vector3	The new value value to set for the variable.

Returns

This function does not return any values.

vector2 ( self, variable ) : stingray.Vector3 Returns the value of the specified two-dimensional variable in the shading environment.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the vector variable whose value you want to retrieve.

Returns

stingray.Vector3

The value set for the variable. The Z-axis component will be 0.

vector3 ( self, variable ) : stingray.Vector3 Returns the value of the specified three-dimensional variable in the shading environment.

Parameters

self :	stingray.ShadingEnvironment	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
variable :	string	The name of the vector variable whose value you want to retrieve.

Returns

stingray.Vector3

The value set for the variable.