EEVEE: Arbitrary Output Variables

This patch adds support for AOVs in EEVEE. AOV Outputs can be defined in the
render pass tab and used in shader materials. Both Object and World based
shaders are supported. The AOV can be previewed in the viewport using the
renderpass selector in the shading popover.

AOV names that conflict with other AOVs are automatically corrected. AOV
conflicts with render passes get a warning icon. The reason behind this is that
changing render engines/passes can change the conflict, but you might not notice
it. Changing this automatically would also make the materials incorrect, so best
to leave this to the user.

**Implementation**

The patch adds a copies the AOV structures of Cycles into Blender. The goal is
that the Cycles will use Blenders AOV defintions. In the Blender kernel
(`layer.c`) the logic of these structures are implemented.

The GLSL shader of any GPUMaterial can hold multiple outputs (the main output
and the AOV outputs) based on the renderPassUBO the right output is selected.
This selection uses an hash that encodes the AOV structure. The full AOV needed
to be encoded when actually drawing the material pass as the AOV type changes
the behavior of the AOV. This isn't known yet when the GLSL is compiled.

**Future Developments**

* The AOV definitions in the render layer panel isn't shared with Cycles.
  Cycles should be migrated to use the same viewlayer aovs. During a previous
  attempt this failed as the AOV validation in cycles and in Blender have
  implementation differences what made it crash when an aov name was invalid.
  This could be fixed by extending the external render engine API.
* Add support to Cycles to render AOVs in the 3d viewport.
* Use a drop down list for selecting AOVs in the AOV Output node.
* Give user feedback when multiple AOV output nodes with the same AOV name
  exists in the same shader.
* Fix viewing single channel images in the image editor [T83314]
* Reduce viewport render time by only render needed draw passes. [T83316]

Reviewed By: Brecht van Lommel, Clément Foucault

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

6 files changed, 359 insertions, 0 deletions

diff --git a/source/blender/blenkernel/BKE_appdir.h b/source/blender/blenkernel/BKE_appdir.h
index 3e52d7f3301..6da6079ea2a 100644
--- a/source/blender/blenkernel/BKE_appdir.h
+++ b/source/blender/blenkernel/BKE_appdir.h
@@ -26,6 +26,7 @@ extern "C" {
 struct ListBase;
 
 void BKE_appdir_init(void);
+void BKE_appdir_exit(void);
 
 /* note on naming: typical _get() suffix is omitted here,
  * since its the main purpose of the API. */
diff --git a/source/blender/blenkernel/BKE_layer.h b/source/blender/blenkernel/BKE_layer.h
index 7091a060243..e5fab35891c 100644
--- a/source/blender/blenkernel/BKE_layer.h
+++ b/source/blender/blenkernel/BKE_layer.h
@@ -42,6 +42,7 @@ struct Depsgraph;
 struct LayerCollection;
 struct Main;
 struct Object;
+struct RenderEngine;
 struct Scene;
 struct View3D;
 struct ViewLayer;
@@ -444,6 +445,15 @@ bool BKE_view_layer_filter_edit_mesh_has_edges(struct Object *ob, void *user_dat
   BKE_view_layer_array_from_objects_in_mode( \
       view_layer, v3d, r_len, {.object_mode = mode, .no_dup_data = true})
 
+struct ViewLayerAOV *BKE_view_layer_add_aov(struct ViewLayer *view_layer);
+void BKE_view_layer_remove_aov(struct ViewLayer *view_layer, struct ViewLayerAOV *aov);
+void BKE_view_layer_set_active_aov(struct ViewLayer *view_layer, struct ViewLayerAOV *aov);
+void BKE_view_layer_verify_aov(struct RenderEngine *engine,
+                               struct Scene *scene,
+                               struct ViewLayer *view_layer);
+bool BKE_view_layer_has_valid_aov(struct ViewLayer *view_layer);
+ViewLayer *BKE_view_layer_find_with_aov(struct Scene *scene, struct ViewLayerAOV *view_layer_aov);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/source/blender/blenkernel/CMakeLists.txt b/source/blender/blenkernel/CMakeLists.txt
index 1a90d6fadd3..a328c600eac 100644
--- a/source/blender/blenkernel/CMakeLists.txt
+++ b/source/blender/blenkernel/CMakeLists.txt
@@ -726,6 +726,7 @@ if(WITH_GTESTS)
     intern/fcurve_test.cc
     intern/lattice_deform_test.cc
     intern/tracking_test.cc
+    intern/layer_test.cc
   )
   set(TEST_INC
     ../editors/include
diff --git a/source/blender/blenkernel/intern/appdir.c b/source/blender/blenkernel/intern/appdir.c
index 2038079744d..b1462167edd 100644
--- a/source/blender/blenkernel/intern/appdir.c
+++ b/source/blender/blenkernel/intern/appdir.c
@@ -114,6 +114,14 @@ void BKE_appdir_init(void)
 #endif
 }
 
+void BKE_appdir_exit(void)
+{
+#ifndef NDEBUG
+  BLI_assert(is_appdir_init == true);
+  is_appdir_init = false;
+#endif
+}
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
diff --git a/source/blender/blenkernel/intern/layer.c b/source/blender/blenkernel/intern/layer.c
index 73b330bc0de..6b346d7a337 100644
--- a/source/blender/blenkernel/intern/layer.c
+++ b/source/blender/blenkernel/intern/layer.c
@@ -57,6 +57,8 @@
 
 #include "DRW_engine.h"
 
+#include "RE_engine.h"
+
 #include "MEM_guardedalloc.h"
 
 #include "BLO_read_write.h"
@@ -279,6 +281,8 @@ void BKE_view_layer_free_ex(ViewLayer *view_layer, const bool do_id_user)
     }
   }
   BLI_freelistN(&view_layer->drawdata);
