Cycles: refactor API for render output

* Add OutputDriver, replacing function callbacks in Session.
* Add PathTraceTile, replacing tile access methods in Session.
* Add more detailed comments about how this driver should be implemented.
* Add OIIOOutputDriver for Cycles standalone to output an image.

Differential Revision: https://developer.blender.org/D12627

6 files changed, 97 insertions, 156 deletions

diff --git a/intern/cycles/render/CMakeLists.txt b/intern/cycles/render/CMakeLists.txt
index ce1a9e5f430..323222b8c85 100644
--- a/intern/cycles/render/CMakeLists.txt
+++ b/intern/cycles/render/CMakeLists.txt
@@ -78,6 +78,7 @@ set(SRC_HEADERS
   constant_fold.h
   denoising.h
   display_driver.h
+  output_driver.h
   film.h
   geometry.h
   graph.h
diff --git a/intern/cycles/render/output_driver.h b/intern/cycles/render/output_driver.h
new file mode 100644
index 00000000000..b7e980d71d4
--- /dev/null
+++ b/intern/cycles/render/output_driver.h
@@ -0,0 +1,82 @@
+/*
+ * Copyright 2021 Blender Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include "util/util_math.h"
+#include "util/util_string.h"
+#include "util/util_types.h"
+
+CCL_NAMESPACE_BEGIN
+
+/* Output driver for reading render buffers.
+ *
+ * Host applications implement this interface for outputting render buffers for offline rendering.
+ * Drivers can be used to copy the buffers into the host application or write them directly to
+ * disk. This interface may also be used for interactive display, however the DisplayDriver is more
+ * efficient for that purpose.
+ */
+class OutputDriver {
+ public:
+  OutputDriver() = default;
+  virtual ~OutputDriver() = default;
+
+  class Tile {
+   public:
+    Tile(const int2 offset,
+         const int2 size,
+         const int2 full_size,
+         const string_view layer,
+         const string_view view)
+        : offset(offset), size(size), full_size(full_size), layer(layer), view(view)
+    {
+    }
+    virtual ~Tile() = default;
+
+    const int2 offset;
+    const int2 size;
+    const int2 full_size;
+    const string layer;
+    const string view;
+
+    virtual bool get_pass_pixels(const string_view pass_name,
+                                 const int num_channels,
+                                 float *pixels) const = 0;
+    virtual bool set_pass_pixels(const string_view pass_name,
+                                 const int num_channels,
+                                 const float *pixels) const = 0;
+  };
+
+  /* Write tile once it has finished rendering. */
+  virtual void write_render_tile(const Tile &tile) = 0;
+
+  /* Update tile while rendering is in progress. Return true if any update
+   * was performed. */
+  virtual bool update_render_tile(const Tile & /* tile */)
+  {
+    return false;
+  }
+
+  /* For baking, read render pass PASS_BAKE_PRIMITIVE and PASS_BAKE_DIFFERENTIAL
+   * to determine which shading points to use for baking at each pixel. Return
+   * true if any data was read. */
+  virtual bool read_render_tile(const Tile & /* tile */)
+  {
+    return false;
+  }
+};
+
+CCL_NAMESPACE_END
diff --git a/intern/cycles/render/session.cpp b/intern/cycles/render/session.cpp
index c191b9a9b4a..550188b196a 100644
--- a/intern/cycles/render/session.cpp
+++ b/intern/cycles/render/session.cpp
@@ -31,6 +31,7 @@
 #include "render/light.h"
 #include "render/mesh.h"
 #include "render/object.h"
+#include "render/output_driver.h"
 #include "render/scene.h"
 #include "render/session.h"
 
@@ -64,25 +65,6 @@ Session::Session(const SessionParams &params_, const SceneParams &scene_params)
   path_trace_ = make_unique<PathTrace>(
       device, scene->film, &scene->dscene, render_scheduler_, tile_manager_);
   path_trace_->set_progress(&progress);
-  path_trace_->tile_buffer_update_cb = [&]() {
-    if (!update_render_tile_cb) {
-      return;
-    }
-    update_render_tile_cb();
-  };
-  path_trace_->tile_buffer_write_cb = [&]() {
-    if (!write_render_tile_cb) {
-      return;
-    }
-    write_render_tile_cb();
-  };
-  path_trace_->tile_buffer_read_cb = [&]() -> bool {
-    if (!read_render_tile_cb) {
-      return false;
-    }
-    read_render_tile_cb();
-    return true;
-  };
   path_trace_->progress_update_cb = [&]() { update_status_time(); };
 
   tile_manager_.full_buffer_written_cb = [&](string_view filename) {
@@ -97,24 +79,6 @@ Session::~Session()
 {
   cancel();
 
-  /* TODO(sergey): Bring the passes in viewport back.
-   * It is unclear why there is such an exception needed though. */
-#if 0
-  if (buffers && params.write_render_cb) {
-    /* Copy to display buffer and write out image if requested */
-    delete display;
-
-    display = new DisplayBuffer(device, false);
-    display->reset(buffers->params);
-    copy_to_display_buffer(params.samples);
-
-    int w = display->draw_width;
-    int h = display->draw_height;
-    uchar4 *pixels = display->rgba_byte.copy_from_device(0, w, h);
-    params.write_render_cb((uchar *)pixels, w, h, 4);
-  }
-#endif
-
   /* Make sure path tracer is destroyed before the device. This is needed because destruction might
    * need to access device for device memory free. */
   /* TODO(sergey): Convert device to be unique_ptr, and rely on C++ to destruct objects in the
@@ -514,6 +478,11 @@ void Session::set_pause(bool pause)
   }
 }
 
+void Session::set_output_driver(unique_ptr<OutputDriver> driver)
+{
+  path_trace_->set_output_driver(move(driver));
+}
+
 void Session::set_display_driver(unique_ptr<DisplayDriver> driver)
 {
   path_trace_->set_display_driver(move(driver));
@@ -637,101 +606,6 @@ void Session::collect_statistics(RenderStats *render_stats)
 }
 
 /* --------------------------------------------------------------------
- * Tile and tile pixels access.
- */
-
-bool Session::has_multiple_render_tiles() const
-{
-  return tile_manager_.has_multiple_tiles();
-}
-
-int2 Session::get_render_tile_size() const
-{
-  return path_trace_->get_render_tile_size();
-}
-
-int2 Session::get_render_tile_offset() const
-{
-  return path_trace_->get_render_tile_offset();
-}
-
-string_view Session::get_render_tile_layer() const
-{
-  const BufferParams &buffer_params = path_trace_->get_render_tile_params();
-  return buffer_params.layer;
-}
-
-string_view Session::get_render_tile_view() const
-{
-  const BufferParams &buffer_params = path_trace_->get_render_tile_params();
-  return buffer_params.view;
-}
-
-bool Session::copy_render_tile_from_device()
-{
-  return path_trace_->copy_render_tile_from_device();
-}
-
-bool Session::get_render_tile_pixels(const string &pass_name, int num_components, float *pixels)
-{
-  /* NOTE: The code relies on a fact that session is fully update and no scene/buffer modification
-   * is happening while this function runs. */
-
-  const BufferParams &buffer_params = path_trace_->get_render_tile_params();
-
-  const BufferPass *pass = buffer_params.find_pass(pass_name);
-  if (pass == nullptr) {
-    return false;
-  }
-
-  const bool has_denoised_result = path_trace_->has_denoised_result();
-  if (pass->mode == PassMode::DENOISED && !has_denoised_result) {
-    pass = buffer_params.find_pass(pass->type);
-    if (pass == nullptr) {
-      /* Happens when denoised result pass is requested but is never written by the kernel. */
-      return false;
-    }
-  }
-
-  pass = buffer_params.get_actual_display_pass(pass);
-
-  const float exposure = buffer_params.exposure;
-  const int num_samples = path_trace_->get_num_render_tile_samples();
-
-  PassAccessor::PassAccessInfo pass_access_info(*pass);
-  pass_access_info.use_approximate_shadow_catcher = buffer_params.use_approximate_shadow_catcher;
-  pass_access_info.use_approximate_shadow_catcher_background =
-      pass_access_info.use_approximate_shadow_catcher && !buffer_params.use_transparent_background;
-
-  const PassAccessorCPU pass_accessor(pass_access_info, exposure, num_samples);
-  const PassAccessor::Destination destination(pixels, num_components);
-
-  return path_trace_->get_render_tile_pixels(pass_accessor, destination);
-}
-
-bool Session::set_render_tile_pixels(const string &pass_name,
-                                     int num_components,
-                                     const float *pixels)
-{
-  /* NOTE: The code relies on a fact that session is fully update and no scene/buffer modification
-   * is happening while this function runs. */
-
-  const BufferPass *pass = buffer_params_.find_pass(pass_name);
-  if (!pass) {
-    return false;
-  }
-
-  const float exposure = scene->film->get_exposure();
-  const int num_samples = render_scheduler_.get_num_rendered_samples();
-
-  const PassAccessor::PassAccessInfo pass_access_info(*pass);
-  PassAccessorCPU pass_accessor(pass_access_info, exposure, num_samples);
-  PassAccessor::Source source(pixels, num_components);
-
-  return path_trace_->set_render_tile_pixels(pass_accessor, source);
-}
-
-/* --------------------------------------------------------------------
  * Full-frame on-disk storage.
  */
 
diff --git a/intern/cycles/render/session.h b/intern/cycles/render/session.h
index 607e40c47c1..46c964bc98c 100644
--- a/intern/cycles/render/session.h
+++ b/intern/cycles/render/session.h
@@ -36,6 +36,7 @@ class BufferParams;
 class Device;
 class DeviceScene;
 class DisplayDriver;
+class OutputDriver;
 class PathTrace;
 class Progress;
 class RenderBuffers;
@@ -67,8 +68,6 @@ class SessionParams {
 
   ShadingSystem shadingsystem;
 
-  function<bool(const uchar *pixels, int width, int height, int channels)> write_render_cb;
-
   SessionParams()
   {
     headless = false;
@@ -114,10 +113,6 @@ class Session {
   Stats stats;
   Profiler profiler;
 
-  function<void(void)> write_render_tile_cb;
-  function<void(void)> update_render_tile_cb;
-  function<void(void)> read_render_tile_cb;
-
   /* Callback is invoked by tile manager whenever on-dist tiles storage file is closed after
    * writing. Allows an engine integration to keep track of those files without worry about
    * transferring the information when it needs to re-create session during rendering. */
@@ -143,6 +138,7 @@ class Session {
   void set_samples(int samples);
   void set_time_limit(double time_limit);
 
+  void set_output_driver(unique_ptr<OutputDriver> driver);
   void set_display_driver(unique_ptr<DisplayDriver> driver);
 
   double get_estimated_remaining_time() const;
@@ -156,24 +152,6 @@ class Session {
   void collect_statistics(RenderStats *stats);
 
   /* --------------------------------------------------------------------
-   * Tile and tile pixels access.
-   */
-
-  bool has_multiple_render_tiles() const;
-
-  /* Get size and offset (relative to the buffer's full x/y) of the currently rendering tile. */
-  int2 get_render_tile_size() const;
-  int2 get_render_tile_offset() const;
-
-  string_view get_render_tile_layer() const;
-  string_view get_render_tile_view() const;
-
-  bool copy_render_tile_from_device();
-
-  bool get_render_tile_pixels(const string &pass_name, int num_components, float *pixels);
-  bool set_render_tile_pixels(const string &pass_name, int num_components, const float *pixels);
-
-  /* --------------------------------------------------------------------
    * Full-frame on-disk storage.
    */
 
diff --git a/intern/cycles/render/tile.cpp b/intern/cycles/render/tile.cpp
index 4ab2e856c5d..7e53a9d0911 100644
--- a/intern/cycles/render/tile.cpp
+++ b/intern/cycles/render/tile.cpp
@@ -420,6 +420,11 @@ const Tile &TileManager::get_current_tile() const
   return tile_state_.current_tile;
 }
 
+const int2 TileManager::get_size() const
+{
+  return make_int2(buffer_params_.width, buffer_params_.height);
+}
+
 bool TileManager::open_tile_output()
 {
   write_state_.filename = path_temp_get("cycles-tile-buffer-" + tile_file_unique_part_ + "-" +
diff --git a/intern/cycles/render/tile.h b/intern/cycles/render/tile.h
index 8392274ff79..08eaa4034f0 100644
--- a/intern/cycles/render/tile.h
+++ b/intern/cycles/render/tile.h
@@ -82,6 +82,7 @@ class TileManager {
   bool done();
 
   const Tile &get_current_tile() const;
+  const int2 get_size() const;
 
   /* Write render buffer of a tile to a file on disk.
    *