Merge branch 'master' into soc-2021-uv-edge-select-supportsoc-2021-uv-edge-select-support

1 files changed, 55 insertions, 119 deletions

diff --git a/source/blender/blenkernel/intern/layer.c b/source/blender/blenkernel/intern/layer.c
index 6aa8e78c4f6..1484d35f28a 100644
--- a/source/blender/blenkernel/intern/layer.c
+++ b/source/blender/blenkernel/intern/layer.c
@@ -77,7 +77,9 @@ static const short g_base_collection_flags = (BASE_VISIBLE_DEPSGRAPH | BASE_VISI
 /* prototype */
 static void object_bases_iterator_next(BLI_Iterator *iter, const int flag);
 
-/*********************** Layer Collections and bases *************************/
+/* -------------------------------------------------------------------- */
+/** \name Layer Collections and Bases
+ * \{ */
 
 static LayerCollection *layer_collection_add(ListBase *lb_parent, Collection *collection)
 {
@@ -113,12 +115,14 @@ static Base *object_base_new(Object *ob)
   return base;
 }
 
-/********************************* View Layer ********************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name View Layer
+ * \{ */
 
 /* RenderLayer */
 
-/* Returns the default view layer to view in workspaces if there is
- * none linked to the workspace yet. */
 ViewLayer *BKE_view_layer_default_view(const Scene *scene)
 {
   LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) {
@@ -131,7 +135,6 @@ ViewLayer *BKE_view_layer_default_view(const Scene *scene)
   return scene->view_layers.first;
 }
 
-/* Returns the default view layer to render if we need to render just one. */
 ViewLayer *BKE_view_layer_default_render(const Scene *scene)
 {
   LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) {
@@ -144,7 +147,6 @@ ViewLayer *BKE_view_layer_default_render(const Scene *scene)
   return scene->view_layers.first;
 }
 
-/* Returns view layer with matching name, or NULL if not found. */
 ViewLayer *BKE_view_layer_find(const Scene *scene, const char *layer_name)
 {
   LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) {
@@ -156,11 +158,6 @@ ViewLayer *BKE_view_layer_find(const Scene *scene, const char *layer_name)
   return NULL;
 }
 
-/**
- * This is a placeholder to know which areas of the code need to be addressed
- * for the Workspace changes. Never use this, you should typically get the
- * active layer from the context or window.
- */
 ViewLayer *BKE_view_layer_context_active_PLACEHOLDER(const Scene *scene)
 {
   BLI_assert(scene->view_layers.first);
@@ -198,10 +195,6 @@ static void layer_collection_exclude_all(LayerCollection *layer_collection)
   }
 }
 
-/**
- * Add a new view layer
- * by default, a view layer has the master collection
- */
 ViewLayer *BKE_view_layer_add(Scene *scene,
                               const char *name,
                               ViewLayer *view_layer_source,
@@ -261,9 +254,6 @@ void BKE_view_layer_free(ViewLayer *view_layer)
   BKE_view_layer_free_ex(view_layer, true);
 }
 
-/**
- * Free (or release) any data used by this ViewLayer.
- */
 void BKE_view_layer_free_ex(ViewLayer *view_layer, const bool do_id_user)
 {
   view_layer->basact = NULL;
@@ -304,9 +294,6 @@ void BKE_view_layer_free_ex(ViewLayer *view_layer, const bool do_id_user)
   MEM_freeN(view_layer);
 }
 
