RenderFarmΒΆ

class RenderFarm

An empty renderfarm interface. To override in plugin.

RenderFarm is the interface which must be inherited and overloaded in order to connect Guerilla to a render manager system and its render farm.

See the submit method for detailed information on implementing a RenderFarm interface

Hierarchy

class RenderFarm < class Node

Members

Methods:

template table gettemplate ( ) Return a property template table to be displayed in the property sheet
nil initrender ( table opts ) Returns true if the interface initialization succeeded for a render, to be overriden.
nil needfiles ( ) Returns true if the interface needs the jobs file dependencies (to sync them with a server for instance). In this case the file list will be passed to the submit method in options['Files'].
boolean success submit ( table jobs , table options ) Submit a list of jobs with options to the renderfarm

Functions:

nil declare ( RenderFarm interface ) Declare a new render farm interface.
RenderFarm result get ( string name ) Get a RenderFarm interface by its name
nil getlocal ( ) Get the batch or local RenderFarm interface
RenderFarm result getmain ( ) Get the current active RenderFarm interface

Inherited from class Node

Plugs:

string Name RW The node name

Methods:

bool result belongstoreference ( Reference ref ) Tells if the node belongs to the reference, or a sub reference
nil delete ( ) Delete a node
any value eval ( Plug plug ) Called by the framework when plug (a node's plug) must be evaluated
Node|Plug child findchild ( string path ) Find a child node or plug using a path
Node parent findparent ( string name ) Find the first parent Node of this Node of a specific class
Node result getchild ( string name ) Get a child node by its name
[string|number] name getname ( ) Get the Node name in its parent
Node parent getparent ( ) Get the parent Node of this Node
string path getpath ( ) Returns the node path as a string that can be reused with findchild
Reference reference getreference ( ) Returns the reference node it is connected to
of table getreferences ( [ topref Reference ] ) Returns the references in the document sorted depth first.
string result getstringcopy ( ) Return a copy of the node and its content as a string to be pasted
Reference reference gettopreference ( ) Returns the top reference node it is connected to
boolean editable iseditable ( ) Indicates if the node can be edited by the user in the UI
boolean indocument isindocument ( ) Tells if the node is inside a document, or is pending in the void
bool result ismoveable ( ) Tells if the node can be moved
boolean result isparent ( Node child ) Tells if this node is parent of the potential child
boolean result isreference ( ) Tells if a node comes from a reference project
boolean state isselected ( ) Tell if the node is selected
{Node} result loadfile ( string filename , [ table options ] ) load a file content in this node. Possible options are: overrideclass to enforce a specific class for the root node.
Node result loadtemplate ( string template , string name ) load a template file
nil move ( Node parent ) Move a node to a new parent
nil onpathchanged ( ) Called by the framework when the name of this node or of one of its parent is modified
{Node},string result,error pastestringcopy ( string copy , [ {} options ] ) Paste a string copy into this node
ReferenceBase refnode referencefile ( string name , string refpath , [ table options ] ) reference a file content in this node.
nil rename ( string name ) Rename a node
bool,string success,error savefile ( string filename ) load a node to a file
nil seteditable ( boolean editable ) Change the editable state of the node
nil setflags ( ) Set the node flags

Documentation

template table gettemplate ( )

Return a property template table to be displayed in the property sheet

Return:

  • table

nil initrender ( table opts )

Returns true if the interface initialization succeeded for a render, to be overriden.

Arguments:

  • opts The options to be used in submit

nil needfiles ( )

Returns true if the interface needs the jobs file dependencies (to sync them with a server for instance). In this case the file list will be passed to the submit method in options['Files'].

boolean success submit ( table jobs , table options )

Submit a list of jobs with options to the renderfarm

The Renderfarm interface has changed in Guerilla 2.0. The Renderfarm plug-ins must be modified to work with Guerilla 2.0:
In Guerilla 1.x, the plug-in crafted its job like that : guerilla.."/lua '"..job:getscriptfile (frame).."'"
In Guerilla 2.x, the plug-in crafts its job like that : fs.expand (job:getcommandline (frame))

This method is called by Guerilla when the user renders frames on the render farm.

The first argument is a list of jobs to execute in order. A job can be either a preprocess (such as baking a shadowmap once for a sequence of frames), a frame process (rendering frames) or a postprocess (building a movie of final frames.)

Submitted jobs can dependent on one another. It is the minimum requirement for a job scheduler to implement dependencies. For instance, a frame job may be dependent on a shadowmap baking, and eventually the final movie job is dependent on the rendering of the frame job.

A job is a simple Lua task containing the following data:

  • number JobId: a unique integer id
  • string Type: "frame", "pre" or "post"
  • boolean Array: the job is an array of frames
  • table Dependencies: the list of job ids this job is dependent on
  • string Script: the template path of the Lua job script to execute at each frame
  • string Name: the template name of the job

Additionally, jobs contain the following methods:

  • string getscriptname (number frame): get the actual name of the job for a given frame
  • string getcommandline (number frame): returns the job command line in a string, like '"$(GUERILLA)/lua" "job.lua" "--frame=1"'. Every command line arguments are quoted. Some arguments may contain environment variables like $(GUERILLA). Those variables must be expanded before to run the command. This command line must be executed in the options.JobsDirectory directory.
  • table getcommandargs (number frame): returns the job command line arguments in a table, like {"$(GUERILLA)/lua", "job.lua", "--frame=1"}. The first argument is the path of the application to run. Each entry of the table in an unquoted command line argument. Some arguments may contain environment variables like $(GUERILLA). Those variables must be expanded before to run the command. This command line must be executed in the options.JobsDirectory directory

The second argument is a table of options. Options are set either by Guerilla or by the caller of the render function. Usual options are:

  • string Name: a human readable name for the jobs to submit, default to the project name
  • string FrameRange: the list of frames to render, see rangetonumbers function for details on the format of the string
  • string ProjectDirectory: the directory of the current project, default to "$(SCENE_PATH)"
  • string JobsDirectory: the directory where job scripts are written, default to "$(JOBS)"
  • string RibsDirectory: the directory where rib files are written, default to "$(RIBS)"

A pseudocode RenderFarm implementation looks like:

-- Subclass RenderFarm
class ("MyFarm", "RenderFarm")

-- Construct MyFarm
function MyFarm:construct ()
    LocalPlug ("MyFarmSettings", self, 0, types.string, "")
    LocalPlug ("MyFarmOtherSettings", self, 0, types.int{min=10,max=20}, 15)
end

-- Generate the property template for MyFarm
function MyFarm:gettemplate ()
    return {"MyFarm",
        {
            { "Settings", self.MyFarmSettings },
            { "Other Settings", self.MyFarmOtherSettings },
        }
    }
end

-- Submit jobs to MyFarm
function MyFarm:submit (jobs, options)
-- Submit jobs to MyFarm
    local    frames = rangetonumbers (options.FrameRange)
    local    guerilla = "/usr/local/guerilla"
    -- A simple way to submit jobs is to submit them in order, and make sure
    -- the next job waits for the previous to finish
    for k, job in ipairs (jobs) do
        print ("Submit job "..job.Name)
        if job.Array then
            -- execute all frames on this job
            -- TODO: replace this with your own scheduler submission command!
            for k, frame in ipairs (frames) do
                lfs.chdir (fs.expand (options.JobsDirectory))
                os.execute ("echo running "..job:getscriptname (frame))
                os.execute (fs.expand (job:getcommandline (frame)))
            end
        else
            -- execute this single job
            -- TODO: replace this with your own scheduler submission command!
            lfs.chdir (fs.expand (options.JobsDirectory))
            os.execute ("echo running "..job:getscriptname (1))
            os.execute (fs.expand (job:getcommandline (1)))
        end
    end
end
Arguments:

  • jobs The list of jobs to submit
  • options The submission options

Return:

  • success Return true if submission is successful

nil declare ( RenderFarm interface )

Declare a new render farm interface.

The Renderfarm.declare function registers a new connection to a render farm system. You must call this function with an instance of a RenderFarm derivated class so Guerilla can edit the render farm properties and connect to it when submitting jobs.
Arguments:

  • interface An instance of the RenderFarm derived class.

RenderFarm result get ( string name )

Get a RenderFarm interface by its name

Arguments:

  • name The RenderFarm class name

Return:

  • result The RenderFarm instance

nil getlocal ( )

Get the batch or local RenderFarm interface

RenderFarm result getmain ( )

Get the current active RenderFarm interface

Return:

  • result The current RenderFarm instance