ANIM_action.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2023 Blender Authors
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */
 
#pragma once
 
#include "ANIM_fcurve.hh"
#include "ANIM_keyframing.hh"
 
#include "DNA_action_types.h"
#include "DNA_anim_types.h"
 
#include "BKE_anim_data.hh"
 
#include "BLI_math_vector.hh"
#include "BLI_span.hh"
#include "BLI_string_ref.hh"
#include "BLI_vector.hh"
 
#include "RNA_types.hh"
 
#include <utility>
 
struct FCurve;
struct FCurve;
struct ID;
struct Main;
struct PointerRNA;
struct Main;
 
namespace blender::animrig {
 
/* Forward declarations for the types defined later in this file. */
class Layer;
class Strip;
class Slot;
 
/* Use an alias for the Slot handle type to help disambiguate function parameters. */
using slot_handle_t = decltype(::ActionSlot::handle);
 
class Action : public ::bAction {
 public:
  Action() = default;
  Action(const Action &other) = delete;
 
  /* Discriminators for 'legacy' and 'layered' Actions. */
  bool is_empty() const;
  bool is_action_legacy() const;
  bool is_action_layered() const;
 
  /* Action Layers access. */
  blender::Span<const Layer *> layers() const;
  blender::Span<Layer *> layers();
  const Layer *layer(int64_t index) const;
  Layer *layer(int64_t index);
 
  Layer &layer_add(std::optional<StringRefNull> name);
 
  bool layer_remove(Layer &layer_to_remove);
 
  void layer_keystrip_ensure();
 
  /* Action Slot access. */
  blender::Span<const Slot *> slots() const;
  blender::Span<Slot *> slots();
  const Slot *slot(int64_t index) const;
  Slot *slot(int64_t index);
 
  Slot *slot_for_handle(slot_handle_t handle);
  const Slot *slot_for_handle(slot_handle_t handle) const;
 
  void slot_name_set(Main &bmain, Slot &slot, StringRefNull new_name);
 
  void slot_name_define(Slot &slot, StringRefNull new_name);
 
  void slot_name_propagate(Main &bmain, const Slot &slot);
 
  Slot *slot_find_by_name(StringRefNull slot_name);
 
  Slot &slot_add();
 
  Slot &slot_add_for_id(const ID &animated_id);
 
  bool slot_remove(Slot &slot_to_remove);
 
  void slot_active_set(slot_handle_t slot_handle);
 
  Slot *slot_active_get();
 
  Span<const StripKeyframeData *> strip_keyframe_data() const;
  Span<StripKeyframeData *> strip_keyframe_data();
 
  Slot *find_suitable_slot_for(const ID &animated_id);
 
  bool is_slot_animated(slot_handle_t slot_handle) const;
 
  bool has_keyframes(slot_handle_t action_slot_handle) const ATTR_WARN_UNUSED_RESULT;
 
  bool has_single_frame() const ATTR_WARN_UNUSED_RESULT;
 
  bool is_cyclic() const ATTR_WARN_UNUSED_RESULT;
 
  Layer *get_layer_for_keyframing();
 
  float2 get_frame_range() const ATTR_WARN_UNUSED_RESULT;
 
  float2 get_frame_range_of_slot(slot_handle_t slot_handle) const ATTR_WARN_UNUSED_RESULT;
 
  float2 get_frame_range_of_keys(bool include_modifiers) const ATTR_WARN_UNUSED_RESULT;
 
  void slot_setup_for_id(Slot &slot, const ID &animated_id);
 
 protected:
  /* Friends for the purpose of adding/removing strip data on the action's strip
   * data arrays. This is needed for the strip creation and removal code in
   * `Strip` and `Layer`'s methods. */
  friend Strip;
  friend Layer;
 
  int64_t find_layer_index(const Layer &layer) const;
 
  int64_t find_slot_index(const Slot &slot) const;
 
  int strip_keyframe_data_append(StripKeyframeData *strip_data);
 
  void strip_keyframe_data_remove_if_unused(int index);
 
 private:
  Slot &slot_allocate();
 
