Anim: move Animation data-block functionality into bAction #121355

New Issue

Sybren A. Stüvel · 2024-05-02T17:11:36+02:00

Sybren A. Stüvel commented

2024-05-02 17:11:36 +02:00

Baklava: from Animation to Action

Current design: Action is slated for removal, Animation is meant as its replacement.

Proposal: move the new data model into the existing Action struct.

Situation Sketch, expressed using the current-in-main Animation data-blocks:

classDiagram
    OBFoxMesh --|> MEFoxMesh
    OBFoxMesh --|> ANFox
    
    OBFoxRig --|> ARFoxArmature
    OBFoxRig --|> ANFox

    class OBFoxMesh{
      Action *action(legacy)
      Animation *animation
      int32 binding_handle
    }
    class OBFoxRig{
      Action *action(legacy)
      Animation *animation
      int32 binding_handle
    }
    class ANFox {
      Binding[] bindings
      Layer[] layers
    }

Same situation sketch, expressed using the proposed Action data-block:

classDiagram
    OBFoxMesh --|> MEFoxMesh
    OBFoxMesh --|> ACFox
    
    OBFoxRig --|> ARFoxArmature
    OBFoxRig --|> ACFox

    class OBFoxMesh{
      Action *action
      int32 binding_handle
    }
    class OBFoxRig{
      Action *action
      int32 binding_handle
    }
    class ACFox {
      Binding[] bindings
      Layer[] layers
      ListBase curves(legacy)
    }

:::info
Action contains a bit more info than shown above, most importantly markers. These are out of the scope of this proposal, and will be kept as-is until further notice.
:::

Definitions

Actions: Legacy vs. Layered

Legacy Action: A legacy Action is any Action that has a non-empty top-level curves list. This is the list of F-Curves that always animate any data-block animated by this Action.
Layered Action: A layered Action is any Action that has either a non-empty list of layers, or a non-empty list of bindings.
Empty Action: By the above definitions, an empty Action is neither 'legacy' nor 'layered'. This means that when legacy Actions are removed, empty Actions are by default in a state that can be used directly, and won't need upgrading.

:::info
This means that there are two moments when Blender has to choose between creating a legacy or an layered Action:

The first time an object is animated: it has no Action at all, and a key is inserted, and
it has an empty Action, and the first key is inserted.

Both should be consistent in whether they create a legacy or a layered Action.
:::

Action Reference: legacy vs. bound vs. unbound

To reference an Action (i.e. an object saying "I'm animated by that"), there will be a difference between legacy, bound, and unbound references.

Legacy Reference: Just an 'Action' pointer. This is what Blender uses now. With the new system, it will behave exactly the same as an 'unbound' reference (defined below).
Bound Reference: An 'Action' pointer combined with a 'Binding'. This will say "I'm animated by Action ANI_Fox_chase, and and the Binding Fox Rig". This will be the standard way of referencing Actions.
Unbound Reference: An 'Action' pointer that is technically combined with a Binding, but that Binding is empty.

Legacy & Unbound references will behave the same: they will cause the legacy F-Curves to be evaluated. In a Legacy Action, this is simply how Actions behave. If the Action has been upgraded to 'layered', and thus that list is empty, it means that the object will not receive any animation.

By using these definitions, there is no functional difference between "legacy reference" and "unbound reference", keeping things simple.

Changes Involved

Code Juggling

Move the fields of the Animation DNA struct into the Action DNA struct.
Move all the other AnimationXXX DNA structs from DNA_anim_types.h to DNA_action_types.h, along with the definition of their default values.
Move the C++ wrappers from ANIM_animation.hh to ANIM_action.hh, and the implementations into the corresponding .cc files.
Move the RNA code from rna_animation_id.cc to rna_action.cc.
Make it possible to switch between old & new behaviour with the experimental flag. Note that the datamodel will always be there when compiled with WITH_EXPERIMENTAL_FEATURES, and the flag in the preferences just toggles visibility in the UI and RNA.
Merge filtering code for Animation and Action, for Dope Sheet and Graph Editor support.
Make the Action Editor aware of the new data model, by showing all bindings of the selected Action.
Show the legacy/layered status in the Action editor.

NLA Support

Investigate how the NLA would interact with this.

If support is feasible for one-layer/one-strip Actions

Build support for this
Document (in code comments) that the current limitation of one layer with one strip is not just for development, but also for compatibility with the NLA.
Implement guards similar to the ones listed below, but then w.r.t. multi-layer/strip Actions.

If support is impossible / hard

Disallow upgrading an Action to 'layered' when it's referenced by an NLA strip.
Disallow selecting layered Actions to link to an NLA strip.
In case of linked Actions that were upgraded to 'layered': Show in NLA strip that its Action is now layered and thus not supported.

