The Realman plugin enables you to create procedural materials using scripts coded in a C-like language.

The system is designed for those users of Realsoft3D who are comfortable programming in C or something similar.  This does not exclude others from using it though as the limited scope of the implementation means that there isn't too much to learn in order to get useful results.

The plugin provides two facilities - a complete material class that adheres to the VSL shader system and a VSL object allowing scripts to be incorporated into VSL materials.

This documentation describes the functionality of Realman only and as such assumes that you are familiar with VSL and the concept of shaders, samples & channels. Consult the Realsoft3D documentation for details of these.

Changes in version 1.19

  • fixed rendertime crash due to thread-unsafe code.
     
  • minor speedup for recursive rendering of realman materials.

Changes in version 1.16

  • fixed crash in raytracer class
     
  • fixed crash due to bad code generation.
     
  • fixed crash due to differing structure alignment methods in Realman & Linux compiler.
     
  • tidied example projects (Linux)

Changes in version 1.15

Realman 1.15 is mainly about releasing the Linux version of the plugin.  Most of the changes in this release are internal and related to the Linux port. There are, however, a few tangible fixes/changes:

  • additional comparison operators for vector/color operands.
     
  • mix() function argument order was not as documented.
     
  • fixed memory corruption under certain conditions.
     
  • dynamic generation of a documented script 'template'.
     
  • property page is now locale aware, though this does not yet apply to
    compiler error messages. Strings supplied for English only - translations
    to other locales will be gratefully received :-)

Installation

The Windows version is supplied as an executable - simply double-click on the downloaded file to start the installer.  By default the installation process creates or adds to the following files and/or folders within your Realsoft3D installation folder:

    locale\english\
       rmmat.ini

    r3icon\default\rmmat\
       rmicon1.ico

    realman\
       installation support files

    realman\docs\
       documentation files

    samples\realman\
       sample projects and support files

    plugins\
       rmmat.dll

    system\
       rmsys1.dll

The Linux version is supplied as a compressed tar. Copy the file to your Realsoft3D folder and extract the content with the command:

    tar -xvzf filename

This creates or adds to the following files and/or folders:

    locale\english\
       rmmat.ini

    r3icon\default\rmmat\
       rmicon1.ico

    realman\docs\
       documentation files

    samples\realman\
       sample projects and support files

    plugins\
       librmmat.so

    lib\
       librmsys1.so

 

Top

 

What you get

When correctly installed this plugin adds two facilities to Realsoft3D (note that images are for illustration only - the GUI may look slightly different depending upon platform and/or version of Realman.)

Realman Material system, an extra item to the context-sensitive menu of the material selection window

Realman VSL object,  an icon on the VSL object window

The property page of a Realman material has the following general appearance


The Attributes area of the property page varies from script to script. This is fully documented as part of the properties function but the general principal is that each gadget allows the user to alter the value of a script variable without having to edit the script itself. The Attribute section only appears if the script was compiled without error and the script exposes some of its variables.

The Script area of the property page is common to all Realman materials.  It gives the user control over the external text file that contains the material-definition script. 

 

RealMan script file

The file-browse button allows selection of the external text file that contains the material-definition script.  The path/filename can also be entered manually. 

Option

A script may have been divided into sections.  Each section could be a material definition in its own right or perhaps just a variation within a single definition. By choosing an option from the list you can select the desired section.

Refresh

When a script has been modified via your favourite text editor, clicking this button causes it to be reloaded into the material. Attribute values are retained where possible.

Auto-refresh

Enabling auto-reload causes the material to automatically check for a modified script and refresh it if necessary.  If this property widow is open then the check occurs on a regular basis; if the window is closed then the check occurs only when rendering is about to start. When rendering an animation beware that the check is made before each frame is rendered so either avoid modifying the script during animation or disable this option.

Embedded

Normally the script remains external to the material. By selecting Embedded the script is loaded into the material and is saved as part of the material and/or project – no further reference is made to the external file.  When Embedded is deselected a file Save requester is opened and a suitable filename and location must be chosen to which the embedded script can be written. If you cancel the Save operation the script will remain embedded.  Attempting to embed then unembed a blank material will solicit the creation of a script template. See the script template for further details.

Reload

Similar to Refresh except that attribute values are initialised to those in the script. 

Debug file

Defines the location and filename of the file written to when debugging scripts.

Enable Debug?

Debug information will only be written if this is ticked.

Title / Author

Optional comments contained in the script.

Provided a valid script is loaded then the Script frame can be closed via the toggle button at the top left.

If a problem is detected during compilation of a script then the material property page will show an error message and the location of the error as in the following screenshot:


 

Top

 

Overview

Consider this simple VSL material

In a Realman script the material would be expressed thus:

    color mycolor( 0.78, 0.1, 0.45 );
    shader SurfaceProperties()
    {
       Surface.Color = mycolor;
    }

The correspondence between the two material definitions is clear;  a variable of type color is declared and its value initialised; a shader for the Surface Properties rendering phase assigns the value of the variable to the Color channel of the Surface sample.

color is a class and thus has a constructor.  We have constructed the variable mycolor with default values for the red, green and blue components.

shader declares a function that is bound to a Realsoft3D rendering phase.  In this case we are declaring a function for the 'Surface properties'  phase.

The names of the rendering phases, samples & channels are defined within Realsoft3D and are subject to change (e.g. locale settings), and addition (new plugins).  To maintain complete flexibility Realman:Materials extracts these names from Realsoft3D at runtime and converts them into legal C identifiers.  The general process is to remove non-alphanumeric characters and capitalize individual words  - hence Surface properties & Ray*Normal in VSL become SurfaceProperties & RayNormal in Realman:Materials.

The final line of executable code demonstrates access to the renderer's channels.  Each rendering phase has at its disposal one or more samples (a collection of channels) .  This particular line of code is assigning the value of mycolor to the Color channel of the Surface sample.

If we frequently needed to alter the color that our script assigns to the surface then frequent editing of the script would be required. To avoid this the language enables you to expose one or more global variables to the user, allowing them to alter values from the GUI.

In modifying the above script to achieve this we'll also add a second variable that will be used to control the intensity of the color.  The result is:

    color mycolor( 0.78, 0.1, 0.45 );
    float intensity = 1.0;

    properties ()
    {
       attribute.color("Object color", mycolor);
       attribute.number("Intensity", intensity);
    }

    shader SurfaceProperties()
    {
       Surface.Color = mycolor * intensity;
    }

The properties function contains a list of calls to member functions of the predefined object attribute.  Realman uses this function to construct the Attributes section of the material property page:

If the script is edited and then Refreshed, any modifications to attribute values are retained provided that the title and type of the attribute remains unchanged. For example if you alter the Intensity slider to 0.5, then modify the script to change the initial value of intensity:

    float intensity = 2.5;

and then click Refresh, despite the change to the script the initial value of intensity will remain at 0.5. Only by clicking Reload will the value in the script override the slider setting.

 

Top