Scripting API
TODO : this is not up to date
You can access some of Predict Unity functionalities via script. The full documentation of the Predict Unity scripting API is not available yet but you can find bellow a quick view of the main functionalities.
The main clases that can be called within the Predict Unity plug-in are the following :
Managers :
Process Manager : start, reload and stop Predict Engine processes,
Input Manager : send user inputs to Predict Engine via the shared memory,
Output Manager : save the Predict Engine or Unity simulation,
Shortcut Manager : a component that gives access to all Predict Unity basic tools,
Batch Renderer : save a batch of Predict Engine simulations.
Components :
UVR Camera Component : the Predict Engine camera settings,
UVR Physical Sensor Component : the Predict Engine physical sensor settings,
UVR Light Component : the Predict Engine light settings,
UVR Skybox Component : the Predict Engine environment settings,
UVR Scene Component : the Predict Engine scene settings,
UVR Cluster Component : the Predict Engine cluster settings.
Pickers :
Transform Picker : move GameObjects in the scene,
Material Picker : change the materials of one or several geometries in the scene,
Rgb Environment Picker : change the environment of one of the cameras in the scene,
Setup Picker : enable and disable elements in the scene,
Geometry Picker : change the mesh on a geometry,
IES Picker : change the IES on a photometric area light,
Display EDF Picker : change the measure on a display area light.
The main functionalities in the Predict Unity plug-in are described bellow :
Start processes
Start a process
You can start a new process by calling the following method :
static IEnumerator UVR.ProcessManager.StartProcessForCameraAsync(Camera camera, UVR.EngineProcess.ProcessTarget target = EngineProcess.ProcessTarget.Overlay, bool loadStructure = true) : Start a new process for the given camera. The target defines if the process is associated with an Overlay, destined to the Renderer view or to the Batch renderer. The scene structure is updated if loadStructure is true.
public void StartOverlayProcessWithCurrentStructureForCamera(Camera camera)
{
UVR.PluginEnvironment.StartCoroutine(UVR.ProcessManager.StartProcessForCameraAsync(camera, EngineProcess.ProcessTarget.Overlay, false);
}
Enable the Predict Engine overlay
You can enable the engine overlay by calling the following method :
static void UVR.ProcessManager.SetOverlayEnabled(bool enabled) : Enable/Disable the engine overlay depending on the enabled value.
public void EnableOverlay()
{
UVR.ProcessManager.SetOverlayEnabled(true);
}
Start the Predict Engine view
You can start the engine view by calling the following method (editor only) :
static void UVR.EngineViewManager.Play() : Start the render view.
public void StartRenderView()
{
UVR.EngineViewManager.Play();
}
Get processes
Get the process for a camera used in the Predict Engine overlay
You can get the process for a camera used in the engine overlay by calling one of the following methods :
static UVR.EngineProcess UVR.ProcessManager.GetProcessForCamera(Camera camera) : Return the first overlay process associated with this camera.
static List<UVR.EngineProcess> UVR.ProcessManager.GetAllProcessesForCamera(Camera camera) : Return all the overlay processes associated with this camera.
public UVR.EngineProcess GetProcessForOverlayCamera(Camera camera)
{
if (camera == null) return;
UVR.EngineProcess lCameraProcess = UVR.ProcessManager.GetProcessForCamera(camera);
return lCameraProcess;
}
Get all the overlay processes
You can get all the processes used in the engine overlay by calling the following method :
static List<UVR.EngineProcess> UVR.ProcessManager.GetAllOverlayProcesses() : Return all the overlay processes.
public List<UVR.EngineProcess> GetAllOverlayProcesses()
{
List<UVR.EngineProcess> lOverlayProcesses = UVR.ProcessManager.GetAllOverlayProcesses();
return lOverlayProcesses;
}
Get the process for the engine view
You can get the process for the engine view by calling the following method :
static UVR.EngineProcess UVR.ProcessManager.GetRendererProcess() : Return the render view process.
public UVR.EngineProcess GetProcessForRenderView()
{
UVR.EngineProcess lProcess = UVR.ProcessManager.GetRendererProcess();
return lProcess;
}
Get all the processes
You can get all the processes currently started by calling the following method :
static List<UVR.EngineProcess> UVR.ProcessManager.GetAllProcesses() : Return all the processes.
public List<UVR.EngineProcess> GetAllProcesses()
{
List<UVR.EngineProcess> lProcesses = UVR.ProcessManager.GetAllProcesses();
return lProcesses;
}
Get the process for the batch renderer
You can get the process for a camera used in the engine overlay by calling the following method :
static UVR.EngineProcess UVR.ProcessManager.GetBatchProcess() : Return the batch renderer process.
public UVR.EngineProcess GetProcessForBatchRenderer()
{
UVR.EngineProcess lBatchProcess = UVR.ProcessManager.GetBatchProcess();
return lBatchProcess;
}
Pause processes
Pause an overlay process
You can pause the Predict Engine renderer for an overlay process by calling the following method :
void UVR.EngineProcess.pause(bool isPaused) : Pause the Predictive Engine renderer for the process. The isPaused attribute defines whether the scene is paused or unpaused.
public void PauseTheRendererForProcess(UVR.EngineProcess process)
{
if (process == null) return;
process.Pause(true);
}
Pause all overlay processes
You can pause the Predict Engine renderer for all overlay processes by calling the following method :
static void UVR.ProcessManager.PauseProcessForAllOverlayCameras(bool paused) : Pause the Predictive Engine renderer for all overlay processes. The isPaused attribute defines whether the scene is paused or unpaused.
public void PauseTheRendererForAllOverlayProcesses()
{
UVR.ProcessManager.PauseProcessForAllOverlayCameras(true);
}
Pause the engine view
You can pause the Predict Engine in the engine view by calling the following method :
static void UVR.EngineViewManager.Pause() : Pause the render view.
public void PauseRenderView()
{
UVR.EngineViewManager.Pause();
}
Reload processes
Reload an overlay process
After you have made changes in the Unity scene, you can reload the Predict Engine scene for a given process by calling the following method:
static IEnumerator UVR.ProcessManager.ReloadOverlayProcess(UVR.EngineProcess process, bool reloadStructure = false) : Reload the given process and reload the scene structure if reloadStructure is true.
public void UpdateStructureAndReloadOverlayProcess(UVR.EngineProcess process)
{
if (process == null) return;
UVR.PluginEnvironment.StartCoroutine(UVR.ProcessManager.ReloadOverlayProcess(process, true));
}
Reload all processes for the engine overlay
After you have made changes in the Unity scene, you can reload the Predict Engine scene for all overlay processes by calling the following method:
static void UVR.ProcessManager.ReloadProcessForAllOverlayCameras(bool reloadStructure = true) : Reload all the engine overlay processes and reload the scene structure if reloadStructure is true.
public void ReloadAllOverlayProcesses()
{
UVR.ProcessManager.ReloadProcessForAllOverlayCameras();
}
Reload the engine view
You can reload the engine view by calling the following method :
static void UVR.EngineViewManager.Reload() : Reload the engine view.
public void ReloadRenderView()
{
UVR.EngineViewManager.Reload();
}
Stop processes
Stop a process
You can stop a process by calling the following method :
static void UVR.ProcessManager.StopProcess(UVR.EngineProcess process) : Stop the given process.
public void StopProcess(UVR.EngineProcess process)
{
if (process == null) return;
UVR.ProcessManager.StopProcess(process);
}
Stop all overlay processes
You can stop all overlay processes by calling the following method :
static void UVR.ProcessManager.StopProcessForAllOverlayCameras() : Stop all overlay processes.
public void StopAllOverlayProcesses()
{
UVR.ProcessManager.StopProcessForAllOverlayCameras();
}
Disable the engine overlay
You can disable the engine overlay by calling the following method :
static void UVR.ProcessManager.SetOverlayEnabled(bool enabled) : Enable/Disable the engine overlay depending on the enabled value.
public void DisableOmenOverlay()
{
UVR.ProcessManager.SetOverlayEnabled(false);
}
Stop the engine view
You can stop the engine view by calling the following method :
static void UVR.EngineViewManager.Stop() : Stop the engine view.
public void StopRenderView()
{
UVR.EngineViewManager.Stop();
}
Quit the application
You can quit the application by calling the following method :
static void UVR.ShortcutManager.Quit() : Stop the render view, stop the batch renderer and stop overlay processes by quitting the application. The application is turned off with a different method depending on the environment :
#if UNITY_EDITOR
UnityEditor.EditorApplication.isPlaying = false;
#else
Application.Quit();
#endif
public void QuitTheApplication()
{
UVR.ShortcutManager.Quit();
}
Save simulations
Save a simulation from the overlay
You can save the Predict Engine simulation from the engine overlay by calling the following method :
static void UVR.InputManager.OpenImageSaver(UVR.InputManager.ImageSaverMode saveMode, UVR.EngineProcess process = null, bool openFolder = true, bool includeRenderViewProcesses = false) : Open an interface to save the Predictive Engine render. The attributes are defined as follow :
saveMode : the output simulation format. Possible values are :
Processed : the post-processed output,
Raw : the raw output,
Unity : the unity view,
All : the raw and the HDR post-processed outputs together.
process : the process for which the simulation is saved. All overlay processes will be saved if this is null.
openFolder : if true, open the folder in the Windows explorer after saving the simulation(s).
includeRenderViewProcesses : if process is null, defines whether the simulation should be saved for the render view process or not.
public void SaveProcessedRenderFromAllOverlayProcess()
{
UVR.InputManager.OpenImageSaver(UVR.InputManager.ImageSaverMode.Processed, null, true, false);
}
public void SaveRawRenderFromOverlayProcess(UVR.EngineProcess process)
{
if (process == null) return;
UVR.InputManager.OpenImageSaver(UVR.InputManager.ImageSaverMode.Raw, process);
}
Save a simulation from the engine view
You can save the Predict Engine simulation from the engine view by calling one of the following methods :
static void UVR.EngineViewManager.SaveProcessed() : Open an interface to save the processed (LDR or HDR) Predictive Engine render from the render view.
static void UVR.EngineViewManager.SaveRaw() : Open an interface to save the raw Predictive Engine render from the render view.
public void SaveProcessedRenderFromRenderView()
{
UVR.EngineViewManager.SaveProcessed();
}
public void SaveRawRenderFromRenderView()
{
UVR.EngineViewManager.SaveRaw();
}
Performances
Get the current Predict Engine performances for the engine view
You can get the Predict Engine performances for the engine view by calling the following method :
static UVR.EngineViewManager.EngineStats UVR.EngineViewManager.GetEngineStats() : Returns the statistics of the engine view process.
public void DebugEnginePerformancesForRenderView()
{
UVR.EngineViewManager.EngineStats stats = UVR.EngineViewManager.GetEngineStats();
UnityEngine.Debug.Log("Predictive Engine state = " + stats.state.ToString());
UnityEngine.Debug.Log("Predictive Engine FPS = " + stats.fpsCount.ToString("F1"));
UnityEngine.Debug.Log("Predictive Engine render time (sec) = " + stats.renderTime.ToString());
UnityEngine.Debug.Log("Predictive Engine samples per pixel = " + stats.sppCount.ToString());
UnityEngine.Debug.Log("Predictive Engine scene is dirty = " + stats.isDirty.ToString());
}
Get the current Predict Engine performances for a process
You can get the Predict Engine performances for a process by calling the following methods :
UVR.EngineProcess.EngineState UVR.EngineProcess.getState() : Returns the current state of the process.
float UVR.EngineProcess.getFPS() : Returns the number of time per second the Predictive Engine render is updated on screen for the process.
float UVR.EngineProcess.getRenderTime() : Returns the current render time of the process.
Vector3 UVR.EngineProcess.getSppMinMaxAvg() : Returns the {minimum, maximum, average} count of samples per pixel for the process.
bool UVR.EngineProcess.isDirty() : Returns true if the process require to be reloaded.
public void DebugOmenPerformancesForProcess(UVR.EngineProcess process)
{
if (process == null) return;
UnityEngine.Debug.Log("OMEN process state = " + process.getState().ToString());
UnityEngine.Debug.Log("OMEN process FPS = " + process.getFPS().ToString("F1"));
UnityEngine.Debug.Log("OMEN process render time (sec) = " + process.getRenderTime().ToString());
UnityEngine.Debug.Log("OMEN process samples per pixel = " + process.getSppMinMaxAvg().ToString());
UnityEngine.Debug.Log("OMEN process is dirty = " + process.isDirty().ToString());
}
Edit interactive settings
Change the exposure
You can get the current exposure of a process' camera by calling the following method :
static float UVR.InputManager.GetExposure(UVR.EngineProcess process) : Return the exposure of the given process' camera, returns 0 if the camera has no tone mapper.
You can change the exposure on all cameras in the scene by calling the following methods :
static void UVR.InputManager.SetExposure(UVR.EngineProcess process, float newValue) : Disable the Auto Exposure mode and set the exposure to the newValue given in the attributes, for the given process.
static float UVR.InputManager.AugmentExposure(bool includeRenderViewProcesses = false) : Disable the Auto Exposure mode and augment the exposure for every overlay process, do the same for the render view process if includeRenderViewProcesses is true.
static float UVR.InputManager.AugmentExposure(UVR.EngineProcess process) : Disable the Auto Exposure mode and augment the exposure. Return the new exposure for the given process.
static float UVR.InputManager.ReduceExposure(bool includeRenderViewProcesses = false) : Disable the Auto Exposure mode and reduce the exposure for every overlay process, do the same for the render view process if includeRenderViewProcesses is true.
static float UVR.InputManager.ReduceExposure(UVR.EngineProcess process) : Disable the Auto Exposure mode and reduce the exposure for the given process.
static void UVR.InputManager.EnableAutoExposure(bool includeRenderViewProcesses = false) : Enable the Auto Exposure mode for every overlay process, do the same for the render view process if includeRenderViewProcesses is true.
static void UVR.InputManager.EnableAutoExposure(UVR.EngineProcess process) : Enable the Auto Exposure mode for the given process.
public void ChangeToneMapperExposureForOverlayCamera(Camera camera)
{
if (camera == null) return;
UVR.EngineProcess lCameraProcess = UVR.ProcessManager.GetProcessForCamera(camera, UVR.EngineProcess.ProcessTarget.Overlay);
if (lCameraProcess == null) return;
float currentExposure = UVR.InputManager.GetExposure(lCameraProcess);
UVR.InputManager.SetExposure(lCameraProcess, currentExposure + 1e-6f);
UVR.InputManager.AugmentExposure(lCameraProcess);
UVR.InputManager.ReduceExposure(lCameraProcess);
UVR.InputManager.EnableAutoExposure(lCameraProcess);
}
Enable/disable the denoiser
You can enable and disable the denoiser in Predict Engine by calling the following method :
static void UVR.InputManager.ToggleDenoiserState(bool includeRenderViewProcesses = false) : Switch on and off the denoiser for every overlay process, switch the denoiser for the render view processes as well if includeRenderViewProcesses is true. This will actually change the "Denoiser Enabled" option on each Omen Camera component.
static void UVR.InputManager.ToggleDenoiserState(UVR.EngineProcess process) : Switch on and off the denoiser for the given process. This will actually change the "Denoiser Enabled" option on the Omen Camera component.
public void ToggleDenoiserForOverlayProcesses()
{
UVR.InputManager.ToggleDenoiserState();
}
Switch between RGB and false colors
If a Camera Settings component uses a Photometric sensor, you can switch between RGB and False Colors rendering by calling the following methods:
static void UVR.InputManager.SwitchRenderWithFalseColor(bool includeRenderViewProcesses = false) : Switch between an RGB and a False Color Color System for every overlay process, also switch for the render view process if includeRenderViewProcesses is true.
static void UVR.InputManager.SwitchRenderWithFalseColor(UVR.EngineProcess process) : Switch between an RGB and a False Color Color System for the given process.
static void UVR.InputManager.ChangeColorSystem(UVR.RenderViewSettings.ColorSystemType type, bool includeRenderViewProcesses = false) : Change the Color System to the type given in the attributes for every overlay process, also change for the render view process if includeRenderViewProcesses is true.
static void UVR.InputManager.ChangeColorSystem(UVR.EngineProcess process, UVR.RenderViewSettings.ColorSystemType type) : Change the Color System to the type given in the attributes for the given process.
These methods won't have any effect on cameras that are not using a Photometric sensor.
public void ToggleBetweenRgbAndFalseColorsInOverlay()
{
UVR.InputManager.SwitchRenderWithFalseColor();
}
public void SetColorSystemInOverlay(UVR.RenderViewSettings.ColorSystemType type)
{
UVR.InputManager.ChangeColorSystem(type);
}
Hide and show the false color scale in the engine overlay
If an Camera Settings component uses a False Color Color System, you can hide and show the false color scale in the engine overlay by calling the following method :
static void UVR.InputManager.ToggleFalseColorScaleDisplay() : Hide the false color scale if it was visible and show it if it was not, the change is applied to every overlay process.
static void UVR.InputManager.ToggleFalseColorScaleDisplay(UVR.EngineProcess process) : Hide the false color scale if it was visible and show it if it was not, the change is applied to the given process.
public void ToggleFalseColorScaleDisplayInOverlay()
{
UVR.InputManager.HideAndShowFalseColorScale();
}
Edit the scene at runtime
Edit the scene using a Picker
Pickers enable you to define a set of configurations for your scene. See the Pickers section for more details.
Once the application is running, you can call a picker with the following methods :
void UVR.GenericPicker.PickOption(int optionId) : Select an option by its id in the options list and apply it to the selected element.
void UVR.GenericPicker.SwitchOption(bool reverse = false) : Pick the next option in the options list and apply it to the selected element. The reverse attribute defines whether the new option should be picked before or after the current option in the list.
When calling a picker, the modification will be automatically applied in Predictive Engine and the scene will be reloaded if required.
public void SelectAPickerOption(UVR.GenericPicker picker, int optionId)
{
if (picker != null || optionId < 0) return;
picker.PickOption(optionId);
}
public void SwitchOptionOnThisMaterialPicker()
{
UVR.MaterialPicker picker = this.GetComponent<UVR.MaterialPicker>();
if (picker == null) return;
picker.SwitchOption();
}
Edit the scene manually and reload the Predict Engine render
If you don't want to use the pickers, you can edit the scene manually or with a custom script of yours. In this case, the modification will not be automatically applied in Predictive Engine : you must reload the scene after editing it. See section above or example bellow.
public void SetANewMaterialManually(MeshRenderer renderer, Material material)
{
if (renderer == null || material == null) return;
renderer.sharedMaterial = material;
//Overlay processes only
UVR.ShortcutManager.Reload();
//All processes
UVR.InputManager.ProcessInput(new UVR.InputManager.EngineInput(UVR.InputManager.EngineInputAction.ToggleDenoiser), true);
}
Overlay
Enable and disable the overlay
You can find out whether the engine overlay is enabled with the following property :
static bool UVR.ProcessManager.IsOverlayEnabled : true if the overlay is enabled.
You can enable and disable the engine overlay by calling the following method :
static void UVR.ProcessManager.SetOverlayEnabled(bool enabled) : Enable or disable the overlay. The enabled attribute defines whether the overlay should be enabled or disabled.
public void EnableOmenOverlay()
{
if (!UVR.ProcessManager.IsOverlayEnabled())
{
UVR.ProcessManager.SetOverlayEnabled(true);
}
}
Change the overlay display mode
The engine overlay is displayed in the Unity game view. There are different display modes, see the Overlay Options section for more details on the overlay modes.
Reminder : The 4 overlay modes can be organized depending on whether or not they are interactive and automatic :
You can change the overlay mode by calling the following methods :
static void UVR.InputManager.SetOverlayMode(int mode) : Set the overlay mode to the given id.
0 = Always On
1 = When Camera Is Static
2 = Lock On User Input
3 = Interactive On User Input
public void SetOverlayMode(UVR.ScreenOverlay.DisplayMode mode)
{
UVR.InputManager.SetOverlayMode((int)mode);
}
You can change the overlay automatic mode by calling the following methods :
static void UVR.InputManager.ToggleOverlayAutomatic() : Change the overlay mode so that it keeps its "interactive" mode and changes its "automatic" mode.
Always On <-- --> Interactive On User Input
When Camera Is Static <-- --> Lock On User Input
static void UVR.InputManager.SetOverlayAutomatic(bool automatic) : Change the overlay mode so that it keeps its "interactive" mode and changes its "automatic" mode. The automatic attributes defines whether the new overlay mode is automatic or not.
public void ToggleOverlayAutomatic()
{
UVR.InputManager.ToggleOverlayAutomatic();
}
public void SetOverlayAutomatic(bool automatic)
{
UVR.InputManager.SetOverlayAutomatic(automatic);
}
You can change the overlay interactive mode by calling the following methods :
static void UVR.InputManager.ToggleOverlayInteractive() : Change the overlay mode so that it keeps its "automatic" mode and changes its "interactive" mode.
Always On <-- --> When Camera Is Static
Interactive On User Input <-- --> Lock On User Input
static void UVR.InputManager.SetOverlayInteractive(bool interactive) : Change the overlay mode so that it keeps its "automatic" mode and changes its "interactive" mode. The interactive attributes defines whether the new overlay mode is interactive or not.
public void ToggleOverlayInteractive()
{
UVR.InputManager.ToggleOverlayInteractive();
}
public void SetOverlayInteractive(bool interactive)
{
UVR.InputManager.SetOverlayInteractive(interactive);
}
Hide and show the overlay
You can hide and show the overlay by calling the following method :
static void UVR.InputManager.HideAndShowOverlay() : if the current display mode is "Always on" or "When camera is static" this function has no effect, otherwise the the visibility of the overlay is toggled.
static void UVR.InputManager.HideAndShowOverlay(bool visible) : if the current display mode is "Always on" or "When camera is static" this function has no effect, otherwise the overlay visibility is set to visible.
public void ShowOverlay(bool visible)
{
UVR.InputManager.HideAndShowOverlay(visible);
}