How to use the API browser

Forums: How to use the API browser
Forum for OctaneRender Lua scripting examples, discussion and support.

How to use the API browser

Postby roeland » Mon Dec 16, 2013 9:56 pm

roeland Mon Dec 16, 2013 9:56 pm
Hi, this is a short introduction of how the Octane Lua API works, and where the different pieces of documentation fit in.

First of all, if you're new to Lua, check out Programming in Lua online:

There are two ways of getting the API documentation. You can use the API browser window in Octane, or you can use our HTML documentation script to get an HTML page.

Remember tables are associative arrays containing name-value pairs. There is an introduction in the Programming in Lua book: The values can be simple values, like numbers or strings, and they can be other tables.


The Octane API exposes a single table called octane. You can find this table in the documentation as the octane module. The octane table contains all the other modules: octane.gui for instance is the gui module in the API browser.

Now let's have a closer look at the gui module. The Members column lists three kinds of items: functions, properties and constants. we will start at the bottom:

The items listed under Constants are other tables. These tables contain constants which can be used as function arguments. You can see all this values listed below the description. So octane.gui.componentType is a table, and octane.gui.componentType.BUTTON is the number 1.

All the constants listed in the octane module are a special case: these are also available directly in the octane table itself: so both octane.attributeId.A_COLOR and octane.A_COLOR are the number 22.

The items under Functions describe all the functions in a module. The create item describes a function in the gui module, you can call it like this: octane.gui.create(table). Functions in Lua have a number of parameters and a number of return values, this one is simple: it has one parameter, and one return value.

The description of parameters and return values follows the following pattern: it gives the type, and some name (you can choose an arbitrary name in your program). The single parameter is listed as table PROPS_GUI_COMPONENT, so it should get a table as argument. The name is chosen to refer to an item under Properties below. The return value is listed as being a component. This is a custom type defined by Octane. We will go into detail below.

The items under Properties are different: these are not actually present in the API, but these are descriptions of information you have to send to a function, or information returned from a function.

A lot of functions in the API return a table. For instance if you get the properties of a GUI component, the returned value is a table, containing information about the object you just created. octane.gui.getProperties for instance returns such a table. The contents of this table depend on the type of the component, but it is described by one of the items here: if you create a slider you will get a table with information described by the PROPS_GUI_SLIDER item. You can also find all the other component types here.

A lot of functions also take a single argument which is a table. octane.gui.create is such a function. These tables are also described here. For this function these are the same descriptions as the ones returned from octane.gui.getProperties.

Example: make a slider

So, let's create a table and then create our slider:
Code: Select all
someTable = {}                                    -- create an empty table
someTable.type = octane.gui.componentType.SLIDER  -- you will find all these properties in the docs in the PROPS_GUI_SLIDER item.
                                                  -- the type takes one of the constants in octane.gui.componentType.
someTable.minValue = 0
someTable.maxValue = 10
someTable.step = 2
someTable.value = 6
slider = octane.gui.create(someTable)

The slider is not visible yet, for this we need to add it to a window. But we are only showing the basics of how to use the API and where the documentation fits in. To see how a complete GUI works, you can look at some of the scripts available elsewhere on this forum.

Now we want to print the value of the slider. There is a function octane.gui.getProperties to get the updated properties of our slider. This function returns a table, which is described by the same PROPS_GUI_SLIDER item in the docs. So if the user moved the slider we can get the new value.

Code: Select all
props = octane.gui.getProperties(slider)

The code you saw here is a lot more verbose than the code in our scripts. There are a few shorthands available in the Lua language:

The first one is for passing a single table as a function argument. Instead of creating a table as a separate variable we may create our table inline like this:
Code: Select all
slider = octane.gui.create( { type = octane.gui.componentType.SLIDER, minValue = 0, maxValue = 10, step = 2, value = 6} )

Lua allows you to omit the parentheses in this case, and only write the curly brackets.
Code: Select all
slider = octane.gui.create{ type = octane.gui.componentType.SLIDER, minValue = 0, maxValue = 10, step = 2, value = 6}

And this is the form you usually see in the scripts.

So, what is this component type again? It's a custom type defined by the Octane API. It behaves a bit like a table, you can also get properties from variables of this type. To make programming a bit less verbose, the Octane API will make all the functions in the GUI module also properties of this custom type. So to get the properties of our slider you can also write:
Code: Select all
props = slider.getProperties(slider)

slider shows up twice in this expression: once in the beginning so we can fetch the getProperties function, and the second time as the first argument of this function. This happens often, and Lua has a shorthand for it:
Code: Select all
props = slider:getProperties()

The colon means: get some function from the slider object, and then use the slider object as the first argument. This is very similar to the dot (.) operator in Python. If you check the description of this function in the API browser, you will see it shows this second form if it is available.

To update the range of our slider you can use the octane.gui.updateProperties. The docs say it takes two arguments: a component and a table. Since our first argument is a component, we can use the colon operator.

If we are updating a component we only have to put the values we want to change in the table. Some values can't be updated: if you open the PROPS_GUI_SLIDER again you will see these these are listed as read-only instead of writable.

Code: Select all
-- long version
octane.gui.updateProperties(slider, { maxValue = 20 })
-- short version. The only argument between the parentheses is a table so we can omit them.
slider:updateProperties{ maxValue = 20 }


There is a second tab in the API browser which lists all the node and graph types. Every entry here lists, for one type, all the input pins and attributes. All the constants here, like NT_CAM_THINLENS, A_LOAD_INITIAL_STATE, and P_ORTHOGRAPHIC can be found in the octane module. If the documentation tells you to use some pin ID, this is one of the ids listed here under Pins. Everything you want to know but were afraid to ask is in this post here:

You will find a lot of examples of how to use this information on this forum, like Creating your own geometry with the Octane Lua API which shows you how to set up attributes for an image texture node.

User avatar
OctaneRender Team
OctaneRender Team
Posts: 1769
Joined: Wed Mar 09, 2011 10:09 pm

Re: How to use the API browser

Postby bepeg4d » Mon Dec 16, 2013 10:29 pm

bepeg4d Mon Dec 16, 2013 10:29 pm
what about adding another item "show API" in the right click contextual menù, just under "show in outliner" or "show in graph editor"?
ciao beppe
User avatar
Octane Guru
Octane Guru
Posts: 8261
Joined: Wed Jun 02, 2010 6:02 am
Location: Italy

Re: How to use the API browser

Postby stratified » Mon Dec 16, 2013 10:40 pm

stratified Mon Dec 16, 2013 10:40 pm
we could add that for the nodes, but it doesn't make much sense for the Lua API itself.

User avatar
OctaneRender Team
OctaneRender Team
Posts: 945
Joined: Wed Aug 15, 2012 6:32 am
Location: Auckland, New Zealand

Return to Lua Scripting

Who is online

Users browsing this forum: No registered users and 1 guest

Sun May 09, 2021 6:45 pm [ UTC ]