PV Render Queue API Documentation

This document describes the nr.pvrq2 module. It exposes a rich API to develop extensions that is used internally by the PV Render Queue 2 plugin as well.

Example

This is a stripped down version of the queue_current_project.py script that is delivered with the plugin. It simply takes the full path to the document and creates a new FileRenderJob from it, appending as the last job in the render queue.

import c4d, os
import nr.pvrq2

def main():
  filename = os.path.join(doc.GetDocumentPath(), doc.GetDocumentName())
  job = nr.pvrq2.FileRenderJob(filename)
  nr.pvrq2.root.append(job)
  c4d.EventAdd()

main()

Data

nr.pvrq2.STATUS_PENDING = 'pending'

Job is pending in the queue

nr.pvrq2.STATUS_RENDERING = 'rendering'

Job is currently rendering

nr.pvrq2.STATUS_COMPLETED = 'completed'

Job has been completed

nr.pvrq2.STATUS_FAILED = 'failed'

Job could not be rendered successfully

nr.pvrq2.STATUS_CANCELLED = 'cancelled'

Job was cancelled by the user

nr.pvrq2.res = None

The resource of the PV Render Queue 2 plugin. Will be bound at the time the plugin is loaded.

nr.pvrq2.root = <nr.pvrq2.Root object at 0x03AE52D0>

Root object that contains all RenderJob and Folder objects.

Functions

nr.pvrq2.register_node_plugin(cls)

Registers a BaseNode subclass to PV Render Queue, allowing instances of that implementation to be serialized when they’re in the render queue.

Parameters:

cls – A BaseNode subclass.

Raises:
  • ValueError – If cls.ident is already used.
  • TypeError – If cls is not a BaseNode subclass.
nr.pvrq2.get_cache_filename()

Returns the filename at which the cache of the queue is saved.

nr.pvrq2.is_rendering(node=None)
Returns:True if any of the nodes in the tree starting at node is currently rendering, False if not.
nr.pvrq2.delete_node(node)

Deletes a node from the render queue. If a render job is encountered that is currently rendering, and the user says not to stop the current rendering, nothing will happen.

Returns:True if the node has been deleted, False if not.
nr.pvrq2.move_selected(direction)

Move the selected nodes up or down.

Parameters:direction'up' or 'down'
nr.pvrq2.move_node(node, direction)

Move the specified node up or down.

Parameters:
  • node – The node to move.
  • direction – The direction to move the node to.
Returns:

True if the node was moved, False if not.

nr.pvrq2.cancel_rendering()

Cancels the external rendering. The user will have to reply wether the rendering should really be cancelled or not. Returns True if the active external rendering was cancelled, False if not.

nr.pvrq2.status_str(status)

Converts a render job status to a localized string.

RenderJob Objects

class nr.pvrq2.RenderJob

Bases: nr.pvrq2.BaseNode

Represents a job that is to be rendered in the Picture Viewer. It is, however, an abstract base class that can be subclassed to implement custom behaviour of the job (eg. pre-processing before rendering, notifications, whatever).

A RenderJob is not expected to have child nodes.

Known subclasses: FileRenderJob

render_tr

A bool flag that specifies whether the job should be rendered with Team Render or using the standard Render to Picture Viewer command.

status

The status of the job. Any of the following values:

error_message

None or a str if there was an error with the job.

resettable

Class-level attribute that specifies if the job is resettable using reset().

completed()

Called when the render job completed. It can not be determined if it finished successfully or not.

get_job_details()

Return a dictionary with meta information about the job.

get_scene()

Called to retrieve the Cinema 4d BaseDocument that should be rendered in the Picture Viewer. Returns None if the scene could not be loaded. The job’s status will be set to STATUS_FAILED.

name

Return the name of the render job (eg. the name of the scene file).

read(hf, disklevel)

Implements reading the RenderJob from a HyperFile. Subclasses must call the parent implementation if they override this method.

