Methods
<Interface>GetManager()
In order to access network rendering through MAXScript, you need to create a manager instance.
The syntax is the following:
NetRender.GetManager()
Mixin Interface: netRender.getManager(...)
Interface: NetManager
This MixinInterface returned by the NetRender.GetManager method lets you access network rendering through MAXScript.
Job Properties that Require SendUpdate
Accessing Render Element Information
Properties
The following properties can be used to get information or set certain properties of the manager.
<netManager>.connected
Returns true if connected to the manager. Read-only.
<netManager>.netStatus
Returns the status of the manager. Various information about the manager can be gathered through netstatus, see netstatus topic. Read-only.
<netManager>.wantControl
If you have QueueControl, and other computers call QueryControl, this indicates whether you want to maintain control, or relinquish it; their call to QueryControl will return whatever you have set for WantControl
<netManager>.haveControl
True, if you currently have QueueControl. Read-only.
<netManager>.numJobs
Returns the number of jobs in the queue. Read-only.
<netManager>.numServers
Returns the number of servers. Read-only.
<netManager>.numGroups
Returns the number of groups. Read-only.
Methods
The following methods can be used to query and or control the manager.
<netManager>.setCallback <#progress | #message | #update | #managerdown | #queuecontrol | #querycontrol> <somefunction>
Used to listen to the manager for certain event types that occur during a network render. For each event type, you can call a single function that you define. Each of the 6 callback types is one type of event, and you can install a callback for any of these event or none.
You must define the function to take a different number of arguements depending on the event type.
Requires 2 arguments, they can be:
#progress myprogess
Called anytime a download/upload is underway, including anytime you fetch information about jobs or servers.
Requires a function defined with 2 integer parameters, ‘Total’ and ‘Current’. Total is the total amount to transfer, and Current is the amount tranferred so far.
Example:
fn myprogress total current = -- NOTE: two integer parameters
format "Progress: completed % out of %\n" current total
m.setcallback #progress myprogress -- sets the #progress callback to use myprogress()
#message mymessage
Called when the manager has a text message for the user. Requires a function defined with 1 string parameter which is the message text.
Example:
fn myNetMessage msg = -- NOTE: one string parameter
format "Message: %\n" msg
m.setcallback #message mymessage -- sets the #message callback to use mymessage()
#update myupdate
Called when something has changed, like a job started or finished. Let's you know when you need to make GetUpdate calls, or other refreshing. Requires a function defined with no parameters.
Example:
fn myUpdate =
job.GetUpdate() --example of what you might do
m.setcallback #update myupdate -- sets the #update callback to use myupdate()
#managerdown mymanagerdown
Called when the manager shuts down. Requires a function defined with no parameters.
Example:
fn myManagerDown =
format "Manager is dead\n"
m.setcallback mymanagerdown -- sets the #managerdown callback to use mymanagerdown()
#queuecontrol myqueuecontrol
Called whenever queue control changes. Requires a function defined with no parameters.
Example:
fn myQueueControl =
format "Queue control has changed\n"
m.setcallback #QueueControl myQueueControl --install the "QueueControl" callback
#querycontrol myquerycontrol
Called when you have Queue Control, and another computer wants it, either via the QueueManager, or with the script function <netManager>.QueryControl(). If you want to keep control, set the value <netManager>.WantControl to true, otherwise set it to false. The function must take one arguement, which is the name of the machine requesting control. See the function <netManager>.QueueControl() for more information.
Example:
fn myQueryControl clientName = ( --NOTE: one string parameter
format "The computer % wants queue control" clientName
m.wantControl = true -- use this to keep queue control
m.wantControl = false -- use this to release queue control
)
m.setcallback #QueryControl myQueryControl --install the "QueryControl" callback
<netManager>.GetCallback <#progress | #message | #update | #managerdown | #queuecontrol | #querycontrol>
Returns the name of the function used for that particular callback. Returns an empty array if no callback is assigned. Requires 1 argument, can be:
#progress : Called anytime a download/upload is underway, including anytime you fetch information about jobs or servers
#message : Called when the manager has a text message for the user
#update : Called when something has changed, like a job started or finished. Let's you know when you need to make GetUpdate calls, or other refreshing
#managerdown : Called when the manager dies
#queuecontrol : Called whenever queue control changes
#querycontrol : Called when you have Queue Control, and another computer wants it
<netManager>.connect #manual <manager name>|<manager IP address> [port:<integer>]
or
<netManager>.connect #automatic <subnet mask> [port:<integer>]
Establishes a connection to the manager, allowing access to job states, server states, editing job settings, etc….It takes 2 arguments and a 3rd optional argument. You can either connect to a manager manually by specifying the manager name or ip address of the manager as a string, or automatically by specifying the subnet mask and optional port number,
for example:
m.connect #manual "manager" -- connects to manager of name "manager"
or
m.connect #manual "192.168.0.1" -- connects to manager of IP 192.168.0.1
or
m.connect #automatic "255.255.255.0" port:1234
-- automatically connects to manager on subnet 255.255.255.0 at port 1234
in either case, you can specify the optional port number should the manager be using a non default port number. Will return true if connection was succesful.
<netManager>.Disconnect()
Disconnects the connection established with <netManager>.connect.
<netManager>.Kill()
Shutsdown the manager. You must have queue control to do this.
<netManager>.QueryControl <#wait | #dontwait>
This requires either #wait or #dontWait. The function works as follows:
Nobody has queue control: #dontWait returns true, #wait returns true.
Someone has queue control: #dontwait returns false, #wait prompts the current queue controller.
In the last case, the queue controller gets the QueryControl callback, and must indicate if they want control. If that user indicates they want to keep control, then the function returns false, if they will give up control (or the 10 second timeout expires), it returns true. Note that the QueueManager gives a prompt for the user to indicate what they want; in MAXScript, you just get the callback and have to use the wantControl value.
Note: Please refer to callback, "#queuecontrol myqueuecontrol", found above in <netManager>.setCallback.
<netManager>.GetControl()
Takes control of the queue. Returns true if control was taken. From that moment on, jobs can be submitted, edited, reprioritized, servers can be removed, until queue control is relinquished.
Note: The current queue controller does not get its QueryControl callback triggered. Instead, they just lose the queue control (unless they also have the queue locked lock). You should always precede a call to GetControl() with a call to QueryControl(true), to be sure if it’s OK to do this.
<netManager>.Lock <true | false>
Locks out others from getting queue control; and if they call QueryControl, it will automatically return false. For example, suppose you got control of the queue through MAXScript using getcontrol(), someone else who has the queuemanager up in readonly mode can request queuecontrol. Setting lock to true, will disallow anyone else to take control until you until you disconnect from the manager, or until you reset the lock to false. Note that the QueueManager always calls QueryControl to check if it can grab the queue.
<netManager>.SetUpdates <true | false>
This function’s usage resembles the Lock() function, in that a boolean value is passed, and you must already have queue control. Setting updates to false will freeze the manager so that it refuses any changes to the queue. It does not affect the callbacks. Fewer Update callbacks will be received, since the job queue is not updating. Use this function when submitting large numbers of changes, and when you want all the changes to take effect at the same time. This will occur when setUpdates is called with a true value.
<netManager>.checkoutputvisibility <path>
Takes 1 argument, a pathname defined as a string, ie "c:\\temp". It verifies that the path exists, returns "The system cannot find the path specified. (0x3)" if the path doesn't exist.
Note:
Note that the manager checks this output path relative to itself, not to your local machine. Thus if you pass "C:\\" and you have not shared you C drive, it will return OK (because the manager checks its own C drive). Thus you should use a network name when calling this function, like "\\\\mymachine\\share\\". Also, if the parameter does not end in \\, the functions assumes you're naming a file (not a directory) and checks whether this file could be created. Always include the \\ at the end if you're checking whether a directory is accessible.
Various functions and properties can be used to access jobs. You can use the GetJobs() function to retrieve an array of all jobs in the queue. The jobs can be filtered in various ways to return an array based on the filter.
Note:
Do not call GetJobs() or GetServers() very often, because these are VERY heavyweight methods.
<netManager>.getjobs [filter:#suspended | #complete | #waiting | #started | #error | #name | #handle | #index] [key:<name> | <handle> | <index>]
The latter three filter types require a corresponding key arguement. If used without a filter, returns an array of all jobs in queue. If no jobs are in the queue, an empty array will be returned.
filter:#suspended: Returns an array of all suspended jobs. Returns an empty array #() if no jobs are suspended
filter:#complete: Returns an array of all completed jobs. Returns an empty array #() if no jobs are complete.
filter:#waiting: Returns an array of jobs that are waiting to be rendered or are being rendered. Will return an empty array #() if no jobs are waiting.
filter:#started: Returns an array of jobs that are actually started and being rendered.
filter:#complete: Returns an array of all completed jobs. Returns an empty array #() if no jobs are complete
filter:#error: Returns an array of all jobs experiencing an error. Returns an empty array #() if no jobs have errors
filter:#name: Pass a name as the Key argument; Returns an array of all jobs with the given name. Returns an empty array #() if the no jobs have that name
filter:#handle: Pass a handle as the Key argument; the job with that handle will be returned (as an array with one element). Returns an empty array #() if the no job has that handle
filter:#index: Pass an integer as the Key argument; the job at that index in the queue will be returned (as an array with one element). Returns an empty array #() if the no job exists at that index
Example:
manager.GetControl() --get queue control
manager.SetUpdates false --the queue is now frozen
jobs = manager.GetJobs()
manager.SetUpdates true --the queue is unfrozen
Note:
The GetJobs() function could return incorrect results if the Queue is changed while the job information is downloading. SetUpdates is used to guarantee that GetJobs operates without error.
<netManager>.SetJobOrder <array>
Changes the order of the jobs in the queue. The array must contain the same jobs that are contained in the array from .getjobs(), although they can be in different order. You must also have queuecontrol, use .getcontrol() function to take control before setting the job order.
<netManager>.NewJob file:<filename>
Creates a new job instance. It requires a valid max file name, ie a max file that exists somewhere on the hard drive or the network. Returns a job definition if the file exists, undefined if the file can’t be found.
Example:
job.newJob file:"file.max" --submitting a file
job.newJob() --submitting the current scene
Note:
Jobs can not have maps included, and render element data will not be available for submitted job but render elements will process correctly. These problems are resent when submitting a job from a file, but not when submitting the current scene.
<job>.GetUpdate()
Updates the information about the selected job. Remember this involves a network interaction, so it’s a heavyweight operation
<job>.SendUpdate()
Updates the job in the queue with new job settings. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. Remember this involves a network interaction, so it’s a heavyweight operation.
<job>.Submit() Servers:<array>
Submits a new job to be rendered to the queue. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control. if no servers are provided, then all servers will be assigned to the job.
<job>.Suspend()
Suspends the selected job. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.
<job>.Resume()
Will cause the job to resume where it left off when it was suspended. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.
<job>.Restart()
Will restart the job from the beginning. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.
<job>.Delete()
Will delete the job from the queue. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.
<job>.AssignServer <server>
Assigns a selected server to the job. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.
<job>.SuspendServer <server>
Removes a server from the selected job. Must have queuecontrol. Use <netManager>.getcontrol() to get queue control.
<job>.GetServerInfo <integer>
Gets information about a particular server assigned to the job. Requires a server number, 1 based.
<job>.nonconcurrentDriver
Returns true if the output cannot be rendered one frame at a time (like an .MOV file). READ-ONLY.
<job>.uninterruptibleDriver
Returns true if the render cannot be resumed after it is interrupted or suspended.
For example, you cannot render half of an .AVI file, then finish it later. You need to render the whole thing without interruption. Read-only.
<job>.GetCameras()
Returns an array of cameras in the scene. An empty array #() is returned if no cameras are in the scene.
<job>.GetLog() start:x numLines:y
Returns the log for the job as text. The 'start' and 'numLines' parameters are optional. If you pass no parameters, you get the entire log. If you only pass start, you get every line starting from the given line. If you pass only numLines, then start is assumed to be 0.
<job>.GetServerStatusText <server>
Returns any messages from the chosen server assigned to the job. Will return an empty string if no messages from the server. Read-only.
<job>.numServers
Returns the number of servers assigned to the job. Read-only.
<job>.state
Returns the state of the job. This can be #complete, #suspended, #busy or #waiting. Read-only.
<job>.serverPID
This function gives low-level information that is intended for internal-use-only.
<job>.handle
Returns the job’s handle. Read-only.
Many of the following values are read-write, but changes you make to these values will not register with the manager until you call <job>.SendUpdate().
Note
SendUpdate requires queue control (obtained via <NetManager>.getControl)
<job>.name
Returns the name of the job. The name can be changed.
<job>.filesize
Returns the job’s file size.
<job>.filesizeExtracted
Returns the job’s extracted file size. Read-only.
<job>.timeSubmitted
Returns the time at which the job was submitted as a string.
<job>.timeStarted
Returns the time at which the job was started as a string. Returns undefined if job hasn’t started. Read-only.
<job>.timeFinished
Returns the time at which the job was finished as a sting. Returns undefined if job hasn’t finished. Read-only.
<job>.notifications
Returns true if notifications are on. Can be changed.
<job>.notifyFailure
Returns true if notified of failures. Can be changed.
<job>.notifyProgress
Returns true if notified of progress. Can be changed.
<job>.notifyCompletion
Returns true if notified of progress is on. Can be changed.
<job>.notifyFrameInterval
Returns an interval at which notifications occur. Can be changed.
<job>.fromFrame
Returns the rendering start frame. Can be changed.
<job>.toFrame
Returns the rendering end frame. Can be changed.
<job>.nthFrame
Returns the rendering frame interval. Can be changed.
<job>.outputWidth
Returns the width of the rendered frame. Can be changed.
<job>.outputHeight
Returns the height of the rendered frame. Can be changed.
<job>.numFramesComplete
The number of completed frames for the job. Read-only.
<job>.priority
Returns the job priority.
<job>.videoPost
Returns true if there is a video post sequence. Read-only.
<job>.nonconcurrentDriver
Returns true if the output cannot be rendered one frame at a time (like .MOV). Read-only.
<job>.includeMaps
Returns true if the job was submitted with include maps on. Can be changed.
<job>.uninterruptibleDriver
Returns true if the render can’t be resumed if it was interrupted or suspended. For an.AVI, you cannot render half the file, then finish it later. You need to render the whole thing without interruption. Read-only.
<job>.skipRenderedFrames
Returns true if skip rendered frames was set to on when job was submitted. Can be changed.
<job>.useAllServers
Returns true if use all servers was set to on when job was submitted. Can be changed
<job>.suspended
Returns true if the job is suspended. Read-only. To suspend the job use <job>.suspend().
<job>.finished
Returns true if the job is finished. Read-only.
<job>.ignoreShare
Returns true if the job was submitted with ignore share on. Can be changed.
<job>.skipOutputTest
Returns true if the job was submitted with skip output test on. Can be changed.
<job>.nonSeqFrames
Returns true if the job was submitted to render non sequential frames. Can be changed.
<job>.combustionJob
Returns false if the job is a max job. Read-only.
<job>.uncompressedFile
Returns false if the job file is compressed. Read-only.
<job>.gammaCorrection
Returns true if the job was submitted with gamma correction on. Can be changed.
<job>.gammaValueIn
Returns a float value of the incomming gamma value. Can be changed.
<job>.gammaValueOut
Returns a float value of the outgoing gamma value. Can be changed.
<job>.renderPixelAspect
Returns a float value of the render pixel aspect ratio. Can be changed.
<job>.renderCamera
Returns a string with the name of the camera view being rendered. Will return an empty string if view being rendered is an non camera view, ie perspective, front, user, etc…Can be changed. Use <job>.getcameras() function to get a list of valid cameras in the scene to change to.
<job>.renderElements
Returns true if a job was submitted with the render elements active. Note that this will return true even there aren’t any elements to be rendered. Can be changed.
<job>.numSceneObjects
Returns the number of objects in the scene as an integer. Read-only.
<job>.numSceneFaces
Returns the number of faces in the scene as an integer. Read-only.
<job>.numSceneLights
Returns the number of lights in the scene as an integer. Read-only.
<job>.sceneStartTime
Returns the scene start time in frames, so if your scene is set to use MM:SS:Ticks, this will still return a value in frames.
<job>.sceneEndTime
Returns the scene end time in frames.
<job>.videoColorCheck
Returns true if the job was submitted with videocolorcheck on. Can be changed.
<job>.force2Sided
Returns true if the job was submitted with force 2 sided on. Can be changed.
<job>.renderHiddenObjects
Returns true if the job was submitted with render hidden objects on. Can be changed.
<job>.renderAtmosphericEffects
Returns true if the job was submitted with render render atmospheric effects on. Can be changed.
<job>.superBlack
Returns true if the job was submitted with superblack on. Can be changed.
<job>.serialNumbering
Returns true if nth serial numbering is on this property is accesible through the preferences \ rendering dialog.
<job>.ditherPaletted
Returns true if Dither Paletted was enabled when the job was submitted. Can be changed.
<job>.ditherTrueColor
Returns true if Dither True Color was enabled when the job was submitted. Can be changed.
<job>.renderFields
Returns true if Render Fields was enabled when the job was submitted. Can be changed.
<job>.renderDisplacements
Returns true if displacements was enabled when the job was submitted. Can be changed.
<job>.renderEffects
Returns true if render effects was enabled when the job was submitted. Can be changed.
<job>.fieldOrder
Returns either #odd or #even depending on what the field order was set to when job was submitted. Can be changed.
<job>.numRenderElements
Returns the number of render elements in the scene. Read-only.
<job>.userName
Returns the name of the user, as a string, that submitted the job. Note that if a job is submitted through MAXScript using <job>.submit(), and the max file was last saved by another user on a different computer, the username will be that of the other user. Read-only
<job>.computerName
Returns the name of the computer, as a string, that the job was submitted from. Note that if a job is submitted through MAXScript using <job>.submit(), and the max file was last saved by another user on a different computer, the computername will be that of the computer on which the max file was last saved. Read-only
<job>.managerShare
Returns the shared folder as a string where all jobs are stored on the manager.
<job>.frames
Returns a string of frames to render, ie "1,3,5-12". Can be changed.
<job>.frameOutputName
Returns the name and path of the output file. Can be changed