  void slot_name_ensure_prefix(Slot &slot);
};
static_assert(sizeof(Action) == sizeof(::bAction),
              "DNA struct and its C++ wrapper must have the same size");
 
class Strip : public ::ActionStrip {
 public:
  enum class Type : int8_t { Keyframe = 0 };
 
  /* Strips typically shouldn't be directly constructed or copied, because their
   * data is actually stored in arrays on the action, and that data also needs
   * to be created and managed along with the strips. */
  Strip() = delete;
 
  explicit Strip(const Strip &other)
  {
    memcpy(this, &other, sizeof(*this));
  }
 
  static Strip &create(Action &owning_action, const Strip::Type type);
 
  Type type() const
  {
    return Type(this->strip_type);
  }
 
  bool is_infinite() const;
  bool contains_frame(float frame_time) const;
  bool is_last_frame(float frame_time) const;
 
  void resize(float frame_start, float frame_end);
 
  template<typename T> const T &data(const Action &owning_action) const;
  template<typename T> T &data(Action &owning_action);
 
  void slot_data_remove(Action &owning_action, slot_handle_t slot_handle);
};
static_assert(sizeof(Strip) == sizeof(::ActionStrip),
              "DNA struct and its C++ wrapper must have the same size");
 
class Layer : public ::ActionLayer {
 public:
  Layer() = default;
  Layer(const Layer &other) = delete;
  ~Layer();
 
  Layer *duplicate_with_shallow_strip_copies(StringRefNull allocation_name) const;
 
  enum class Flags : uint8_t {
    /* Set by default, cleared to mute. */
    Enabled = (1 << 0),
    /* When adding/removing a flag, also update the ENUM_OPERATORS() invocation below. */
  };
 
  Flags flags() const
  {
    return static_cast<Flags>(this->layer_flags);
  }
 
  enum class MixMode : int8_t {
    Replace = 0,
    Offset = 1,
    Add = 2,
    Subtract = 3,
    Multiply = 4,
  };
 
  MixMode mix_mode() const
  {
    return static_cast<MixMode>(this->layer_mix_mode);
  }
 
  /* Strip access. */
  blender::Span<const Strip *> strips() const;
  blender::Span<Strip *> strips();
  const Strip *strip(int64_t index) const;
  Strip *strip(int64_t index);
 
  Strip &strip_add(Action &owning_action, Strip::Type strip_type);
 
  bool strip_remove(Action &owning_action, Strip &strip);
 
  void slot_data_remove(Action &owning_action, slot_handle_t slot_handle);
 
 protected:
  int64_t find_strip_index(const Strip &strip) const;
};
static_assert(sizeof(Layer) == sizeof(::ActionLayer),
              "DNA struct and its C++ wrapper must have the same size");
 
ENUM_OPERATORS(Layer::Flags, Layer::Flags::Enabled);
 
class Slot : public ::ActionSlot {
 public:
  Slot();
  explicit Slot(const Slot &other);
  ~Slot();
 
  void blend_read_post();
 
  constexpr static slot_handle_t unassigned = 0;
 
  constexpr static int name_length_min = 3;
 
  constexpr static int name_length_max = MAX_ID_NAME;
  static_assert(sizeof(AnimData::slot_name) == name_length_max);
  static_assert(sizeof(NlaStrip::action_slot_name) == name_length_max);
 
  std::string name_prefix_for_idtype() const;
 
  StringRefNull name_without_prefix() const;
 
  bool is_suitable_for(const ID &animated_id) const;
 
  bool has_idtype() const;
 
  /* Flags access. */
  enum class Flags : uint8_t {
    Expanded = (1 << 0),
    Selected = (1 << 1),
    Active = (1 << 2),
    /* When adding/removing a flag, also update the ENUM_OPERATORS() invocation,
     * all the way below the Slot class. */
  };
  Flags flags() const;
  bool is_expanded() const;
  void set_expanded(bool expanded);
  bool is_selected() const;
  void set_selected(bool selected);
  bool is_active() const;
 
  Span<ID *> users(Main &bmain) const;
 
  Vector<ID *> runtime_users();
 
  void users_add(ID &animated_id);
 
  void users_remove(ID &animated_id);
 
  static void users_invalidate(Main &bmain);
 