reset()

Reset the status of the job, allowing it to be processed by the render queue once again. This method should only be called if resettable is True.

show_job_details()

Called to open a dialog with information on the job. The default implementation will use the dictionary returned by get_job_details() and display it in a dialog.

write(hf)

Implements writing the RenderJob information to a HyperFile. Subclasses must call the parent implementation if they override this method.

FileRenderJob Objects

class nr.pvrq2.FileRenderJob(filename='')

Bases: nr.pvrq2.RenderJob

This class implements a render job from a scene file.

Folder Objects

class nr.pvrq2.Folder(name='???')

Bases: nr.pvrq2.BaseNode

Represents a folder that can contain a number of render jobs. All children of a folder are supposed to be RenderJob objects.

folder = nr.pvrq2.Folder('John Doe's stuff')
folder.append(job1)
folder.append(job2)
nr.pvrq2.root.append(folder)

BaseNode Objects

class nr.pvrq2.BaseNode

Base class for nodes in the render queue. Provides properties such as an elements enabled and selection state. Instances of this class can be serialized to and from c4d.HyperFile objects but their constructor must be callable with no arguments for that to work.

enabled

A bool flag that is used to determine if the node is enabled. In the case of a RenderJob, this member determines if the job should be rendered or skipped.

selected

A bool flag that specifies whether the node is selected in the GUI or not. This member is not saved during serialization.

uuid

The uuid.UUID of the node. This is used to keep track of parent-child relationships during the serialization process with read() and write().

enabled_state

Returns the enabled state of the node, based on its own state and the state of its parent nodes.

Returns:'enabled', 'disabled' or 'tristate'
get_selected_nodes(children=True, result=None)

Returns a list of the selected nodes including self.

iter_tree(filter=None)

Recursively iterate over the complete tree.

name

Return the name of the node.

read(hf, disklevel)

Overridable. Read a node from a HyperFile.

Parameters:
  • hf – A HyperFile object.
  • disklevel – The disklevel of the data that was written to the HyperFile, as it was specified to register_node_plugin().
Raises:

NotImplementedError – Default implementation. Should be raised if serializable() would return False.

Returns:

The BaseNode object or None if it could not be read.

set_selected(selected, recursive=False)

Set the selection state of the node, optionally recursively.

write(hf)

Overridable. Write the node to a HyperFile.

Parameters:hf – A c4d.HyperFile object.
Returns:True if the job was written successfully, False if not.

TreeNodeBase Objects

class nr.pvrq2.node.TreeNodeBase

A base class to construct tree structures.

root
Getter:Returns the root of the tree.
Type:TreeNodeBase
parent
Getter:Returns the parent node of this node.
Type:TreeNodeBase
next
Getter:Returns the next node of this node.
Type:TreeNodeBase
pred
Getter:Returns the preceding node of this node.
Type:TreeNodeBase
down
Getter:Returns the first child node of this node.
Type:TreeNodeBase
down_last
Getter:Returns the last child node of this node.
Type:TreeNodeBase
children
Getter:Returns a list of the node’s children.
Type:list of TreeNodeBase
append(node, index=None)

Appends node at the specified index. If index is None, node will be inserted at the end of the children list. The index can not be a negative value as it would need to count the number of childrens first.

flush_children()

Remove all child nodes from this node.

insert_after(node)

Inserts self after node. self must be free (not in a hierarchy) and node must have a parent node, otherwise a RuntimeError is raised.

insert_before(node)

Inserts self before node. self must be free (not in a hierarchy) and node must have a parent node, otherwise a RuntimeError is raised.

is_dangling()

Returns True if the node is a dangling node, meaning it is not inserted in a hierarchy. A dangling node has no parent or neighbouring nodes.

iter_children(recursive=False)

Iterator for the children of this node. If recursive is True, the function will iterate recursively over all children as well.

remove()

Removes the node from the parent and neighbouring nodes. Does not detach child nodes.