renderer, unity: replaces the single onFrame tick with discrete render passes

This replaces the single `onFrame` tick with discrete render passes, allowing finer-grained control over each stage of rendering.

- Introduces `UnityRenderPassEvent` and dispatches per-pass events in `OnUnityRenderEvent`.  
- Adds new lifecycle methods (`onBeforeRendering`, `onOpaquesRenderPass`, `onTransparentsRenderPass`, `onAfterRendering`) in `TrEmbedder` and `TrConstellation`.  
- Refactors renderer interfaces and updates the OpenGL example to call the new pass methods.

Author: yorkie

docs/api/embedder.md

@@ -102,11 +102,26 @@ The above fields are used to configure the runtime:
 
 Internally, this method will start the internal components: renderer, content manager, media service and other services.
 
-#### `void onFrame()`
+#### `void onBeforeRendering()`
 
-This method should be called in every frame to update the runtime, such as `Update()` in Unity or `Tick()` in Unreal.
+Call this method before rendering in each frame, it will prepare the runtime for rendering, such as updating the renderer
+and content manager.
 
-Note: This frame in the method name doesn't mean the actual frame especially in the case of XR, it represents an update cycle by the host engine, the frame in OpenXR or WebXR should be configured by the `configureXrDevice(bool enabled, xr::TrDeviceInit &init)` method which will be explained later.
+#### `void onOpaquesRenderPass()`
+
+Call this method to render the opaque objects.
+
+This pass is the mainly render pass which renders all the opaque objects of the JSAR applications, and also schedules  the draw calls which should be rendered in the next passes, such as transparents, post-processing, and other render-texture rendering.
+
+#### `void onTransparentsRenderPass()`
+
+Call this method to render the transparent objects.
+
+This pass executes the draw calls which enabled the blending, and uses the Weighted Blended OIT algorithm to render all the transparents elements (e.g. glass, water and GUIs) without depth sorting.
+
+#### `void onAfterRendering()`
+
+In this pass, it uses to achieve some post-processing effects or asynchronous rendering tasks.
 
 #### `bool configureXrDevice(bool enabled, xr::TrDeviceInit &init)`
 

src/examples/desktop_opengl.cpp

@@ -358,6 +358,8 @@ namespace jsar::example
         if (embedder_ == nullptr)
           continue; // Skip the rendering if the embedder is not ready.
 
+        embedder_->onBeforeRendering();
+
         if (xrEnabled)
         {
           auto xrRenderer = windowCtx_->xrRenderer;
@@ -393,7 +395,10 @@ namespace jsar::example
 
                 auto viewerBaseMatrix = const_cast<float *>(glm::value_ptr(xrRenderer->getViewerBaseMatrix()));
                 xrDevice->updateViewerBaseMatrix(viewerBaseMatrix);
-                embedder_->onFrame();
+
+                // Enqueue passes
+                embedder_->onOpaquesRenderPass();
+                embedder_->onTransparentsRenderPass();
               }
             }
           }
@@ -420,16 +425,22 @@ namespace jsar::example
               xrDevice->updateViewMatrix(viewIndex, viewMatrix);
               xrDevice->updateProjectionMatrix(viewIndex, projectionMatrix);
             }
-            embedder_->onFrame();
+
+            embedder_->onOpaquesRenderPass();
+            embedder_->onTransparentsRenderPass();
           }
         }
         else // Non-XR rendering
         {
           glViewport(0, 0, drawingViewport.width(), drawingViewport.height());
           glGetError(); // Clear the error
-          embedder_->onFrame();
+
+          embedder_->onOpaquesRenderPass();
+          embedder_->onTransparentsRenderPass();
         }
 
+        embedder_->onAfterRendering();
+
         // render screen-space panel
         panel->render();
 

src/renderer/renderer.cpp

@@ -47,9 +47,9 @@ namespace renderer
     startWatchers();
   }
 
-  void TrRenderer::tick(analytics::PerformanceCounter &perfCounter)
+  void TrRenderer::onOpaquesRenderPass(analytics::PerformanceCounter &perfCounter)
   {
-    if (TR_UNLIKELY(api == nullptr))
+    if (api == nullptr) [[unlikely]]
       return; // Skip if api is not ready.
 
     tickingTimepoint = std::chrono::high_resolution_clock::now();
@@ -95,6 +95,12 @@ namespace renderer
     perfCounter.record("  renderer.finishedHostContextRestore");
   }
 
