Anim: make it easier to convert from legacy to current Action API

The changes:

1. Add `group_name` to the `channelbag.fcurves.new()` and
   `action.fcurve_ensure_for_datablock()` RNA functions.
2. Add `anim_utils.action_ensure_channelbag_for_slot(action, slot)`.
3. Add `channelbag.fcurves.ensure()` RNA function.

This makes it possible to replace this legacy code:

```py
fcurve = action.fcurves.new("location", index=2, action_group="Name")
```

with this code:

```py
channelbag = action_ensure_channelbag_for_slot(action, action_slot)
fcurve = channelbag.fcurves.new("location", index=2, group_name="Name")
```

or replace this legacy code:

```py
fcurve = action.fcurves.find("location", index=2, action_group="Name")
if not fcurve:
    fcurve = action.fcurves.new("location", index=2, action_group="Name")
```

with this code:

```py
channelbag = action_ensure_channelbag_for_slot(action, action_slot)
fcurve = channelbag.fcurves.ensure("location", index=2, group_name="Name")
```

Note that the parameter name is different (`action_group` became
`group_name`). This clarifies that this is the name of the group, and
not a reference to the group itself.

This is part of #146586

Pull Request: https://projects.blender.org/blender/blender/pulls/146977
This commit is contained in:
Sybren A. Stüvel
2025-09-30 14:43:56 +02:00
parent 1e8636962e
commit dbcb701eb2
3 changed files with 109 additions and 15 deletions

View File

@@ -96,7 +96,9 @@ def action_get_channelbag_for_slot(action: Action | None, slot: ActionSlot | Non
return None
def _ensure_channelbag_exists(action: Action, slot: ActionSlot) -> ActionChannelbag:
def action_ensure_channelbag_for_slot(action: Action, slot: ActionSlot) -> ActionChannelbag:
"""Ensure a layer and a keyframe strip exists, then ensure that that strip has a channelbag for the slot."""
try:
layer = action.layers[0]
except IndexError:
@@ -732,7 +734,7 @@ class KeyframesCo:
if fcurve is None:
data_path, array_index = fc_key
assert action.is_action_layered
channelbag = _ensure_channelbag_exists(action, action_slot)
channelbag = action_ensure_channelbag_for_slot(action, action_slot)
fcurve = channelbag.fcurves.new(data_path, index=array_index)
keyframe_points = fcurve.keyframe_points