# Baklava: from Animation to Action **Current design:** `Action` is slated for removal, `Animation` is meant as its replacement. **Proposal:** move the new data model into the existing `Action` struct. --------------- Situation Sketch, expressed using the current-in-`main` `Animation` data-blocks: ```mermaid classDiagram OBFoxMesh --|> MEFoxMesh OBFoxMesh --|> ANFox OBFoxRig --|> ARFoxArmature OBFoxRig --|> ANFox class OBFoxMesh{ Action *action(legacy) Animation *animation int32 binding_handle } class OBFoxRig{ Action *action(legacy) Animation *animation int32 binding_handle } class ANFox { Binding[] bindings Layer[] layers } ``` Same situation sketch, expressed using the proposed `Action` data-block: ```mermaid classDiagram OBFoxMesh --|> MEFoxMesh OBFoxMesh --|> ACFox OBFoxRig --|> ARFoxArmature OBFoxRig --|> ACFox class OBFoxMesh{ Action *action int32 binding_handle } class OBFoxRig{ Action *action int32 binding_handle } class ACFox { Binding[] bindings Layer[] layers ListBase curves(legacy) } ``` :::info `Action` contains a bit more info than shown above, most importantly *markers*. These are out of the scope of this proposal, and will be kept as-is until further notice. ::: ## Definitions ### Actions: Legacy vs. Layered Legacy Action : A *legacy Action* is any Action that has a non-empty top-level `curves` list. This is the list of F-Curves that always animate any data-block animated by this Action. Layered Action : A *layered Action* is any Action that has either a non-empty list of *layers*, or a non-empty list of *bindings*. Empty Action : By the above definitions, an *empty Action* is neither 'legacy' nor 'layered'. This means that when legacy Actions are removed, empty Actions are by default in a state that can be used directly, and won't need upgrading. :::info This means that there are two moments when Blender has to choose between creating a legacy or an layered Action: 1. The first time an object is animated: it has no Action at all, and a key is inserted, and 2. it has an empty Action, and the first key is inserted. Both should be consistent in whether they create a *legacy* or a *layered* Action. ::: ### Action Reference: legacy vs. bound vs. unbound To reference an Action (i.e. an object saying "I'm animated by *that*"), there will be a difference between legacy, bound, and unbound references. Legacy Reference : Just an 'Action' pointer. This is what Blender uses now. With the new system, it will behave exactly the same as an 'unbound' reference (defined below). Bound Reference : An 'Action' pointer combined with a 'Binding'. This will say "I'm animated by Action `ANI_Fox_chase`, and and the Binding `Fox Rig`". This will be the standard way of referencing Actions. Unbound Reference : An 'Action' pointer that is technically combined with a Binding, but that Binding is empty. Legacy & Unbound references will behave the same: they will cause the legacy F-Curves to be evaluated. In a Legacy Action, this is simply how Actions behave. If the Action has been upgraded to 'layered', and thus that list is empty, it means that the object will not receive any animation. By using these definitions, there is no functional difference between "legacy reference" and "unbound reference", keeping things simple. ## Changes Involved ### Code Juggling 1. Move the fields of the `Animation` DNA struct into the `Action` DNA struct. 2. Move all the other `AnimationXXX` DNA structs from `DNA_anim_types.h` to `DNA_action_types.h`, along with the definition of their default values. 3. Move the C++ wrappers from `ANIM_animation.hh` to `ANIM_action.hh`, and the implementations into the corresponding `.cc` files. 4. Move the RNA code from `rna_animation_id.cc` to `rna_action.cc`. 5. Make it possible to switch between old & new behaviour with the experimental flag. Note that the datamodel will always be there when compiled with `WITH_EXPERIMENTAL_FEATURES`, and the flag in the preferences just toggles visibility in the UI and RNA. 6. Merge filtering code for `Animation` and `Action`, for Dope Sheet and Graph Editor support. 7. Make the Action Editor aware of the new data model, by showing all bindings of the selected Action. 8. Show the legacy/layered status in the Action editor. ### NLA Support - [ ] Investigate how the NLA would interact with this. #### If support is feasible for one-layer/one-strip Actions - [ ] Build support for this - [ ] Document (in code comments) that the current limitation of one layer with one strip is not just for development, but also for compatibility with the NLA. - [ ] Implement guards similar to the ones listed below, but then w.r.t. multi-layer/strip Actions. #### If support is impossible / hard - [ ] Disallow upgrading an Action to 'layered' when it's referenced by an NLA strip. - [ ] Disallow selecting layered Actions to link to an NLA strip. - [ ] In case of linked Actions that were upgraded to 'layered': Show in NLA strip that its Action is now layered and thus not supported.

👀 1 🎉 1

Sybren A. Stüvel added the

labels 2024-05-02 17:11:36 +02:00

Sybren A. Stüvel referenced this issue

2024-05-02 17:13:30 +02:00

Anim: merge Animation data-block into bAction #121357

Sybren A. Stüvel referenced this issue from a commit

2024-05-13 15:58:39 +02:00