Cycles: add Path Guiding on CPU through Intel OpenPGL

This adds path guiding features into Cycles by integrating Intel's Open Path
Guiding Library. It can be enabled in the Sampling > Path Guiding panel in the
render properties.

This feature helps reduce noise in scenes where finding a path to light is
difficult for regular path tracing.

The current implementation supports guiding directional sampling decisions on
surfaces, when the material contains a least one diffuse component, and in
volumes with isotropic and anisotropic Henyey-Greenstein phase functions.

On surfaces, the guided sampling decision is proportional to the product of
the incident radiance and the normal-oriented cosine lobe and in volumes it
is proportional to the product of the incident radiance and the phase function.

The incident radiance field of a scene is learned and updated during rendering
after each per-frame rendering iteration/progression.

At the moment, path guiding is only supported by the CPU backend. Support for
GPU backends will be added in future versions of OpenPGL.

Ref T92571

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

5 files changed, 182 insertions, 1 deletions

diff --git a/intern/cycles/blender/addon/engine.py b/intern/cycles/blender/addon/engine.py
index 1a99674d239..794338fe78e 100644
--- a/intern/cycles/blender/addon/engine.py
+++ b/intern/cycles/blender/addon/engine.py
@@ -156,6 +156,11 @@ def with_osl():
     return _cycles.with_osl
 
 
+def with_path_guiding():
+    import _cycles
+    return _cycles.with_path_guiding
+
+
 def system_info():
     import _cycles
     return _cycles.system_info()
diff --git a/intern/cycles/blender/addon/properties.py b/intern/cycles/blender/addon/properties.py
index cd263e5b9c4..b5ac39d09e6 100644
--- a/intern/cycles/blender/addon/properties.py
+++ b/intern/cycles/blender/addon/properties.py
@@ -179,6 +179,12 @@ enum_view3d_shading_render_pass = (
     ('SAMPLE_COUNT', "Sample Count", "Per-pixel number of samples"),
 )
 
+enum_guiding_distribution = (
+    ('PARALLAX_AWARE_VMM', "Parallax-Aware VMM", "Use Parallax-aware von Mises-Fisher models as directional distribution", 0),
+    ('DIRECTIONAL_QUAD_TREE', "Directional Quad Tree", "Use Directional Quad Trees as directional distribution", 1),
+    ('VMM', "VMM", "Use von Mises-Fisher models as directional distribution", 2),
+)
+
 
 def enum_openimagedenoise_denoiser(self, context):
     import _cycles
@@ -358,7 +364,9 @@ class CyclesRenderSettings(bpy.types.PropertyGroup):
     preview_samples: IntProperty(
         name="Viewport Samples",
         description="Number of samples to render in the viewport, unlimited if 0",
-        min=0, max=(1 << 24),
+        min=0,
+        soft_min=1,
+        max=(1 << 24),
         default=1024,
     )
 
@@ -507,6 +515,78 @@ class CyclesRenderSettings(bpy.types.PropertyGroup):
         default=1.0,
     )
 
