Previous
NOTES
This manual documents the creation of the Lightflow
entities using the Python Module.
Since this creation is always made using arbitrary parameter lists,
we adopt here a special syntax to describe what does a function
expect.
In particular parameter lists are generic lists that may
contain whatever type you want, and in this sense there is no the
C / C++ limitation of the homogeneous arrays, that are always made
by the same kind of element.
This generality allows to create a sort of new type of function
call endowed with named arguments. In Python this functionality
already exists, but C++ have no similar constructs, and thus the
Lightflow Rendering Interface provides an inner mechanism
to do this without relying on a particular feature of a
particular language.
Usually functions that accept a parameter list expect
the first token to be a string, that will declare what is the next
parameter. This is why we call it a named argument. Note that it
is not strictly necessary for the declarator to be a string, it
could be as well a number or anything else, but a string is the
usual choice since it helps us to remember the meaning of things.
In this documentation we will show what are all the possible
arguments for each function by writing them in a list. All the
rows of this list will start by the declarator of the argument.
The declarator will be specified by its type and its value.
Then the argument follows, as a list of types and names. Note that
an argument is not a single object, it is rather a set of
elements which go under the same name.
For example if a function has an argument named
"sampling-pattern" that is specified by a string representing the
type of pattern and a number indicating the amount of samples,
you are likely to find this:
- string "sampling-pattern", string type, int samples
Note that the last two names 'type' and 'samples' have no real
functionality, their purpose is only to give a handle to the
argument for use in the explanations, that is to say it is a
commodity that allow us not to write periphrases like "the
argument number 4" every time we want to address one of them.
In some cases the argument may contain elements that are optional
or that may be repeated many times.
In the first case the argument is put in square brackets:
- string "sampling-pattern", string type, [int samples]
If a default value is present the square brackets are removed and
the value is assigned to the element:
- string "sampling-pattern", string type, int samples = 3
In the second case the block of elements that may be repeated zero or
more times is bracketed with '{' '}':
- string "sampling-pattern", {string type, int samples}
Another frequent symbol is the vertical slash '|', that is used to
indicate an 'or' operation.
For example float | pattern
means that either a float or a pattern may be given.
The same syntax may be used also in more complex expressions using
parentheses, like in:
(float value1, float value2) | (pattern value1, pattern value2).