 protected:
  friend Action;
 
  void name_ensure_prefix();
 
  void set_active(bool active);
};
static_assert(sizeof(Slot) == sizeof(::ActionSlot),
              "DNA struct and its C++ wrapper must have the same size");
ENUM_OPERATORS(Slot::Flags, Slot::Flags::Active);
 
class StripKeyframeData : public ::ActionStripKeyframeData {
 public:
  /* Value of `Strip::type()` that corresponds to this type. */
  static constexpr Strip::Type TYPE = Strip::Type::Keyframe;
 
  StripKeyframeData() = default;
  explicit StripKeyframeData(const StripKeyframeData &other);
  ~StripKeyframeData();
 
  /* ChannelBag array access. */
  blender::Span<const ChannelBag *> channelbags() const;
  blender::Span<ChannelBag *> channelbags();
  const ChannelBag *channelbag(int64_t index) const;
  ChannelBag *channelbag(int64_t index);
 
  const ChannelBag *channelbag_for_slot(const Slot &slot) const;
  ChannelBag *channelbag_for_slot(const Slot &slot);
  const ChannelBag *channelbag_for_slot(slot_handle_t slot_handle) const;
  ChannelBag *channelbag_for_slot(slot_handle_t slot_handle);
 
  ChannelBag &channelbag_for_slot_add(const Slot &slot);
 
  ChannelBag &channelbag_for_slot_ensure(const Slot &slot);
 
  bool channelbag_remove(ChannelBag &channelbag_to_remove);
 
  void slot_data_remove(slot_handle_t slot_handle);
 
  int64_t find_channelbag_index(const ChannelBag &channelbag) const;
 
  SingleKeyingResult keyframe_insert(Main *bmain,
                                     const Slot &slot,
                                     FCurveDescriptor fcurve_descriptor,
                                     float2 time_value,
                                     const KeyframeSettings &settings,
                                     eInsertKeyFlags insert_key_flags = INSERTKEY_NOFLAGS);
};
static_assert(sizeof(StripKeyframeData) == sizeof(::ActionStripKeyframeData),
              "DNA struct and its C++ wrapper must have the same size");
 
class ChannelBag : public ::ActionChannelBag {
 public:
  ChannelBag() = default;
  explicit ChannelBag(const ChannelBag &other);
  ~ChannelBag();
 
  /* FCurves access. */
  blender::Span<const FCurve *> fcurves() const;
  blender::Span<FCurve *> fcurves();
  const FCurve *fcurve(int64_t index) const;
  FCurve *fcurve(int64_t index);
 
  const FCurve *fcurve_find(FCurveDescriptor fcurve_descriptor) const;
  FCurve *fcurve_find(FCurveDescriptor fcurve_descriptor);
 
  FCurve &fcurve_ensure(Main *bmain, FCurveDescriptor fcurve_descriptor);
 
  FCurve *fcurve_create_unique(Main *bmain, FCurveDescriptor fcurve_descriptor);
 
  void fcurve_append(FCurve &fcurve);
 
  bool fcurve_remove(FCurve &fcurve_to_remove);
 
  void fcurve_remove_by_index(int64_t fcurve_array_index);
 
  bool fcurve_detach(FCurve &fcurve_to_detach);
 
  void fcurve_detach_by_index(int64_t fcurve_array_index);
 
  void fcurve_move(FCurve &fcurve, int to_fcurve_index);
 
  void fcurves_clear();
 
  /* Channel group access. */
  blender::Span<const bActionGroup *> channel_groups() const;
  blender::Span<bActionGroup *> channel_groups();
  const bActionGroup *channel_group(int64_t index) const;
  bActionGroup *channel_group(int64_t index);
 
  const bActionGroup *channel_group_find(StringRef name) const;
  bActionGroup *channel_group_find(StringRef name);
 
  int channel_group_containing_index(int fcurve_array_index);
 
  bActionGroup &channel_group_create(StringRefNull name);
 
  bActionGroup &channel_group_ensure(StringRefNull name);
 
  bool channel_group_remove(bActionGroup &group);
 
  void channel_group_move(bActionGroup &group, int to_group_index);
 
