diff options
| -rw-r--r-- | source/blender/makesrna/RNA_access.h | 258 | ||||
| -rw-r--r-- | source/blender/makesrna/RNA_define.h | 52 | ||||
| -rw-r--r-- | source/blender/makesrna/RNA_enum_types.h | 6 | ||||
| -rw-r--r-- | source/blender/makesrna/intern/rna_access.c | 194 | ||||
| -rw-r--r-- | source/blender/makesrna/intern/rna_access_compare_override.c | 21 | ||||
| -rw-r--r-- | source/blender/makesrna/intern/rna_access_internal.h | 7 | ||||
| -rw-r--r-- | source/blender/makesrna/intern/rna_armature.c | 4 | ||||
| -rw-r--r-- | source/blender/makesrna/intern/rna_asset.c | 3 | ||||
| -rw-r--r-- | source/blender/makesrna/intern/rna_constraint.c | 3 | ||||
| -rw-r--r-- | source/blender/makesrna/intern/rna_define.c | 36 | ||||
| -rw-r--r-- | source/blender/makesrna/intern/rna_internal.h | 17 | ||||
| -rw-r--r-- | source/blender/makesrna/intern/rna_pose.c | 1 | ||||
| -rw-r--r-- | source/blender/makesrna/intern/rna_wm.c | 5 |
13 files changed, 336 insertions, 271 deletions
diff --git a/source/blender/makesrna/RNA_access.h b/source/blender/makesrna/RNA_access.h index 188f933dba5..7fa7405add1 100644 --- a/source/blender/makesrna/RNA_access.h +++ b/source/blender/makesrna/RNA_access.h @@ -801,6 +801,11 @@ PropertyRNA *RNA_struct_name_property(const StructRNA *type); const EnumPropertyItem *RNA_struct_property_tag_defines(const StructRNA *type); PropertyRNA *RNA_struct_iterator_property(StructRNA *type); StructRNA *RNA_struct_base(StructRNA *type); +/** + * Use to find the sub-type directly below a base-type. + * + * So if type were `RNA_SpotLight`, `RNA_struct_base_of(type, &RNA_ID)` would return `&RNA_Light`. + */ const StructRNA *RNA_struct_base_child_of(const StructRNA *type, const StructRNA *parent_type); bool RNA_struct_is_ID(const StructRNA *type); @@ -823,16 +828,32 @@ struct IDProperty *RNA_struct_idprops(PointerRNA *ptr, bool create); bool RNA_struct_idprops_check(StructRNA *srna); bool RNA_struct_idprops_register_check(const StructRNA *type); bool RNA_struct_idprops_datablock_allowed(const StructRNA *type); +/** + * Whether given type implies datablock usage by IDProperties. + * This is used to prevent classes allowed to have IDProperties, + * but not datablock ones, to indirectly use some + * (e.g. by assigning an IDP_GROUP containing some IDP_ID pointers...). + */ bool RNA_struct_idprops_contains_datablock(const StructRNA *type); +/** + * Remove an id-property. + */ bool RNA_struct_idprops_unset(PointerRNA *ptr, const char *identifier); PropertyRNA *RNA_struct_find_property(PointerRNA *ptr, const char *identifier); bool RNA_struct_contains_property(PointerRNA *ptr, PropertyRNA *prop_test); unsigned int RNA_struct_count_properties(StructRNA *srna); -/* lower level functions for access to type properties */ +/** + * Low level direct access to type->properties, + * note this ignores parent classes so should be used with care. + */ const struct ListBase *RNA_struct_type_properties(StructRNA *srna); PropertyRNA *RNA_struct_type_find_property_no_base(StructRNA *srna, const char *identifier); +/** + * \note #RNA_struct_find_property is a higher level alternative to this function + * which takes a #PointerRNA instead of a #StructRNA. + */ PropertyRNA *RNA_struct_type_find_property(StructRNA *srna, const char *identifier); FunctionRNA *RNA_struct_find_function(StructRNA *srna, const char *identifier); @@ -840,6 +861,9 @@ const struct ListBase *RNA_struct_type_functions(StructRNA *srna); char *RNA_struct_name_get_alloc(PointerRNA *ptr, char *fixedbuf, int fixedlen, int *r_len); +/** + * Use when registering structs with the #STRUCT_PUBLIC_NAMESPACE flag. + */ bool RNA_struct_available_or_report(struct ReportList *reports, const char *identifier); bool RNA_struct_bl_idname_ok_or_report(struct ReportList *reports, const char *identifier, @@ -861,17 +885,32 @@ PropertyUnit RNA_property_unit(PropertyRNA *prop); PropertyScaleType RNA_property_ui_scale(PropertyRNA *prop); int RNA_property_flag(PropertyRNA *prop); int RNA_property_override_flag(PropertyRNA *prop); +/** + * Get the tags set for \a prop as int bitfield. + * \note Doesn't perform any validity check on the set bits. #RNA_def_property_tags does this + * in debug builds (to avoid performance issues in non-debug builds), which should be + * the only way to set tags. Hence, at this point we assume the tag bitfield to be valid. + */ int RNA_property_tags(PropertyRNA *prop); bool RNA_property_builtin(PropertyRNA *prop); void *RNA_property_py_data_get(PropertyRNA *prop); int RNA_property_array_length(PointerRNA *ptr, PropertyRNA *prop); bool RNA_property_array_check(PropertyRNA *prop); +/** + * Return the size of Nth dimension. + */ int RNA_property_multi_array_length(PointerRNA *ptr, PropertyRNA *prop, int dimension); +/** + * Used by BPY to make an array from the python object. + */ int RNA_property_array_dimension(PointerRNA *ptr, PropertyRNA *prop, int length[]); char RNA_property_array_item_char(PropertyRNA *prop, int index); int RNA_property_array_item_index(PropertyRNA *prop, char name); +/** + * \return the maximum length including the \0 terminator. '0' is used when there is no maximum. + */ int RNA_property_string_maxlength(PropertyRNA *prop); const char *RNA_property_ui_name(const PropertyRNA *prop); @@ -906,6 +945,10 @@ bool RNA_enum_name(const EnumPropertyItem *item, const int value, const char **r bool RNA_enum_description(const EnumPropertyItem *item, const int value, const char **description); int RNA_enum_from_value(const EnumPropertyItem *item, const int value); int RNA_enum_from_identifier(const EnumPropertyItem *item, const char *identifier); +/** + * Take care using this with translated enums, + * prefer #RNA_enum_from_identifier where possible. + */ int RNA_enum_from_name(const EnumPropertyItem *item, const char *name); unsigned int RNA_enum_items_count(const EnumPropertyItem *item); @@ -967,27 +1010,54 @@ StructRNA *RNA_property_pointer_type(PointerRNA *ptr, PropertyRNA *prop); bool RNA_property_pointer_poll(PointerRNA *ptr, PropertyRNA *prop, PointerRNA *value); bool RNA_property_editable(PointerRNA *ptr, PropertyRNA *prop); +/** + * Version of #RNA_property_editable that tries to return additional info in \a r_info + * that can be exposed in UI. + */ bool RNA_property_editable_info(PointerRNA *ptr, PropertyRNA *prop, const char **r_info); +/** + * Same as RNA_property_editable(), except this checks individual items in an array. + */ bool RNA_property_editable_index(PointerRNA *ptr, PropertyRNA *prop, int index); -/* without lib check, only checks the flag */ +/** + * Without lib check, only checks the flag. + */ bool RNA_property_editable_flag(PointerRNA *ptr, PropertyRNA *prop); bool RNA_property_animateable(PointerRNA *ptr, PropertyRNA *prop); bool RNA_property_animated(PointerRNA *ptr, PropertyRNA *prop); +/** + * \note Does not take into account editable status, this has to be checked separately + * (using #RNA_property_editable_flag() usually). + */ bool RNA_property_overridable_get(PointerRNA *ptr, PropertyRNA *prop); +/** + * Should only be used for custom properties. + */ bool RNA_property_overridable_library_set(PointerRNA *ptr, PropertyRNA *prop, const bool is_overridable); bool RNA_property_overridden(PointerRNA *ptr, PropertyRNA *prop); bool RNA_property_comparable(PointerRNA *ptr, PropertyRNA *prop); +/** + * This function is to check if its possible to create a valid path from the ID + * its slow so don't call in a loop. + */ bool RNA_property_path_from_ID_check(PointerRNA *ptr, PropertyRNA *prop); /* slow, use with care */ void RNA_property_update(struct bContext *C, PointerRNA *ptr, PropertyRNA *prop); +/** + * \param scene: may be NULL. + */ void RNA_property_update_main(struct Main *bmain, struct Scene *scene, PointerRNA *ptr, PropertyRNA *prop); +/** + * \note its possible this returns a false positive in the case of #PROP_CONTEXT_UPDATE + * but this isn't likely to be a performance problem. + */ bool RNA_property_update_check(struct PropertyRNA *prop); /* Property Data */ @@ -1031,15 +1101,28 @@ char *RNA_property_string_get_alloc( PointerRNA *ptr, PropertyRNA *prop, char *fixedbuf, int fixedlen, int *r_len); void RNA_property_string_set(PointerRNA *ptr, PropertyRNA *prop, const char *value); void RNA_property_string_set_bytes(PointerRNA *ptr, PropertyRNA *prop, const char *value, int len); +/** + * \return the length without `\0` terminator. + */ int RNA_property_string_length(PointerRNA *ptr, PropertyRNA *prop); void RNA_property_string_get_default(PropertyRNA *prop, char *value, int max_len); char *RNA_property_string_get_default_alloc( PointerRNA *ptr, PropertyRNA *prop, char *fixedbuf, int fixedlen, int *r_len); +/** + * \return the length without `\0` terminator. + */ int RNA_property_string_default_length(PointerRNA *ptr, PropertyRNA *prop); int RNA_property_enum_get(PointerRNA *ptr, PropertyRNA *prop); void RNA_property_enum_set(PointerRNA *ptr, PropertyRNA *prop, int value); int RNA_property_enum_get_default(PointerRNA *ptr, PropertyRNA *prop); +/** + * Get the value of the item that is \a step items away from \a from_value. + * + * \param from_value: Item value to start stepping from. + * \param step: Absolute value defines step size, sign defines direction. + * E.g to get the next item, pass 1, for the previous -1. + */ int RNA_property_enum_step( const struct bContext *C, PointerRNA *ptr, PropertyRNA *prop, int from_value, int step); @@ -1068,6 +1151,9 @@ int RNA_property_collection_lookup_string(PointerRNA *ptr, PointerRNA *r_ptr); int RNA_property_collection_lookup_string_index( PointerRNA *ptr, PropertyRNA *prop, const char *key, PointerRNA *r_ptr, int *r_index); +/** + * Zero return is an assignment error. + */ int RNA_property_collection_assign_int(PointerRNA *ptr, PropertyRNA *prop, const int key, @@ -1125,31 +1211,99 @@ char *RNA_path_append( char *RNA_path_back(const char *path); #endif -/* path_resolve() variants only ensure that a valid pointer (and optionally property) exist */ +/* RNA_path_resolve() variants only ensure that a valid pointer (and optionally property) exist. */ + +/** + * Resolve the given RNA Path to find the pointer and/or property + * indicated by fully resolving the path. + * + * \warning Unlike \a RNA_path_resolve_property(), that one *will* try to follow RNAPointers, + * e.g. the path 'parent' applied to a RNAObject \a ptr will return the object.parent in \a r_ptr, + * and a NULL \a r_prop... + * + * \note Assumes all pointers provided are valid + * \return True if path can be resolved to a valid "pointer + property" OR "pointer only" + */ bool RNA_path_resolve(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop); +/** + * Resolve the given RNA Path to find the pointer and/or property + array index + * indicated by fully resolving the path. + * + * \note Assumes all pointers provided are valid. + * \return True if path can be resolved to a valid "pointer + property" OR "pointer only" + */ bool RNA_path_resolve_full( PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index); +/** + * A version of #RNA_path_resolve_full doesn't check the value of #PointerRNA.data. + * + * \note While it's correct to ignore the value of #PointerRNA.data + * most callers need to know if the resulting pointer was found and not null. + */ bool RNA_path_resolve_full_maybe_null( PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index); -/* path_resolve_property() variants ensure that pointer + property both exist */ +/* RNA_path_resolve_property() variants ensure that pointer + property both exist. */ + +/** + * Resolve the given RNA Path to find both the pointer AND property + * indicated by fully resolving the path. + * + * This is a convenience method to avoid logic errors and ugly syntax. + * \note Assumes all pointers provided are valid + * \return True only if both a valid pointer and property are found after resolving the path + */ bool RNA_path_resolve_property(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop); +/** + * Resolve the given RNA Path to find the pointer AND property (as well as the array index) + * indicated by fully resolving the path. + * + * This is a convenience method to avoid logic errors and ugly syntax. + * \note Assumes all pointers provided are valid + * \return True only if both a valid pointer and property are found after resolving the path + */ bool RNA_path_resolve_property_full( PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index); -/* path_resolve_property_and_item_pointer() variants ensure that pointer + property both exist, +/* RNA_path_resolve_property_and_item_pointer() variants ensure that pointer + property both exist, * and resolve last Pointer value if possible (Pointer prop or item of a Collection prop). */ + +/** + * Resolve the given RNA Path to find both the pointer AND property + * indicated by fully resolving the path, and get the value of the Pointer property + * (or item of the collection). + * + * This is a convenience method to avoid logic errors and ugly syntax, + * it combines both \a RNA_path_resolve and #RNA_path_resolve_property in a single call. + * \note Assumes all pointers provided are valid. + * \param r_item_ptr: The final Pointer or Collection item value. + * You must check for its validity before use! + * \return True only if both a valid pointer and property are found after resolving the path + */ bool RNA_path_resolve_property_and_item_pointer(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, PointerRNA *r_item_ptr); +/** + * Resolve the given RNA Path to find both the pointer AND property (as well as the array index) + * indicated by fully resolving the path, + * and get the value of the Pointer property (or item of the collection). + * + * This is a convenience method to avoid logic errors and ugly syntax, + * it combines both \a RNA_path_resolve_full and + * \a RNA_path_resolve_property_full in a single call. + * \note Assumes all pointers provided are valid. + * \param r_item_ptr: The final Pointer or Collection item value. + * You must check for its validity before use! + * \return True only if both a valid pointer and property are found after resolving the path + */ bool RNA_path_resolve_property_and_item_pointer_full(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, @@ -1164,10 +1318,36 @@ struct PropertyElemRNA { PropertyRNA *prop; int index; }; +/** + * Resolve the given RNA Path into a linked list of #PropertyElemRNA's. + * + * To be used when complex operations over path are needed, like e.g. get relative paths, + * to avoid too much string operations. + * + * \return True if there was no error while resolving the path + * \note Assumes all pointers provided are valid + */ bool RNA_path_resolve_elements(PointerRNA *ptr, const char *path, struct ListBase *r_elements); +/** + * Find the path from the structure referenced by the pointer to the runtime RNA-defined + * #IDProperty object. + * + * \note Does *not* handle pure user-defined IDProperties (a.k.a. custom properties). + * + * \param ptr: Reference to the object owning the custom property storage. + * \param needle: Custom property object to find. + * \return Relative path or NULL. + */ char *RNA_path_from_struct_to_idproperty(PointerRNA *ptr, struct IDProperty *needle); +/** + * Find the actual ID pointer and path from it to the given ID. + * + * \param id: ID reference to search the global owner for. + * \param[out] r_path: Path from the real ID to the initial ID. + * \return The ID pointer, or NULL in case of failure. + */ struct ID *RNA_find_real_ID_and_path(struct Main *bmain, struct ID *id, const char **r_path); char *RNA_path_from_ID_to_struct(const PointerRNA *ptr); @@ -1175,6 +1355,11 @@ char *RNA_path_from_ID_to_struct(const PointerRNA *ptr); char *RNA_path_from_real_ID_to_struct(struct Main *bmain, PointerRNA *ptr, struct ID **r_real); char *RNA_path_from_ID_to_property(PointerRNA *ptr, PropertyRNA *prop); +/** + * \param index_dim: The dimension to show, 0 disables. 1 for 1d array, 2 for 2d. etc. + * \param index: The *flattened* index to use when \a `index_dim > 0`, + * this is expanded when used with multi-dimensional arrays. + */ char *RNA_path_from_ID_to_property_index(PointerRNA *ptr, PropertyRNA *prop, int index_dim, @@ -1187,19 +1372,43 @@ char *RNA_path_from_real_ID_to_property_index(struct Main *bmain, int index, struct ID **r_real_id); +/** + * \return the path to given ptr/prop from the closest ancestor of given type, + * if any (else return NULL). + */ char *RNA_path_resolve_from_type_to_property(struct PointerRNA *ptr, struct PropertyRNA *prop, const struct StructRNA *type); +/** + * Get the ID as a python representation, eg: + * bpy.data.foo["bar"] + */ char *RNA_path_full_ID_py(struct Main *bmain, struct ID *id); +/** + * Get the ID.struct as a python representation, eg: + * bpy.data.foo["bar"].some_struct + */ char *RNA_path_full_struct_py(struct Main *bmain, struct PointerRNA *ptr); +/** + * Get the ID.struct.property as a python representation, eg: + * bpy.data.foo["bar"].some_struct.some_prop[10] + */ char *RNA_path_full_property_py_ex( struct Main *bmain, PointerRNA *ptr, PropertyRNA *prop, int index, bool use_fallback); char *RNA_path_full_property_py(struct Main *bmain, struct PointerRNA *ptr, struct PropertyRNA *prop, int index); +/** + * Get the struct.property as a python representation, eg: + * some_struct.some_prop[10] + */ char *RNA_path_struct_property_py(struct PointerRNA *ptr, struct PropertyRNA *prop, int index); +/** + * Get the struct.property as a python representation, eg: + * some_prop[10] + */ char *RNA_path_property_py(const struct PointerRNA *ptr, struct PropertyRNA *prop, int index); /* Quick name based property access @@ -1314,24 +1523,38 @@ void RNA_collection_clear(PointerRNA *ptr, const char *name); } \ ((void)0) -/* check if the idproperty exists, for operators */ +/** + * Check if the #IDproperty exists, for operators. + */ bool RNA_property_is_set_ex(PointerRNA *ptr, PropertyRNA *prop, bool use_ghost); bool RNA_property_is_set(PointerRNA *ptr, PropertyRNA *prop); void RNA_property_unset(PointerRNA *ptr, PropertyRNA *prop); bool RNA_struct_property_is_set_ex(PointerRNA *ptr, const char *identifier, bool use_ghost); bool RNA_struct_property_is_set(PointerRNA *ptr, const char *identifier); bool RNA_property_is_idprop(const PropertyRNA *prop); +/** + * \note Mainly for the UI. + */ bool RNA_property_is_unlink(PropertyRNA *prop); void RNA_struct_property_unset(PointerRNA *ptr, const char *identifier); -/* python compatible string representation of this property, (must be freed!) */ +/** + * Python compatible string representation of this property, (must be freed!). + */ char *RNA_property_as_string( struct bContext *C, PointerRNA *ptr, PropertyRNA *prop, int index, int max_prop_length); +/** + * String representation of a property, Python compatible but can be used for display too. + * \param C: can be NULL. + */ char *RNA_pointer_as_string_id(struct bContext *C, PointerRNA *ptr); char *RNA_pointer_as_string(struct bContext *C, PointerRNA *ptr, PropertyRNA *prop_ptr, PointerRNA *ptr_prop); +/** + * \param C: can be NULL. + */ char *RNA_pointer_as_string_keywords_ex(struct bContext *C, PointerRNA *ptr, const bool as_function, @@ -1383,7 +1606,9 @@ void RNA_parameter_get(ParameterList *parms, PropertyRNA *parm, void **value); void RNA_parameter_get_lookup(ParameterList *parms, const char *identifier, void **value); void RNA_parameter_set(ParameterList *parms, PropertyRNA *parm, const void *value); void RNA_parameter_set_lookup(ParameterList *parms, const char *identifier, const void *value); + /* Only for PROP_DYNAMIC properties! */ + int RNA_parameter_dynamic_length_get(ParameterList *parms, PropertyRNA *parm); int RNA_parameter_dynamic_length_get_data(ParameterList *parms, PropertyRNA *parm, void *data); void RNA_parameter_dynamic_length_set(ParameterList *parms, PropertyRNA *parm, int length); @@ -1454,6 +1679,7 @@ StructRNA *ID_code_to_RNA_type(short idcode); # define RNA_warning(format, ...) _RNA_warning("%s: " format "\n", __FUNCTION__, __VA_ARGS__) #endif +/** Use to implement the #RNA_warning macro which includes `__func__` suffix. */ void _RNA_warning(const char *format, ...) ATTR_PRINTF_FORMAT(1, 2); /* Equals test. */ @@ -1520,6 +1746,16 @@ typedef enum eRNAOverrideStatus { RNA_OVERRIDE_STATUS_LOCKED = 1 << 3, } eRNAOverrideStatus; +/** + * Check whether reference and local overridden data match (are the same), + * with respect to given restrictive sets of properties. + * If requested, will generate needed new property overrides, and/or restore values from reference. + * + * \param r_report_flags: If given, + * will be set with flags matching actions taken by the function on \a ptr_local. + * + * \return True if _resulting_ \a ptr_local does match \a ptr_reference. + */ bool RNA_struct_override_matches(struct Main *bmain, struct PointerRNA *ptr_local, struct PointerRNA *ptr_reference, @@ -1529,6 +1765,10 @@ bool RNA_struct_override_matches(struct Main *bmain, const eRNAOverrideMatch flags, eRNAOverrideMatchResult *r_report_flags); +/** + * Store needed second operands into \a storage data-block + * for differential override operations. + */ bool RNA_struct_override_store(struct Main *bmain, struct PointerRNA *ptr_local, struct PointerRNA *ptr_reference, @@ -1544,6 +1784,10 @@ typedef enum eRNAOverrideApplyFlag { RNA_OVERRIDE_APPLY_FLAG_IGNORE_ID_POINTERS = 1 << 0, } eRNAOverrideApplyFlag; +/** + * Apply given \a override operations on \a ptr_dst, using \a ptr_src + * (and \a ptr_storage for differential ops) as source. + */ void RNA_struct_override_apply(struct Main *bmain, struct PointerRNA *ptr_dst, struct PointerRNA *ptr_src, diff --git a/source/blender/makesrna/RNA_define.h b/source/blender/makesrna/RNA_define.h index 01e26cbb41c..3596a5f2234 100644 --- a/source/blender/makesrna/RNA_define.h +++ b/source/blender/makesrna/RNA_define.h @@ -49,6 +49,10 @@ void RNA_free(BlenderRNA *brna); void RNA_define_verify_sdna(bool verify); void RNA_define_animate_sdna(bool animate); void RNA_define_fallback_property_update(int noteflag, const char *updatefunc); +/** + * Properties defined when this is enabled are lib-overridable by default + * (except for Pointer ones). + */ void RNA_define_lib_overridable(const bool make_overridable); void RNA_init(void); @@ -56,6 +60,9 @@ void RNA_exit(void); /* Struct */ +/** + * Struct Definition. + */ StructRNA *RNA_def_struct_ptr(BlenderRNA *brna, const char *identifier, StructRNA *srnafrom); StructRNA *RNA_def_struct(BlenderRNA *brna, const char *identifier, const char *from); void RNA_def_struct_sdna(StructRNA *srna, const char *structname); @@ -72,6 +79,9 @@ void RNA_def_struct_register_funcs(StructRNA *srna, const char *unreg, const char *instance); void RNA_def_struct_path_func(StructRNA *srna, const char *path); +/** + * Only used in one case when we name the struct for the purpose of useful error messages. + */ void RNA_def_struct_identifier_no_struct_map(StructRNA *srna, const char *identifier); void RNA_def_struct_identifier(BlenderRNA *brna, StructRNA *srna, const char *identifier); void RNA_def_struct_ui_text(StructRNA *srna, const char *name, const char *description); @@ -176,6 +186,9 @@ PropertyRNA *RNA_def_enum(StructOrFunctionRNA *cont, int default_value, const char *ui_name, const char *ui_description); +/** + * Same as above but sets #PROP_ENUM_FLAG before setting the default value. + */ PropertyRNA *RNA_def_enum_flag(StructOrFunctionRNA *cont, const char *identifier, const EnumPropertyItem *items, @@ -362,6 +375,13 @@ void RNA_def_property_flag(PropertyRNA *prop, PropertyFlag flag); void RNA_def_property_clear_flag(PropertyRNA *prop, PropertyFlag flag); void RNA_def_property_override_flag(PropertyRNA *prop, PropertyOverrideFlag flag); void RNA_def_property_override_clear_flag(PropertyRNA *prop, PropertyOverrideFlag flag); +/** + * Add the property-tags passed as \a tags to \a prop (if valid). + * + * \note Multiple tags can be set by passing them within \a tags (using bit-flags). + * \note Doesn't do any type-checking with the tags defined in the parent #StructRNA + * of \a prop. This should be done before (e.g. see #WM_operatortype_prop_tag). + */ void RNA_def_property_tags(PropertyRNA *prop, int tags); void RNA_def_property_subtype(PropertyRNA *prop, PropertySubType subtype); void RNA_def_property_array(PropertyRNA *prop, int length); @@ -381,11 +401,25 @@ void RNA_def_property_boolean_array_default(PropertyRNA *prop, const bool *array void RNA_def_property_int_default(PropertyRNA *prop, int value); void RNA_def_property_int_array_default(PropertyRNA *prop, const int *array); void RNA_def_property_float_default(PropertyRNA *prop, float value); +/** + * Array must remain valid after this function finishes. + */ void RNA_def_property_float_array_default(PropertyRNA *prop, const float *array); void RNA_def_property_enum_default(PropertyRNA *prop, int value); void RNA_def_property_string_default(PropertyRNA *prop, const char *value); void RNA_def_property_ui_text(PropertyRNA *prop, const char *name, const char *description); +/** + * The values hare are a little confusing: + * + * \param step: Used as the value to increase/decrease when clicking on number buttons, + * as well as scaling mouse input for click-dragging number buttons. + * For floats this is (step * UI_PRECISION_FLOAT_SCALE), why? - nobody knows. + * For ints, whole values are used. + * + * \param precision: The number of zeros to show + * (as a whole number - common range is 1 - 6), see UI_PRECISION_FLOAT_MAX + */ void RNA_def_property_ui_range( PropertyRNA *prop, double min, double max, double step, int precision); void RNA_def_property_ui_scale_type(PropertyRNA *prop, PropertyScaleType scale_type); @@ -395,6 +429,11 @@ void RNA_def_property_update(PropertyRNA *prop, int noteflag, const char *update void RNA_def_property_editable_func(PropertyRNA *prop, const char *editable); void RNA_def_property_editable_array_func(PropertyRNA *prop, const char *editable); +/** + * Set custom callbacks for override operations handling. + * + * \note \a diff callback will also be used by RNA comparison/equality functions. + */ void RNA_def_property_override_funcs(PropertyRNA *prop, const char *diff, const char *store, @@ -472,6 +511,9 @@ void RNA_def_property_translation_context(PropertyRNA *prop, const char *context FunctionRNA *RNA_def_function(StructRNA *srna, const char *identifier, const char *call); FunctionRNA *RNA_def_function_runtime(StructRNA *srna, const char *identifier, CallFunc call); +/** + * C return value only! multiple RNA returns can be done with #RNA_def_function_output. + */ void RNA_def_function_return(FunctionRNA *func, PropertyRNA *ret); void RNA_def_function_output(FunctionRNA *func, PropertyRNA *ret); void RNA_def_function_flag(FunctionRNA *func, int flag); @@ -514,7 +556,8 @@ void RNA_def_property_free_identifier_deferred_finish(StructOrFunctionRNA *cont_ void RNA_def_property_free_pointers_set_py_data_callback( void (*py_data_clear_fn)(PropertyRNA *prop)); -/* utilities */ +/* Utilities. */ + const char *RNA_property_typename(PropertyType type); #define IS_DNATYPE_FLOAT_COMPAT(_str) (strcmp(_str, "float") == 0 || strcmp(_str, "double") == 0) #define IS_DNATYPE_INT_COMPAT(_str) \ @@ -525,16 +568,19 @@ const char *RNA_property_typename(PropertyType type); void RNA_identifier_sanitize(char *identifier, int property); +/* Common arguments for length. */ + extern const int rna_matrix_dimsize_3x3[]; extern const int rna_matrix_dimsize_4x4[]; extern const int rna_matrix_dimsize_4x2[]; +/* Common arguments for defaults. */ + extern const float rna_default_axis_angle[4]; extern const float rna_default_quaternion[4]; extern const float rna_default_scale_3d[3]; -/* max size for dynamic defined type descriptors, - * this value is arbitrary */ +/** Maximum size for dynamic defined type descriptors, this value is arbitrary. */ #define RNA_DYN_DESCR_MAX 240 #ifdef __cplusplus diff --git a/source/blender/makesrna/RNA_enum_types.h b/source/blender/makesrna/RNA_enum_types.h index d7520834287..da07f1043a7 100644 --- a/source/blender/makesrna/RNA_enum_types.h +++ b/source/blender/makesrna/RNA_enum_types.h @@ -83,8 +83,10 @@ const EnumPropertyItem *rna_TransformOrientation_itemf(struct bContext *C, struct PropertyRNA *prop, bool *r_free); -/* Generic functions, return an enum from library data, index is the position - * in the linked list can add more for different types as needed */ +/** + * Generic functions, return an enum from library data, index is the position + * in the linked list can add more for different types as needed. + */ const EnumPropertyItem *RNA_action_itemf(struct bContext *C, struct PointerRNA *ptr, struct PropertyRNA *prop, diff --git a/source/blender/makesrna/intern/rna_access.c b/source/blender/makesrna/intern/rna_access.c index 40b5f3ed1da..ab9568aa3de 100644 --- a/source/blender/makesrna/intern/rna_access.c +++ b/source/blender/makesrna/intern/rna_access.c @@ -438,12 +438,6 @@ static PropertyRNA *arraytypemap[IDP_NUMTYPES] = { (PropertyRNA *)&rna_PropertyGroupItem_double_array, }; -/* This function initializes a PropertyRNAOrID with all required info, from a given PropertyRNA - * and PointerRNA data. It deals properly with the three cases (static RNA, runtime RNA, and - * IDProperty). - * WARNING: given `ptr` PointerRNA is assumed to be a valid data one here, calling code is - * responsible to ensure that. - */ void rna_property_rna_or_id_get(PropertyRNA *prop, PointerRNA *ptr, PropertyRNAOrID *r_prop_rna_or_id) @@ -515,8 +509,6 @@ void rna_property_rna_or_id_get(PropertyRNA *prop, } } -/* This function only returns an IDProperty, - * or NULL (in case IDProp could not be found, or prop is a real RNA property). */ IDProperty *rna_idproperty_check(PropertyRNA **prop, PointerRNA *ptr) { PropertyRNAOrID prop_rna_or_id; @@ -527,8 +519,6 @@ IDProperty *rna_idproperty_check(PropertyRNA **prop, PointerRNA *ptr) return prop_rna_or_id.idprop; } -/* This function always return the valid, real data pointer, be it a regular RNA property one, - * or an IDProperty one. */ PropertyRNA *rna_ensure_property_realdata(PropertyRNA **prop, PointerRNA *ptr) { PropertyRNAOrID prop_rna_or_id; @@ -661,11 +651,6 @@ StructRNA *RNA_struct_base(StructRNA *type) return type->base; } -/** - * Use to find the subtype directly below a base-type. - * - * So if type were `RNA_SpotLIght`, `RNA_struct_base_of(type, &RNA_ID)` would return `&RNA_Light`. - */ const StructRNA *RNA_struct_base_child_of(const StructRNA *type, const StructRNA *parent_type) { while (type) { @@ -697,18 +682,11 @@ bool RNA_struct_idprops_datablock_allowed(const StructRNA *type) return (type->flag & (STRUCT_NO_DATABLOCK_IDPROPERTIES | STRUCT_NO_IDPROPERTIES)) == 0; } -/** - * Whether given type implies datablock usage by IDProperties. - * This is used to prevent classes allowed to have IDProperties, - * but not datablock ones, to indirectly use some - * (e.g. by assigning an IDP_GROUP containing some IDP_ID pointers...). - */ bool RNA_struct_idprops_contains_datablock(const StructRNA *type) { return (type->flag & (STRUCT_CONTAINS_DATABLOCK_IDPROPERTIES | STRUCT_ID)) != 0; } -/* remove an id-property */ bool RNA_struct_idprops_unset(PointerRNA *ptr, const char *identifier) { IDProperty *group = RNA_struct_idprops(ptr, 0); @@ -825,8 +803,6 @@ unsigned int RNA_struct_count_properties(StructRNA *srna) return counter; } -/* Low level direct access to type->properties, - * note this ignores parent classes so should be used with care. */ const struct ListBase *RNA_struct_type_properties(StructRNA *srna) { return &srna->cont.properties; @@ -837,10 +813,6 @@ PropertyRNA *RNA_struct_type_find_property_no_base(StructRNA *srna, const char * return BLI_findstring_ptr(&srna->cont.properties, identifier, offsetof(PropertyRNA, identifier)); } -/** - * \note #RNA_struct_find_property is a higher level alternative to this function - * which takes a #PointerRNA instead of a #StructRNA. - */ PropertyRNA *RNA_struct_type_find_property(StructRNA *srna, const char *identifier) { for (; srna; srna = srna->base) { @@ -953,9 +925,6 @@ char *RNA_struct_name_get_alloc(PointerRNA *ptr, char *fixedbuf, int fixedlen, i return NULL; } -/** - * Use when registering structs with the #STRUCT_PUBLIC_NAMESPACE flag. - */ bool RNA_struct_available_or_report(ReportList *reports, const char *identifier) { const StructRNA *srna_exists = RNA_struct_find(identifier); @@ -1098,12 +1067,6 @@ int RNA_property_flag(PropertyRNA *prop) return rna_ensure_property(prop)->flag; } -/** - * Get the tags set for \a prop as int bitfield. - * \note Doesn't perform any validity check on the set bits. #RNA_def_property_tags does this - * in debug builds (to avoid performance issues in non-debug builds), which should be - * the only way to set tags. Hence, at this point we assume the tag bitfield to be valid. - */ int RNA_property_tags(PropertyRNA *prop) { return rna_ensure_property(prop)->tags; @@ -1129,7 +1092,6 @@ bool RNA_property_array_check(PropertyRNA *prop) return rna_ensure_property_array_check(prop); } -/* used by BPY to make an array from the python object */ int RNA_property_array_dimension(PointerRNA *ptr, PropertyRNA *prop, int length[]) { PropertyRNA *rprop = rna_ensure_property(prop); @@ -1141,7 +1103,6 @@ int RNA_property_array_dimension(PointerRNA *ptr, PropertyRNA *prop, int length[ return rprop->arraydimension; } -/* Return the size of Nth dimension. */ int RNA_property_multi_array_length(PointerRNA *ptr, PropertyRNA *prop, int dim) { int len[RNA_MAX_ARRAY_DIMENSION]; @@ -1445,9 +1406,6 @@ int RNA_property_int_clamp(PointerRNA *ptr, PropertyRNA *prop, int *value) return 0; } -/** - * \return the maximum length including the \0 terminator. '0' is used when there is no maximum. - */ int RNA_property_string_maxlength(PropertyRNA *prop) { StringPropertyRNA *sprop = (StringPropertyRNA *)rna_ensure_property(prop); @@ -1774,10 +1732,6 @@ int RNA_enum_from_identifier(const EnumPropertyItem *item, const char *identifie return -1; } -/** - * Take care using this with translated enums, - * prefer #RNA_enum_from_identifier where possible. - */ int RNA_enum_from_name(const EnumPropertyItem *item, const char *name) { int i = 0; @@ -1973,10 +1927,6 @@ bool RNA_property_editable(PointerRNA *ptr, PropertyRNA *prop_orig) (!ID_IS_OVERRIDE_LIBRARY(id) || RNA_property_overridable_get(ptr, prop_orig))))); } -/** - * Version of #RNA_property_editable that tries to return additional info in \a r_info - * that can be exposed in UI. - */ bool RNA_property_editable_info(PointerRNA *ptr, PropertyRNA *prop, const char **r_info) { ID *id = ptr->owner_id; @@ -2027,7 +1977,6 @@ bool RNA_property_editable_flag(PointerRNA *ptr, PropertyRNA *prop) return (flag & PROP_EDITABLE) != 0; } -/* same as RNA_property_editable(), except this checks individual items in an array */ bool RNA_property_editable_index(PointerRNA *ptr, PropertyRNA *prop, int index) { ID *id; @@ -2090,8 +2039,6 @@ bool RNA_property_animated(PointerRNA *ptr, PropertyRNA *prop) return false; } -/* this function is to check if its possible to create a valid path from the ID - * its slow so don't call in a loop */ bool RNA_property_path_from_ID_check(PointerRNA *ptr, PropertyRNA *prop) { char *path = RNA_path_from_ID_to_property(ptr, prop); @@ -2194,11 +2141,9 @@ static void rna_property_update( } } -/* must keep in sync with 'rna_property_update' - * NOTE: its possible this returns a false positive in the case of #PROP_CONTEXT_UPDATE - * but this isn't likely to be a performance problem. */ bool RNA_property_update_check(PropertyRNA *prop) { + /* NOTE: must keep in sync with #rna_property_update. */ return (prop->magic != RNA_MAGIC || prop->update || prop->noteflag); } @@ -2207,7 +2152,6 @@ void RNA_property_update(bContext *C, PointerRNA *ptr, PropertyRNA *prop) rna_property_update(C, CTX_data_main(C), CTX_data_scene(C), ptr, prop); } -/* NOTE: `scene` pointer may be NULL. */ void RNA_property_update_main(Main *bmain, Scene *scene, PointerRNA *ptr, PropertyRNA *prop) { rna_property_update(NULL, bmain, scene, ptr, prop); @@ -3277,7 +3221,6 @@ char *RNA_property_string_get_alloc( return buf; } -/* this is the length without \0 terminator */ int RNA_property_string_length(PointerRNA *ptr, PropertyRNA *prop) { StringPropertyRNA *sprop = (StringPropertyRNA *)prop; @@ -3417,7 +3360,6 @@ char *RNA_property_string_get_default_alloc( return buf; } -/* this is the length without \0 terminator */ int RNA_property_string_default_length(PointerRNA *UNUSED(ptr), PropertyRNA *prop) { StringPropertyRNA *sprop = (StringPropertyRNA *)rna_ensure_property(prop); @@ -3498,13 +3440,6 @@ int RNA_property_enum_get_default(PointerRNA *UNUSED(ptr), PropertyRNA *prop) return eprop->defaultvalue; } -/** - * Get the value of the item that is \a step items away from \a from_value. - * - * \param from_value: Item value to start stepping from. - * \param step: Absolute value defines step size, sign defines direction. - * E.g to get the next item, pass 1, for the previous -1. - */ int RNA_property_enum_step( const bContext *C, PointerRNA *ptr, PropertyRNA *prop, int from_value, int step) { @@ -4212,7 +4147,6 @@ int RNA_property_collection_lookup_string(PointerRNA *ptr, return RNA_property_collection_lookup_string_index(ptr, prop, key, r_ptr, &index); } -/* zero return is an assignment error */ int RNA_property_collection_assign_int(PointerRNA *ptr, PropertyRNA *prop, const int key, @@ -5326,17 +5260,6 @@ static bool rna_path_parse(PointerRNA *ptr, return true; } -/** - * Resolve the given RNA Path to find the pointer and/or property - * indicated by fully resolving the path. - * - * \warning Unlike \a RNA_path_resolve_property(), that one *will* try to follow RNAPointers, - * e.g. the path 'parent' applied to a RNAObject \a ptr will return the object.parent in \a r_ptr, - * and a NULL \a r_prop... - * - * \note Assumes all pointers provided are valid - * \return True if path can be resolved to a valid "pointer + property" OR "pointer only" - */ bool RNA_path_resolve(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop) { if (!rna_path_parse(ptr, path, r_ptr, r_prop, NULL, NULL, NULL, true)) { @@ -5346,13 +5269,6 @@ bool RNA_path_resolve(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, Prop return r_ptr->data != NULL; } -/** - * Resolve the given RNA Path to find the pointer and/or property + array index - * indicated by fully resolving the path. - * - * \note Assumes all pointers provided are valid. - * \return True if path can be resolved to a valid "pointer + property" OR "pointer only" - */ bool RNA_path_resolve_full( PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index) { @@ -5363,26 +5279,12 @@ bool RNA_path_resolve_full( return r_ptr->data != NULL; } -/** - * A version of #RNA_path_resolve_full doesn't check the value of #PointerRNA.data. - * - * \note While it's correct to ignore the value of #PointerRNA.data - * most callers need to know if the resulting pointer was found and not null. - */ bool RNA_path_resolve_full_maybe_null( PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index) { return rna_path_parse(ptr, path, r_ptr, r_prop, r_index, NULL, NULL, true); } -/** - * Resolve the given RNA Path to find both the pointer AND property - * indicated by fully resolving the path. - * - * This is a convenience method to avoid logic errors and ugly syntax. - * \note Assumes all pointers provided are valid - * \return True only if both a valid pointer and property are found after resolving the path - */ bool RNA_path_resolve_property(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, @@ -5395,14 +5297,6 @@ bool RNA_path_resolve_property(PointerRNA *ptr, return r_ptr->data != NULL && *r_prop != NULL; } -/** - * Resolve the given RNA Path to find the pointer AND property (as well as the array index) - * indicated by fully resolving the path. - * - * This is a convenience method to avoid logic errors and ugly syntax. - * \note Assumes all pointers provided are valid - * \return True only if both a valid pointer and property are found after resolving the path - */ bool RNA_path_resolve_property_full( PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index) { @@ -5413,18 +5307,6 @@ bool RNA_path_resolve_property_full( return r_ptr->data != NULL && *r_prop != NULL; } -/** - * Resolve the given RNA Path to find both the pointer AND property - * indicated by fully resolving the path, and get the value of the Pointer property - * (or item of the collection). - * - * This is a convenience method to avoid logic errors and ugly syntax, - * it combines both \a RNA_path_resolve and #RNA_path_resolve_property in a single call. - * \note Assumes all pointers provided are valid. - * \param r_item_ptr: The final Pointer or Collection item value. - * You must check for its validity before use! - * \return True only if both a valid pointer and property are found after resolving the path - */ bool RNA_path_resolve_property_and_item_pointer(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, @@ -5438,19 +5320,6 @@ bool RNA_path_resolve_property_and_item_pointer(PointerRNA *ptr, return r_ptr->data != NULL && *r_prop != NULL; } -/** - * Resolve the given RNA Path to find both the pointer AND property (as well as the array index) - * indicated by fully resolving the path, - * and get the value of the Pointer property (or item of the collection). - * - * This is a convenience method to avoid logic errors and ugly syntax, - * it combines both \a RNA_path_resolve_full and - * \a RNA_path_resolve_property_full in a single call. - * \note Assumes all pointers provided are valid. - * \param r_item_ptr: The final Pointer or Collection item value. - * You must check for its validity before use! - * \return True only if both a valid pointer and property are found after resolving the path - */ bool RNA_path_resolve_property_and_item_pointer_full(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, @@ -5464,15 +5333,6 @@ bool RNA_path_resolve_property_and_item_pointer_full(PointerRNA *ptr, return r_ptr->data != NULL && *r_prop != NULL; } -/** - * Resolve the given RNA Path into a linked list of PropertyElemRNA's. - * - * To be used when complex operations over path are needed, like e.g. get relative paths, - * to avoid too much string operations. - * - * \return True if there was no error while resolving the path - * \note Assumes all pointers provided are valid - */ bool RNA_path_resolve_elements(PointerRNA *ptr, const char *path, ListBase *r_elements) { return rna_path_parse(ptr, path, NULL, NULL, NULL, NULL, r_elements, false); @@ -5723,16 +5583,6 @@ static char *rna_idp_path(PointerRNA *ptr, return path; } -/** - * Find the path from the structure referenced by the pointer to the runtime RNA-defined - * #IDProperty object. - * - * \note Does *not* handle pure user-defined IDProperties (a.k.a. custom properties). - * - * \param ptr: Reference to the object owning the custom property storage. - * \param needle: Custom property object to find. - * \return Relative path or NULL. - */ char *RNA_path_from_struct_to_idproperty(PointerRNA *ptr, IDProperty *needle) { IDProperty *haystack = RNA_struct_idprops(ptr, false); @@ -5759,13 +5609,6 @@ static char *rna_path_from_ID_to_idpgroup(const PointerRNA *ptr) return RNA_path_from_struct_to_idproperty(&id_ptr, ptr->data); } -/** - * Find the actual ID pointer and path from it to the given ID. - * - * \param id: ID reference to search the global owner for. - * \param[out] r_path: Path from the real ID to the initial ID. - * \return The ID pointer, or NULL in case of failure. - */ ID *RNA_find_real_ID_and_path(Main *bmain, ID *id, const char **r_path) { if (r_path) { @@ -5918,11 +5761,6 @@ static void rna_path_array_multi_string_from_flat_index(PointerRNA *ptr, } } -/** - * \param index_dim: The dimension to show, 0 disables. 1 for 1d array, 2 for 2d. etc. - * \param index: The *flattened* index to use when \a `index_dim > 0`, - * this is expanded when used with multi-dimensional arrays. - */ char *RNA_path_from_ID_to_property_index(PointerRNA *ptr, PropertyRNA *prop, int index_dim, @@ -5994,10 +5832,6 @@ char *RNA_path_from_real_ID_to_property_index( return path != NULL ? rna_prepend_real_ID_path(bmain, ptr->owner_id, path, r_real_id) : NULL; } -/** - * \return the path to given ptr/prop from the closest ancestor of given type, - * if any (else return NULL). - */ char *RNA_path_resolve_from_type_to_property(PointerRNA *ptr, PropertyRNA *prop, const StructRNA *type) @@ -6036,10 +5870,6 @@ char *RNA_path_resolve_from_type_to_property(PointerRNA *ptr, return path; } -/** - * Get the ID as a python representation, eg: - * bpy.data.foo["bar"] - */ char *RNA_path_full_ID_py(Main *bmain, ID *id) { const char *path; @@ -6075,10 +5905,6 @@ char *RNA_path_full_ID_py(Main *bmain, ID *id) path); } -/** - * Get the ID.struct as a python representation, eg: - * bpy.data.foo["bar"].some_struct - */ char *RNA_path_full_struct_py(Main *bmain, struct PointerRNA *ptr) { char *id_path; @@ -6107,10 +5933,6 @@ char *RNA_path_full_struct_py(Main *bmain, struct PointerRNA *ptr) return ret; } -/** - * Get the ID.struct.property as a python representation, eg: - * bpy.data.foo["bar"].some_struct.some_prop[10] - */ char *RNA_path_full_property_py_ex( Main *bmain, PointerRNA *ptr, PropertyRNA *prop, int index, bool use_fallback) { @@ -6164,10 +5986,6 @@ char *RNA_path_full_property_py(Main *bmain, PointerRNA *ptr, PropertyRNA *prop, return RNA_path_full_property_py_ex(bmain, ptr, prop, index, false); } -/** - * Get the struct.property as a python representation, eg: - * some_struct.some_prop[10] - */ char *RNA_path_struct_property_py(PointerRNA *ptr, PropertyRNA *prop, int index) { char *data_path; @@ -6205,10 +6023,6 @@ char *RNA_path_struct_property_py(PointerRNA *ptr, PropertyRNA *prop, int index) return ret; } -/** - * Get the struct.property as a python representation, eg: - * some_prop[10] - */ char *RNA_path_property_py(const PointerRNA *UNUSED(ptr), PropertyRNA *prop, int index) { char *ret; @@ -6678,7 +6492,6 @@ bool RNA_property_is_idprop(const PropertyRNA *prop) return (prop->magic != RNA_MAGIC); } -/* mainly for the UI */ bool RNA_property_is_unlink(PropertyRNA *prop) { const int flag = RNA_property_flag(prop); @@ -6688,9 +6501,6 @@ bool RNA_property_is_unlink(PropertyRNA *prop) return (flag & (PROP_NEVER_UNLINK | PROP_NEVER_NULL)) == 0; } -/* string representation of a property, python - * compatible but can be used for display too, - * context may be NULL */ char *RNA_pointer_as_string_id(bContext *C, PointerRNA *ptr) { DynStr *dynstr = BLI_dynstr_new(); @@ -6752,7 +6562,6 @@ char *RNA_pointer_as_string(bContext *C, return rna_pointer_as_string__bldata(CTX_data_main(C), ptr_prop); } -/* context can be NULL */ char *RNA_pointer_as_string_keywords_ex(bContext *C, PointerRNA *ptr, const bool as_function, @@ -8115,7 +7924,6 @@ bool RNA_property_assign_default(PointerRNA *ptr, PropertyRNA *prop) } } -/* use RNA_warning macro which includes __func__ suffix */ void _RNA_warning(const char *format, ...) { va_list args; diff --git a/source/blender/makesrna/intern/rna_access_compare_override.c b/source/blender/makesrna/intern/rna_access_compare_override.c index 6ac44ae6121..8cc6a095c1d 100644 --- a/source/blender/makesrna/intern/rna_access_compare_override.c +++ b/source/blender/makesrna/intern/rna_access_compare_override.c @@ -126,8 +126,6 @@ int RNA_property_override_flag(PropertyRNA *prop) return rna_ensure_property(prop)->flag_override; } -/** \note Does not take into account editable status, this has to be checked separately - * (using #RNA_property_editable_flag() usually). */ bool RNA_property_overridable_get(PointerRNA *ptr, PropertyRNA *prop) { if (prop->magic == RNA_MAGIC) { @@ -170,7 +168,6 @@ bool RNA_property_overridable_get(PointerRNA *ptr, PropertyRNA *prop) return (idprop->flag & IDP_FLAG_OVERRIDABLE_LIBRARY) != 0; } -/* Should only be used for custom properties */ bool RNA_property_overridable_library_set(PointerRNA *UNUSED(ptr), PropertyRNA *prop, const bool is_overridable) @@ -635,16 +632,6 @@ static bool rna_property_override_operation_apply(Main *bmain, return success; } -/** - * Check whether reference and local overridden data match (are the same), - * with respect to given restrictive sets of properties. - * If requested, will generate needed new property overrides, and/or restore values from reference. - * - * \param r_report_flags: If given, - * will be set with flags matching actions taken by the function on \a ptr_local. - * - * \return True if _resulting_ \a ptr_local does match \a ptr_reference. - */ bool RNA_struct_override_matches(Main *bmain, PointerRNA *ptr_local, PointerRNA *ptr_reference, @@ -928,10 +915,6 @@ bool RNA_struct_override_matches(Main *bmain, return matching; } -/** - * Store needed second operands into \a storage data-block - * for differential override operations. - */ bool RNA_struct_override_store(Main *bmain, PointerRNA *ptr_local, PointerRNA *ptr_reference, @@ -1195,10 +1178,6 @@ static void rna_property_override_apply_ex(Main *bmain, } } -/** - * Apply given \a override operations on \a ptr_dst, using \a ptr_src - * (and \a ptr_storage for differential ops) as source. - */ void RNA_struct_override_apply(Main *bmain, PointerRNA *ptr_dst, PointerRNA *ptr_src, diff --git a/source/blender/makesrna/intern/rna_access_internal.h b/source/blender/makesrna/intern/rna_access_internal.h index 73407123863..9f1be5bbd67 100644 --- a/source/blender/makesrna/intern/rna_access_internal.h +++ b/source/blender/makesrna/intern/rna_access_internal.h @@ -27,6 +27,13 @@ struct IDProperty; struct PropertyRNAOrID; +/** + * This function initializes a #PropertyRNAOrID with all required info, from a given #PropertyRNA + * and #PointerRNA data. It deals properly with the three cases + * (static RNA, runtime RNA, and #IDProperty). + * \warning given `ptr` #PointerRNA is assumed to be a valid data one here, calling code is + * responsible to ensure that. + */ void rna_property_rna_or_id_get(PropertyRNA *prop, PointerRNA *ptr, PropertyRNAOrID *r_prop_rna_or_id); diff --git a/source/blender/makesrna/intern/rna_armature.c b/source/blender/makesrna/intern/rna_armature.c index 690506fa517..7a934443907 100644 --- a/source/blender/makesrna/intern/rna_armature.c +++ b/source/blender/makesrna/intern/rna_armature.c @@ -669,10 +669,10 @@ static void rna_Armature_transform(bArmature *arm, float mat[16]) #else -/* Settings for curved bbone settings - - * The posemode values get applied over the top of the editmode ones. */ void rna_def_bone_curved_common(StructRNA *srna, bool is_posebone, bool is_editbone) { + /* NOTE: The pose-mode values get applied over the top of the edit-mode ones. */ + # define RNA_DEF_CURVEBONE_UPDATE(prop, is_posebone, is_editbone) \ { \ if (is_posebone) { \ diff --git a/source/blender/makesrna/intern/rna_asset.c b/source/blender/makesrna/intern/rna_asset.c index 0d25a0ba079..e79cbc838d4 100644 --- a/source/blender/makesrna/intern/rna_asset.c +++ b/source/blender/makesrna/intern/rna_asset.c @@ -493,9 +493,6 @@ static void rna_def_asset_library_reference(BlenderRNA *brna) srna, "Asset Library Reference", "Identifier to refer to the asset library"); } -/** - * \note the UI text and updating has to be set by the caller. - */ PropertyRNA *rna_def_asset_library_reference_common(struct StructRNA *srna, const char *get, const char *set) diff --git a/source/blender/makesrna/intern/rna_constraint.c b/source/blender/makesrna/intern/rna_constraint.c index bde348c1848..0c993660f39 100644 --- a/source/blender/makesrna/intern/rna_constraint.c +++ b/source/blender/makesrna/intern/rna_constraint.c @@ -3446,7 +3446,8 @@ static void rna_def_constraint_transform_cache(BlenderRNA *brna) RNA_define_lib_overridable(false); } -/* base struct for constraints */ +/* Define the base struct for constraints. */ + void RNA_def_constraint(BlenderRNA *brna) { StructRNA *srna; diff --git a/source/blender/makesrna/intern/rna_define.c b/source/blender/makesrna/intern/rna_define.c index bd5ade36eaa..b17ca7d8d59 100644 --- a/source/blender/makesrna/intern/rna_define.c +++ b/source/blender/makesrna/intern/rna_define.c @@ -753,10 +753,6 @@ void RNA_define_verify_sdna(bool verify) DefRNA.verify = verify; } -/** - * Properties defined when this is enabled are lib-overridable by default (except for Pointer - * ones). - */ void RNA_define_lib_overridable(const bool make_overridable) { DefRNA.make_overridable = make_overridable; @@ -915,7 +911,6 @@ static StructDefRNA *rna_find_def_struct(StructRNA *srna) return NULL; } -/* Struct Definition */ StructRNA *RNA_def_struct_ptr(BlenderRNA *brna, const char *identifier, StructRNA *srnafrom) { StructRNA *srna; @@ -1243,9 +1238,6 @@ void RNA_def_struct_identifier(BlenderRNA *brna, StructRNA *srna, const char *id srna->identifier = identifier; } -/** - * Only used in one case when we name the struct for the purpose of useful error messages. - */ void RNA_def_struct_identifier_no_struct_map(StructRNA *srna, const char *identifier) { if (DefRNA.preprocess) { @@ -1532,13 +1524,6 @@ void RNA_def_property_override_clear_flag(PropertyRNA *prop, PropertyOverrideFla prop->flag_override &= ~flag; } -/** - * Add the property-tags passed as \a tags to \a prop (if valid). - * - * \note Multiple tags can be set by passing them within \a tags (using bitflags). - * \note Doesn't do any type-checking with the tags defined in the parent StructRNA - * of \a prop. This should be done before (e.g. see #WM_operatortype_prop_tag). - */ void RNA_def_property_tags(PropertyRNA *prop, int tags) { prop->tags |= tags; @@ -1616,12 +1601,10 @@ void RNA_def_property_array(PropertyRNA *prop, int length) } } -/* common args for defaults. */ const float rna_default_quaternion[4] = {1, 0, 0, 0}; const float rna_default_axis_angle[4] = {0, 0, 1, 0}; const float rna_default_scale_3d[3] = {1, 1, 1}; -/* common args for length */ const int rna_matrix_dimsize_3x3[] = {3, 3}; const int rna_matrix_dimsize_4x4[] = {4, 4}; const int rna_matrix_dimsize_4x2[] = {4, 2}; @@ -1692,17 +1675,6 @@ void RNA_def_property_ui_icon(PropertyRNA *prop, int icon, int consecutive) } } -/** - * The values hare are a little confusing: - * - * \param step: Used as the value to increase/decrease when clicking on number buttons, - * as well as scaling mouse input for click-dragging number buttons. - * For floats this is (step * UI_PRECISION_FLOAT_SCALE), why? - nobody knows. - * For ints, whole values are used. - * - * \param precision: The number of zeros to show - * (as a whole number - common range is 1 - 6), see UI_PRECISION_FLOAT_MAX - */ void RNA_def_property_ui_range( PropertyRNA *prop, double min, double max, double step, int precision) { @@ -2082,7 +2054,6 @@ void RNA_def_property_float_default(PropertyRNA *prop, float value) break; } } -/* array must remain valid after this function finishes */ void RNA_def_property_float_array_default(PropertyRNA *prop, const float *array) { StructRNA *srna = DefRNA.laststruct; @@ -2920,11 +2891,6 @@ void RNA_def_property_editable_array_func(PropertyRNA *prop, const char *editabl } } -/** - * Set custom callbacks for override operations handling. - * - * \note \a diff callback will also be used by RNA comparison/equality functions. - */ void RNA_def_property_override_funcs(PropertyRNA *prop, const char *diff, const char *store, @@ -3813,7 +3779,6 @@ PropertyRNA *RNA_def_enum(StructOrFunctionRNA *cont_, return prop; } -/* same as above but sets 'PROP_ENUM_FLAG' before setting the default value */ PropertyRNA *RNA_def_enum_flag(StructOrFunctionRNA *cont_, const char *identifier, const EnumPropertyItem *items, @@ -4320,7 +4285,6 @@ FunctionRNA *RNA_def_function_runtime(StructRNA *srna, const char *identifier, C return func; } -/* C return value only!, multiple RNA returns can be done with RNA_def_function_output */ void RNA_def_function_return(FunctionRNA *func, PropertyRNA *ret) { if (ret->flag & PROP_DYNAMIC) { diff --git a/source/blender/makesrna/intern/rna_internal.h b/source/blender/makesrna/intern/rna_internal.h index fd6664ff0de..c1989a5b10d 100644 --- a/source/blender/makesrna/intern/rna_internal.h +++ b/source/blender/makesrna/intern/rna_internal.h @@ -251,6 +251,9 @@ bool rna_AnimaData_override_apply(struct Main *bmain, void rna_def_animviz_common(struct StructRNA *srna); void rna_def_motionpath_common(struct StructRNA *srna); +/** + * Settings for curved bbone settings. + */ void rna_def_bone_curved_common(struct StructRNA *srna, bool is_posebone, bool is_editbone); void rna_def_texmat_common(struct StructRNA *srna, const char *texspace_editable); @@ -268,6 +271,9 @@ void rna_def_texpaint_slots(struct BlenderRNA *brna, struct StructRNA *srna); void rna_def_view_layer_common(struct BlenderRNA *brna, struct StructRNA *srna, const bool scene); int rna_AssetMetaData_editable(struct PointerRNA *ptr, const char **r_info); +/** + * \note the UI text and updating has to be set by the caller. + */ PropertyRNA *rna_def_asset_library_reference_common(struct StructRNA *srna, const char *get, const char *set); @@ -276,6 +282,9 @@ const EnumPropertyItem *rna_asset_library_reference_itemf(struct bContext *C, struct PropertyRNA *prop, bool *r_free); +/** + * Common properties for Action/Bone Groups - related to color. + */ void rna_def_actionbone_group_common(struct StructRNA *srna, int update_flag, const char *update_cb); @@ -509,8 +518,16 @@ extern StructRNA RNA_PropertyGroupItem; extern StructRNA RNA_PropertyGroup; #endif +/** + * This function only returns an #IDProperty, + * or NULL (in case IDProp could not be found, or prop is a real RNA property). + */ struct IDProperty *rna_idproperty_check(struct PropertyRNA **prop, struct PointerRNA *ptr) ATTR_WARN_UNUSED_RESULT; +/** + * This function always return the valid, real data pointer, be it a regular RNA property one, + * or an #IDProperty one. + */ struct PropertyRNA *rna_ensure_property_realdata(struct PropertyRNA **prop, struct PointerRNA *ptr) ATTR_WARN_UNUSED_RESULT; struct PropertyRNA *rna_ensure_property(struct PropertyRNA *prop) ATTR_WARN_UNUSED_RESULT; diff --git a/source/blender/makesrna/intern/rna_pose.c b/source/blender/makesrna/intern/rna_pose.c index 87173adc38f..76bfea00a79 100644 --- a/source/blender/makesrna/intern/rna_pose.c +++ b/source/blender/makesrna/intern/rna_pose.c @@ -869,7 +869,6 @@ static void rna_PoseChannel_custom_shape_transform_set(PointerRNA *ptr, #else -/* common properties for Action/Bone Groups - related to color */ void rna_def_actionbone_group_common(StructRNA *srna, int update_flag, const char *update_cb) { PropertyRNA *prop; diff --git a/source/blender/makesrna/intern/rna_wm.c b/source/blender/makesrna/intern/rna_wm.c index 1cb1397a0ed..8c128292fd7 100644 --- a/source/blender/makesrna/intern/rna_wm.c +++ b/source/blender/makesrna/intern/rna_wm.c @@ -142,9 +142,10 @@ static const EnumPropertyItem event_ndof_type_items[] = { }; #endif /* RNA_RUNTIME */ -/* not returned: CAPSLOCKKEY, UNKNOWNKEY */ const EnumPropertyItem rna_enum_event_type_items[] = { - /* Note we abuse 'tooltip' message here to store a 'compact' form of some (too) long names. */ + /* - Note we abuse 'tooltip' message here to store a 'compact' form of some (too) long names. + * - Intentionally excluded: #CAPSLOCKKEY, #UNKNOWNKEY. + */ {0, "NONE", 0, "", ""}, {LEFTMOUSE, "LEFTMOUSE", 0, "Left Mouse", "LMB"}, {MIDDLEMOUSE, "MIDDLEMOUSE", 0, "Middle Mouse", "MMB"}, |