+  BLI_freelistN(&view_layer->aovs);
+  view_layer->active_aov = NULL;
 
   MEM_SAFE_FREE(view_layer->stats);
 
@@ -412,6 +416,28 @@ void BKE_view_layer_base_select_and_set_active(struct ViewLayer *view_layer, Bas
 }
 
 /**************************** Copy View Layer and Layer Collections ***********************/
+static void layer_aov_copy_data(ViewLayer *view_layer_dst,
+                                const ViewLayer *view_layer_src,
+                                ListBase *aovs_dst,
+                                const ListBase *aovs_src)
+{
+  if (aovs_src != NULL) {
+    BLI_duplicatelist(aovs_dst, aovs_src);
+  }
+
+  ViewLayerAOV *aov_dst = aovs_dst->first;
+  const ViewLayerAOV *aov_src = aovs_src->first;
+
+  while (aov_dst != NULL) {
+    BLI_assert(aov_src);
+    if (aov_src == view_layer_src->active_aov) {
+      view_layer_dst->active_aov = aov_dst;
+    }
+
+    aov_dst = aov_dst->next;
+    aov_src = aov_src->next;
+  }
+}
 
 static void layer_collections_copy_data(ViewLayer *view_layer_dst,
                                         const ViewLayer *view_layer_src,
@@ -482,6 +508,10 @@ void BKE_view_layer_copy_data(Scene *scene_dst,
   LayerCollection *lc_scene_dst = view_layer_dst->layer_collections.first;
   lc_scene_dst->collection = scene_dst->master_collection;
 
+  BLI_listbase_clear(&view_layer_dst->aovs);
+  layer_aov_copy_data(
+      view_layer_dst, view_layer_src, &view_layer_dst->aovs, &view_layer_src->aovs);
+
   if ((flag & LIB_ID_CREATE_NO_USER_REFCOUNT) == 0) {
     id_us_plus((ID *)view_layer_dst->mat_override);
   }
@@ -1864,6 +1894,9 @@ void BKE_view_layer_blend_write(BlendWriter *writer, ViewLayer *view_layer)
   LISTBASE_FOREACH (FreestyleLineSet *, fls, &view_layer->freestyle_config.linesets) {
     BLO_write_struct(writer, FreestyleLineSet, fls);
   }
+  LISTBASE_FOREACH (ViewLayerAOV *, aov, &view_layer->aovs) {
+    BLO_write_struct(writer, ViewLayerAOV, aov);
+  }
   write_layer_collections(writer, &view_layer->layer_collections);
 }
 
@@ -1899,6 +1932,9 @@ void BKE_view_layer_blend_read_data(BlendDataReader *reader, ViewLayer *view_lay
   BLO_read_list(reader, &(view_layer->freestyle_config.modules));
   BLO_read_list(reader, &(view_layer->freestyle_config.linesets));
 
+  BLO_read_list(reader, &view_layer->aovs);
+  BLO_read_data_address(reader, &view_layer->active_aov);
+
   BLI_listbase_clear(&view_layer->drawdata);
   view_layer->object_bases_array = NULL;
   view_layer->object_bases_hash = NULL;
@@ -1952,3 +1988,129 @@ void BKE_view_layer_blend_read_lib(BlendLibReader *reader, Library *lib, ViewLay
 
   IDP_BlendReadLib(reader, view_layer->id_properties);
 }
+
+/* -------------------------------------------------------------------- */
+/** \name Shader AOV
+ * \{ */
+
+static void viewlayer_aov_make_name_unique(ViewLayer *view_layer)
+{
+  ViewLayerAOV *aov = view_layer->active_aov;
+  if (aov == NULL) {
+    return;
+  }
+  BLI_uniquename(
+      &view_layer->aovs, aov, DATA_("AOV"), '.', offsetof(ViewLayerAOV, name), sizeof(aov->name));
+}
+
+static void viewlayer_aov_active_set(ViewLayer *view_layer, ViewLayerAOV *aov)
+{
+  if (aov != NULL) {
+    BLI_assert(BLI_findindex(&view_layer->aovs, aov) != -1);
+    view_layer->active_aov = aov;
+  }
+  else {
+    view_layer->active_aov = NULL;
+  }
+}
+
+struct ViewLayerAOV *BKE_view_layer_add_aov(struct ViewLayer *view_layer)
+{
+  ViewLayerAOV *aov;
+  aov = MEM_callocN(sizeof(ViewLayerAOV), __func__);
+  aov->type = AOV_TYPE_COLOR;
+  BLI_strncpy(aov->name, DATA_("AOV"), sizeof(aov->name));
+  BLI_addtail(&view_layer->aovs, aov);
+  viewlayer_aov_active_set(view_layer, aov);
+  viewlayer_aov_make_name_unique(view_layer);
+  return aov;
+}
+
+void BKE_view_layer_remove_aov(ViewLayer *view_layer, ViewLayerAOV *aov)
+{
+  BLI_assert(BLI_findindex(&view_layer->aovs, aov) != -1);
+  BLI_assert(aov != NULL);
+  if (view_layer->active_aov == aov) {
+    if (aov->next) {
+      viewlayer_aov_active_set(view_layer, aov->next);
+    }
+    else {
+      viewlayer_aov_active_set(view_layer, aov->prev);
+    }
+  }
+  BLI_freelinkN(&view_layer->aovs, aov);
+}
+
+void BKE_view_layer_set_active_aov(ViewLayer *view_layer, ViewLayerAOV *aov)
+{
+  viewlayer_aov_active_set(view_layer, aov);
+}
+
+static void bke_view_layer_verify_aov_cb(void *userdata,
+                                         Scene *UNUSED(scene),
+                                         ViewLayer *UNUSED(view_layer),
+                                         const char *name,
+                                         int UNUSED(channels),
+                                         const char *UNUSED(chanid),
+                                         int UNUSED(type))
+{
+  GHash *name_count = userdata;
+  void **value_p;
+  void *key = BLI_strdup(name);
+
+  if (!BLI_ghash_ensure_p(name_count, key, &value_p)) {
+    *value_p = POINTER_FROM_INT(1);
+  }
+  else {
+    int value = POINTER_AS_INT(*value_p);
+    value++;
+    *value_p = POINTER_FROM_INT(value);
+    MEM_freeN(key);
+  }
+}
+
+/* Update the naming and conflicts of the AOVs.
+ *
+ * Name must be unique between all AOVs.
+ * Conflicts with render passes will show a conflict icon. Reason is that switching a render
+ * engine or activating a render pass could lead to other conflicts that wouldn't be that clear
+ * for the user. */
+void BKE_view_layer_verify_aov(struct RenderEngine *engine,
+                               struct Scene *scene,
+                               struct ViewLayer *view_layer)
+{
+  viewlayer_aov_make_name_unique(view_layer);
+
+  GHash *name_count = BLI_ghash_str_new(__func__);
+  RE_engine_update_render_passes(
+      engine, scene, view_layer, bke_view_layer_verify_aov_cb, name_count);
+  LISTBASE_FOREACH (ViewLayerAOV *, aov, &view_layer->aovs) {
+    void **value_p = BLI_ghash_lookup(name_count, aov->name);
+    int count = POINTER_AS_INT(value_p);
+    SET_FLAG_FROM_TEST(aov->flag, count > 1, AOV_CONFLICT);
+  }
+  BLI_ghash_free(name_count, MEM_freeN, NULL);
+}
+
+/* Check if the given view layer has at least one valid AOV. */
+bool BKE_view_layer_has_valid_aov(ViewLayer *view_layer)
+{
+  LISTBASE_FOREACH (ViewLayerAOV *, aov, &view_layer->aovs) {
+    if ((aov->flag & AOV_CONFLICT) == 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+ViewLayer *BKE_view_layer_find_with_aov(struct Scene *scene, struct ViewLayerAOV *aov)
+{
+  LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) {
+    if (BLI_findindex(&view_layer->aovs, aov) != -1) {
+      return view_layer;
+    }
+  }
+  return NULL;
+}
+
+/** \} */
diff --git a/source/blender/blenkernel/intern/layer_test.cc b/source/blender/blenkernel/intern/layer_test.cc
new file mode 100644
index 00000000000..84a96ed0895
--- /dev/null
+++ b/source/blender/blenkernel/intern/layer_test.cc
@@ -0,0 +1,177 @@
+/*
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * The Original Code is Copyright (C) 2020 by Blender Foundation.
+ */
+#include "testing/testing.h"
+
+#include "MEM_guardedalloc.h"
+
+#include "BKE_appdir.h"
+#include "BKE_idtype.h"
+#include "BKE_layer.h"
+
+#include "BLI_string.h"
+
+#include "RE_engine.h"
+
+#include "IMB_imbuf.h"
+
+#include "CLG_log.h"
+
+#include "RNA_access.h"
+
+namespace blender::bke::tests {
+
+TEST(view_layer, aov_unique_names)
+{
+  /* Set Up */
+  CLG_init();
+  BKE_appdir_init();
+  IMB_init();
+  RE_engines_init();
+
+  Scene scene = {{NULL}};
+  IDType_ID_SCE.init_data(&scene.id);
+  ViewLayer *view_layer = static_cast<ViewLayer *>(scene.view_layers.first);
+
+  RenderEngineType *engine_type = RE_engines_find(scene.r.engine);
+  RenderEngine *engine = RE_engine_create(engine_type);
+
+  EXPECT_FALSE(BKE_view_layer_has_valid_aov(view_layer));
+  EXPECT_EQ(view_layer->active_aov, nullptr);
+
+  /* Add an AOV */
+  ViewLayerAOV *aov1 = BKE_view_layer_add_aov(view_layer);
+  BKE_view_layer_verify_aov(engine, &scene, view_layer);
+  EXPECT_EQ(view_layer->active_aov, aov1);
+  EXPECT_TRUE(BKE_view_layer_has_valid_aov(view_layer));
+  EXPECT_FALSE((aov1->flag & AOV_CONFLICT) != 0);
+
+  /* Add a second AOV */
+  ViewLayerAOV *aov2 = BKE_view_layer_add_aov(view_layer);
+  BKE_view_layer_verify_aov(engine, &scene, view_layer);
+  EXPECT_EQ(view_layer->active_aov, aov2);
+  EXPECT_TRUE(BKE_view_layer_has_valid_aov(view_layer));
+  EXPECT_FALSE((aov1->flag & AOV_CONFLICT) != 0);
+  EXPECT_FALSE((aov2->flag & AOV_CONFLICT) != 0);
+  EXPECT_TRUE(STREQ(aov1->name, "AOV"));
+  EXPECT_TRUE(STREQ(aov2->name, "AOV.001"));
+
+  /* Revert previous resolution */
+  BLI_strncpy(aov2->name, "AOV", MAX_NAME);
+  BKE_view_layer_verify_aov(engine, &scene, view_layer);
+  EXPECT_TRUE(BKE_view_layer_has_valid_aov(view_layer));
+  EXPECT_FALSE((aov1->flag & AOV_CONFLICT) != 0);
+  EXPECT_FALSE((aov2->flag & AOV_CONFLICT) != 0);
+  EXPECT_TRUE(STREQ(aov1->name, "AOV"));
+  EXPECT_TRUE(STREQ(aov2->name, "AOV.001"));
+
+  /* Resolve by removing AOV resolution */
+  BKE_view_layer_remove_aov(view_layer, aov2);
+  aov2 = NULL;
+  BKE_view_layer_verify_aov(engine, &scene, view_layer);
+  EXPECT_TRUE(BKE_view_layer_has_valid_aov(view_layer));
+  EXPECT_FALSE((aov1->flag & AOV_CONFLICT) != 0);
+
+  /* Tear down */
+  RE_engine_free(engine);
+  RE_engines_exit();
+  IDType_ID_SCE.free_data(&scene.id);
+  IMB_exit();
+  BKE_appdir_exit();
+  CLG_exit();
+}
+
+static void test_render_pass_conflict(Scene *scene,
+                                      RenderEngine *engine,
+                                      ViewLayer *view_layer,
+                                      ViewLayerAOV *aov,
+                                      const char *render_pass_name,
+                                      const char *rna_prop_name)
+{
+  PointerRNA ptr;
+  RNA_pointer_create(&scene->id, &RNA_ViewLayer, view_layer, &ptr);
+  RNA_boolean_set(&ptr, rna_prop_name, false);
+
+  /* Rename to Conflicting name */
+  BLI_strncpy(aov->name, render_pass_name, MAX_NAME);
+  BKE_view_layer_verify_aov(engine, scene, view_layer);
+  EXPECT_TRUE(BKE_view_layer_has_valid_aov(view_layer));
+  EXPECT_FALSE((aov->flag & AOV_CONFLICT) != 0);
+  EXPECT_TRUE(STREQ(aov->name, render_pass_name));
+
+  /* Activate render pass */
+  RNA_boolean_set(&ptr, rna_prop_name, true);
+  BKE_view_layer_verify_aov(engine, scene, view_layer);
+  EXPECT_FALSE(BKE_view_layer_has_valid_aov(view_layer));
+  EXPECT_TRUE((aov->flag & AOV_CONFLICT) != 0);
+  EXPECT_TRUE(STREQ(aov->name, render_pass_name));
+
+  /* Deactivate render pass */
+  RNA_boolean_set(&ptr, rna_prop_name, false);
+  BKE_view_layer_verify_aov(engine, scene, view_layer);
+  EXPECT_TRUE(BKE_view_layer_has_valid_aov(view_layer));
+  EXPECT_FALSE((aov->flag & AOV_CONFLICT) != 0);
+  EXPECT_TRUE(STREQ(aov->name, render_pass_name));
+}
+
+TEST(view_layer, aov_conflict)
+{
+  /* Set Up */
+  CLG_init();
+  BKE_appdir_init();
+  IMB_init();
+  RE_engines_init();
+
+  Scene scene = {{NULL}};
+  IDType_ID_SCE.init_data(&scene.id);
+  ViewLayer *view_layer = static_cast<ViewLayer *>(scene.view_layers.first);
+
+  RenderEngineType *engine_type = RE_engines_find(scene.r.engine);
+  RenderEngine *engine = RE_engine_create(engine_type);
+
+  EXPECT_FALSE(BKE_view_layer_has_valid_aov(view_layer));
+  EXPECT_EQ(view_layer->active_aov, nullptr);
+
+  /* Add an AOV */
+  ViewLayerAOV *aov = BKE_view_layer_add_aov(view_layer);
+  BKE_view_layer_verify_aov(engine, &scene, view_layer);
+  EXPECT_EQ(view_layer->active_aov, aov);
+  EXPECT_TRUE(BKE_view_layer_has_valid_aov(view_layer));
+  EXPECT_FALSE((aov->flag & AOV_CONFLICT) != 0);
+
+  test_render_pass_conflict(&scene, engine, view_layer, aov, "Depth", "use_pass_z");
+  test_render_pass_conflict(&scene, engine, view_layer, aov, "Normal", "use_pass_normal");
+  test_render_pass_conflict(&scene, engine, view_layer, aov, "Mist", "use_pass_mist");
+  test_render_pass_conflict(&scene, engine, view_layer, aov, "Shadow", "use_pass_shadow");
+  test_render_pass_conflict(&scene, engine, view_layer, aov, "AO", "use_pass_ambient_occlusion");
+  test_render_pass_conflict(&scene, engine, view_layer, aov, "Emit", "use_pass_emit");
+  test_render_pass_conflict(&scene, engine, view_layer, aov, "Env", "use_pass_environment");
+  test_render_pass_conflict(&scene, engine, view_layer, aov, "DiffDir", "use_pass_diffuse_direct");
+  test_render_pass_conflict(&scene, engine, view_layer, aov, "DiffCol", "use_pass_diffuse_color");
+  test_render_pass_conflict(&scene, engine, view_layer, aov, "GlossDir", "use_pass_glossy_direct");
+  test_render_pass_conflict(&scene, engine, view_layer, aov, "GlossCol", "use_pass_glossy_color");
+
+  /* Tear down */
+  RE_engine_free(engine);
+  RE_engines_exit();
+  IDType_ID_SCE.free_data(&scene.id);
+  IMB_exit();
+  BKE_appdir_exit();
+  CLG_exit();
+}
+
+}  // namespace blender::bke::tests