RenderStream and Unity
RenderStream is the proprietary disguise protocol for controlling third party render engines from Disguise software. This topic covers the steps to configure Unity with RenderStream.
Warning: For cluster rendering it's recommended to use render nodes from the same Disguise product range, e.g. all rx series machines. Mixing of machines from different product ranges is untested and unsupported.
Unity is a third-party game engine that can be used to create 3D scenes. Unity projects can be adapted such that they create RenderStream output streams using disguise's Unity plugin. This plugin supports both camera and non-camera based mappings.
A professional license is required when working in Unity. Please visit the Unity website for more information on purchasing licenses and training on the Unity software.
-
In order to communicate with Disguise software, Unity requires the installation of a plugin on the render node.
-
The RenderStream pre-packaged plugins for Unity are available in the disguise github.
-
For the most up to date Unity plugin, you can compile the plugin from the source code here
-
Place the plugin into this folder : Unity: PROJECT_ROOT/Assets/DisguiseUnityRenderStream.
-
When adding a plugin to a Unity project, it is important that it is placed in the correct location and that the folder containing the plugin files is named correctly otherwise unexpected errors may occur.
-
Launch Unity, navigate to Projects and select New.
-
Select a project template (e.g. 3D)
-
Name the project, set the location to: “C:\Users\USERNAME\Documents\Renderstream Projects” or “D:\Renderstream Projects” if using a system with a media drive (e.g. RX) and select ‘Create’.
-
Open the project folder and place the plugin inside the ‘Assets’ folder.
-
Select File followed by Build Settings:
-
Set Architecture to Intel 64-bit.
-
-
Navigate to Player Settings… and Configuration:
-
Set Api Compatibility Level to .NET Framework
-
-
Optionally, set game object Channel visibility:
-
-
Edit then navigate to Project Settings…
-
Tags and Layers and Layers.
-
Give any empty User Layer a name.
-
Select any object from the scene
-
Set Layer to your newly defined Layer from the Inspector panel.
-
Select your Camera(s)
-
Select whether or not you want the Camera(s) to see the objects in your newly defined Layer by opening the Culling Mask dropdown from the Inspector panel.
-
-
Build the Unity project.
-
Save and close Unity.
Please note: Ensure the correct version of the disguise software is installed on all machines in network, including render nodes.
-
Create a new RenderStream Layer.
-
Select Asset and choose your Unity executable.
-
Right-click the Asset to open its editor:
-
Set Source Machine to the machine with the asset (used for syncing content).
-
-
Select Cluster pool and create a new cluster.
-
Within the Cluster Pool, add the desired machines.
-
Select Cluster assigner and create a new Cluster Assigner.
-
Within the Cluster Assigner:
-
-
Select the Asset.
-
Select Create Channels.
-
Within each Channel’s Cluster Assigner and/or the default Cluster Assigner:
-
Select the distribution strategy and video transport options (changes to transport settings require the workload to be restarted).
-
-
-
Expand the Default separator and right-click MultiChannelMap to open its editor:
-
Select Create Channels.
-
Assign one or more Mapping (regular Disguise mapping) to each Channel (e.g. frontplate). Each unique Channel-Mapping combination creates a new workload.
-
-
Right-click Workload to open its editor:
-
If the machines in the cluster pool do not have the content or the project has changed, press Sync.
-
Ensure all Sync Tasks are marked completed.
-
Press Start.
-
Wait for Workload status to switch to Running.
-
Warning: When launching a Unity executable for the first time, a Windows Firewall popup will appear. If the executable is not allowed through the firewall, Disguise software will not be able to receive the RemoteStream.
Warning: Unity assets can only be split across multiple nodes when using 3D Mappings (i.e. Camera Plate or Spatial). Attempting to split using a 2D Mapping will not work; all nodes will render the entire frame.
The Unity plugin allows you to expose certain options for each component of an object available within the scene. These options will be presented as parameters within the RenderStream Layer in Disguise software. Modifying the value of a parameter in turn changes the value of the corresponding option in Unity thus altering the options of the selected object within the scene.
-
Exposing a parameter in Unity:
-
Select an object from within the scene (e.g. any light source).
-
Select ‘Add Component’ at the bottom of the Inspector panel.
-
Add the ‘Remote Parameters’ component.
-
Drag and drop the component you wish to expose (e.g. Light) into the ‘Exposed Object’ field.
-
Expand the ‘Fields’ separator.
-
Select all options you wish to expose (e.g. Colour and Intensity).
-
-
Build the Unity project.
-
Save and close Unity.
-
Open the RenderStream layer in Disguise software and start the workload.
-
Modify parameter value(s).
The Unity plugins offers support for sharing textures remotely through the use of exposed parameters. This allows a two-way flow of video content between Disguise software and the Unity engine.
-
[Optional] Add a Plane (or any other 3D game object) to the scene.
-
Create a new Render Texture: Select 'Assets' in the Project panel. Right-click inside and select Create → Render Texture.
-
Drag and drop the new Render Texture onto your Plane (or 3D game object of your choice) in the scene. Confirm that the new Render Texture has been added as a 'Material' component to your game object. Confirm that the new Render Texture has been set as a material element in the 'Mesh Renderer' component of your game object.
-
Expose the Render Texture as a remote parameter: Add a 'Remote Parameters' component to the Plane (or 3D game object of your choice). Drag and drop the new Render Texture (Material) component into 'Exposed Object'. Open the 'Fields' separator and ensure that "Main Texture" is enabled (no need to enable any other fields).
-
Build the Unity project.
-
Save and close Unity.
-
Open the RenderStream Layerin Disguise software and start the workload.
-
Create a new layer (e.g. Video) and assign media (e.g. Ada).
-
Move the new layer underneath the RenderStream Layer with Ctrl+Alt+down arrow.
-
Alt+drag to arrow the newly created layer into the RenderStream Layer.
-
Confirm arrowed input appears in the RenderStream content.
You can also expose a Unity GameObject's transform parameters; this will allow you to control the object's movements in two ways which is defined by the field you expose. When exposing a GameObject's Transform, you will have the options to expose the following fields:
Transform: This allows you to control the full 3D transform (translation, rotation, scale) of the GameObject using a null object in the disguise software. This workflow is known as 3D Object Transform. The null object acts as a 'proxy', allowing you to move objects in 3D via the on-screen transform handles, or by linking it to a dynamic transform data source, e.g. a tracking device.
Local Rotation, Local Position, Local Scale: If you expose the local options these will give you the ability to keyframe the rotation, positions and scale in the disguise software allow for quick and easy manipulation of a Unity object on the Disguise timeline.
Note: if you expose all of the fields, the Local Rotation, Local Position and Local Scale will override the Transform in Disguise software. This will result in the null object not controlling the Unity GameObject.
The Exposed Parameter workflow can also be used to expose live text parameters using a “3D text” actor in the Unity engine. You can use the Remote Parameters workflows to expose the text input field in the disguise software allowing you to edit the text in real time.
Scenes in Unity can be composed of any number of game objects which are unique to that scene (by default). The Unity plugin offers two forms of multi-scene support:
Manual - this option restricts Disguise software's control of scenes and instead merges all Channels and remote parameters into a single scene.
Selection - this option allows scenes to be controlled from inside Disguise software; Channels are merged into a single list (duplicates removed) and remote parameters are per-scene.
-
Create a new scene:
-
Open the Kebab menu for your current scene in the Hierarchy panel.
-
Select Add New Scene.
-
Optionally, populate scene with your desired game objects and exposed parameters.
-
Select Resources then DisguiseRenderStreamSettings from the Project panel.
-
Set Scene Control option accordingly.
-
Build the Unity project.
-
Save and close Unity.
-
Open the RenderStream Layer in Disguise softwareand Start the workload.
-
Modify the Scene parameter as part of your normal sequencing.
The Unity plugin offers Timecode support. This means that if any game object has a ‘Playable Director’ component and is animated using timeline functionality, it will be reflected in Disguise software timeline.
-
Adding time control to an object in Unity:
-
Select Windowfollowed by Sequencing followed by Timeline.
-
Optionally, move the Timeline Window from the main panel to the bottom panel (i.e. drag and drop Timeline Window next to Console Window).
-
Select an object from within the scene (e.g. any user placed prop).
-
Click the Create button within the Timeline Window.
-
Save the new Timeline.
-
Hit the Record button on the newly created Animator for the chosen object within the Timeline.
-
Add an initial keyframe by right-clicking on any animatable property of the object (e.g. Position) and select Add Key.
-
Move the Playhead along the Timeline.
-
Modify your chosen property either by using the 3D controls within the Scene or by updating the value directly from within the Inspector panel (a keyframe will be added automatically when a value is changed).
-
Hit the Record button again to stop recording.
-
Return the Playhead to the beginning of the Timeline and play the sequence to confirm your animation is correct.
-
With the object still selected, select Add Component at the bottom of the Inspector panel.
-
Add the Time Control component.
-
-
Build the Unity project.
-
Save and close Unity.
-
Open the RenderStream Layer inDisguise software and Start the workload.
-
Play your timeline within Disguise software.
-
There is no need to attach the Disguise RenderStream script to the cameras in Unity. Cameras will auto-configure on asset launch.
-
When using the ‘Manual’ scene selection option in Unity, game objects from all built scenes will not appear in the “Default” scene. In order to merge scenes and/or dynamically load/unload them, a custom script must be used.
-
The “Default” scene will be the first indexed scene from within the ‘Scenes In Build’ table in Unity’s build options.
-
The exposed parameters from all scenes will still show within Disguise software, even if game objects from all built scenes are not merged into the “Default” scene.
-
When using the ‘Selection’ option in Unity, game objects and exposed parameters are unique to each scene. There is no shared object scene similar to the “Persistent” level in Unreal Engine.
- When launching a Unity executable for the first time, a Windows Firewall popup will appear. If the executable is not allowed through the firewall, Disguise software will not be able to receive the RemoteStream
-
Game objects included as part of a Unity template may not be be able to be controlled via Timecode. This is a Unity issue rather than one with the disguise script.
-
If attempting to use the Unity High Definition Render Pipeline (HDRP):
-
Both the ‘Windows 10 SDK' and 'Game Development with C++’ modules must be installed as part of your Visual Studio installation.
-
The ‘Scripting Backend’ must be set to “Mono” when building the executable.
-
- Since Unity Assets are built executables, Disguisewill not recognise the ‘Engine’ of them; they will simply be reported as “Custom”. Disguise will not be able to report the Unity plugin version used within built executables. If an incompatible Disguise-Unity plugin combination is used, no explicit notification will be shown.