Lua Reference

Beast offers a Lua render pass, which allows users to take complete control over baking by providing a custom Lua script. This separate pass exists for both texture baking and surface transfer, as well as for point cloud baking. For details on creating the Lua pass, see Creating Render Passes.

When you create the Lua pass, you must provide the path and file name of a script file that will be called to carry out the baking. This page describes how to write that script, and details the Lua functions built in to Beast that you can use in your script.

Lua bake script structure

The baking script that you provide in the call to ILBCreateLuaPass() should have the following structure:

function setup()
    -- Required. Sets configuration options for baking.
    -- See  Lua Reference.
end

function basis(x, y, z)
    -- Optional. Defines the function basis to which data will be fit.
    -- See  Lua Reference.
end

function bake()
    -- Optional. Computes the data output to texture or point cloud for each point.
    -- See  Lua Reference.
end

The setup() function

This function is called once before the baking process begins. Its main purpose is to set values for the different configuration options that will control the way the baking is carried out.

To set the value of an option, call the bset() function. Pass as arguments:

The name of the configuration option you want to set.
The new value you want to set.

For example:

function setup()
    -- Sampling hemispherically in tangent space.
    bset("gather.sampletype", "indirect illumination")
    bset("gather.space", "tangent space")
    bset("gather.distribution", "equiareal")
    bset("gather.minsamples", 300)
    bset("gather.maxsamples", 600)
    bset("gather.coneangle", 180)

    bset("output.size", 9)
end

The following table describes all available configuration options, with their accepted and default values.

option	type	description
gather.useRadianceCache	Boolean	Determines whether baking uses the radiance cache or brute force sampling. When enabled, all gather functionality is controlled via the final gather options described below. If you enable this setting, you must also set the basis.type option to sh. NOTE:This function is only available for scenes that use "classic" materials, not physical materials.
gather.sampletype	string	Determines the type of light to gather. Accepts the following values: none or n: The gather before each execution of the basis() function is disabled. This is useful when no gather is needed, such as when baking only direct static light. indirect illumination or ii: Gathers indirect illumination only. If you want direct illumination, you need to manually add it in your bake() function. This setting is typically used for baking radiosity normal maps (RNMs). dynamic illumination or dyni: Gathers outgoing lighting depending on incoming light direction, also known as precomputed radiance transfer. NOTE:This setting is only available for scenes that use "classic" materials, not physical materials. direct dynamic illumination or ddyni: As dynamic illumination, but does not consider indirect light. NOTE:This setting is only available for scenes that use "classic" materials, not physical materials. indirect dynamic illumination or idyni: As dynamic illumination, but considers only indirect light. NOTE:This setting is only available for scenes that use "classic" materials, not physical materials. The default value is direct dynamic illumination.
gather.space	string	Specifies the coordinate system in which the gather will be performed. Accepts the following values: world space or ws object space or os tangent space or ts The default value is tangent space.
gather.distribution	string	Determines how samples are spread out over the sphere or hemisphere. Accepts the following values: cosine weighted or cw: The gather distribution will be cosine-weighted around the surface normal. This setting might be useful when baking occlusion maps. equiareal or ea: The gather space will be uniformly sampled. The default value is equiareal.
gather.minsamples	int	Specifies the minimum number of samples to be used for the gather. This number is used to determine the number of sample cells to use in the gather distribution. Note that the actual number of sample cells used will not necessarily match the value of this setting, since the sample distribution needs to distribute the samples over the sphere or hemisphere in an efficient way. Accepts any value greater than 1. The default value is 128.
gather.maxsamples	int	Specifies the maximum number of samples to be used for the gather. This setting provides an upper limit for super-sampling in the gather distribution. Accepts any value greater than the value of the gather.minsamples option. The default value is 256.
gather.coneangle	int	Specifies the cone angle to use for the gather distribution. Accepts any value between 0 and 360 inclusive. In most cases, use 180 or 360. The default value is 180.
gather.clamp	Boolean	Determines whether or not the values sampled during the gather are clamped. The default value is false.
gather.cosweighdynamic	Boolean	Determines whether or not the gathered dynamic light should be cosine-weighed according to the sample normal. The default value is false.
gather.aomaxdistance	float	Sets the maximum distance a ray can travel before being considered un-occluded. This will affect the occlusion appearance. If this option is not defined, the size of the whole scene will be used. Therefore, you must define this option for indoor scenes. If you do not, all surfaces will be fully occluded.
gather.aoscale	float	Determines the scaling of the occlusion value for occlusion sampling. Can be used to boost the shadowing effect.
gather.aocontrast	float	Controls the amount of contrast in the occlusion. A higher value will increase the contrast, making dark areas darker and bright areas brighter.
gather.aoinfluence	float	Determines whether the output values from Lua should be scaled by ambient occlusion automatically. Accepts any value between 0.0 and 1.0: 0.0 produces no occlusion scaling. 1.0 produces full occlusion scaling. Values between 0.0 and 1.0 produce a weighted blend between these extremes.
gather.obeytransparency	Boolean	Determines whether or not rays will be transmitted through transparent surfaces. The default value is false.
output.size	int	Specifies the number of elements in the array returned by the bake() function. The default value is 4.
basis.type	string	Determines the type of function basis the gathered data will fit. Accepts the following values: none or n ptm: polynomial texture mapping. sh: spherical harmonics. custom or c: The basis will be determined by calling the basis() function defined in your script. See Lua Reference below. If set to any value other than none, the bake() function can be omitted from the script, and the coefficients for the specified function basis will be generated automatically. The default value is none.
basis.rgb	Boolean	This option is taken into consideration when baking function coefficients. Set this option to true if your bake() implementation returns a set of coefficients for each color channel. The coefficients for all three channels should be returned as one concatenated array. Set this option to false if the bake() function generates coefficients for the intensity of the gathered data, but the relative values of the color channels are not important. The default value is false.
basis.sh.bands	int	Specify the number of bands to use when generating spherical harmonics coefficients. Read only when the basis.type option is set to sh. Accepts any value from 1 to 10 inclusive. The default value is 2.

