feat(multi-render-order): add support for multi render order

- Add support for multi render order
- Add support for dynamic render order

Author: Thibault-Pelletier

Docs/extension_architecture.md

@@ -90,8 +90,11 @@ use this strategy to render on top of other elements.
 In the extension, the renderers are not manipulated directly by developers in their pipelines but automatically managed
 by the LayerManager class.
 
-From a developer standpoint, only the `GetRenderOrder` value needs to be returned. This value is a static value read
-when new pipelines are added / removed from the pipeline manager.
+From a developer standpoint, only the `GetRenderOrder` (or `GetRenderOrders` when designing DM with multi layers) value
+needs to be returned. This value is read when new pipelines are added / removed from the pipeline manager.
+
+If the grouping configuration (render order or custom cameras) changes dynamically, the pipeline should emit the
+`RenderGroupingModified` event.
 
 Pipelines with the same GetRenderOrder and the same GetCustomCamera will be grouped in the same renderer layer. If the
 value is set to 0, the pipelines will be set to the default renderer layer.

Docs/getting_started.md

@@ -91,12 +91,18 @@ class MyPipeline(vtkMRMLLayerDMScriptedPipeline):
 
 ## Rendering on top of other actors
 
-Pipelines can define their rendering order through the `GetRenderOrder` method.
+Pipelines can define their rendering order through the `GetRenderOrder` or `GetRenderOrders` method(s).
 
 * `virtual unsigned int GetRenderOrder() const`: Return render order priority (default = 0).
+* `virtual std::vector<unsigned int> GetRenderOrders() const`: Return render order priorities for each renderer layer
+  the pipeline wants to use. This method is recommended when the pipelines wants to manage both background / foreground
+  representations. The pipeline can return an arbitrary long list of RenderOrders (default = {GetRenderOrder()}).
 
 If the value 0 is used, then the objects will be rendered in the default view renderer along builtin 3D Slicer objects.
 
