Blender V5.3
versioning.cc
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2024 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
8
9/* This is versioning code, so it's allowed to touch on deprecated DNA fields. */
10
11#define DNA_DEPRECATED_ALLOW
12
13#include "ANIM_action.hh"
15#include "ANIM_action_legacy.hh"
16#include "ANIM_versioning.hh"
17
18#include "DNA_action_types.h"
19
20#include "BKE_lib_id.hh"
21#include "BKE_main.hh"
22#include "BKE_nla.hh"
23#include "BKE_node.hh"
24#include "BKE_report.hh"
25
26#include "BLI_listbase.hh"
27#include "BLI_string_utf8.hh"
28
29#include "BLT_translation.hh"
30
31#include "BLO_readfile.hh"
32
33#include "RNA_access.hh"
34#include "RNA_prototypes.hh"
35
37
38bool action_is_layered(const bAction &dna_action)
39{
40 /* NOTE: due to how forward-compatibility is handled when writing Actions to
41 * blend files, it is important that this function does NOT check
42 * `Action.idroot` as part of its determination of whether this is a layered
43 * action or not.
44 *
45 * See: `action_blend_write()` and `action_blend_read_data()`
46 */
47
48 const animrig::Action &action = dna_action.wrap();
49
50 const bool has_layered_data = action.layer_array_num > 0 || action.slot_array_num > 0;
51 const bool has_animato_data = !(action.curves.is_empty() && action.groups.is_empty());
52
53 return has_layered_data || !has_animato_data;
54}
55
57{
58 for (bAction &dna_action : bmain.actions) {
59 animrig::Action &action = dna_action.wrap();
60
61 if (action_is_layered(action) && !action.is_empty()) {
62 /* This is just a safety net. Blender files that trigger this versioning code are not
63 * expected to have any layered/slotted Actions.
64 *
65 * Empty Actions, even though they are valid "layered" Actions, should still get through
66 * versioning, though, to ensure they have the default "Legacy Slot" and a zero idroot. */
67 continue;
68 }
69
71 }
72}
73
75{
76 Action &action = dna_action.wrap();
77 /* Check that this is a legacy action.
78 * Cannot use `!action_is_layered` because that would be false on empty actions. */
79 BLI_assert(action.layer_array_num == 0 && action.slot_array_num == 0);
80
81 /* Store this ahead of time, because adding the slot sets the action's idroot
82 * to 0. We also set the action's idroot to 0 manually, just to be defensive
83 * so we don't depend on esoteric behavior in `slot_add()`. */
84 const int16_t idtype = action.idroot;
85 action.idroot = 0;
86
87 /* Initialize the Action's last_slot_handle field to its default value, before
88 * we create a new slot. */
90
91 Slot &slot = action.slot_add();
92 slot.idtype = idtype;
93
94 const std::string slot_identifier{slot.idtype_string() +
96 action.slot_identifier_define(slot, slot_identifier);
97
99 animrig::Strip &strip = layer.strip_add(action, animrig::Strip::Type::Keyframe);
100 Channelbag &bag = strip.data<StripKeyframeData>(action).channelbag_for_slot_ensure(slot);
101 const int fcu_count = action.curves.count();
102 const int group_count = action.groups.count();
103 bag.fcurve_array = MEM_new_array_zeroed<FCurve *>(fcu_count, "Action versioning - fcurves");
104 bag.fcurve_array_num = fcu_count;
106 "Action versioning - groups");
107 bag.group_array_num = group_count;
108
109 int fcurve_index = 0;
110 for (const auto [group_index, group] : action.groups.enumerate()) {
111 bag.group_array[group_index] = &group;
112
113 group.channelbag = &bag;
114 group.fcurve_range_start = fcurve_index;
115
116 for (FCurve &fcu : group.channels) {
117 if (fcu.grp != &group) {
118 break;
119 }
120 bag.fcurve_array[fcurve_index++] = &fcu;
121 }
122
123 group.fcurve_range_length = fcurve_index - group.fcurve_range_start;
124 }
125
126 for (FCurve &fcu : action.curves) {
127 /* Any fcurves with groups have already been added to the fcurve array. */
128 if (fcu.grp) {
129 continue;
130 }
131 bag.fcurve_array[fcurve_index++] = &fcu;
132 }
133
134 BLI_assert(fcurve_index == fcu_count);
135
136 action.curves = {nullptr, nullptr};
137 action.groups = {nullptr, nullptr};
138}
139
144
146{
147 /* This function is only called when the blend-file is old enough to NOT use
148 * slotted Actions, so we can safely tag anything that uses an Action. */
149
150 auto flag_adt = [](ID &animated_id,
151 bAction *& /*action_ptr_ref*/,
152 slot_handle_t & /*slot_handle_ref*/,
153 char * /*last_slot_identifier*/) -> bool {
155
156 /* Once tagged, the foreach loop can stop, because more tagging of the same
157 * ID doesn't do anything. */
158 return false;
159 };
160
161 ID *id;
162 FOREACH_MAIN_ID_BEGIN (&bmain, id) {
164
165 /* Process embedded IDs, as these are not listed in bmain, but still can
166 * have their own Action+Slot. Unfortunately there is no generic looper
167 * for embedded IDs. At this moment the only animatable embedded ID is a
168 * node tree. */
169 bNodeTree *node_tree = bke::node_tree_from_id(id);
170 if (node_tree) {
171 foreach_action_slot_use_with_references(node_tree->id, flag_adt);
172 }
173 }
175}
176
178{
179 auto version_slot_assignment = [&](ID &animated_id,
180 bAction *dna_action,
181 PointerRNA &action_slot_owner_ptr,
182 PropertyRNA &action_slot_prop,
183 char *last_used_slot_identifier) {
184 BLI_assert(dna_action); /* Ensured by the foreach loop. */
185 Action &action = dna_action->wrap();
186
187 if (action.slot_array_num == 0) {
188 /* There's a few reasons why this Action doesn't have a slot. It could simply be a slotted
189 * Action without slots, or a legacy-but-not-yet-versioned Action, or it could be it is a
190 * _really_ old (pre-2.50) Action. The latter are upgraded in do_versions_after_setup(), but
191 * this function can be called earlier than that. So better gracefully skip those. */
192 return true;
193 }
194
195 /* If there is already a slot assigned, there's nothing to do here. */
196 PointerRNA current_slot_ptr = RNA_property_pointer_get(&action_slot_owner_ptr,
197 &action_slot_prop);
198 if (current_slot_ptr) {
199 return true;
200 }
201
202 /* Reset the "last used slot identifier" to the default "Legacy Slot". That way
203 * generic_slot_for_autoassign() will pick up on legacy slots automatically.
204 *
205 * Note that this function should only run on legacy users of Actions, i.e. they are not
206 * expected to have any last-used slot at all. The field in DNA can still be set, though,
207 * because the 4.3 code already has the data model for slotted Actions. */
208
209 /* Ensure that the identifier has the correct ID type prefix. */
210 *reinterpret_cast<short *>(last_used_slot_identifier) = GS(animated_id.name);
211
212 static_assert(Slot::identifier_length_max > 2); /* Because of the -2 below. */
213 BLI_strncpy_utf8(last_used_slot_identifier + 2,
216
217 Slot *slot_to_assign = generic_slot_for_autoassign(
218 animated_id, action, last_used_slot_identifier);
219 if (!slot_to_assign) {
220 /* This means that there is no slot that can be found by name, not even the "Legacy Slot"
221 * name. Keep the ID unanimated, as this means that the referenced Action has changed
222 * significantly since this file was opened. */
223 BKE_reportf(reports,
225 "\"%s\" is using Action \"%s\", which does not have a slot with identifier "
226 "\"%s\" or \"%s\". Manually assign the right action slot to \"%s\".\n",
227 animated_id.name,
228 action.id.name + 2,
229 last_used_slot_identifier,
230 animated_id.name,
231 animated_id.name + 2);
232 return true;
233 }
234
235 PointerRNA slot_to_assign_ptr = RNA_pointer_create_discrete(
236 &action.id, RNA_ActionSlot, slot_to_assign);
238 &action_slot_owner_ptr, &action_slot_prop, slot_to_assign_ptr, reports);
239 RNA_property_update_main(&bmain, nullptr, &action_slot_owner_ptr, &action_slot_prop);
240
241 return true;
242 };
243
244 /* Note that the code below does not remove the `action_assignment_needs_slot` tag. One ID can
245 * use multiple Actions (via NLA, Action constraints, etc.); if one of those Action is a legacy
246 * one from a linked datablock, this ID may needs to be re-visited after the library file was
247 * versioned. Rather than trying to figure out if re-visiting is necessary, this function is safe
248 * to call multiple times, and all that's lost is a little bit of CPU time. */
249
250 ID *id;
251 FOREACH_MAIN_ID_BEGIN (&bmain, id) {
252 /* Process the ID itself. */
254 foreach_action_slot_use_with_rna(*id, version_slot_assignment);
255 }
256
257 /* Process embedded IDs, as these are not listed in bmain, but still can
258 * have their own Action+Slot. Unfortunately there is no generic looper
259 * for embedded IDs. At this moment the only animatable embedded ID is a
260 * node tree. */
261 bNodeTree *node_tree = bke::node_tree_from_id(id);
262 if (node_tree && BLO_readfile_id_runtime_tags(node_tree->id).action_assignment_needs_slot) {
263 foreach_action_slot_use_with_rna(node_tree->id, version_slot_assignment);
264 }
265 }
267}
268
270{
271 if (!act) {
272 return;
273 }
274 /* Check that this is a legacy action.
275 * Cannot use `!action_is_layered` because that would be false on empty actions. */
276 BLI_assert(act->layer_array_num == 0 && act->slot_array_num == 0);
277 /* Clear out all group channels. Channels that are actually in use are
278 * reconstructed below; this step is necessary to clear out unused groups. */
279 for (bActionGroup &group : act->groups) {
280 group.channels.clear_no_delete();
281 }
282 /* Sort the channels into the group lists, destroying the act->curves list. */
283 ListBaseT<FCurve> ungrouped = {nullptr, nullptr};
284 for (FCurve &fcurve : act->curves.items_mutable()) {
285 if (fcurve.grp) {
286 BLI_assert(BLI_findindex(&act->groups, fcurve.grp) >= 0);
287 BLI_addtail(&fcurve.grp->channels, &fcurve);
288 }
289 else {
290 BLI_addtail(&ungrouped, &fcurve);
291 }
292 }
293 /* Recombine into the main list. */
294 act->curves.clear_no_delete();
295 for (bActionGroup &group : act->groups) {
296 /* Copy the list header to preserve the pointers in the group. */
297 ListBase tmp = group.channels;
298 BLI_movelisttolist(&act->curves, &tmp);
299 }
300 BLI_movelisttolist(&act->curves, &ungrouped);
301}
302
304
311 ListBaseT<FCurve> *fcurves,
312 const IDFCurveCallback func)
313{
314 for (FCurve &fcu : *fcurves) {
315 if (!func(id, &fcu)) {
316 return false;
317 }
318 }
319 return true;
320}
321
322/* Helper for adt_apply_all_fcurves_cb() - Recursively go through each NLA strip */
324 ListBaseT<NlaStrip> *strips,
325 const IDFCurveCallback func)
326{
327 for (NlaStrip &strip : *strips) {
328 if (strip.act) {
329 if (!fcurves_listbase_apply_cb(id, &strip.act->curves, func)) {
330 return false;
331 }
332 }
333 if (!nlastrips_apply_all_curves_cb(id, &strip.strips, func)) {
334 return false;
335 }
336 }
337 return true;
338}
339
340static bool adt_apply_all_fcurves_cb(ID *id, AnimData *adt, const IDFCurveCallback func)
341{
342 if (adt->action) {
343 if (!fcurves_listbase_apply_cb(id, &adt->action->curves, func)) {
344 return false;
345 }
346 }
347
348 if (adt->tmpact) {
349 if (!fcurves_listbase_apply_cb(id, &adt->tmpact->curves, func)) {
350 return false;
351 }
352 }
353
354 /* Drivers, stored as a list of F-Curves. */
355 if (!fcurves_listbase_apply_cb(id, &adt->drivers, func)) {
356 return false;
357 }
358
359 /* NLA Data - Animation Data for Strips */
360 for (NlaTrack &nlt : adt->nla_tracks) {
361 if (!nlastrips_apply_all_curves_cb(id, &nlt.strips, func)) {
362 return false;
363 }
364 }
365 return true;
366}
367
368void fcurves_id_cb(ID *id, const FunctionRef<void(ID *, FCurve *)> func)
369{
371 if (adt != nullptr) {
372 /* Use a little wrapper function to always return 'true' and thus keep the loop looping. */
373 const auto wrapper = [&func](ID *id, FCurve *fcurve) {
374 func(id, fcurve);
375 return true;
376 };
377 adt_apply_all_fcurves_cb(id, adt, wrapper);
378 }
379}
380
381void fcurves_main_cb(Main *bmain, const FunctionRef<void(ID *, FCurve *)> func)
382{
383 /* Use a little wrapper function to always return 'true' and thus keep the loop looping. */
384 const auto wrapper = [&func](ID *id, FCurve *fcurve) {
385 func(id, fcurve);
386 return true;
387 };
388
389 /* Use the AnimData-based function so that we don't have to reimplement all that stuff */
391 [&](ID *id, AnimData *adt) { adt_apply_all_fcurves_cb(id, adt, wrapper); });
392}
393
395{
396 if (!action) {
397 return {};
398 }
399 Vector<FCurve *> fcurves;
400 for (FCurve &fcu : action->curves) {
401 fcurves.append(&fcu);
402 }
403 return fcurves;
404}
405
406} // namespace blender::animrig::versioning
Functions and classes to work with Actions.
Functionality to iterate an Action in various ways.
Functions for backward compatibility with the legacy Action API.
Versioning of old animation data. Most animation versioning code lives in the versioning_xxx....
#define FOREACH_MAIN_ID_END
Definition BKE_main.hh:735
#define FOREACH_MAIN_ID_BEGIN(_bmain, _id)
Definition BKE_main.hh:729
external readfile function prototypes.
#define DATA_(msgid)
#define DNA_DEFAULT_ACTION_LAST_SLOT_HANDLE
void append(const T &value)
void slot_identifier_define(Slot &slot, StringRefNull new_identifier)
Layer & layer_add(std::optional< StringRefNull > name)
std::string idtype_string() const
static constexpr int identifier_length_max
const T & data(const Action &owning_action) const
#define layer
constexpr const char * DEFAULT_LEGACY_LAYER_NAME
constexpr const char * DEFAULT_LEGACY_SLOT_NAME
void action_groups_reconstruct(bAction *act)
static bool adt_apply_all_fcurves_cb(ID *id, AnimData *adt, const IDFCurveCallback func)
void fcurves_main_cb(Main *bmain, const FunctionRef< void(ID *, FCurve *)> func)
static bool fcurves_listbase_apply_cb(ID *id, ListBaseT< FCurve > *fcurves, const IDFCurveCallback func)
void convert_legacy_animato_action(bAction &dna_action)
Definition versioning.cc:74
void tag_action_user_for_slotted_actions_conversion(ID &animated_id)
void fcurves_id_cb(ID *id, const FunctionRef< void(ID *, FCurve *)> func)
bool action_is_layered(const bAction &dna_action)
Definition versioning.cc:38
static bool nlastrips_apply_all_curves_cb(ID *id, ListBaseT< NlaStrip > *strips, const IDFCurveCallback func)
void convert_legacy_action_assignments(Main &bmain, ReportList *reports)
void convert_legacy_animato_actions(Main &bmain)
Definition versioning.cc:56
Vector< FCurve * > fcurves_for_legacy_action(bAction *action)
void tag_action_users_for_slotted_actions_conversion(Main &bmain)
FunctionRef< bool(ID *, FCurve *)> IDFCurveCallback
decltype(blender::ActionSlot::handle) slot_handle_t
bool foreach_action_slot_use_with_rna(ID &animated_id, FunctionRef< bool(ID &animated_id, bAction *action, PointerRNA &action_slot_owner_ptr, PropertyRNA &action_slot_prop, char *last_slot_identifier)> callback)
bool foreach_action_slot_use_with_references(ID &animated_id, FunctionRef< bool(ID &animated_id, bAction *&action_ptr_ref, slot_handle_t &slot_handle_ref, char *last_slot_identifier)> callback)
Slot * generic_slot_for_autoassign(const ID &animated_id, Action &action, StringRefNull last_slot_identifier)
bNodeTree * node_tree_from_id(ID *id)
Definition node.cc:5337
BLI_assert(slot->slot_subtype.map==BMO_OP_SLOT_SUBTYPE_MAP_FLT)
PointerRNA RNA_property_pointer_get(PointerRNA *ptr, PropertyRNA *prop)
@ RPT_WARNING
Definition BKE_report.hh:40
void RNA_property_pointer_set(PointerRNA *ptr, PropertyRNA *prop, PointerRNA ptr_value, ReportList *reports)
void RNA_property_update_main(Main *bmain, Scene *scene, PointerRNA *ptr, PropertyRNA *prop)
char * BLI_strncpy_utf8(char *__restrict dst, const char *__restrict src, size_t dst_maxncpy) ATTR_NONNULL(1
void BKE_animdata_main_cb(struct Main *bmain, FunctionRef< void(ID *, AnimData *)> func)
void void void BLI_movelisttolist(ListBase *dst, ListBase *src) ATTR_NONNULL(1
Definition listbase.cc:32
AnimData * BKE_animdata_from_id(const ID *id)
Definition anim_data.cc:93
int BLI_findindex(const ListBase *listbase, const void *vlink) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1)
Definition listbase.cc:593
PointerRNA RNA_pointer_create_discrete(ID *id, StructRNA *type, void *data)
void BKE_reportf(ReportList *reports, eReportType type, const char *format,...) ATTR_PRINTF_FORMAT(3
Definition report.cc:191
void BLI_addtail(ListBase *listbase, void *vlink) ATTR_NONNULL(1)
Definition listbase.cc:118
ID_Type GS(const char *name)
Definition DNA_ID.h:410
ID_Readfile_Data::Tags BLO_readfile_id_runtime_tags(const ID &id)
Definition readfile.cc:2297
void * MEM_new_array_zeroed(size_t len, size_t size, const char *str) ATTR_WARN_UNUSED_RESULT ATTR_ALLOC_SIZE(1
signed short int16_t
Definition BKE_text.h:77
struct bActionGroup ** group_array
ListBaseT< FCurve > drivers
ListBaseT< NlaTrack > nla_tracks
bActionGroup * grp
struct blender::ID_Readfile_Data::Tags tags
char name[258]
Definition DNA_ID.h:433
bke::id::ID_Runtime * runtime
Definition DNA_ID.h:541
ListBaseT< bAction > actions
Definition BKE_main.hh:408
ListBaseT< NlaStrip > strips
ListBaseT< FCurve > channels
struct ActionChannelbag * channelbag
ListBaseT< FCurve > curves
ListBaseT< bActionGroup > groups
ID_Readfile_Data * readfile_data
Definition BKE_lib_id.hh:93