The basis(x, y, z) function

This optional function allows you to define the values of the function basis that your gathered data should fit.

When defined, this function is called once for every direction used in the gather before baking. It is passed a vector that defines a point on the sampling sphere. Your implementation must determine what values this vector will produce in your custom basis, and must return an array with the correct number of coefficients. The sampled data will automatically be fitted to your basis during rendering.

In order to use this function:

Your setup() function must set the basis.type option to custom.
Your setup() function must set the output.size option to the number of coefficients returned by your basis() and bake() implementations.

For example, the following simple implementation defines a basis for polynomial texture mapping (PTM):

function basis(x, y, z)
    return {x*x, y*y, x*y, x, y, 1}
end

The bake() function

The bake() function is executed once for every pixel (or every super-sample if super-sampling is enabled). It must return an array that contains the data that should be output to the texture or point cloud. The size of the returned array must match the value of the output.size option set by the setup() function.

In your implementation of the bake() function, you may need to access information about the point under consideration, or to query Beast for additional information about the scene. The following sections describe the different functions and classes that you can use.

The vec3 class

The vec3 class represents a vector of three floating-point values. It can be constructed by calling vec3(x,y,z).

This class implements the following operators:

+: Aliased to add3.
- (binary): Aliased to sub3.
- (unary): Aliased to neg3.
*: Aliased to mul3.
/: Aliased to div3.
[i]: Returns the component at index i within the vec3. The index value may be 1, 2 or 3.

Functions for retrieving point data

The following table describes the functions available for obtaining information about the point currently being treated by the bake() function.

function	description
vec3 getPoint()	Returns the intersection point of the fragment in world space.
vec3 getNormal()	Returns the normal of the fragment.
vec3 getTangentU()	Returns the tangent of the fragment.
vec3 getTangentV()	Returns the bitangent of the fragment.
vec3 getViewDir()	Returns the vector from the fragment to the eye in world space.
vec3 getUV()	Returns the texture coordinates of the fragment. Uses only the first two components of the vec3.
vec3 getdTdX()	Returns the projection of the X axis of the screen space pixel in texture space. Uses only the first two components of the vec3.
vec3 getdTdY()	Returns the projection of the Y axis of the screen space pixel in texture space. Uses only the first two components of the vec3.
vec3 getT()	Returns the distance from the ray origin to the current fragment.

Functions for lighting

The following table describes the functions that you can call to retrieve information about the light sources that are light-linked to the point being baked. The getLights() function returns the total number light sources linked to the point; the other functions retrieve information about a single linked light source in that list, specified by the index you provide.

function	description
int getLights()	Returns the number of lights linked to the current point.
bool getLightName(i)	Returns the name of the light at the specified index.
vec3 getLightDir(i)	Returns the direction in world space from the current point to the light at the specified index.
float getLightDist(i)	Returns the distance in world space between the current point and the light at the specified index.
vec3 getLightCol(i)	Returns the color of the light at the specified index. Includes attenuation and shadows.
vec3 getLightColUnshadowed(i)	Returns the color of the light at the specified index. Does not include shadows.
bool getLightAmb(i)	Returns true if the light at the specified index is ambient.
bool getLightInd(i)	Returns true if the light at the specified index is indirect.
bool getLightCastShadows(i)	Returns true if the light at the specified index casts shadows.
float getLightLambertianReflectance(i, vec3)	Returns the Lambertian reflectance of the light with the specified index, around the normal direction specified by the vec3 argument.

