Christopher Beckford

Updated : September 04, 2024 09:07

Created : July 12, 2017 13:43

SUMMARY

This article explains how Live Rendering can be implemented in a renderer plug-in and covers the following topics:

• Attribute Convention
• RendererInfo Plug-in functions
• Render Plug-in functions
• Python Utilities
  - LiveRenderAPI
  - LiveRenderActions
  - Callbacks
• Gotchas
  - Single Sampled Updates
  - Non persistent updates
  

For a general explanation of LiveRendering, please find a description of it in the Katana User Guide section on Render Types, as well as see the Starting and Stopping Live Rendering sub-section of Performing a Render, and the section on Controlling Live Rendering.

A detailed description of other parts of renderer plug-ins, and documentation of other functions of the RenderAPI that are not directly related to LiveRendering can be found in the Renderer Plug-ins section of the Katana Developer Guide.

MORE INFORMATION

Attribute Convention

Katana’s Live Rendering system is powered by attributes in the scene graph. In the name of efficiency, only the attributes that are required to update the renderer are sent to the render plug-in. There is an attribute convention to determine which attributes these are, which is as follows:

liveRender.<updateGroup>.<attributeName>

<updateGroup> - This is a GroupAttribute that is used to group attributes together into a single update.

<attributeName> - This is the name of the top-level attribute to monitor. In the image above the liveRender.geoXform.xform attribute is instructing the live render system to send any changes to the top-level xform attribute. Note that this is a StringAttribute whose value usually matches the updateGroup this is for legacy reasons, but is not generally used internally. If multiple attributes are specified in the same update group they will all be sent to the renderer when ever any one of them changes.

RendererInfo Plug-in functions

void fillLiveRenderTerminalOps(OpDefinitionQueue& terminalOps,
                               const FnAttribute::GroupAttribute& stateArgs)

While it is possible to set up the above attribute convention in the node graph, it is typically more useful to use the fillLiveRenderTerminalOps() function in the RendererInfo plug-in to set up the attributes automatically when the Live Render starts. The function is passed an argument called terminalOps that is a std::deque that contains none or more std::pair objects containing the op type (as a std::string), and the op arguments (as a GroupAttribute).

Eg. The below code monitors changes in the xform attribute of light locations below /root/world/lgt.

FnAttribute::GroupBuilder opArgs;
opArgs.set("type", FnAttribute::StringAttribute("light"));
opArgs.set("location", FnAttribute::StringAttribute("/root/world/lgt"));
opArgs.set("attributeNames", FnAttribute::StringAttribute("xform"));
terminalOps.push_back(std::make_pair("LiveRenderFilter", opArgs.build()));

There are several Geolib3 Ops that ship with Katana that are useful here:

Renderer Plug-in functions

int startLiveEditing()

int stopLiveEditing()

These two functions are called from Katana to notify you of when live rendering is active and that updates to locations should be expected

int processControlCommand(const std::string & command)

This function is a method of communication from the Katana UI to the render plug-in. The UI can send a command as a string via the python LiveRenderAPI.SendCommand() function, which you can handle in the render plug-in for whatever purpose you desire.

int queueDataUpdates(FnAttribute::GroupAttribute updateAttribute)

When a monitored attribute changes, it’s new value will be passed to the render plug-in via this function. The passed attribute will contain three child attributes:

• type - The type of update (this is the <updateGroup> listed above in the attribute convention section)
• location - The scene graph location that this update is for.
• attributes - The value of the changed attributes. Note that if the location has been deleted, this will contain an attribute named deleted
  
  

Note that this function is called in a dedicated thread that is exclusively for the receiving of live render updates.

bool hasPendingDataUpdates()

This function tells the renderboot process whether there are live render updates that have been queued in queueDataUpdates() that should be applied.

int applyPendingDataUpdates() 

This function is called in the main render thread and should take any queued live updates and actually apply them. It is only called if hasPendingDataUpdates() returns true.

Python Utilities

Katana’s UI has several utilities to help improve the Live Rendering experience, presented below: 

LiveRenderAPI

This API allows you to send a custom command (string) or live update to the running live render with the LiveRenderAPI.SendCommand() and LiveRenderAPI.SendData() functions. It also has various functions to query and modify the list of terminal ops that are being used by the Live render subsystem. These terminal ops are used to determine when a location is changed, rather than cause changes to the current scene graph (as generated by your nodes). This is effectively a way to change the ops that were passed during the call to RendererInfo::fillLiveRenderTerminalOps().

LiveRenderActions

It is possible to extend the Render > Live Rendering menu with your own custom menu items through the use of the class in plugin_apis/python/BaseLiveRenderAction.py. Simply derive from the BaseLiverRenderAction class (which itself is derived from QtGui.QAction) and override the member functions. Your class can then make use of any of Katana’s python APIs, including the LiveRenderAPI, allowing it to send custom commands or updates to the render plug-in. Instances of LiveRenderActions should be placed in a $KATANA_RESOURCES/UIPlugins directory to ensure they only attempt to load during UI sessions.

Callbacks

Before sending either a live update or a live render command to the render plug-in the Katana will trigger a callback named onLiveRenderUpdate or onLiveRenderCommand respectively. These callbacks will be passed the command or update attribute that is about to be passed to the render plug-in. This is primarily for monitoring purposes, allowing you to inspect the data that is being passed to the render plug-in but it is also possible to prevent the message from being sent by raising an exception. This however will trigger an error message in Katana’s Message log.

Gotchas

Single Sampled Updates

When a render starts, geolib generates multi-sampled attributes to allow for motion blur etc. However in the Katana UI, attributes are generally only retrieved using a single sample and the Live Render updates come from the Katana UI. This means that attributes that are sent during a live update generally only have a single time sample.

Non persistent updates

When a render starts, the op tree to generate the scene is written to disk by Katana and read by the render process, which uses its own Geolib3 runtime. The render plug-in is given access to a SceneGraphIterator to query the scene graph and its attributes. This scene however is immutable. When a live render update is passed from Katana it cannot update the Geolib3 runtime. This means that the SceneGraphIterators will always return the original scene, even if live updates have been received by the render plug-in. It is therefore a requirement that live update attributes contain all of the information that the render plug-in needs, as you cannot safely use a SceneGraphIterator to get additional information.