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_action.hh"
#include "BKE_anim_data.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;

class Action : public ::bAction {
 public:
  Action() = default;
  Action(const Action &other) = delete;
 
  /* Discriminators for 'legacy' and 'layered' Actions.
   *
   * Note: `is_action_legacy()` and `is_action_layered()` are transitional APIs,
   * and should eventually be removed. See their documentation below for
   * details.
   */
  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_display_name_set(Main &bmain, Slot &slot, StringRefNull new_display_name);

  void slot_display_name_define(Slot &slot, StringRefNull new_display_name);

  void slot_idtype_define(Slot &slot, ID_Type idtype);

  void slot_identifier_set(Main &bmain, Slot &slot, StringRefNull new_identifier);

  void slot_identifier_define(Slot &slot, StringRefNull new_identifier);

  void slot_identifier_propagate(Main &bmain, const Slot &slot);

  Slot *slot_find_by_identifier(StringRefNull slot_identifier);

  Slot &slot_add();

  Slot &slot_add_for_id_type(ID_Type idtype);

  Slot &slot_add_for_id(const ID &animated_id);

  bool slot_remove(Slot &slot_to_remove);

  void slot_move_to_index(Slot &slot, int to_slot_index);

  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();

  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_identifier_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) = default;

  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);
};
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 array 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);
 
 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 identifier_length_min = 3;
 
  constexpr static int identifier_length_max = MAX_ID_NAME;
  static_assert(sizeof(AnimData::last_slot_identifier) == identifier_length_max);
  static_assert(sizeof(NlaStrip::last_slot_identifier) == identifier_length_max);

  std::string idtype_string() const;

  StringRef identifier_prefix() const;

  StringRefNull identifier_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);

  void identifier_ensure_prefix();
 
 protected:
  friend Action;

  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_add(slot_handle_t slot_handle);

  Channelbag &channelbag_for_slot_ensure(const Slot &slot);
  Channelbag &channelbag_for_slot_ensure(slot_handle_t slot_handle);

  bool channelbag_remove(Channelbag &channelbag_to_remove);

  void slot_data_remove(slot_handle_t slot_handle);

  void slot_data_duplicate(slot_handle_t source_slot_handle, slot_handle_t target_slot_handle);

  int64_t find_channelbag_index(const Channelbag &channelbag) const;
 
  SingleKeyingResult keyframe_insert(Main *bmain,
                                     const Slot &slot,
                                     const FCurveDescriptor &fcurve_descriptor,
                                     float2 time_value,
                                     const KeyframeSettings &settings,
                                     eInsertKeyFlags insert_key_flags = INSERTKEY_NOFLAGS,
                                     std::optional<float2> cycle_range = std::nullopt);
};
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(const FCurveDescriptor &fcurve_descriptor) const;
  FCurve *fcurve_find(const FCurveDescriptor &fcurve_descriptor);

  FCurve &fcurve_ensure(Main *bmain, const FCurveDescriptor &fcurve_descriptor);

  FCurve *fcurve_create_unique(Main *bmain, const FCurveDescriptor &fcurve_descriptor);

  Vector<FCurve *> fcurve_create_many(Main *bmain, Span<FCurveDescriptor> fcurve_descriptors);

  void fcurve_append(FCurve &fcurve);

  bool fcurve_remove(FCurve &fcurve_to_remove);

  void fcurve_remove_by_index(int64_t fcurve_index);

  bool fcurve_detach(FCurve &fcurve_to_detach);

  void fcurve_detach_by_index(int64_t fcurve_index);

  void fcurve_move_to_index(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_find_index(const bActionGroup *group) const;

  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_to_index(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, const 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);
 
/* ---------- Action & Slot Assignment --------------- */
 
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. */
};

[[nodiscard]] bool is_action_assignable_to(const bAction *dna_action, ID_Type id_code);

[[nodiscard]] bool assign_action(bAction *action, ID &animated_id);

[[nodiscard]] bool assign_action(bAction *action, OwnedAnimData owned_adt);
 
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);

[[nodiscard]] Slot *assign_action_ensure_slot_for_keying(Action &action, ID &animated_id);

[[nodiscard]] bool assign_tmpaction(bAction *action, OwnedAnimData owned_adt);
 
[[nodiscard]] ActionSlotAssignmentResult assign_tmpaction_and_slot_handle(
    bAction *action, slot_handle_t slot_handle, OwnedAnimData owned_adt);

[[nodiscard]] bool unassign_action(ID &animated_id);

[[nodiscard]] bool unassign_action(OwnedAnimData owned_adt);

[[nodiscard]] bool generic_assign_action(ID &animated_id,
                                         bAction *action_to_assign,
                                         bAction *&action_ptr_ref,
                                         slot_handle_t &slot_handle_ref,
                                         char *slot_identifier);

[[nodiscard]] ActionSlotAssignmentResult generic_assign_action_slot(Slot *slot_to_assign,
                                                                    ID &animated_id,
                                                                    bAction *&action_ptr_ref,
                                                                    slot_handle_t &slot_handle_ref,
                                                                    char *slot_identifier);

[[nodiscard]] 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_identifier);

[[nodiscard]] Slot *generic_slot_for_autoassign(const ID &animated_id,
                                                Action &action,
                                                StringRefNull last_slot_identifier);
 
/* --------------- Accessors --------------------- */

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);

Channelbag &action_channelbag_ensure(bAction &dna_action, ID &animated_id);

FCurve &action_fcurve_ensure(Main *bmain,
                             bAction &action,
                             ID &animated_id,
                             const FCurveDescriptor &fcurve_descriptor);

FCurve *action_fcurve_ensure_ex(Main *bmain,
                                bAction *act,
                                const char group[],
                                PointerRNA *ptr,
                                const FCurveDescriptor &fcurve_descriptor);

FCurve *action_fcurve_ensure_legacy(Main *bmain,
                                    bAction *act,
                                    const char group[],
                                    PointerRNA *ptr,
                                    const FCurveDescriptor &fcurve_descriptor);

FCurve *fcurve_find_in_action(bAction *act, const FCurveDescriptor &fcurve_descriptor);

FCurve *fcurve_find_in_action_slot(bAction *act,
                                   slot_handle_t slot_handle,
                                   const FCurveDescriptor &fcurve_descriptor);

FCurve *fcurve_find_in_assigned_slot(AnimData &adt, const 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);

Vector<FCurve *> fcurves_in_span_filtered(Span<FCurve *> fcurves,
                                          FunctionRef<bool(const FCurve &fcurve)> predicate);

Vector<FCurve *> fcurves_in_listbase_filtered(ListBase /* FCurve * */ fcurves,
                                              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);

void channelbag_fcurves_move(Channelbag &channelbag_dst, Channelbag &channelbag_src);

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);

Slot &duplicate_slot(Action &action, const Slot &slot);

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);
}