Functions for ray tracing

The following table describes the functions that you can call to cast rays into the scene.

function	description
vec3 shootRay(vec3 o, vec3 d)	Shoots a ray from the o coordinates in the direction d, with shading. Returns the color of the first intersection found (if any).
float shootOccRay(vec3 o, vec3 d, [float tmax])	Shoots a ray from the o coordinates in the direction d, with shading. Returns the distance to the closest intersection, or -1.0f if no intersection is found. The occlusion ray ignores the transparency of the occluder. If desired, you can specify the maximum distance to the intersection using the tmax parameter.

function

description

vec3 shootRay(vec3 o, vec3 d)

Shoots a ray from the o coordinates in the direction d, with shading. Returns the color of the first intersection found (if any).

float shootOccRay(vec3 o, vec3 d, [float tmax])

Shoots a ray from the o coordinates in the direction d, with shading. Returns the distance to the closest intersection, or -1.0f if no intersection is found.

The occlusion ray ignores the transparency of the occluder.

If desired, you can specify the maximum distance to the intersection using the tmax parameter.

Other utility functions

The following table describes the other utility functions provided by Beast that you can call in your bake() function.

function	description
float length(vec3)	Returns the length of the specified vector.
float smoothstep(min, max, x)	Returns a value that indicates where x falls within the interval specified by min and max. If x is less than min, returns 0.0. If x is greater than max, returns 1.0. If x is between min and max, returns a value between 0.0 and 1.0 that interpolates x along a smooth curve within that interval.
float step(min, max, x)	Returns a value that indicates where x falls within the interval specified by min and max. If x is less than min, returns 0.0. If x is greater than max, returns 1.0. If x is between min and max, returns a value between 0.0 and 1.0 that interpolates x proportionally within that interval.
float dot3(vec3 x, vec3 y)	Returns the scalar product of x and y.
vec3 cross3(vec3 x, vec3 y)	Returns the cross product of x and y.
float add3(vec3 x, y)	Returns x + y. The y argument can be a floating-point number or a vec3.
float sub3(vec3 x, y)	Returns x - y. The y argument can be a floating-point number or a vec3.
float neg3(vec3 x)	Returns -x.
float mul3(vec3 x, y)	Returns x * y. The y argument can be a floating-point number or a vec3. If y is a vec3, the multiplication is element-wise.
float div3(vec3 x, float y)	Returns x / y.
vec3 reflect(vec3 v, vec3 normal)	Returns the v vector reflected around the specified normal.
vec3 refract(vec3 v, vec3 normal, float inIor, float outIor)	Returns the v vector refracted around the specified normal. The inIor parameter is the index of refraction for the material the ray is leaving, and the outIor parameter is the index of refraction for the material the ray is entering.
vec3 normalize(vec3 v)	Returns the v vector normalized.
int getSampleCount()	Returns the number of sample cells used in the distribution. Note that the number of sample cells does necessarily match the minimum number of samples set in the setup() function.
vec3 getSampleValue(int)	Returns the color of the sample at the specified index. The red, green and blue values are stored in the components of the returned vec3.
vec3 getSampleDirection(int, boolean)	Returns the direction of the sample cell at the specified index. The boolean parameter specifies the desired coordinate system for the returned vector. Use true to retrieve the direction in world space. Use false to retrieve the direction in gather space.
vec3 getSampleMean()	Returns the mean value of all sample cells as a vec3 (not weighed by sample cell area).
vec3 getSampleProjectedSum(vec3, boolean)	Returns the sum of all sample cell values as a vec3. This sum is weighed using the scalar product between the sample cell direction and the vector specified in the vec3 parameter. The boolean parameter determines whether or not to include values with negative weight.
float getSampleOcclusion()	Returns a value in the range [0.0, 1.0] that represents the occlusion over all sample cells. 0.0 represents no occlusion. 1.0 represents full occlusion. Values between 0.0 and 1.0 represent interpolations between these two extremes.
vec3 getGatherSpaceVector(int)	Returns a world space vector equivalent to one of the components of the gather space vector. The integer argument specifies which of the gather space vector components to use. May be 1, 2, or 3.
array getBasisCoefficients(int):	Returns the array of basis coefficients for the chosen basis, from the data specified in the integer parameter: 0: color intensity. 1: red channel. 2: green channel. 3: blue channel.
array evalSHBasis(vec3, int)	Returns an array of spherical harmonic values for the direction specified in the vec3 parameter. The integer argument specifies the number of SH bands to use. May be any value in the range [1,10] .
vec3 gatherToWorld(vec3)	Converts the specified vector from gather space to world space.
vec3 worldToGather(vec3)	Converts the specified vector from world space to gather space.

Lua Examples