RNA: Make is clear that `Scene` parameter of `update` callback may be NULL.

There are cases where there is no way to ensure we do have/know about an
active scene. Further more, this should not be required to perform
'real' updates on data, only to perform additional special handling in
current scene (mostly related to editing tools, UI, etc.).

This pointer is actually almost never used in practice, and half of its current
 usages are fairly close to abuse of the system (like calls to
`ED_gpencil_tag_scene_gpencil` or `BKE_rigidbody_cache_reset`).

This commit ensures that the few places using this 'active scene' pointer are
safely handling the `NULL` case, and clearly document the fact that a
NULL scene pointer is valid.

1 files changed, 10 insertions, 1 deletions

diff --git a/source/blender/makesrna/intern/rna_internal_types.h b/source/blender/makesrna/intern/rna_internal_types.h
index 22a9b9d930a..29df7a53c44 100644
--- a/source/blender/makesrna/intern/rna_internal_types.h
+++ b/source/blender/makesrna/intern/rna_internal_types.h
@@ -44,11 +44,20 @@ typedef struct IDProperty IDProperty;
 
 /* Function Callbacks */
 
-typedef void (*UpdateFunc)(struct Main *main, struct Scene *scene, struct PointerRNA *ptr);
+/** Update callback for an RNA property.
+ *
+ *  \note This is NOT called automatically when writing into the property, it needs to be called
+ * manually (through #RNA_property_update or #RNA_property_update_main) when needed.
+ *
+ *  \param bmain: the Main data-base to which `ptr` data belongs.
+ *  \param active_scene: The current active scene (may be NULL in some cases).
+ *  \param ptr: The RNA pointer data to update. */
+typedef void (*UpdateFunc)(struct Main *bmain, struct Scene *active_scene, struct PointerRNA *ptr);
 typedef void (*ContextPropUpdateFunc)(struct bContext *C,
                                       struct PointerRNA *ptr,
                                       struct PropertyRNA *prop);
 typedef void (*ContextUpdateFunc)(struct bContext *C, struct PointerRNA *ptr);
+
 typedef int (*EditableFunc)(struct PointerRNA *ptr, const char **r_info);
 typedef int (*ItemEditableFunc)(struct PointerRNA *ptr, int index);
 typedef struct IDProperty **(*IDPropertiesFunc)(struct PointerRNA *ptr);