The Lua API¶
The scripted interface is slightly different than its counterpart since it has been adapted to take advantage of the niceties of Lua. The main differences with the C API are:
No need to pass a ɴsɪ context to function calls since it’s already embodied in the ɴsɪ Lua table (which is used as a class).
The
type
argument can be omitted if the argument is an integer, real or string (as with theKd
andfilename
in the example below).ɴsɪ arguments can either be passed as a variable number of arguments or as a single argument representing an array of arguments (as in the
"ggx"
shader below)There is no need to call
NSIBegin()
andNSIEnd()
equivalents since the Lua script is run in a valid context.
Below is an example shader creation logic in Lua.
1nsi.Create( "lambert", "shader" );
2nsi.SetAttribute(
3 "lambert", {
4 { name = "filename", data = "lambert_material.oso" },
5 { name = "Kd", data = 0.55 },
6 { name = "albedo", data = { 1, 0.5, 0.3 }, type = nsi.TypeColor }
7 }
8);
9
10nsi.Create( "ggx", "shader" );
11nsi.SetAttribute(
12 "ggx", {
13 {name = "filename", data = "ggx_material.oso" },
14 {name = "anisotropy_direction", data = {0.13, 0 ,1}, type = nsi.TypeVector }
15 }
16);
API calls¶
All (in a scripting context) useful ɴsɪ functions are provided and are
listed below. There is also a nsi.utilities
class which, for now, only
contains a method to print errors.
Lua Function |
C equivalent |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Optional function arguments format¶
Each single argument is passed as a Lua table containing the following key values:
name
– the name of the argument.data
– the argument data. Either a value (integer, float or string) or an array.type
– the type of the argument. Possible values are:¶ Lua Type
C equivalent
nsi.TypeFloat
NSITypeFloat
nsi.TypeInteger
NSITypeInteger
nsi.TypeString
NSITypeString
nsi.TypeNormal
NSITypeNormal
nsi.TypeVector
NSITypeVector
nsi.TypePoint
NSITypePoint
nsi.TypeMatrix
NSITypeMatrix
arraylength
– length of the array for each element.
Here are some example of well formed arguments:
1--[[ strings, floats and integers do not need a 'type' specifier ]] --
2p1 = {
3 name = "shaderfilename",
4 data = "emitter"
5};
6p2 = {
7 name = "power",
8 data = 10.13
9};
10p3 = {
11 name = "toggle",
12 data = 1
13};
14
15--[[ All other types, including colors and points, need a
16 type specified for disambiguation. ]]--
17p4 = {
18 name = "Cs",
19 data = { 1, 0.9, 0.7 },
20 type=nsi.TypeColor
21};
22
23--[[ An array of 2 colors ]] --
24p5 = {
25 name = "vertex_color",
26 arraylength = 2,
27 data= { 1, 1, 1, 0, 0, 0 },
28 type= nsi.TypeColor
29};
30
31--[[ Create a simple mesh and connect it root ]] --
32nsi.Create( "floor", "mesh" )
33nsi.SetAttribute(
34 "floor", {
35 name = "nvertices",
36 data = 4
37 }, {
38 name = "P",
39 type = nsi.TypePoint,
40 data = { -2, -1, -1, 2, -1, -1, 2, 0, -3, -2, 0, -3 }
41 }
42)
43nsi.Connect( "floor", "", ".root", "objects" )
Evaluating a Lua script¶
Script evaluation is done through C, an ɴsɪ stream or even another Lua script. Here is an example using an ɴsɪ stream:
1Evaluate
2 "filename" "string" 1 ["test.nsi.lua"]
3 "type" "string" 1 ["lua"]
It is also possible to evaluate a Lua script inline using the
script
argument. For example:
1Evaluate
2 "script" "string" 1 ["nsi.Create(\"light\", \"shader\");"]
3 "type" "string" 1 ["lua"]
Both filename
and script
can be specified to NSIEvaluate()
in one go, in which case the inline script will be evaluated before the
file and both scripts will share the same ɴsɪ and Lua contexts.
Any error during script parsing or evaluation will be sent to ɴsɪ’s error handler.
Some utilities, such as error reporting, are available through the
nsi.utilities
class.
Note
All Lua scripts are run in a sandbox in which all Lua system libraries are disabled.
Passing arguments to a Lua script¶
All arguments passed to NSIEvaluate()
will appear in the
nsi.scriptarguments
table. For example, the following call:
1Evaluate
2 "filename" "string" 1 ["test.lua"]
3 "type" "string" 1 ["lua"]
4 "userdata" "color[2]" 1 [1 0 1 2 3 4]
Will register a userdata
entry in the nsi.scriptarguments
table. So executing the following line in the test.lua
script
that the above snippete references:
print( nsi.scriptarguments.userdata.data[5] );
Will print:
3.0
Reporting errors from a Lua script¶
Use nsi.utilities.ReportError()
to send error messages to the error
handler defined in the current nsi context. For example:
nsi.utilities.ReportError( nsi.ErrWarning, "Watch out!" );
The and are shown in .
Lua Error Codes |
C equivalent |
---|---|
|
|
|
|
|
|
|
|