43d7558e5b
This commit takes the 'Slotted Actions' out of the experimental phase. As a result: - All newly created Actions will be slotted Actions. - Legacy Actions loaded from disk will be versioned to slotted Actions. - The new Python API for slots, layers, strips, and channel bags is available. - The legacy Python API for accessing F-Curves and Action Groups is still available, and will operate on the F-Curves/Groups for the first slot only. - Creating an Action by keying (via the UI, operators, or the `rna_struct.keyframe_insert` function) will try and share Actions between related data-blocks. See !126655 for more info about this. - Assigning an Action to a data-block will auto-assign a suitable Action Slot. The logic for this is described below. However, There are cases where this does _not_ automatically assign a slot, and thus the Action will effectively _not_ animate the data-block. Effort has been spent to make Action selection work both reliably for Blender users as well as keep the behaviour the same for Python scripts. Where these two goals did not converge, reliability and understandability for users was prioritised. Auto-selection of the Action Slot upon assigning the Action works as follows. The first rule to find a slot wins. 1. The data-block remembers the slot name that was last assigned. If the newly assigned Action has a slot with that name, it is chosen. 2. If the Action has a slot with the same name as the data-block, it is chosen. 3. If the Action has only one slot, and it has never been assigned to anything, it is chosen. 4. If the Action is assigned to an NLA strip or an Action constraint, and the Action has a single slot, and that slot has a suitable ID type, it is chosen. This last step is what I was referring to with "Where these two goals did not converge, reliability and understandability for users was prioritised." For regular Action assignments (like via the Action selectors in the Properties editor) this rule doesn't apply, even though with legacy Actions the final state ("it is animated by this Action") differs from the final state with slotted Actions ("it has no slot so is not animated"). This is done to support the following workflow: - Create an Action by animating Cube. - In order to animate Suzanne with that same Action, assign the Action to Suzanne. - Start keying Suzanne. This auto-creates and auto-assigns a new slot for Suzanne. If rule 4. above would apply in this case, the 2nd step would automatically select the Cube slot for Suzanne as well, which would immediately overwrite Suzanne's properties with the Cube animation. Technically, this commit: - removes the `WITH_ANIM_BAKLAVA` build flag, - removes the `use_animation_baklava` experimental flag in preferences, - updates the code to properly deal with the fact that empty Actions are now always considered slotted/layered Actions (instead of that relying on the user preference). Note that 'slotted Actions' and 'layered Actions' are the exact same thing, just focusing on different aspects (slot & layers) of the new data model. The "Baklava phase 1" assumptions are still asserted. This means that: - an Action can have zero or one layer, - that layer can have zero or one strip, - that strip must be of type 'keyframe' and be infinite with zero offset. The code to handle legacy Actions is NOT removed in this commit. It will be removed later. For now it's likely better to keep it around as reference to the old behaviour in order to aid in some inevitable bugfixing. Ref: #120406
159 lines
6.4 KiB
Python
159 lines
6.4 KiB
Python
# SPDX-FileCopyrightText: 2023 Blender Authors
|
|
#
|
|
# SPDX-License-Identifier: GPL-2.0-or-later
|
|
|
|
"""
|
|
Tests the evaluation of NLA strips based on their properties and placement on NLA tracks.
|
|
|
|
blender -b --factory-startup --python tests/python/bl_animation_nla_strip.py
|
|
"""
|
|
|
|
import bpy
|
|
import sys
|
|
import unittest
|
|
|
|
|
|
class AbstractNlaStripTest(unittest.TestCase):
|
|
""" Sets up a series of strips in one NLA track. """
|
|
|
|
test_object: bpy.types.Object = None
|
|
""" Object whose X Location is animated to check strip evaluation. """
|
|
|
|
nla_tracks: bpy.types.NlaTracks = None
|
|
""" NLA tracks of the test object, which are cleared after each test case. """
|
|
|
|
action: bpy.types.Action = None
|
|
""" Action with X Location keyed on frames 1 to 4 with the same value as the frame, with constant interpolation. """
|
|
|
|
def setUp(self):
|
|
bpy.ops.wm.read_factory_settings(use_empty=True)
|
|
|
|
self.test_object = bpy.data.objects.new(name="Object", object_data=bpy.data.meshes.new("Mesh"))
|
|
bpy.context.collection.objects.link(self.test_object)
|
|
self.test_object.animation_data_create()
|
|
|
|
self.nla_tracks = self.test_object.animation_data.nla_tracks
|
|
|
|
self.action = bpy.data.actions.new(name="ObjectAction")
|
|
x_location_fcurve = self.action.fcurves.new(data_path="location", index=0, action_group="Object Transforms")
|
|
for frame in range(1, 5):
|
|
x_location_fcurve.keyframe_points.insert(frame, value=frame).interpolation = "CONSTANT"
|
|
|
|
def add_strip_no_extrapolation(self, nla_track: bpy.types.NlaTrack, start: int) -> bpy.types.NlaStrip:
|
|
""" Places a new strip with the test action on the given track, setting extrapolation to nothing. """
|
|
strip = nla_track.strips.new("ObjectAction", start, self.action)
|
|
strip.extrapolation = "NOTHING"
|
|
return strip
|
|
|
|
def assertFrameValue(self, frame: float, expected_value: float):
|
|
""" Checks the evaluated X Location at the given frame. """
|
|
int_frame, subframe = divmod(frame, 1)
|
|
bpy.context.scene.frame_set(frame=int(int_frame), subframe=subframe)
|
|
self.assertEqual(expected_value, self.test_object.evaluated_get(
|
|
bpy.context.evaluated_depsgraph_get()
|
|
).matrix_world.translation[0])
|
|
|
|
|
|
class NlaStripSingleTest(AbstractNlaStripTest):
|
|
""" Tests the inner values as well as the boundaries of one strip on one track. """
|
|
|
|
def test_extrapolation_nothing(self):
|
|
""" Tests one strip with no extrapolation. """
|
|
self.add_strip_no_extrapolation(self.nla_tracks.new(), 1)
|
|
|
|
self.assertFrameValue(0.9, 0.0)
|
|
self.assertFrameValue(1.0, 1.0)
|
|
self.assertFrameValue(1.1, 1.0)
|
|
self.assertFrameValue(3.9, 3.0)
|
|
self.assertFrameValue(4.0, 4.0)
|
|
self.assertFrameValue(4.1, 0.0)
|
|
|
|
|
|
class NlaStripBoundaryTest(AbstractNlaStripTest):
|
|
""" Tests two strips, the second one starting when the first one ends. """
|
|
|
|
# Incorrectly, the first strip is currently evaluated at the boundary between two adjacent strips (see #113487).
|
|
@unittest.expectedFailure
|
|
def test_adjacent(self):
|
|
""" The second strip should be evaluated at the boundary between two adjacent strips. """
|
|
nla_track = self.nla_tracks.new()
|
|
self.add_strip_no_extrapolation(nla_track, 1)
|
|
self.add_strip_no_extrapolation(nla_track, 4)
|
|
|
|
self.assertFrameValue(3.9, 3.0)
|
|
self.assertFrameValue(4.0, 1.0)
|
|
self.assertFrameValue(4.1, 1.0)
|
|
|
|
def test_adjacent_muted(self):
|
|
""" The first strip should be evaluated at the boundary if it is adjacent to a muted strip. """
|
|
nla_track = self.nla_tracks.new()
|
|
self.add_strip_no_extrapolation(nla_track, 1)
|
|
self.add_strip_no_extrapolation(nla_track, 4).mute = True
|
|
|
|
self.assertFrameValue(3.9, 3.0)
|
|
self.assertFrameValue(4.0, 4.0)
|
|
self.assertFrameValue(4.1, 0.0)
|
|
|
|
def test_first_above_second(self):
|
|
""" The first strip should be evaluated at the boundary, when followed by another strip on a track below. """
|
|
self.add_strip_no_extrapolation(self.nla_tracks.new(), 4)
|
|
self.add_strip_no_extrapolation(self.nla_tracks.new(), 1)
|
|
|
|
self.assertFrameValue(3.9, 3.0)
|
|
self.assertFrameValue(4.0, 4.0)
|
|
self.assertFrameValue(4.1, 1.0)
|
|
|
|
def test_second_above_first(self):
|
|
""" The second strip should be evaluated at the boundary, when preceded by another strip on a track below. """
|
|
self.add_strip_no_extrapolation(self.nla_tracks.new(), 1)
|
|
self.add_strip_no_extrapolation(self.nla_tracks.new(), 4)
|
|
|
|
self.assertFrameValue(3.9, 3.0)
|
|
self.assertFrameValue(4.0, 1.0)
|
|
self.assertFrameValue(4.1, 1.0)
|
|
|
|
|
|
class NLAStripActionSlotSelectionTest(AbstractNlaStripTest):
|
|
def test_two_strips_for_same_action(self):
|
|
action = bpy.data.actions.new("StripAction")
|
|
action.slots.new()
|
|
self.assertTrue(action.is_action_layered)
|
|
self.assertEqual(1, len(action.slots))
|
|
|
|
track = self.nla_tracks.new()
|
|
|
|
self.assertEqual('UNSPECIFIED', action.slots[0].id_root)
|
|
|
|
strip1 = track.strips.new("name", 1, action)
|
|
self.assertEqual(action.slots[0], strip1.action_slot)
|
|
self.assertEqual('OBJECT', action.slots[0].id_root, "Slot should have been rooted to object")
|
|
|
|
strip2 = track.strips.new("name", 10, action)
|
|
self.assertEqual(action.slots[0], strip2.action_slot)
|
|
|
|
def test_switch_action_via_assignment(self):
|
|
action1 = bpy.data.actions.new("StripAction 1")
|
|
action1.slots.new()
|
|
self.assertTrue(action1.is_action_layered)
|
|
self.assertEqual(1, len(action1.slots))
|
|
|
|
action2 = bpy.data.actions.new("StripAction 2")
|
|
action2.slots.new()
|
|
self.assertTrue(action2.is_action_layered)
|
|
self.assertEqual(1, len(action2.slots))
|
|
|
|
track = self.nla_tracks.new()
|
|
|
|
strip = track.strips.new("name", 1, action1)
|
|
self.assertEqual(action1.slots[0], strip.action_slot)
|
|
self.assertEqual('OBJECT', action1.slots[0].id_root, "Slot of Action 1 should have been rooted to object")
|
|
|
|
strip.action = action2
|
|
self.assertEqual(action2.slots[0], strip.action_slot)
|
|
self.assertEqual('OBJECT', action2.slots[0].id_root, "Slot of Action 2 should have been rooted to object")
|
|
|
|
|
|
if __name__ == "__main__":
|
|
# Drop all arguments before "--", or everything if the delimiter is absent. Keep the executable path.
|
|
unittest.main(argv=sys.argv[:1] + (sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []))
|