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

5 files changed, 187 insertions, 20 deletions

diff --git a/intern/cycles/integrator/CMakeLists.txt b/intern/cycles/integrator/CMakeLists.txt
index 8acd72f0508..949254606b8 100644
--- a/intern/cycles/integrator/CMakeLists.txt
+++ b/intern/cycles/integrator/CMakeLists.txt
@@ -28,6 +28,7 @@ set(SRC
   pass_accessor_cpu.cpp
   pass_accessor_gpu.cpp
   path_trace_display.cpp
+  path_trace_tile.cpp
   path_trace_work.cpp
   path_trace_work_cpu.cpp
   path_trace_work_gpu.cpp
@@ -49,6 +50,7 @@ set(SRC_HEADERS
   pass_accessor_cpu.h
   pass_accessor_gpu.h
   path_trace_display.h
+  path_trace_tile.h
   path_trace_work.h
   path_trace_work_cpu.h
   path_trace_work_gpu.h
diff --git a/intern/cycles/integrator/path_trace.cpp b/intern/cycles/integrator/path_trace.cpp
index 36cd7314b4c..7624b244175 100644
--- a/intern/cycles/integrator/path_trace.cpp
+++ b/intern/cycles/integrator/path_trace.cpp
@@ -20,6 +20,7 @@
 #include "device/device.h"
 #include "integrator/pass_accessor.h"
 #include "integrator/path_trace_display.h"
+#include "integrator/path_trace_tile.h"
 #include "integrator/render_scheduler.h"
 #include "render/pass.h"
 #include "render/scene.h"
@@ -535,6 +536,11 @@ void PathTrace::denoise(const RenderWork &render_work)
   render_scheduler_.report_denoise_time(render_work, time_dt() - start_time);
 }
 
+void PathTrace::set_output_driver(unique_ptr<OutputDriver> driver)
+{
+  output_driver_ = move(driver);
+}
+
 void PathTrace::set_display_driver(unique_ptr<DisplayDriver> driver)
 {
   if (driver) {
@@ -567,7 +573,7 @@ void PathTrace::update_display(const RenderWork &render_work)
     return;
   }
 
-  if (!display_ && !tile_buffer_update_cb) {
+  if (!display_ && !output_driver_) {
     VLOG(3) << "Ignore display update.";
     return;
   }
@@ -579,10 +585,11 @@ void PathTrace::update_display(const RenderWork &render_work)
 
   const double start_time = time_dt();
 
-  if (tile_buffer_update_cb) {
+  if (output_driver_) {
     VLOG(3) << "Invoke buffer update callback.";
 
-    tile_buffer_update_cb();
+    PathTraceTile tile(*this);
+    output_driver_->update_render_tile(tile);
   }
 
   if (display_) {
@@ -758,20 +765,26 @@ bool PathTrace::is_cancel_requested()
 
 void PathTrace::tile_buffer_write()
 {
-  if (!tile_buffer_write_cb) {
+  if (!output_driver_) {
     return;
   }
 
-  tile_buffer_write_cb();
+  PathTraceTile tile(*this);
+  output_driver_->write_render_tile(tile);
 }
 
 void PathTrace::tile_buffer_read()
 {
-  if (!tile_buffer_read_cb) {
+  if (!device_scene_->data.bake.use) {
     return;
   }
 
-  if (tile_buffer_read_cb()) {
+  if (!output_driver_) {
+    return;
+  }
+
+  PathTraceTile tile(*this);
+  if (output_driver_->read_render_tile(tile)) {
     tbb::parallel_for_each(path_trace_works_, [](unique_ptr<PathTraceWork> &path_trace_work) {
       path_trace_work->copy_render_buffers_to_device();
     });
@@ -1010,6 +1023,11 @@ int2 PathTrace::get_render_tile_offset() const
   return make_int2(tile.x, tile.y);
 }
 
+int2 PathTrace::get_render_size() const
+{
+  return tile_manager_.get_size();
+}
+
 const BufferParams &PathTrace::get_render_tile_params() const
 {
   if (full_frame_state_.render_buffers) {
diff --git a/intern/cycles/integrator/path_trace.h b/intern/cycles/integrator/path_trace.h
index 46eb0435c91..dbb22c204d9 100644
--- a/intern/cycles/integrator/path_trace.h
+++ b/intern/cycles/integrator/path_trace.h
@@ -37,6 +37,7 @@ class RenderBuffers;
 class RenderScheduler;
 class RenderWork;
 class PathTraceDisplay;
+class OutputDriver;
 class Progress;
 class TileManager;
 
@@ -99,7 +100,10 @@ class PathTrace {
    * Use this to configure the adaptive sampler before rendering any samples. */
   void set_adaptive_sampling(const AdaptiveSampling &adaptive_sampling);
 
-  /* Set display driver which takes care of drawing the render result. */
+  /* Sets output driver for render buffer output. */
+  void set_output_driver(unique_ptr<OutputDriver> driver);
+
+  /* Set display driver for interactive render buffer display. */
   void set_display_driver(unique_ptr<DisplayDriver> driver);
 
   /* Clear the display buffer by filling it in with all zeroes. */
@@ -158,6 +162,7 @@ class PathTrace {
    * instead. */
   int2 get_render_tile_size() const;
   int2 get_render_tile_offset() const;
+  int2 get_render_size() const;
 
   /* Get buffer parameters of the current tile.
    *
@@ -169,18 +174,6 @@ class PathTrace {
    * times, and so on. */
   string full_report() const;
 
-  /* Callback which communicates an updates state of the render buffer of the current big tile.
-   * Is called during path tracing to communicate work-in-progress state of the final buffer. */
-  function<void(void)> tile_buffer_update_cb;
-
-  /* Callback which communicates final rendered buffer. Is called after path-tracing is done. */
-  function<void(void)> tile_buffer_write_cb;
-
-  /* Callback which initializes rendered buffer. Is called before path-tracing starts.
-   *
-   * This is used for baking. */
-  function<bool(void)> tile_buffer_read_cb;
-
   /* Callback which is called to report current rendering progress.
    *
    * It is supposed to be cheaper than buffer update/write, hence can be called more often.
@@ -253,8 +246,12 @@ class PathTrace {
   RenderScheduler &render_scheduler_;
   TileManager &tile_manager_;
 
+  /* Display driver for interactive render buffer display. */
   unique_ptr<PathTraceDisplay> display_;
 
+  /* Output driver to write render buffer to. */
+  unique_ptr<OutputDriver> output_driver_;
+
   /* Per-compute device descriptors of work which is responsible for path tracing on its configured
    * device. */
   vector<unique_ptr<PathTraceWork>> path_trace_works_;
diff --git a/intern/cycles/integrator/path_trace_tile.cpp b/intern/cycles/integrator/path_trace_tile.cpp
new file mode 100644
index 00000000000..540f4aa5f68
--- /dev/null
+++ b/intern/cycles/integrator/path_trace_tile.cpp
@@ -0,0 +1,107 @@
+/*
+ * 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.
+ */
+
+#include "integrator/path_trace_tile.h"
+#include "integrator/pass_accessor_cpu.h"
+#include "integrator/path_trace.h"
+
+#include "render/buffers.h"
+#include "render/film.h"
+#include "render/pass.h"
+#include "render/scene.h"
+
+CCL_NAMESPACE_BEGIN
+
+PathTraceTile::PathTraceTile(PathTrace &path_trace)
+    : OutputDriver::Tile(path_trace.get_render_tile_offset(),
+                         path_trace.get_render_tile_size(),
+                         path_trace.get_render_size(),
+                         path_trace.get_render_tile_params().layer,
+                         path_trace.get_render_tile_params().view),
+      path_trace_(path_trace),
+      copied_from_device_(false)
+{
+}
+
+bool PathTraceTile::get_pass_pixels(const string_view pass_name,
+                                    const int num_channels,
+                                    float *pixels) const
+{
+  /* NOTE: The code relies on a fact that session is fully update and no scene/buffer modification
+   * is happening while this function runs. */
+
+  if (!copied_from_device_) {
+    /* Copy from device on demand. */
+    path_trace_.copy_render_tile_from_device();
+    const_cast<PathTraceTile *>(this)->copied_from_device_ = true;
+  }
+
+  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_channels);
+
+  return path_trace_.get_render_tile_pixels(pass_accessor, destination);
+}
+
+bool PathTraceTile::set_pass_pixels(const string_view pass_name,
+                                    const int num_channels,
+                                    const float *pixels) const
+{
+  /* 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) {
+    return false;
+  }
+
+  const float exposure = buffer_params.exposure;
+  const int num_samples = 1;
+
+  const PassAccessor::PassAccessInfo pass_access_info(*pass);
+  PassAccessorCPU pass_accessor(pass_access_info, exposure, num_samples);
+  PassAccessor::Source source(pixels, num_channels);
+
+  return path_trace_.set_render_tile_pixels(pass_accessor, source);
+}
+
+CCL_NAMESPACE_END
diff --git a/intern/cycles/integrator/path_trace_tile.h b/intern/cycles/integrator/path_trace_tile.h
new file mode 100644
index 00000000000..fd3e2969f6c
--- /dev/null
+++ b/intern/cycles/integrator/path_trace_tile.h
@@ -0,0 +1,43 @@
+/*
+ * 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 "render/output_driver.h"
+
+CCL_NAMESPACE_BEGIN
+
+/* PathTraceTile
+ *
+ * Implementation of OutputDriver::Tile interface for path tracer. */
+
+class PathTrace;
+
+class PathTraceTile : public OutputDriver::Tile {
+ public:
+  PathTraceTile(PathTrace &path_trace);
+
+  bool get_pass_pixels(const string_view pass_name, const int num_channels, float *pixels) const;
+  bool set_pass_pixels(const string_view pass_name,
+                       const int num_channels,
+                       const float *pixels) const;
+
+ private:
+  PathTrace &path_trace_;
+  bool copied_from_device_;
+};
+
+CCL_NAMESPACE_END