Help:Lua scripting in RenderWarrior

From RandomControl Wiki

RenderWarrior provides a Lua framework that allows you to use some of the most remarkable features in RCSDK (which is the codebase fryrender and Arion are built upon). Basically, this Lua framework provides I/O access to:

• .dsi files and their properties.
• .rcm materials and their properties.
• .rcs scenes and their properties.

Remarkably, you can also invoke Arion and fryrender from Lua, so you can render still frames and animations programmatically.

Some examples of things you could do with scripting are:

• Load a scene, change some parameters over time and render a programmatic animation (such as a turntable).
• Load a scene, swap one of its materials over a pool of .rcm files and batch one render per material.
• Scan all the scenes in a directory and batch one render per scene.
• Merge all the .dsi files in a directory.
• ...

Actually, you can do any programmatic modification on scenes, materials or .dsi renders, and batch rendering processes in any way you need.

Highlights

• General RenderWarrior documentation.
• Main scene manipulation and rendering functions.

What is Lua?

(From Wikipedia) Lua is a lightweight multi-paradigm programming language designed as a scripting language with extensible semantics as a primary goal.

Lua has gained increased importance in the recent past, after being adopted by many real-time app and video-game developers, perhaps owing to how easy it is to embed, its fast execution, and its small learning curve.

Lua can be considered a high-performance alternative to other older scripting languages such as Python. Actually, you can find a detailed list of the reasons why we chose Lua over Python in this link: Lua vs. Python.

The following code snippet is a very simple Lua script that loads a scene and renders it with Arion:

local s = rcs.new()

rcs.load( s , "c:\\my scenes\\scene.rcs" )

rcs.render_arn( s , "-w:640 -h:480 -passes:25 -rgb:\"z:\\my renders\\output.png\"" )

The following code snippet merges all the .dsi files found in a directory into a single .dsi:

local list = filesys.scan( "z:\\renderwarrior\\renders\\" , "*.dsi" , true , false )

local d = dsi.new()

for i = 0 , #list do

    if ( i == 0 ) then
         dsi.load ( d , list[i] )
    else dsi.merge( d , list[i] ) end

end

dsi.save( d , "z:\\renderwarrior\\merged.dsi" )

If you're serious about mastering Lua scripting, we encourage you to read the Lua documentation or even get one of the official books on Lua. However, note that Lua is really clean and simple, so you may get started by playing around with the example scripts we have included in the Arion and fryrender setups:

• basic_test.lua - Tests some basic operations and provides some text output.
• multi_merge.lua - Merges all the .dsi files found in a directory.
• rip_materials.lua - Extracts all the materials in a scene and saves them in .rcm files.
• swap_and_render.lua - Combines a couple of directories (one with scenes and one with materials).
• turntable.lua - Takes a scene and renders a turntable around it.

How to run Lua from RenderWarrior

Lua scripting is accessed through the commandline, using renderwarrior.exe:

 renderwarrior -{fryrender|arion} -lua:<file>

For example, the following command runs a Lua script picking the installed Arion customer license:

 renderwarrior -arion -lua:"c:\my scripts\turntable.lua"

You can find extended information on RenderWarrior and the supported commandline arguments here.

Reference manual

The Lua framework provided by RenderWarrior is layered in three levels:

• Built-in Lua libraries - This is the raw Lua scripting language itself.
• Base RCSDK libraries - Some basic utility routines from our codebase that may come handy in many scripts.
  • Library filesys - Multi-platform access to the file system.
  • Library path - Path string management.
  • Library vec2 - Basic 2D floating-point algebra.
  • Library vec3 - Basic 3D floating-point algebra.
• RenderWarrior libraries - Management routines for .rcs, .rcm and .dsi files, plus the ability to invoke the actual fryrender and Arion render kernels.
  • Library dsi - .dsi I/O and manipulation.
  • Library rcs - .rcs I/O and actual rendering with fryrender and Arion.
  • Library pivot - Geometric pivot.