  bool fcurve_assign_to_channel_group(FCurve &fcurve, bActionGroup &to_group);
 
  bool fcurve_ungroup(FCurve &fcurve);
 
 protected:
  FCurve &fcurve_create(Main *bmain, FCurveDescriptor fcurve_descriptor);
 
 private:
  void channel_group_remove_raw(int group_index);
 
  void restore_channel_group_invariants();
};
 
static_assert(sizeof(ChannelBag) == sizeof(::ActionChannelBag),
              "DNA struct and its C++ wrapper must have the same size");
 
class ChannelGroup : public ::bActionGroup {
 public:
  bool is_legacy() const;
 
  Span<FCurve *> fcurves();
  Span<const FCurve *> fcurves() const;
};
 
static_assert(sizeof(ChannelGroup) == sizeof(::bActionGroup),
              "DNA struct and its C++ wrapper must have the same size");
 
Action &action_add(Main &bmain, StringRefNull name);
 
[[nodiscard]] bool assign_action(bAction *action, ID &animated_id);
 
[[nodiscard]] bool assign_action(bAction *action, OwnedAnimData owned_adt);
 
[[nodiscard]] bool assign_tmpaction(bAction *action, OwnedAnimData owned_adt);
 
[[nodiscard]] bool unassign_action(ID &animated_id);
 
[[nodiscard]] bool unassign_action(OwnedAnimData owned_adt);
 
[[nodiscard]] Slot *assign_action_ensure_slot_for_keying(Action &action, ID &animated_id);
 
[[nodiscard]] bool generic_assign_action(ID &animated_id,
                                         bAction *action_to_assign,
                                         bAction *&action_ptr_ref,
                                         slot_handle_t &slot_handle_ref,
                                         char *slot_name);
 
enum class ActionSlotAssignmentResult : int8_t {
  OK = 0,
  SlotNotFromAction = 1, /* Slot does not belong to the assigned Action. */
  SlotNotSuitable = 2,   /* Slot is not suitable for the given ID type.*/
  MissingAction = 3,     /* No Action assigned yet, so cannot assign slot. */
};
 
ActionSlotAssignmentResult generic_assign_action_slot(Slot *slot_to_assign,
                                                      ID &animated_id,
                                                      bAction *&action_ptr_ref,
                                                      slot_handle_t &slot_handle_ref,
                                                      char *slot_name) ATTR_WARN_UNUSED_RESULT;
 
ActionSlotAssignmentResult generic_assign_action_slot_handle(slot_handle_t slot_handle_to_assign,
                                                             ID &animated_id,
                                                             bAction *&action_ptr_ref,
                                                             slot_handle_t &slot_handle_ref,
                                                             char *slot_name)
    ATTR_WARN_UNUSED_RESULT;
 
bool is_action_assignable_to(const bAction *dna_action, ID_Type id_code) ATTR_WARN_UNUSED_RESULT;
 
ActionSlotAssignmentResult assign_action_slot(Slot *slot_to_assign, ID &animated_id);
 
ActionSlotAssignmentResult assign_action_and_slot(Action *action,
                                                  Slot *slot_to_assign,
                                                  ID &animated_id);
 
Action *get_action(ID &animated_id);
 
std::optional<std::pair<Action *, Slot *>> get_action_slot_pair(ID &animated_id);
 
const animrig::ChannelBag *channelbag_for_action_slot(const Action &action,
                                                      slot_handle_t slot_handle);
animrig::ChannelBag *channelbag_for_action_slot(Action &action, slot_handle_t slot_handle);
 
Span<FCurve *> fcurves_for_action_slot(Action &action, slot_handle_t slot_handle);
Span<const FCurve *> fcurves_for_action_slot(const Action &action, slot_handle_t slot_handle);
 
FCurve *action_fcurve_ensure(Main *bmain,
                             bAction *act,
                             const char group[],
                             PointerRNA *ptr,
                             FCurveDescriptor fcurve_descriptor);
 
FCurve *fcurve_find_in_action(bAction *act, FCurveDescriptor fcurve_descriptor);
 
FCurve *fcurve_find_in_action_slot(bAction *act,
                                   slot_handle_t slot_handle,
                                   FCurveDescriptor fcurve_descriptor);
 
FCurve *fcurve_find_in_assigned_slot(AnimData &adt, FCurveDescriptor fcurve_descriptor);
 
bool fcurve_matches_collection_path(const FCurve &fcurve,
                                    StringRefNull collection_rna_path,
                                    StringRefNull data_name);
 
Vector<FCurve *> fcurves_in_action_slot_filtered(
    bAction *act, slot_handle_t slot_handle, FunctionRef<bool(const FCurve &fcurve)> predicate);
 
bool action_fcurve_remove(Action &action, FCurve &fcu);
 
bool action_fcurve_detach(Action &action, FCurve &fcurve_to_detach);
 
void action_fcurve_attach(Action &action,
                          slot_handle_t action_slot,
                          FCurve &fcurve_to_attach,
                          std::optional<StringRefNull> group_name);
 
void action_fcurve_move(Action &action_dst,
                        slot_handle_t action_slot_dst,
                        Action &action_src,
                        FCurve &fcurve);
 
ID *action_slot_get_id_for_keying(Main &bmain,
                                  Action &action,
                                  slot_handle_t slot_handle,
                                  ID *primary_id);
 
ID *action_slot_get_id_best_guess(Main &bmain, Slot &slot, ID *primary_id);
 
slot_handle_t first_slot_handle(const ::bAction &dna_action);
 
void assert_baklava_phase_1_invariants(const Action &action);
void assert_baklava_phase_1_invariants(const Layer &layer);
void assert_baklava_phase_1_invariants(const Strip &strip);
 
Action *convert_to_layered_action(Main &bmain, const Action &legacy_action);
 
void move_slot(Main &bmain, Slot &slot, Action &from_action, Action &to_action);
 
void deselect_keys_actions(blender::Span<bAction *> actions);
 
void action_deselect_keys(Action &action);
 
}  // namespace blender::animrig
 