+If the grouping configuration (render order or custom cameras) changes dynamically, the pipeline should emit the
+`RenderGroupingModified` event.
+
 ```python
 class MyPipeline(vtkMRMLLayerDMScriptedPipeline):
     def GetRenderOrder(self) -> int:

LayerDM/MRMLDM/Python/vtkMRMLLayerDMScriptedPipeline.py

@@ -45,10 +45,11 @@ def CanProcessInteractionEvent(self, eventData: vtkMRMLInteractionEventData) ->
 
         return False, sys.float_info.max
 
-    def GetCustomCamera(self) -> vtkCamera | None:
+    def GetCustomCamera(self, renderOrder: int) -> vtkCamera | None:
         """
-        Custom pipeline camera.
-        If the returned value is not None, then the pipeline (or dedicated logic) is expected to handle its own camera.
+        Custom pipeline camera for the input renderOrder.
+        If the returned value is not None, then the pipeline (or dedicated logic) is expected to handle its own camera
+        for the given input render order.
         Otherwise, the pipeline will be moved in a renderer with a default camera synchronized on its view default camera.
 
         :return: None by default
@@ -74,6 +75,16 @@ def GetRenderOrder(self) -> int:
         """
         return 0
 
+    def GetRenderOrders(self) -> list[int]:
+        """
+        Arbitrary render orders number where the pipeline wants to be displayed.
+        Allows the pipeline to be displayed in more than one renderer (for instance in the background / foreground).
+        Return larger values to be rendered on top of pipelines with lower render orders.
+
+        :return: default = [self.GetRenderOrder()]
+        """
+        return [self.GetRenderOrder()]
+
     def GetWidgetState(self) -> int:
         """
         Current widget state of the pipeline.
@@ -98,7 +109,7 @@ def OnDefaultCameraModified(self, camera: vtkCamera) -> None:
         """
         pass
 
-    def OnReferenceToDisplayNodeAdded(self, fromNode: vtkMRMLNode | None, role:str) -> None:
+    def OnReferenceToDisplayNodeAdded(self, fromNode: vtkMRMLNode | None, role: str) -> None:
         """
         Triggered when a reference to the display node is added
         default behavior: does nothing.
@@ -109,7 +120,7 @@ def OnReferenceToDisplayNodeAdded(self, fromNode: vtkMRMLNode | None, role:str)
         """
         pass
 
-    def OnReferenceToDisplayNodeRemoved(self, fromNode: vtkMRMLNode | None, role:str) -> None:
+    def OnReferenceToDisplayNodeRemoved(self, fromNode: vtkMRMLNode | None, role: str) -> None:
         """
         Triggered when a reference to the display node is removed
         default behavior: does nothing.

LayerDM/MRMLDM/vtkMRMLLayerDMInteractionLogic.cxx

@@ -76,7 +76,7 @@ std::tuple<double, int> vtkMRMLLayerDMInteractionLogic::PrioritizeCanProcessPipe
       int widgetState = std::max(this->MinWidgetState(), pipeline->GetWidgetState());
       minDistance = std::min(minDistance, pipelineDistance);
       maxState = std::max(widgetState, maxState);
-      priority[pipeline] = std::make_tuple(widgetState, pipeline->GetRenderOrder(), -pipelineDistance);
+      priority[pipeline] = std::make_tuple(widgetState, pipeline->GetMaxRenderOrder(), -pipelineDistance);
     }
   }
   // Sort can process by layer order and inverted square distance (larger layer number first and closest to interaction)

LayerDM/MRMLDM/vtkMRMLLayerDMLayerManager.cxx

@@ -1,6 +1,7 @@
 #include "vtkMRMLLayerDMLayerManager.h"
 
 // Layer DM includes
+#include "vtkMRMLLayerDMObjectEventObserver.h"
 #include "vtkMRMLLayerDMPipelineI.h"
 
 // VTK includes
@@ -13,29 +14,35 @@
 
 vtkStandardNewMacro(vtkMRMLLayerDMLayerManager);
 
-void vtkMRMLLayerDMLayerManager::AddPipeline(vtkMRMLLayerDMPipelineI* pipeline)
+bool vtkMRMLLayerDMLayerManager::AddPipelineLayers(vtkMRMLLayerDMPipelineI* pipeline)
 {
   if (!pipeline)
   {
-    return;
+    return false;
   }
 
-  auto key = this->GetPipelineLayerKey(pipeline);
-  if (!this->ContainsLayerKey(key))
+  for (const auto order : pipeline->GetRenderOrders())
   {
-    this->m_pipelineLayers[key] = {};
+    auto key = std::make_tuple(order, GetCameraId(pipeline->GetCustomCamera(order)));
+    if (!this->ContainsLayerKey(key))
+    {
+      this->m_pipelineLayers[key] = {};
+    }
+    this->m_pipelineLayers[key].emplace(pipeline);
   }
-  this->m_pipelineLayers[key].emplace(pipeline);
-  this->UpdateLayers();
+  return true;
 }
 
-vtkMRMLLayerDMLayerManager::LayerKey vtkMRMLLayerDMLayerManager::GetPipelineLayerKey(vtkMRMLLayerDMPipelineI* pipeline)
+void vtkMRMLLayerDMLayerManager::AddPipeline(vtkMRMLLayerDMPipelineI* pipeline)
 {
   if (!pipeline)
   {
-    return {};
+    return;
   }
-  return { pipeline->GetRenderOrder(), vtkMRMLLayerDMLayerManager::GetCameraId(pipeline->GetCustomCamera()) };
+
+  this->m_obs->UpdateObserver(nullptr, pipeline, vtkMRMLLayerDMPipelineI::RenderGroupingModified);
+  this->AddPipelineLayers(pipeline);
+  this->UpdateLayers();
 }
 
 int vtkMRMLLayerDMLayerManager::GetNumberOfDistinctLayers() const
@@ -53,24 +60,24 @@ int vtkMRMLLayerDMLayerManager::GetNumberOfRenderers() const
   return static_cast<int>(this->m_renderers.size());
 }
 
-void vtkMRMLLayerDMLayerManager::RemovePipeline(vtkMRMLLayerDMPipelineI* pipeline)
+void vtkMRMLLayerDMLayerManager::RemovePipelineLayers(vtkMRMLLayerDMPipelineI* pipeline)
 {
-  if (!pipeline)
+  for (auto& [key, pipelines] : m_pipelineLayers)
   {
-    return;
+    pipelines.erase(pipeline);
   }
+}
 
-  auto key = this->GetPipelineLayerKey(pipeline);
-  if (!this->ContainsLayerKey(key))
+void vtkMRMLLayerDMLayerManager::RemovePipeline(vtkMRMLLayerDMPipelineI* pipeline)
+{
+  if (!pipeline)
   {
     return;
   }
 
-  // Remove pipeline from its renderer
+  this->m_obs->UpdateObserver(pipeline, nullptr);
   this->RemovePipelineRenderer(pipeline);
-
-  // Update the other pipeline layers if needed
-  this->m_pipelineLayers[key].erase(pipeline);
+  this->RemovePipelineLayers(pipeline);
   this->UpdateLayers();
 }
 
@@ -114,7 +121,18 @@ void vtkMRMLLayerDMLayerManager::SetDefaultCamera(const vtkSmartPointer<vtkCamer
 
 vtkMRMLLayerDMLayerManager::vtkMRMLLayerDMLayerManager()
   : m_emptyPipeline(vtkSmartPointer<vtkMRMLLayerDMPipelineI>::New())
+  , m_obs(vtkSmartPointer<vtkMRMLLayerDMObjectEventObserver>::New())
 {
+  this->m_obs->SetUpdateCallback(
+    [this](vtkObject* obj)
+    {
+      if (auto pipeline = vtkMRMLLayerDMPipelineI::SafeDownCast(obj))
+      {
+        this->RemovePipelineLayers(pipeline);
+        this->AddPipelineLayers(pipeline);
+        this->UpdateLayers();
+      }
+    });
   this->AddPipeline(this->m_emptyPipeline);
 }
 
@@ -201,7 +219,7 @@ vtkCamera* vtkMRMLLayerDMLayerManager::GetCameraForLayer(const LayerKey& key, co
   {
     if (pipeline)
     {
-      return pipeline->GetCustomCamera();
+      return pipeline->GetCustomCamera(std::get<0>(key));
     }
   }
 
@@ -248,7 +266,7 @@ void vtkMRMLLayerDMLayerManager::RemovePipelineRenderer(vtkMRMLLayerDMPipelineI*
 {
   if (pipeline)
   {
-    pipeline->SetRenderer(nullptr);
+    pipeline->SetRenderers({}, {});
   }
 }
 
@@ -304,17 +322,27 @@ void vtkMRMLLayerDMLayerManager::ResetRenderersCameraClippingRange(const std::se
 
 void vtkMRMLLayerDMLayerManager::SynchronizePipelineRenderers()
 {
-  for (const auto& pair : m_pipelineLayers)
+  std::map<vtkMRMLLayerDMPipelineI*, std::vector<vtkRenderer*>> pipelineRenderers;
+  std::map<vtkMRMLLayerDMPipelineI*, std::vector<unsigned int>> pipelineOrders;
+
+  for (const auto& [key, pipelines] : m_pipelineLayers)
   {
-    auto renderer = this->GetRendererMatchingKey(pair.first);
-    for (const auto& pipeline : pair.second)
+    auto renderer = this->GetRendererMatchingKey(key);
+    auto order = std::get<0>(key);
+    for (const auto& pipeline : pipelines)
     {
       if (pipeline)
       {
-        pipeline->SetRenderer(renderer);
+        pipelineRenderers[pipeline.GetPointer()].push_back(renderer);
+        pipelineOrders[pipeline.GetPointer()].push_back(order);
       }
     }
   }
+
+  for (auto& [pipeline, renderers] : pipelineRenderers)
+  {
+    pipeline->SetRenderers(renderers, pipelineOrders[pipeline]);
+  }
 }
 
 void vtkMRMLLayerDMLayerManager::UpdateRenderWindowNumberOfLayers() const

LayerDM/MRMLDM/vtkMRMLLayerDMLayerManager.h

@@ -20,6 +20,7 @@ class vtkMRMLLayerDMPipelineI;
 class vtkRenderWindow;
 class vtkRenderer;
 class vtkCamera;
+class vtkMRMLLayerDMObjectEventObserver;
 
 /// \brief Responsible for adding and removing renderer layers to a vtkRenderWindow depending on the
 /// display pipeline preferred render order value.
@@ -45,8 +46,6 @@ class VTK_SLICER_LAYERDM_MODULE_MRMLDISPLAYABLEMANAGER_EXPORT vtkMRMLLayerDMLaye
   /// Will trigger the SetRenderer call on the pipeline when it's added to its layer.
   void AddPipeline(vtkMRMLLayerDMPipelineI* pipeline);
 
-  static LayerKey GetPipelineLayerKey(vtkMRMLLayerDMPipelineI* pipeline);
-
   int GetNumberOfDistinctLayers() const;
   int GetNumberOfManagedLayers() const;
 
@@ -94,9 +93,15 @@ class VTK_SLICER_LAYERDM_MODULE_MRMLDISPLAYABLEMANAGER_EXPORT vtkMRMLLayerDMLaye
   void UpdateRendererLayerOrdering() const;
   void UpdateRendererCamera();
 
+  bool AddPipelineLayers(vtkMRMLLayerDMPipelineI* pipeline);
+  void RemovePipelineLayers(vtkMRMLLayerDMPipelineI* pipeline);
+
   // Map of pipeline layers ordered by ascending <layer value, camera synchronization mode>
   std::map<LayerKey, std::set<vtkWeakPointer<vtkMRMLLayerDMPipelineI>>> m_pipelineLayers;
 
+  /// Pipeline observer listening for \sa vtkMRMLLayerDMPipelineI::RenderGroupingModified events.
+  vtkSmartPointer<vtkMRMLLayerDMObjectEventObserver> m_obs;
+
   // Placeholder empty pipeline with target layer = 0 and camera sync to layer 0 for default renderer
   vtkSmartPointer<vtkMRMLLayerDMPipelineI> m_emptyPipeline;