-/**
- * Tag all the selected objects of a render-layer.
- */
 void BKE_view_layer_selected_objects_tag(ViewLayer *view_layer, const int tag)
 {
   LISTBASE_FOREACH (Base *, base, &view_layer->object_bases) {
@@ -332,13 +319,6 @@ static bool find_scene_collection_in_scene_collections(ListBase *lb, const Layer
   return false;
 }
 
-/**
- * Fallback for when a Scene has no camera to use
- *
- * \param view_layer: in general you want to use the same ViewLayer that is used
- * for depsgraph. If rendering you pass the scene active layer, when viewing in the viewport
- * you want to get ViewLayer from context.
- */
 Object *BKE_view_layer_camera_find(ViewLayer *view_layer)
 {
   LISTBASE_FOREACH (Base *, base, &view_layer->object_bases) {
@@ -350,9 +330,6 @@ Object *BKE_view_layer_camera_find(ViewLayer *view_layer)
   return NULL;
 }
 
-/**
- * Find the ViewLayer a LayerCollection belongs to
- */
 ViewLayer *BKE_view_layer_find_from_collection(const Scene *scene, LayerCollection *lc)
 {
   LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) {
@@ -422,7 +399,12 @@ void BKE_view_layer_base_select_and_set_active(struct ViewLayer *view_layer, Bas
   }
 }
 
-/**************************** Copy View Layer and Layer Collections ***********************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Copy View Layer and Layer Collections
+ * \{ */
+
 static void layer_aov_copy_data(ViewLayer *view_layer_dst,
                                 const ViewLayer *view_layer_src,
                                 ListBase *aovs_dst,
@@ -471,11 +453,6 @@ static void layer_collections_copy_data(ViewLayer *view_layer_dst,
   }
 }
 
-/**
- * Only copy internal data of ViewLayer from source to already allocated/initialized destination.
- *
- * \param flag: Copying options (see BKE_lib_id.h's LIB_ID_COPY_... flags for more).
- */
 void BKE_view_layer_copy_data(Scene *scene_dst,
                               const Scene *UNUSED(scene_src),
                               ViewLayer *view_layer_dst,
@@ -620,26 +597,17 @@ static bool layer_collection_hidden(ViewLayer *view_layer, LayerCollection *lc)
   return false;
 }
 
-/**
- * Get the collection for a given index
- */
 LayerCollection *BKE_layer_collection_from_index(ViewLayer *view_layer, const int index)
 {
   int i = 0;
   return collection_from_index(&view_layer->layer_collections, index, &i);
 }
 
-/**
- * Get the active collection
- */
 LayerCollection *BKE_layer_collection_get_active(ViewLayer *view_layer)
 {
   return view_layer->active_collection;
 }
 
-/*
- * Activate collection
- */
 bool BKE_layer_collection_activate(ViewLayer *view_layer, LayerCollection *lc)
 {
   if (lc->flag & LAYER_COLLECTION_EXCLUDE) {
@@ -650,9 +618,6 @@ bool BKE_layer_collection_activate(ViewLayer *view_layer, LayerCollection *lc)
   return true;
 }
 
-/**
- * Activate first parent collection
- */
 LayerCollection *BKE_layer_collection_activate_parent(ViewLayer *view_layer, LayerCollection *lc)
 {
   CollectionParent *parent = lc->collection->parents.first;
@@ -690,10 +655,6 @@ static int collection_count(const ListBase *lb)
   return i;
 }
 
-/**
- * Get the total number of collections
- * (including all the nested collections)
- */
 int BKE_layer_collection_count(const ViewLayer *view_layer)
 {
   return collection_count(&view_layer->layer_collections);
@@ -721,16 +682,16 @@ static int index_from_collection(ListBase *lb, const LayerCollection *lc, int *i
   return -1;
 }
 
-/**
- * Return -1 if not found
- */
 int BKE_layer_collection_findindex(ViewLayer *view_layer, const LayerCollection *lc)
 {
   int i = 0;
   return index_from_collection(&view_layer->layer_collections, lc, &i);
 }
 
-/*********************************** Syncing *********************************
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Syncing
  *
  * The layer collection tree mirrors the scene collection tree. Whenever that
  * changes we need to synchronize them so that there is a corresponding layer
@@ -740,9 +701,9 @@ int BKE_layer_collection_findindex(ViewLayer *view_layer, const LayerCollection
  *
  * The view layer also contains a list of bases for each object that exists
  * in at least one layer collection. That list is also synchronized here, and
- * stores state like selection. */
-
-/* This API allows to temporarily forbid resync of LayerCollections.
+ * stores state like selection.
+ *
+ * This API allows to temporarily forbid resync of LayerCollections.
  *
  * This can greatly improve performances in cases where those functions get
  * called a lot (e.g. during massive remappings of IDs).
@@ -751,19 +712,20 @@ int BKE_layer_collection_findindex(ViewLayer *view_layer, const LayerCollection
  * code must ensures it resync LayerCollections before any UI/Event loop
  * handling can happen.
  *
- * WARNING: This is not threadsafe at all, only use from main thread.
+ * \warning This is not threadsafe at all, only use from main thread.
  *
- * NOTE: It is probably needed to use #BKE_main_collection_sync_remap instead
+ * \note It is probably needed to use #BKE_main_collection_sync_remap instead
  *       of just #BKE_main_collection_sync after disabling LayerCollection resync,
  *       unless it is absolutely certain that no ID remapping (or any other process
  *       that may invalidate the caches) will happen while it is disabled.
  *
- * NOTE: This is a quick and safe band-aid around the long-known issue
+ * \note This is a quick and safe band-aid around the long-known issue
  *       regarding this resync process.
  *       Proper fix would be to make resync itself lazy, i.e. only happen
  *       when actually needed.
  *       See also T73411.
- */
+ * \{ */
+
 static bool no_resync = false;
 
 void BKE_layer_collection_resync_forbid(void)
@@ -1220,11 +1182,6 @@ static bool view_layer_objects_base_cache_validate(ViewLayer *UNUSED(view_layer)
 }
 #endif
 
-/**
- * Update view layer collection tree from collections used in the scene.
- * This is used when collections are removed or added, both while editing
- * and on file loaded in case linked data changed or went missing.
- */
 void BKE_layer_collection_sync(const Scene *scene, ViewLayer *view_layer)
 {
   if (no_resync) {
@@ -1377,14 +1334,12 @@ void BKE_main_collection_sync_remap(const Main *bmain)
   BKE_main_collection_sync(bmain);
 }
 
-/* ---------------------------------------------------------------------- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object Selection
+ * \{ */
 
-/**
- * Select all the objects of this layer collection
- *
- * It also select the objects that are in nested collections.
- * \note Recursive
- */
 bool BKE_layer_collection_objects_select(ViewLayer *view_layer, LayerCollection *lc, bool deselect)
 {
   if (lc->collection->flag & COLLECTION_HIDE_SELECT) {
@@ -1461,9 +1416,12 @@ bool BKE_layer_collection_has_layer_collection(LayerCollection *lc_parent,
   return false;
 }
 
-/* ---------------------------------------------------------------------- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object Visibility
+ * \{ */
 
-/* Update after toggling visibility of an object base. */
 void BKE_base_set_visible(Scene *scene, ViewLayer *view_layer, Base *base, bool extend)
 {
   if (!extend) {
@@ -1536,6 +1494,12 @@ bool BKE_object_is_visible_in_viewport(const View3D *v3d, const struct Object *o
   return true;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Collection Isolation & Local View
+ * \{ */
+
 static void layer_collection_flag_set_recursive(LayerCollection *lc, const int flag)
 {
   lc->flag |= flag;
@@ -1552,14 +1516,6 @@ static void layer_collection_flag_unset_recursive(LayerCollection *lc, const int
   }
 }
 
-/**
- * Isolate the collection - hide all other collections but this one.
- * Make sure to show all the direct parents and all children of the layer collection as well.
- * When extending we simply show the collections and its direct family.
- *
- * If the collection or any of its parents is disabled, make it enabled.
- * Don't change the children disable state though.
- */
 void BKE_layer_collection_isolate_global(Scene *scene,
                                          ViewLayer *view_layer,
                                          LayerCollection *lc,
@@ -1668,9 +1624,6 @@ void BKE_layer_collection_local_sync(ViewLayer *view_layer, const View3D *v3d)
   }
 }
 
-/**
- * Sync the local collection for all the 3D Viewports.
- */
 void BKE_layer_collection_local_sync_all(const Main *bmain)
 {
   if (no_resync) {
@@ -1694,11 +1647,6 @@ void BKE_layer_collection_local_sync_all(const Main *bmain)
   }
 }
 
-/**
- * Isolate the collection locally
- *
- * Same as BKE_layer_collection_isolate_local but for a viewport
- */
 void BKE_layer_collection_isolate_local(ViewLayer *view_layer,
                                         const View3D *v3d,
                                         LayerCollection *lc,
@@ -1771,11 +1719,6 @@ static void layer_collection_bases_hide_recursive(ViewLayer *view_layer, LayerCo
   }
 }
 
-/**
- * Hide/show all the elements of a collection.
- * Don't change the collection children enable/disable state,
- * but it may change it for the collection itself.
- */
 void BKE_layer_collection_set_visible(ViewLayer *view_layer,
                                       LayerCollection *lc,
                                       const bool visible,
@@ -1862,9 +1805,6 @@ static LayerCollection *find_layer_collection_by_scene_collection(LayerCollectio
   return NULL;
 }
 
-/**
- * Return the first matching LayerCollection in the ViewLayer for the Collection.
- */
 LayerCollection *BKE_layer_collection_first_from_scene_collection(const ViewLayer *view_layer,
                                                                   const Collection *collection)
 {
@@ -1878,17 +1818,11 @@ LayerCollection *BKE_layer_collection_first_from_scene_collection(const ViewLaye
   return NULL;
 }
 
-/**
- * See if view layer has the scene collection linked directly, or indirectly (nested)
- */
 bool BKE_view_layer_has_collection(const ViewLayer *view_layer, const Collection *collection)
 {
   return BKE_layer_collection_first_from_scene_collection(view_layer, collection) != NULL;
 }
 
-/**
- * See if the object is in any of the scene layers of the scene
- */
 bool BKE_scene_has_object(Scene *scene, Object *ob)
 {
   LISTBASE_FOREACH (ViewLayer *, view_layer, &scene->view_layers) {
@@ -1999,6 +1933,8 @@ static void objects_iterator_end(BLI_Iterator *iter)
   object_bases_iterator_end(iter);
 }
 
+/** \} */
+
 /* -------------------------------------------------------------------- */
 /** \name BKE_view_layer_selected_objects_iterator
  * See: #FOREACH_SELECTED_OBJECT_BEGIN
@@ -2188,11 +2124,10 @@ void BKE_view_layer_bases_in_mode_iterator_end(BLI_Iterator *UNUSED(iter))
 
 /** \} */
 
-/* Evaluation. */
+/* -------------------------------------------------------------------- */
+/** \name Evaluation
+ * \{ */
 
-/* Applies object's restrict flags on top of flags coming from the collection
- * and stores those in base->flag. BASE_VISIBLE_DEPSGRAPH ignores viewport flags visibility
- * (i.e., restriction and local collection). */
 void BKE_base_eval_flags(Base *base)
 {
   /* Apply collection flags. */
@@ -2251,6 +2186,12 @@ void BKE_layer_eval_view_layer_indexed(struct Depsgraph *depsgraph,
   layer_eval_view_layer(depsgraph, scene, view_layer);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Blend File I/O
+ * \{ */
+
 static void write_layer_collections(BlendWriter *writer, ListBase *lb)
 {
   LISTBASE_FOREACH (LayerCollection *, lc, lb) {
@@ -2371,6 +2312,8 @@ void BKE_view_layer_blend_read_lib(BlendLibReader *reader, Library *lib, ViewLay
   IDP_BlendReadLib(reader, view_layer->id_properties);
 }
 
+/** \} */
+
 /* -------------------------------------------------------------------- */
 /** \name Shader AOV
  * \{ */
@@ -2455,12 +2398,6 @@ static void bke_view_layer_verify_aov_cb(void *userdata,
   }
 }
 
-/* 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)
@@ -2478,7 +2415,6 @@ void BKE_view_layer_verify_aov(struct RenderEngine *engine,
   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) {