+    use_guiding: BoolProperty(
+        name="Guiding",
+        description="Use path guiding for sampling paths. Path guiding incrementally "
+        "learns the light distribution of the scene and guides path into directions "
+        "with high direct and indirect light contributions",
+        default=False,
+    )
+
+    use_deterministic_guiding: BoolProperty(
+        name="Deterministic",
+        description="Makes path guiding deterministic which means renderings will be"
+        "reproducible with the same pixel values every time. This feature slows down"
+        "training",
+        default=True,
+    )
+
+    guiding_distribution_type: EnumProperty(
+        name="Guiding Distribution Type",
+        description="Type of representation for the guiding distribution",
+        items=enum_guiding_distribution,
+        default='PARALLAX_AWARE_VMM',
+    )
+
+    use_surface_guiding: BoolProperty(
+        name="Surface Guiding",
+        description="Use guiding when sampling directions on a surface",
+        default=True,
+    )
+
+    surface_guiding_probability: FloatProperty(
+        name="Surface Guiding Probability",
+        description="The probability of guiding a direction on a surface",
+        min=0.0, max=1.0,
+        default=0.5,
+    )
+
+    use_volume_guiding: BoolProperty(
+        name="Volume Guiding",
+        description="Use guiding when sampling directions inside a volume",
+        default=True,
+    )
+
+    guiding_training_samples: IntProperty(
+        name="Training Samples",
+        description="The maximum number of samples used for training path guiding. "
+        "Higher samples lead to more accurate guiding, however may also unnecessarily slow "
+        "down rendering once guiding is accurate enough. "
+        "A value 0 will continue training until the last sample",
+        min=0,
+        soft_min=1,
+        default=128,
+    )
+
+    volume_guiding_probability: FloatProperty(
+        name="Volume Guiding Probability",
+        description="The probability of guiding a direction inside a volume",
+        min=0.0, max=1.0,
+        default=0.5,
+    )
+
+    use_guiding_direct_light: BoolProperty(
+        name="Guide Direct Light",
+        description="Consider the contribution of directly visible light sources during guiding",
+        default=True,
+    )
+
+    use_guiding_mis_weights: BoolProperty(
+        name="Use MIS Weights",
+        description="Use the MIS weight to weight the contribution of directly visible light sources during guiding",
+        default=True,
+    )
+
     max_bounces: IntProperty(
         name="Max Bounces",
         description="Total maximum number of bounces",
diff --git a/intern/cycles/blender/addon/ui.py b/intern/cycles/blender/addon/ui.py
index ee284dd899a..7036e58f6fb 100644
--- a/intern/cycles/blender/addon/ui.py
+++ b/intern/cycles/blender/addon/ui.py
@@ -278,6 +278,63 @@ class CYCLES_RENDER_PT_sampling_render_denoise(CyclesButtonsPanel, Panel):
             col.prop(cscene, "denoising_prefilter", text="Prefilter")
 
 
+class CYCLES_RENDER_PT_sampling_path_guiding(CyclesButtonsPanel, Panel):
+    bl_label = "Path Guiding"
+    bl_parent_id = "CYCLES_RENDER_PT_sampling"
+    bl_options = {'DEFAULT_CLOSED'}
+
+    @classmethod
+    def poll(cls, context):
+        from . import engine
+        return use_cpu(context) and engine.with_path_guiding()
+
+    def draw_header(self, context):
+        scene = context.scene
+        cscene = scene.cycles
+
+        self.layout.prop(cscene, "use_guiding", text="")
+
+    def draw(self, context):
+        scene = context.scene
+        cscene = scene.cycles
+
+        layout = self.layout
+        layout.use_property_split = True
+        layout.use_property_decorate = False
+        layout.active = cscene.use_guiding
+
+        col = layout.column(align=True)
+        col.prop(cscene, "use_surface_guiding")
+        col.prop(cscene, "use_volume_guiding")
+        col.prop(cscene, "guiding_training_samples")
+
+
+class CYCLES_RENDER_PT_sampling_path_guiding_debug(CyclesDebugButtonsPanel, Panel):
+    bl_label = "Debug"
+    bl_parent_id = "CYCLES_RENDER_PT_sampling_path_guiding"
+    bl_options = {'DEFAULT_CLOSED'}
+
+    def draw(self, context):
+        scene = context.scene
+        cscene = scene.cycles
+
+        layout = self.layout
+        layout.use_property_split = True
+        layout.use_property_decorate = False
+        layout.active = cscene.use_guiding
+
+        layout.prop(cscene, "guiding_distribution_type", text="Distribution Type")
+
+        col = layout.column(align=True)
+        col.prop(cscene, "surface_guiding_probability")
+        col.prop(cscene, "volume_guiding_probability")
+
+        col = layout.column(align=True)
+        col.prop(cscene, "use_deterministic_guiding")
+        col.prop(cscene, "use_guiding_direct_light")
+        col.prop(cscene, "use_guiding_mis_weights")
+
+
 class CYCLES_RENDER_PT_sampling_advanced(CyclesButtonsPanel, Panel):
     bl_label = "Advanced"
     bl_parent_id = "CYCLES_RENDER_PT_sampling"
@@ -2286,6 +2343,8 @@ classes = (
     CYCLES_RENDER_PT_sampling_viewport_denoise,
     CYCLES_RENDER_PT_sampling_render,
     CYCLES_RENDER_PT_sampling_render_denoise,
+    CYCLES_RENDER_PT_sampling_path_guiding,
+    CYCLES_RENDER_PT_sampling_path_guiding_debug,
     CYCLES_RENDER_PT_sampling_advanced,
     CYCLES_RENDER_PT_light_paths,
     CYCLES_RENDER_PT_light_paths_max_bounces,
diff --git a/intern/cycles/blender/python.cpp b/intern/cycles/blender/python.cpp
index 077875aecb2..9e42f6b8b60 100644
--- a/intern/cycles/blender/python.cpp
+++ b/intern/cycles/blender/python.cpp
@@ -15,6 +15,7 @@
 
 #include "util/debug.h"
 #include "util/foreach.h"
+#include "util/guiding.h"
 #include "util/log.h"
 #include "util/md5.h"
 #include "util/opengl.h"
@@ -1008,6 +1009,15 @@ void *CCL_python_module_init()
   PyModule_AddStringConstant(mod, "osl_version_string", "unknown");
 #endif
 
+  if (ccl::guiding_supported()) {
+    PyModule_AddObject(mod, "with_path_guiding", Py_True);
+    Py_INCREF(Py_True);
+  }
+  else {
+    PyModule_AddObject(mod, "with_path_guiding", Py_False);
+    Py_INCREF(Py_False);
+  }
+
 #ifdef WITH_EMBREE
   PyModule_AddObject(mod, "with_embree", Py_True);
   Py_INCREF(Py_True);
diff --git a/intern/cycles/blender/sync.cpp b/intern/cycles/blender/sync.cpp
index 6081c4626f0..23bc92de022 100644
--- a/intern/cycles/blender/sync.cpp
+++ b/intern/cycles/blender/sync.cpp
@@ -413,6 +413,22 @@ void BlenderSync::sync_integrator(BL::ViewLayer &b_view_layer, bool background)
   integrator->set_direct_light_sampling_type(direct_light_sampling_type);
 #endif
 
+  integrator->set_use_guiding(get_boolean(cscene, "use_guiding"));
+  integrator->set_use_surface_guiding(get_boolean(cscene, "use_surface_guiding"));
+  integrator->set_use_volume_guiding(get_boolean(cscene, "use_volume_guiding"));
+  integrator->set_guiding_training_samples(get_int(cscene, "guiding_training_samples"));
+
+  if (use_developer_ui) {
+    integrator->set_deterministic_guiding(get_boolean(cscene, "use_deterministic_guiding"));
+    integrator->set_surface_guiding_probability(get_float(cscene, "surface_guiding_probability"));
+    integrator->set_volume_guiding_probability(get_float(cscene, "volume_guiding_probability"));
+    integrator->set_use_guiding_direct_light(get_boolean(cscene, "use_guiding_direct_light"));
+    integrator->set_use_guiding_mis_weights(get_boolean(cscene, "use_guiding_mis_weights"));
+    GuidingDistributionType guiding_distribution_type = (GuidingDistributionType)get_enum(
+        cscene, "guiding_distribution_type", GUIDING_NUM_TYPES, GUIDING_TYPE_PARALLAX_AWARE_VMM);
+    integrator->set_guiding_distribution_type(guiding_distribution_type);
+  }
+
   DenoiseParams denoise_params = get_denoise_params(b_scene, b_view_layer, background);
 
   /* No denoising support for vertex color baking, vertices packed into image
@@ -737,6 +753,17 @@ void BlenderSync::sync_render_passes(BL::RenderLayer &b_rlay, BL::ViewLayer &b_v
     pass_add(scene, PASS_DENOISING_DEPTH, "Denoising Depth", PassMode::NOISY);
   }
 
+#ifdef WITH_CYCLES_DEBUG
+  b_engine.add_pass("Guiding Color", 3, "RGB", b_view_layer.name().c_str());
+  pass_add(scene, PASS_GUIDING_COLOR, "Guiding Color", PassMode::NOISY);
+
+  b_engine.add_pass("Guiding Probability", 1, "X", b_view_layer.name().c_str());
+  pass_add(scene, PASS_GUIDING_PROBABILITY, "Guiding Probability", PassMode::NOISY);
+
+  b_engine.add_pass("Guiding Average Roughness", 1, "X", b_view_layer.name().c_str());
+  pass_add(scene, PASS_GUIDING_AVG_ROUGHNESS, "Guiding Average Roughness", PassMode::NOISY);
+#endif
+
   /* Custom AOV passes. */
   BL::ViewLayer::aovs_iterator b_aov_iter;
   for (b_view_layer.aovs.begin(b_aov_iter); b_aov_iter != b_view_layer.aovs.end(); ++b_aov_iter) {