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 the Kd and filename 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() and NSIEnd() equivalents since the Lua script is run in a valid context.

Below is an example shader creation logic in Lua.

shader creation example 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.

ɴsɪ functions

Lua Function

C equivalent

nsi.SetAttribute()

NSISetAttribute()

nsi.SetAttributeAtTime()

NSISetAttributeAtTime()

nsi.Create()

NSICreate()

nsi.Delete()

NSIDelete()

nsi.DeleteAttribute()

NSIDeleteAttribute()

nsi.Connect()

NSIConnect()

nsi.Disconnect()

NSIDisconnect()

Evaluate()

NSIEvaluate()

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 ɴsɪ argument types

    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 ɴsɪ error codes

Lua Error Codes

C equivalent

nsi.ErrMessage

NSIErrMessage

nsi.ErrWarning

NSIErrMessage

nsi.ErrInfo

NSIErrInfo

nsi.ErrError

NSIErrError