The script language employed by Realman is very much like 'C'. However, the scope of the environment in which it is used is very narrow and specialised resulting in a language that is much less than 'C' yet having some powerful additions.
Script files
Scripts are created using your favourite text editor. There are no conventions for file names or extensions - feel free to choose your own. For efficient execution, scripts are compiled to an internal representation ("bytecode") by Realman upon loading and/or prior to rendering. There is deliberately no facility to save or export a script's bytecode. By this means we can enhance the internal representation as development of the plugin progresses without being hampered by compatibility considerations.
Examine the example scripts to get a feel for Realman. If you are in any way familiar with 'C' or a comparable language then you may recognise such things as comments, directives, global variable declarations, function definitions etc.
The script template
The dynamic nature of Realsoft3D means that updates, new versions and third party extensions can alter what shaders and channels are available to the material system. When creating a VSL material the GUI offers you up-to-date choices and options in a context-sensitive manner, such as offering a list of channels relevant to the currently selected shader & operation.
When writing a script for Realman no such luxury exists. There is, however a little comfort available - the script template. If, within the Realman Material system, you embed then un-embed a blank material (see the Introduction) Realman will offer to save a template file containing all the shader and channel information available from your current version. (As we'll see later there are two types of script - the template information only applies to one of them. The other has a simpler format that does not warrant a documenting template.)
Here is an excerpt from the template. It describes the LightProperties rendering phase:
/***************************
PHASE: LightProperties
***************************/
/* Raysample Light contains:
vector UVcoords;
vector Coordinates;
float Distance;
vector Ray;
vector Mapcoords;
color Illumination;
vector Antialiasing;
float Time;
float Scope;
*/
/* Raysample Target contains:
vector Coordinates;
color Color;
color Illumination;
*/
shader LightProperties ( /* raysample Light, raysample Target */ )
{
}
Most of the above is descriptive comment. It tells us that this rendering phase uses two raysamples: Light and Target, and the channels those raysamples contain. Raysamples equate, approximately, to 'C' language structs and are declared dynamically by the compiler.
The only executable code in the above is the empty LightProperties shader function. The commented parameter list shows that the shader has access to the two raysamples previously described. These can be referenced by name within this shader's code. eg.
shader LightProperties ( /* raysample Light, raysample Target */ )
{
Target.Illumination = Light.Illumination * Light.Time;
}
Despite the fact that raysamples are passed to the shader function as arguments there is no explicit function parameter list. This is to prevent the raysample parameter being named differently to what the compiler has dynamically generated (which would lead to compilation errors) and also because as mentioned previously, the raysamples are only 'approximately' like C structs and their real implementation is hidden in order to simplify the script language.
So, making a copy of the template and using it as the basis for your script will aid your script construction. But be careful to remove the empty shader functions that you are not going to use - despite being empty they will increase the processing overhead and thus slow down your renders!
Two types of script
As mentioned in the introduction Realman embodies two extensions to Realsoft 3D. Both employ the same script language but there is a fundamental difference between them in terms of what is required in the script file. (They have things in common too!)
Realman Material system scripts
The Realman Material system operates in much the same way as the native VSL system - using the concept of shaders and channels. A shader is part of a material definition that takes some sort of action at a particular phase in the rendering process. A channel is the means by which information is passed between the renderer and the shader.
The template described above pertains to this part of Realman. Thus for a Realman Material system script to do anything useful you need to code one or more shader functions and manipulate one or more channels. The example above and in the Introduction illustrate this.
Realman VSL object scripts
The Realman VSL object allows you to embed a script within a native VSL material. At this level of material processing there is no concept of shaders or channels, only raw data - be they vector, color or float.
A VSL object takes the data given to it, performs one or more operations on that data and then passes back a result. For example, the native VSL Linear object multiplies it's input by a given factor then adds a constant value to yield the result.
For the Realman VSL object this operation is described in the script using a function:
operation( <type> &result, <type> &input1, ...)
{
}
(if there were to be a template for these scripts then the above would be it!)
We could therefore simulate a basic version of the VSL Linear object with the following script:
vector factor(0.5, 0.5, 0.5);
vector constant(0.3, 0.3, 0.3);
operation( vector &result, vector &input )
{
result = (input * factor) + constant;
}
Unlike the shader functions described above the operation function does have an explicit parameter list. The first parameter is where the computed result must be stored. Subsequent parameters (of which there can be up to 15) provide the input data.
Note that all parameters are declared as 'pass by reference' by virtue of the '&' operator before each name. This is essential - expect strange things to happen if you forget!
What's common to both script types
Everything else about the language is common to both Realman Material and Realman VSL object. See the pages linked to in the submenu on the left for full details of data types, statements, properties and more.