/* Wrap functions for the DNA structs. */
 
inline blender::animrig::ChannelGroup &bActionGroup::wrap()
{
  return *reinterpret_cast<blender::animrig::ChannelGroup *>(this);
}
inline const blender::animrig::ChannelGroup &bActionGroup::wrap() const
{
  return *reinterpret_cast<const blender::animrig::ChannelGroup *>(this);
}
 
inline blender::animrig::Action &bAction::wrap()
{
  return *reinterpret_cast<blender::animrig::Action *>(this);
}
inline const blender::animrig::Action &bAction::wrap() const
{
  return *reinterpret_cast<const blender::animrig::Action *>(this);
}
 
inline blender::animrig::Layer &ActionLayer::wrap()
{
  return *reinterpret_cast<blender::animrig::Layer *>(this);
}
inline const blender::animrig::Layer &ActionLayer::wrap() const
{
  return *reinterpret_cast<const blender::animrig::Layer *>(this);
}
 
inline blender::animrig::Slot &ActionSlot::wrap()
{
  return *reinterpret_cast<blender::animrig::Slot *>(this);
}
inline const blender::animrig::Slot &ActionSlot::wrap() const
{
  return *reinterpret_cast<const blender::animrig::Slot *>(this);
}
 
inline blender::animrig::Strip &ActionStrip::wrap()
{
  return *reinterpret_cast<blender::animrig::Strip *>(this);
}
inline const blender::animrig::Strip &ActionStrip::wrap() const
{
  return *reinterpret_cast<const blender::animrig::Strip *>(this);
}
 
inline blender::animrig::StripKeyframeData &ActionStripKeyframeData::wrap()
{
  return *reinterpret_cast<blender::animrig::StripKeyframeData *>(this);
}
inline const blender::animrig::StripKeyframeData &ActionStripKeyframeData::wrap() const
{
  return *reinterpret_cast<const blender::animrig::StripKeyframeData *>(this);
}
 
inline blender::animrig::ChannelBag &ActionChannelBag::wrap()
{
  return *reinterpret_cast<blender::animrig::ChannelBag *>(this);
}
inline const blender::animrig::ChannelBag &ActionChannelBag::wrap() const
{
  return *reinterpret_cast<const blender::animrig::ChannelBag *>(this);
}