+  void TrRenderer::onTransparentsRenderPass(analytics::PerformanceCounter &perfCounter)
+  {
+    if (api == nullptr) [[unlikely]]
+      return; // Skip if api is not ready.
+  }
+
   void TrRenderer::shutdown()
   {
     stopWatchers();

src/renderer/renderer.hpp

@@ -67,7 +67,8 @@ namespace renderer
 
   public:
     void initialize();
-    void tick(analytics::PerformanceCounter &perfCounter);
+    void onOpaquesRenderPass(analytics::PerformanceCounter &);
+    void onTransparentsRenderPass(analytics::PerformanceCounter &);
     void shutdown();
     void setLogFilter(string filterExpr);
     /**

src/runtime/constellation.cpp

@@ -90,30 +90,48 @@ void TrConstellation::shutdown()
   initialized = false;
 }
 
-void TrConstellation::tick(analytics::PerformanceCounter &perfCounter)
+void TrConstellation::onBeforeRendering(analytics::PerformanceCounter &perfCounter)
 {
-  if (TR_UNLIKELY(initialized == false || disableTicking))
+  if (initialized == false || disableTicking) [[unlikely]]
     return;
 
   contentManager->tickOnFrame();
   perfCounter.record("finishContentManager");
-  renderer->tick(perfCounter);
+}
+
+void TrConstellation::onOpaquesRenderPass(analytics::PerformanceCounter &perfCounter)
+{
+  if (initialized == false || disableTicking) [[unlikely]]
+    return;
+
+  renderer->onOpaquesRenderPass(perfCounter);
   perfCounter.record("finishRenderer");
 
-  if (xrDevice->enabled())
+  // TODO(yorkie): move the input sources sync to the metrices update?
+  if (xrDevice->enabled()) [[likely]]
   {
     xrDevice->tick();
     perfCounter.record("finishInputSourcesSync");
   }
+}
 
-#ifdef TR_ENABLE_INSPECTOR
-  inspector->tick();
-#endif
+void TrConstellation::onTransparentsRenderPass(analytics::PerformanceCounter &perfCounter)
+{
+  if (initialized == false || disableTicking) [[unlikely]]
+    return;
+
+  renderer->onTransparentsRenderPass(perfCounter);
+  perfCounter.record("finishRenderer");
 }
 
-TrEmbedder *TrConstellation::getEmbedder()
+void TrConstellation::onAfterRendering()
 {
-  return embedder;
+  if (initialized == false || disableTicking) [[unlikely]]
+    return;
+
+#ifdef TR_ENABLE_INSPECTOR
+  inspector->tick();
+#endif
 }
 
 uint32_t TrConstellation::open(string url, optional<TrDocumentRequestInit> init)

src/runtime/constellation.hpp

@@ -215,32 +215,20 @@ class TrConstellation
    * @returns If the constellation is initialized successfully.
    */
   bool initialize();
-  /**
-   * Shutdown the constellation.
-   */
   void shutdown();
-  /**
-   * This method `tick()` should be called in the main loop of the runtime, it will update the sub-systems.
-   *
-   * @param perfCounter The performance counter to record the time.
-   */
-  void tick(analytics::PerformanceCounter &perfCounter);
-  /**
-   * @returns The reference to the constellation options.
-   */
+
+  void onBeforeRendering(analytics::PerformanceCounter &);
+  void onOpaquesRenderPass(analytics::PerformanceCounter &);
+  void onTransparentsRenderPass(analytics::PerformanceCounter &);
+  void onAfterRendering();
+
   TrConstellationInit &getOptions();
-  /**
-   * @returns If the constellation is initialized.
-   */
   bool isInitialized();
-  /**
-   * @returns If the runtime is ready.
-   */
   bool isRuntimeReady();
-  /**
-   * @returns The embedder pointer.
-   */
-  TrEmbedder *getEmbedder();
+  inline TrEmbedder *getEmbedder()
+  {
+    return embedder;
+  }
 
 public:
   /**

src/runtime/embedder.cpp

@@ -47,17 +47,39 @@ void TrEmbedder::setRequestAuthorizationHeaders(std::string rawHeaders, std::vec
   constellation->contentManager->setRequestAuthorizationHeaders(rawHeaders, allowedOrigins);
 }
 
-bool TrEmbedder::onFrame()
+void TrEmbedder::onBeforeRendering()
 {
-  analytics::PerformanceCounter perfCounter("HostTick");
-  constellation->tick(perfCounter);
+  analytics::PerformanceCounter perfCounter("RenderingPreparation");
+  constellation->onBeforeRendering(perfCounter);
+  perfCounter.end();
+}
+
+void TrEmbedder::onOpaquesRenderPass()
+{
+  analytics::PerformanceCounter perfCounter("OpaquesRenderPass");
+  constellation->onOpaquesRenderPass(perfCounter);
   perfCounter.end();
 
 #ifdef TR_ENABLE_PERF_COUNTER
   auto frameDuration = perfCounter.duration();
   if (frameDuration > 2.0)
-    DEBUG(LOG_TAG_ERROR, "Detected a long tick(>=2ms) in host frame: \n%s", perfCounter.toString().c_str());
+  {
+    DEBUG(LOG_TAG_ERROR,
+          "Detected a long tick(>=2ms) in opaques renderpass: \n%s",
+          perfCounter.toString().c_str());
+  }
   constellation->perfFs->setFrameDuration(frameDuration);
 #endif
-  return true;
+}
+
+void TrEmbedder::onTransparentsRenderPass()
+{
+  analytics::PerformanceCounter perfCounter("TransparentsRenderPass");
+  constellation->onTransparentsRenderPass(perfCounter);
+  perfCounter.end();
+}
+
+void TrEmbedder::onAfterRendering()
+{
+  constellation->onAfterRendering();
 }

src/runtime/embedder.hpp

@@ -104,11 +104,40 @@ class TrEmbedder
 
 public: // API for lifecycle
   /**
-   * The lifecycle `onFrame` should be called when your application is to render a frame.
-   *
-   * @returns `true` if the frame is rendered, `false` otherwise.
+   * The lifecycle `onBeforeRendering`.
+   * 
+   * In this pass, JSAR internally prepares the rendering pass, such as collecting viewports, cameras, and other 
+   * rendering-related data.
+   */
+  void onBeforeRendering();
+  /**
+   * The lifecycle `onOpaqueRenderPass`.
+   * 
+   * The main render pass which renders all the opaque objects of the JSAR applications, and also schedules the draw 
+   * calls which should be rendered in the next passes, such as transparents, post-processing, and other render-texture
+   * rendering.
+   * 
+   * NOTE(yorkie): In tile-based architectural GPU, the multisampled framebuffer's buffers are bound to the on-tile
+   * memory, so the multisampled framebuffer can't be switched in the middle of the rendering pass, for example, if you
+   * render to a new framebuffer and then switch back the multisampled framebuffer, it will cause the buffers in the
+   * multisampled framebuffer to be corrupted. To resolve this issue, JSAR will find the draw calls which render target
+   * is not the current framebuffer, and schedule them to the `onAfterRenderPass` lifecycle, at which all the render
+   * passes has been achieved and the multisampled framebuffer is also free to resolved.
+   */
+  void onOpaquesRenderPass();
+  /**
+   * The lifecycle `onTransparentsRenderPass`.
+   * 
+   * This pass executes the draw calls which enabled the blending, and uses the Weighted Blended OIT algorithm to
+   * render all the transparents elements (e.g. glass, water and GUIs) without depth sorting.
+   */
+  void onTransparentsRenderPass();
+  /**
+   * The lifecycle `onAfterRendering`.
+   * 
+   * In this pass, it uses to achieve some post-processing effects or asynchronous rendering tasks.
    */
-  bool onFrame();
+  void onAfterRendering();
   /**
    * The lifecycle `onEvent` should be called once an event is received from a specfic (content) source.
    *

src/runtime/unity_entry.cpp

@@ -305,12 +305,40 @@ extern "C"
     TR_ENSURE_EMBEDDER(/** void */, { embedder->unload(); });
   }
 
+  enum UnityRenderPassEvent
+  {
+    kBeforeRenderingPass = 0,
+    kOpaquesRenderPass = 1,
+    kTransparentsRenderPass = 2,
+    kPostProcessingRenderPass = 3,
+    kAfterRenderingPass = 4,
+  };
+
   /**
    * The render event hook for the plugin, it will be called when the plugin is rendering.
    */
   static void OnUnityRenderEvent(int eventID)
   {
-    TR_ENSURE_EMBEDDER(/** void */, { embedder->onFrame(); });
+    TR_ENSURE_EMBEDDER(/** void */, {
+      switch ((UnityRenderPassEvent)eventID)
+      {
+      case kBeforeRenderingPass:
+        embedder->onBeforeRendering();
+        break;
+      case kOpaquesRenderPass:
+        embedder->onOpaquesRenderPass();
+        break;
+      case kTransparentsRenderPass:
+        embedder->onTransparentsRenderPass();
+        break;
+      case kAfterRenderingPass:
+        embedder->onAfterRendering();
+        break;
+      default:
+        // TODO(yorkie): ignore the event.
+        break;
+      }
+    });
   }
 
   /**