From 14d7736f31f83933374fd59a0dab9b277263775e Mon Sep 17 00:00:00 2001 From: Darby Johnston Date: Wed, 2 Apr 2025 16:35:31 -0700 Subject: [PATCH 1/2] Add Doxygen comments to opentimelineio Signed-off-by: Darby Johnston --- src/opentimelineio/anyDictionary.h | 67 ++++++++++------ src/opentimelineio/anyVector.h | 37 +++++---- src/opentimelineio/clip.h | 49 ++++++++++-- src/opentimelineio/composable.h | 12 +++ src/opentimelineio/composition.h | 62 ++++++++++++--- src/opentimelineio/deserialization.h | 2 + src/opentimelineio/effect.h | 12 +++ src/opentimelineio/errorStatus.h | 24 ++++-- src/opentimelineio/externalReference.h | 10 +++ src/opentimelineio/freezeFrame.h | 6 ++ src/opentimelineio/gap.h | 20 +++++ src/opentimelineio/generatorReference.h | 14 ++++ src/opentimelineio/imageSequenceReference.h | 47 +++++++++++ src/opentimelineio/item.h | 27 +++++++ src/opentimelineio/linearTimeWarp.h | 10 +++ src/opentimelineio/marker.h | 20 +++++ src/opentimelineio/mediaReference.h | 13 ++++ src/opentimelineio/missingReference.h | 11 +++ src/opentimelineio/safely_typed_any.h | 42 ++++++---- src/opentimelineio/serializableCollection.h | 48 +++++++++--- src/opentimelineio/serializableObject.h | 77 ++++++++++++++----- .../serializableObjectWithMetadata.h | 10 +++ src/opentimelineio/serialization.h | 2 + src/opentimelineio/stack.h | 22 ++++-- src/opentimelineio/stackAlgorithm.h | 3 + src/opentimelineio/stringUtils.h | 5 ++ src/opentimelineio/timeEffect.h | 7 ++ src/opentimelineio/timeline.h | 39 +++++++--- src/opentimelineio/track.h | 24 ++++-- src/opentimelineio/trackAlgorithm.h | 1 + src/opentimelineio/transition.h | 21 ++++- src/opentimelineio/typeRegistry.h | 45 +++++++---- src/opentimelineio/unknownSchema.h | 8 ++ src/opentimelineio/vectorIndexing.h | 1 + src/opentimelineio/version.h | 4 +- 35 files changed, 661 insertions(+), 141 deletions(-) diff --git a/src/opentimelineio/anyDictionary.h b/src/opentimelineio/anyDictionary.h index 19eeabdf06..34d2ec8515 100644 --- a/src/opentimelineio/anyDictionary.h +++ b/src/opentimelineio/anyDictionary.h @@ -12,37 +12,39 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { -/** - * An AnyDictionary has exactly the same API as - * std::map - * - * except that it records a "time-stamp" that bumps monotonically every time an - * operation that would invalidate iterators is performed. - * (This happens for operator=, clear, erase, insert, swap). The stamp also - * lets external observers know when the map has been destroyed (which includes - * the case of the map being relocated in memory). - * - * This allows us to hand out iterators that can be aware of mutation and moves - * and take steps to safe-guard themselves from causing a crash. (Yes, - * I'm talking to you, Python...) - */ +/// @brief This class provides a replacement for "std::map". +/// +/// This class has exactly the same API as "std::map", +/// except that it records a "time-stamp" that bumps monotonically every time an +/// operation that would invalidate iterators is performed (this happens for +/// operator =, clear, erase, insert, and swap). The stamp also lets external +/// observers know when the map has been destroyed (which includes the case of +/// the map being relocated in memory). +/// +/// This allows us to hand out iterators that can be aware of mutation and moves +/// and take steps to safe-guard themselves from causing a crash. (Yes, I'm +/// talking to you, Python...) class AnyDictionary : private std::map { public: using map::map; + /// @brief Create an empty dictionary. AnyDictionary() : map{} , _mutation_stamp{} {} - // to be safe, avoid brace-initialization so as to not trigger - // list initialization behavior in older compilers: + /// @brief Create a copy of a dictionary. + /// + /// To be safe, avoid brace-initialization so as to not trigger + /// list initialization behavior in older compilers: AnyDictionary(const AnyDictionary& other) : map(other) , _mutation_stamp{} {} + /// @brief Destructor. ~AnyDictionary() { if (_mutation_stamp) @@ -52,6 +54,7 @@ class AnyDictionary : private std::map } } + /// @brief Copy operator. AnyDictionary& operator=(const AnyDictionary& other) { mutate(); @@ -59,6 +62,7 @@ class AnyDictionary : private std::map return *this; } + /// @brief Move operator. AnyDictionary& operator=(AnyDictionary&& other) { mutate(); @@ -67,6 +71,7 @@ class AnyDictionary : private std::map return *this; } + /// @brief Copy operator. AnyDictionary& operator=(std::initializer_list ilist) { mutate(); @@ -88,6 +93,7 @@ class AnyDictionary : private std::map using map::rbegin; using map::rend; + /// @brief Clear the dictionary. void clear() noexcept { mutate(); @@ -97,24 +103,28 @@ class AnyDictionary : private std::map using map::emplace_hint; using map::insert; + /// @brief Erase an item. iterator erase(const_iterator pos) { mutate(); return map::erase(pos); } + /// @brief Erase a range of items. iterator erase(const_iterator first, const_iterator last) { mutate(); return map::erase(first, last); } + /// @brief Erase an item with the given key. size_type erase(const key_type& key) { mutate(); return map::erase(key); } + /// @brief Swap dictionaries. void swap(AnyDictionary& other) { mutate(); @@ -122,11 +132,15 @@ class AnyDictionary : private std::map map::swap(other); } - /// @TODO: remove all of these @{ + /// @todo Remove all of these. + /// + ///@{ - // if key is in this, and the type of key matches the type of result, then - // set result to the value of std::any_cast(this[key]) and return true, - // otherwise return false + /// @brief Return whether the given key has been set. + /// + /// If key is in this, and the type of key matches the type of result, then + /// set result to the value of std::any_cast(this[key]) and return true, + /// otherwise return false. template bool get_if_set(const std::string& key, containedType* result) const { @@ -150,13 +164,16 @@ class AnyDictionary : private std::map } } + /// @brief Return whether the dictionary contains the given key. inline bool has_key(const std::string& key) const { return (this->find(key) != this->end()); } - // if key is in this, place the value in result and return true, otherwise - // store the value in result at key and return false + /// @brief Set the default for the given key. + /// + /// If key is in this, place the value in result and return true, otherwise + /// store the value in result at key and return false. template bool set_default(const std::string& key, containedType* result) { @@ -181,6 +198,8 @@ class AnyDictionary : private std::map } } + ///@} + using map::empty; using map::max_size; using map::size; @@ -210,8 +229,10 @@ class AnyDictionary : private std::map using map::size_type; using map::value_type; + /// @brief This struct provides a mutation time stamp. struct MutationStamp { + /// @brief Create a new time stamp. constexpr MutationStamp(AnyDictionary* d) noexcept : stamp{ 1 } , any_dictionary{ d } @@ -223,6 +244,7 @@ class AnyDictionary : private std::map MutationStamp(MutationStamp const&) = delete; MutationStamp& operator=(MutationStamp const&) = delete; + /// @brief Destructor. ~MutationStamp() { if (any_dictionary) @@ -249,6 +271,7 @@ class AnyDictionary : private std::map } }; + /// @brief Get or crate a mutation time stamp. MutationStamp* get_or_create_mutation_stamp() { if (!_mutation_stamp) diff --git a/src/opentimelineio/anyVector.h b/src/opentimelineio/anyVector.h index ee78c3f6c8..6cdd72534e 100644 --- a/src/opentimelineio/anyVector.h +++ b/src/opentimelineio/anyVector.h @@ -11,34 +11,35 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { -/** - * An AnyVector has exactly the same API as - * std::vector - * - * except that it records a "time-stamp" that - * lets external observers know when the vector has been destroyed (which includes - * the case of the vector being relocated in memory). - * - * This allows us to hand out iterators that can be aware of moves - * and take steps to safe-guard themselves from causing a crash. - */ - +/// @brief This class provides a replacement for "std::vector". +/// +/// This class has exactly the same API as "std::vector", except +/// that it records a "time-stamp" that lets external observers know when +/// the vector has been destroyed (which includes the case of the vector +/// being relocated in memory). +/// +/// This allows us to hand out iterators that can be aware of moves +/// and take steps to safe-guard themselves from causing a crash. class AnyVector : private std::vector { public: using vector::vector; + /// @brief Create an empty vector. AnyVector() : _mutation_stamp{} {} - // must avoid brace-initialization so as to not trigger - // list initialization behavior in older compilers: + /// @brief Create a copy of a vector. + /// + /// To be safe, avoid brace-initialization so as to not trigger + /// list initialization behavior in older compilers: AnyVector(const AnyVector& other) : vector(other) , _mutation_stamp{ nullptr } {} + /// @brief Destructor. ~AnyVector() { if (_mutation_stamp) @@ -47,18 +48,21 @@ class AnyVector : private std::vector } } + /// @brief Copy operator. AnyVector& operator=(const AnyVector& other) { vector::operator=(other); return *this; } + /// @brief Move operator. AnyVector& operator=(AnyVector&& other) { vector::operator=(other); return *this; } + /// @brief Copy operator. AnyVector& operator=(std::initializer_list ilist) { vector::operator=(ilist); @@ -113,10 +117,13 @@ class AnyVector : private std::vector using vector::size_type; using vector::value_type; + /// @brief Swap vectors. void swap(AnyVector& other) { vector::swap(other); } + /// @brief This struct provides a mutation time stamp. struct MutationStamp { + /// @brief Create a new time stamp. MutationStamp(AnyVector* v) : any_vector{ v } , owning{ false } @@ -127,6 +134,7 @@ class AnyVector : private std::vector MutationStamp(MutationStamp const&) = delete; MutationStamp& operator=(MutationStamp const&) = delete; + /// @brief Destructor. ~MutationStamp() { if (any_vector) @@ -151,6 +159,7 @@ class AnyVector : private std::vector } }; + /// @brief Get or create a mutation time stamp. MutationStamp* get_or_create_mutation_stamp() { if (!_mutation_stamp) diff --git a/src/opentimelineio/clip.h b/src/opentimelineio/clip.h index 27f8bc9cf5..b46e4b2d4a 100644 --- a/src/opentimelineio/clip.h +++ b/src/opentimelineio/clip.h @@ -9,11 +9,16 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief A clip is a segment of editable media (usually audio or video). +/// +/// Contains a MediaReference and a trim on that media reference. class Clip : public Item { public: + /// @brief The default media within a clip. static char constexpr default_media_key[] = "DEFAULT_MEDIA"; + /// @brief This struct provides the Clip schema. struct Schema { static auto constexpr name = "Clip"; @@ -22,6 +27,18 @@ class Clip : public Item using Parent = Item; + /// @brief Create a new clip. + /// + /// @param name The name of the clip. + /// @param media_reference The media reference for the clip. Note + /// that the Clip keeps a Retainer to the media reference. + /// @param source_range The source range of the clip. + /// @param metadata The metadata for the clip. + /// @param effects The list of effects for the clip. Note that the + /// the clip keeps a retainer to each effect. + /// @param markers The list of markers for the clip. Note that the + /// the clip keeps a retainer to each marker. + /// @param active_media_reference_key The active media reference. Clip( std::string const& name = std::string(), MediaReference* media_reference = nullptr, @@ -31,21 +48,37 @@ class Clip : public Item std::vector const& markers = std::vector(), std::string const& active_media_reference_key = default_media_key); - void set_media_reference(MediaReference* media_reference); + /// @name Media References + ///@{ + + /// @brief Set the media reference. Note that the Clip keeps a Retainer to + /// the media reference. + void set_media_reference(MediaReference* media_reference); + + /// @brief Return the media reference. MediaReference* media_reference() const noexcept; using MediaReferences = std::map; + /// @brief Return the list of media references. MediaReferences media_references() const noexcept; - void set_media_references( - MediaReferences const& media_references, - std::string const& new_active_key, - ErrorStatus* error_status = nullptr) noexcept; + /// @brief Set the list of media references. Note that the Clip keeps a + /// Retainer to each media reference. + void set_media_references( + MediaReferences const& media_references, + std::string const& new_active_key, + ErrorStatus* error_status = nullptr) noexcept; + + /// @brief Return the active media reference. std::string active_media_reference_key() const noexcept; - void set_active_media_reference_key( - std::string const& new_active_key, - ErrorStatus* error_status = nullptr) noexcept; + + /// @brief Set the active media reference. + void set_active_media_reference_key( + std::string const& new_active_key, + ErrorStatus* error_status = nullptr) noexcept; + + ///@} TimeRange available_range(ErrorStatus* error_status = nullptr) const override; diff --git a/src/opentimelineio/composable.h b/src/opentimelineio/composable.h index 4f6385634b..c74ec937da 100644 --- a/src/opentimelineio/composable.h +++ b/src/opentimelineio/composable.h @@ -12,9 +12,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { class Composition; +/// @brief An object that can be composed within a Composition (such as a Track or Stack). class Composable : public SerializableObjectWithMetadata { public: + /// @brief This struct provides the Composable schema. struct Schema { static auto constexpr name = "Composable"; @@ -23,17 +25,27 @@ class Composable : public SerializableObjectWithMetadata using Parent = SerializableObjectWithMetadata; + /// @brief Create a new composable. + /// + /// @param name The name of the composable. + /// @param metadata The metadata for the clip. Composable( std::string const& name = std::string(), AnyDictionary const& metadata = AnyDictionary()); + /// @brief Return whether the composable is visible. virtual bool visible() const; + + /// @brief Return whether the composable is overlapping another item. virtual bool overlapping() const; + /// @brief Return the parent composition. Composition* parent() const { return _parent; } + /// @brief Return the duration of the composable. virtual RationalTime duration(ErrorStatus* error_status = nullptr) const; + /// @brief Return the available image bounds. virtual std::optional available_image_bounds(ErrorStatus* error_status) const; diff --git a/src/opentimelineio/composition.h b/src/opentimelineio/composition.h index f23ec57927..b65936ab1b 100644 --- a/src/opentimelineio/composition.h +++ b/src/opentimelineio/composition.h @@ -9,9 +9,13 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief Base class for an Item that contains Composables. +/// +/// Should be subclassed (for example by Track Stack), not used directly. class Composition : public Item { public: + /// @brief This struct provides the Composition schema. struct Schema { static auto constexpr name = "Composition"; @@ -20,6 +24,15 @@ class Composition : public Item using Parent = Item; + /// @brief Create a new composition. + /// + /// @param name The name of the composition. + /// @param source_range The source range of the composition. + /// @param metadata The metadata for the composition. + /// @param effects The list of effects for the composition. Note that the + /// the composition keeps a retainer to each effect. + /// @param markers The list of markers for the composition. Note that the + /// the composition keeps a retainer to each marker. Composition( std::string const& name = std::string(), std::optional const& source_range = std::nullopt, @@ -27,89 +40,118 @@ class Composition : public Item std::vector const& effects = std::vector(), std::vector const& markers = std::vector()); + /// @brief Return the kind of composition. virtual std::string composition_kind() const; + /// @brief Return the list of children. std::vector> const& children() const noexcept { return _children; } + /// @brief Clear the children. void clear_children(); + /// @brief Set the list of children. Note that the composition keeps a + /// retainer to each child. bool set_children( std::vector const& children, ErrorStatus* error_status = nullptr); + /// @brief Insert a child. Note that the composition keeps a retainer to the child. bool insert_child( int index, Composable* child, ErrorStatus* error_status = nullptr); + /// @brief Set the child at the given index. Note that the composition keeps a + /// retainer to the child. bool set_child( int index, Composable* child, ErrorStatus* error_status = nullptr); + /// @brief Remove the child at the given index. bool remove_child(int index, ErrorStatus* error_status = nullptr); + /// @brief Append the child. Note that the composition keeps a retainer to + /// the child. bool append_child(Composable* child, ErrorStatus* error_status = nullptr) { return insert_child(int(_children.size()), child, error_status); } + /// @brief Return the index of the given child. int index_of_child( Composable const* child, ErrorStatus* error_status = nullptr) const; + /// @brief Return whether this is the parent of the given child. bool is_parent_of(Composable const* other) const; + /// @brief Return the in and out handles of the given child. virtual std::pair, std::optional> handles_of_child( Composable const* child, ErrorStatus* error_status = nullptr) const; + /// @brief Return the range of the given child. virtual TimeRange range_of_child_at_index( int index, ErrorStatus* error_status = nullptr) const; + + /// @brief Return the trimmed range of the given child. virtual TimeRange trimmed_range_of_child_at_index( int index, ErrorStatus* error_status = nullptr) const; - // leaving out reference_space argument for now: + /// @brief Return the range of the given child. + /// + /// @todo Leaving out reference_space argument for now. TimeRange range_of_child( Composable const* child, ErrorStatus* error_status = nullptr) const; + + /// @brief Return the trimmed range of the given child. std::optional trimmed_range_of_child( Composable const* child, ErrorStatus* error_status = nullptr) const; + /// @brief Return the given range trimmed to this source range. std::optional trim_child_range(TimeRange child_range) const; + /// @brief Return whether this contains the given child. bool has_child(Composable* child) const; + /// @brief Return whether this contains any child clips. bool has_clips() const; + /// @brief Return the range of all children. virtual std::map range_of_all_children(ErrorStatus* error_status = nullptr) const; - // Return the child that overlaps with time search_time. - // - // If shallow_search is false, will recurse into children. + /// @brief Return the child that overlaps with the given time. + /// + /// @param search_time The search time. + /// @param error_status The return status. + /// @param shallow_search The search is recursive unless shallow_search is + /// set to true. Retainer child_at_time( RationalTime const& search_time, ErrorStatus* error_status = nullptr, bool shallow_search = false) const; - // Return all objects within the given search_range. + /// @brief Return all objects within the given search_range. virtual std::vector> children_in_range( TimeRange const& search_range, ErrorStatus* error_status = nullptr) const; - // Find child objects that match the given template type. - // - // An optional search_time may be provided to limit the search. - // - // The search is recursive unless shallow_search is set to true. + /// @brief Find child objects that match the given template type. + /// + /// @param error_status The return status. + /// @param search_range An optional range to limit the search. + /// @param shallow_search The search is recursive unless shallow_search is + /// set to true. template std::vector> find_children( ErrorStatus* error_status = nullptr, diff --git a/src/opentimelineio/deserialization.h b/src/opentimelineio/deserialization.h index 2ee044a1d8..8c4b85fd9f 100644 --- a/src/opentimelineio/deserialization.h +++ b/src/opentimelineio/deserialization.h @@ -11,11 +11,13 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief Deserialize JSON data from a string. bool deserialize_json_from_string( std::string const& input, std::any* destination, ErrorStatus* error_status = nullptr); +/// @brief Deserialize JSON data from a file. bool deserialize_json_from_file( std::string const& file_name, std::any* destination, diff --git a/src/opentimelineio/effect.h b/src/opentimelineio/effect.h index 5d27ba24d1..f0f9e59628 100644 --- a/src/opentimelineio/effect.h +++ b/src/opentimelineio/effect.h @@ -8,9 +8,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief An effect that can be applied to an item, such as an image or audio filter. class Effect : public SerializableObjectWithMetadata { public: + /// @brief This struct provides the Effect schema. struct Schema { static auto constexpr name = "Effect"; @@ -19,21 +21,31 @@ class Effect : public SerializableObjectWithMetadata using Parent = SerializableObjectWithMetadata; + /// @brief Create a new effect. + /// + /// @param name The name of the effect object. + /// @param name The name of the effect. + /// @param metadata The metadata for the clip. + /// @param enabled Whether the effect is enabled. Effect( std::string const& name = std::string(), std::string const& effect_name = std::string(), AnyDictionary const& metadata = AnyDictionary(), bool enabled = true); + /// @brief Return the effect name. std::string effect_name() const noexcept { return _effect_name; } + /// @brief Set the effect name. void set_effect_name(std::string const& effect_name) { _effect_name = effect_name; } + /// @brief Return whether the effect is enabed. bool enabled() const { return _enabled; }; + /// @brief Set whether the effect is enabled. void set_enabled(bool enabled) { _enabled = enabled; } protected: diff --git a/src/opentimelineio/errorStatus.h b/src/opentimelineio/errorStatus.h index 67a8059fdc..eafff9e230 100644 --- a/src/opentimelineio/errorStatus.h +++ b/src/opentimelineio/errorStatus.h @@ -10,8 +10,10 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { class SerializableObject; +/// @brief This struct represents the return status of a function. struct ErrorStatus { + /// @brief This enumeration represents the possible outcomes. enum Outcome { OK = 0, @@ -45,11 +47,13 @@ struct ErrorStatus NOT_A_GAP }; + /// @brief Construct a new status with no error. ErrorStatus() : outcome(OK) , object_details(nullptr) {} + /// @brief Construct a new status with the given outcome. ErrorStatus(Outcome in_outcome) : outcome(in_outcome) , details(outcome_to_string(in_outcome)) @@ -57,6 +61,7 @@ struct ErrorStatus , object_details(nullptr) {} + /// @brief Construct a new status with the given outcome, details, and object. ErrorStatus( Outcome in_outcome, std::string const& in_details, @@ -67,28 +72,37 @@ struct ErrorStatus , object_details(object) {} + /// @brief Copy operator. ErrorStatus& operator=(Outcome in_outcome) { *this = ErrorStatus(in_outcome); return *this; } - Outcome outcome; - std::string details; - std::string full_description; + /// @brief The outcome of the function. + Outcome outcome; + + /// @brief A human readable string that provides details about the outcome. + std::string details; + + /// @brief A human readable string that provides the full description of the status. + std::string full_description; + + /// @brief The object related to the status. SerializableObject const* object_details; + //! @brief Return a human readable string for the given outcome. static std::string outcome_to_string(Outcome); }; -// Check whether the given ErrorStatus is an error. +/// @brief Check whether the given ErrorStatus is an error. constexpr bool is_error(const ErrorStatus& es) noexcept { return ErrorStatus::Outcome::OK != es.outcome; } -// Check whether the given ErrorStatus* is non-null and an error. +/// @brief Check whether the given ErrorStatus* is non-null and an error. constexpr bool is_error(const ErrorStatus* es) noexcept { diff --git a/src/opentimelineio/externalReference.h b/src/opentimelineio/externalReference.h index 6488fc8730..ac6fdebc7e 100644 --- a/src/opentimelineio/externalReference.h +++ b/src/opentimelineio/externalReference.h @@ -8,9 +8,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief A reference to a media file. class ExternalReference final : public MediaReference { public: + /// @brief This struct provides the ExternalReference schema. struct Schema { static auto constexpr name = "ExternalReference"; @@ -19,6 +21,12 @@ class ExternalReference final : public MediaReference using Parent = MediaReference; + /// @brief Create a new external reference. + /// + /// @param target_url The URL to the media. + /// @param available_range The available range of the media. + /// @param metadata The metadata for the media. + /// @param available_image_bounds The spatial bounds of the media. ExternalReference( std::string const& target_url = std::string(), std::optional const& available_range = std::nullopt, @@ -26,8 +34,10 @@ class ExternalReference final : public MediaReference std::optional const& available_image_bounds = std::nullopt); + /// @brief Return the media file URL. std::string target_url() const noexcept { return _target_url; } + /// @brief Set the media file URL. void set_target_url(std::string const& target_url) { _target_url = target_url; diff --git a/src/opentimelineio/freezeFrame.h b/src/opentimelineio/freezeFrame.h index ca025e6bc2..397eb15095 100644 --- a/src/opentimelineio/freezeFrame.h +++ b/src/opentimelineio/freezeFrame.h @@ -8,9 +8,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief Hold the first frame of the clip for the duration of the clip. class FreezeFrame : public LinearTimeWarp { public: + /// @brief This struct provides the FreezeFrame schema. struct Schema { static auto constexpr name = "FreezeFrame"; @@ -19,6 +21,10 @@ class FreezeFrame : public LinearTimeWarp using Parent = LinearTimeWarp; + /// @brief Create a new freeze frame time effect. + /// + /// @param name The name of the time effect. + /// @param metadata The metadata for the time effect. FreezeFrame( std::string const& name = std::string(), AnyDictionary const& metadata = AnyDictionary()); diff --git a/src/opentimelineio/gap.h b/src/opentimelineio/gap.h index e1d4cc7e3f..149a759aa2 100644 --- a/src/opentimelineio/gap.h +++ b/src/opentimelineio/gap.h @@ -9,9 +9,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief An empty item within a timeline. class Gap : public Item { public: + /// @brief This struct provides the Gap schema. struct Schema { static auto constexpr name = "Gap"; @@ -20,12 +22,30 @@ class Gap : public Item using Parent = Item; + /// @brief Create a new gap. + /// + /// @param source_range The source range of the gap. + /// @param name The name of the gap. + /// @param effects The list of effects for the gap. Note that the + /// the gap keeps a retainer to each effect. + /// @param markers The list of markers for the gap. Note that the + /// the gap keeps a retainer to each marker. + /// @param metadata The metadata for the gap. Gap(TimeRange const& source_range = TimeRange(), std::string const& name = std::string(), std::vector const& effects = std::vector(), std::vector const& markers = std::vector(), AnyDictionary const& metadata = AnyDictionary()); + /// @brief Create a new gap. + /// + /// @param duration The duration of the gap. + /// @param name The name of the gap. + /// @param effects The list of effects for the gap. Note that the + /// the gap keeps a retainer to each effect. + /// @param markers The list of markers for the gap. Note that the + /// the gap keeps a retainer to each marker. + /// @param metadata The metadata for the gap. Gap(RationalTime duration, std::string const& name = std::string(), std::vector const& effects = std::vector(), diff --git a/src/opentimelineio/generatorReference.h b/src/opentimelineio/generatorReference.h index 1bbb21e5a8..9a247cdfe6 100644 --- a/src/opentimelineio/generatorReference.h +++ b/src/opentimelineio/generatorReference.h @@ -8,9 +8,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief A reference to dynamically generated media. class GeneratorReference final : public MediaReference { public: + /// @brief This struct provides the GeneratorReference schema. struct Schema { static auto constexpr name = "GeneratorReference"; @@ -19,6 +21,14 @@ class GeneratorReference final : public MediaReference using Parent = MediaReference; + /// @brief Create a new generator reference. + /// + /// @param name The name of the generator. + /// @param generator_kind The kind of generator. + /// @param available_range The available range of the generator. + /// @param parameters The parameters used to configure the generator. + /// @param metadata The metadata for the generator. + /// @param available_image_bounds The spatial bounds of the generator. GeneratorReference( std::string const& name = std::string(), std::string const& generator_kind = std::string(), @@ -28,15 +38,19 @@ class GeneratorReference final : public MediaReference std::optional const& available_image_bounds = std::nullopt); + /// @brief Return the kind of generator. std::string generator_kind() const noexcept { return _generator_kind; } + /// @brief Set the kind of generator. void set_generator_kind(std::string const& generator_kind) { _generator_kind = generator_kind; } + /// @brief Modify the generator parameters. AnyDictionary& parameters() noexcept { return _parameters; } + /// @brief Return the generator parameters. AnyDictionary parameters() const noexcept { return _parameters; } protected: diff --git a/src/opentimelineio/imageSequenceReference.h b/src/opentimelineio/imageSequenceReference.h index 5821c1aacc..7af3296e6c 100644 --- a/src/opentimelineio/imageSequenceReference.h +++ b/src/opentimelineio/imageSequenceReference.h @@ -8,9 +8,19 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief A reference to an image sequence. +/// +/// Image file names are composed from a target URL base, name prefix, name +/// suffix, frame number, and zero padding. For example the image file name +/// "file:///path/to/image.000100.exr": +/// * Target URL base: file:///path/to/ +/// * Name prefix: "image." +/// * Name suffix: ".exr" +/// * Frame number padded to six zeroes: "000100" class ImageSequenceReference final : public MediaReference { public: + /// @brief How to handle missing frames. enum MissingFramePolicy { error = 0, @@ -18,6 +28,7 @@ class ImageSequenceReference final : public MediaReference black = 2 }; + /// @brief This struct provides the ImageSequenceReference schema. struct Schema { static auto constexpr name = "ImageSequenceReference"; @@ -26,6 +37,19 @@ class ImageSequenceReference final : public MediaReference using Parent = MediaReference; + /// @brief Create a new image sequence reference. + /// + /// @param target_url_base The base of the URL. + /// @param name_prefix The prefix of the file name. + /// @param name_suffix The suffix of the file name. + /// @param start_frame The start frame of the image sequence. + /// @param frame_step The frame step of the image sequence. + /// @param rate The frame rate of the image sequence. + /// @param frame_zero_padding The number of zeroes used to pad the frame numbers. + /// @param missing_frame_policy How to handle missing frames. + /// @param available_range The available range of the image sequence. + /// @param metadata The metadata for the image sequence. + /// @param available_image_bounds The spatial bounds of the image sequence. ImageSequenceReference( std::string const& target_url_base = std::string(), std::string const& name_prefix = std::string(), @@ -41,70 +65,93 @@ class ImageSequenceReference final : public MediaReference std::optional const& available_image_bounds = std::nullopt); + /// @brief Return the URL base. std::string target_url_base() const noexcept { return _target_url_base; } + /// @brief Set the URL base. void set_target_url_base(std::string const& target_url_base) { _target_url_base = target_url_base; } + /// @brief Return the file name prefix. std::string name_prefix() const noexcept { return _name_prefix; } + /// @brief Set the file name prefix. void set_name_prefix(std::string const& target_url_base) { _name_prefix = target_url_base; } + /// @brief Return the file name suffix. std::string name_suffix() const noexcept { return _name_suffix; } + /// @brief Set the file name suffix. void set_name_suffix(std::string const& target_url_base) { _name_suffix = target_url_base; } + /// @brief Return the start frame. int start_frame() const noexcept { return _start_frame; } + /// @brief Set the start frame. void set_start_frame(int start_frame) noexcept { _start_frame = start_frame; } + /// @brief Return the frame step. int frame_step() const noexcept { return _frame_step; } + /// @brief Set the frame step. void set_frame_step(int frame_step) noexcept { _frame_step = frame_step; } + /// @brief Return the frame rate. double rate() const noexcept { return _rate; } + /// @brief Set the frame rate. void set_rate(double rate) noexcept { _rate = rate; } + /// @brief Return the frame number zero padding. int frame_zero_padding() const noexcept { return _frame_zero_padding; } + /// @brief Set the frame number zero padding. void set_frame_zero_padding(int frame_zero_padding) noexcept { _frame_zero_padding = frame_zero_padding; } + /// @brief Set the missing frame policy. void set_missing_frame_policy(MissingFramePolicy missing_frame_policy) noexcept { _missing_frame_policy = missing_frame_policy; } + /// @brief Return the missing frame policy. MissingFramePolicy missing_frame_policy() const noexcept { return _missing_frame_policy; } + /// @brief Return the end frame. int end_frame() const; + + /// @brief Return the number of images in the sequence. int number_of_images_in_sequence() const; + + /// @brief Return the frame for the given time. int frame_for_time( RationalTime const& time, ErrorStatus* error_status = nullptr) const; + /// @brief Return the target URL for the given image number. std::string target_url_for_image_number( int image_number, ErrorStatus* error_status = nullptr) const; + /// @brief Return the presentation time for the given image number. RationalTime presentation_time_for_image_number( int image_number, ErrorStatus* error_status = nullptr) const; diff --git a/src/opentimelineio/item.h b/src/opentimelineio/item.h index 9e64c8ed51..80d341e110 100644 --- a/src/opentimelineio/item.h +++ b/src/opentimelineio/item.h @@ -13,9 +13,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { class Effect; class Marker; +/// @brief An item in the timeline. class Item : public Composable { public: + /// @brief This struct provides the Item schema. struct Schema { static auto constexpr name = "Item"; @@ -24,6 +26,16 @@ class Item : public Composable using Parent = Composable; + /// @brief Create a new item. + /// + /// @param name The name of the item. + /// @param source_range The source range of the item. + /// @param metadata The metadata for the item. + /// @param effects The list of effects for the item. Note that the + /// the item keeps a retainer to each effect. + /// @param markers The list of markers for the item. Note that the + /// the item keeps a retainer to each marker. + /// @param enabled Whether the item is enabled. Item( std::string const& name = std::string(), std::optional const& source_range = std::nullopt, @@ -35,29 +47,37 @@ class Item : public Composable bool visible() const override; bool overlapping() const override; + /// @brief Return whether the item is enabled. bool enabled() const { return _enabled; }; + /// @brief Set whether the item is enabled. void set_enabled(bool enabled) { _enabled = enabled; } + /// @brief Return the source range of the item. std::optional source_range() const noexcept { return _source_range; } + /// @brief Set the source range of the item. void set_source_range(std::optional const& source_range) { _source_range = source_range; } + /// @brief Modify the list of effects. std::vector>& effects() noexcept { return _effects; } + /// @brief Return the list of effects. std::vector> const& effects() const noexcept { return _effects; } + /// @brief Modify the list of markers. std::vector>& markers() noexcept { return _markers; } + /// @brief Return the list of markers. std::vector> const& markers() const noexcept { return _markers; @@ -65,26 +85,33 @@ class Item : public Composable RationalTime duration(ErrorStatus* error_status = nullptr) const override; + /// @brief Return the available range of the item. virtual TimeRange available_range(ErrorStatus* error_status = nullptr) const; + /// @brief Return the trimmed range of the item. TimeRange trimmed_range(ErrorStatus* error_status = nullptr) const { return _source_range ? *_source_range : available_range(error_status); } + /// @brief Return the visible range of the item. TimeRange visible_range(ErrorStatus* error_status = nullptr) const; + /// @brief Return the trimmed range of the item in the parent's time. std::optional trimmed_range_in_parent(ErrorStatus* error_status = nullptr) const; + /// @brief Return the range of the item in the parent's time. TimeRange range_in_parent(ErrorStatus* error_status = nullptr) const; + /// @brief Return the time transformed to another item in the hierarchy. RationalTime transformed_time( RationalTime time, Item const* to_item, ErrorStatus* error_status = nullptr) const; + /// @brief Return the time range transformed to another item in the hierarchy. TimeRange transformed_time_range( TimeRange time_range, Item const* to_item, diff --git a/src/opentimelineio/linearTimeWarp.h b/src/opentimelineio/linearTimeWarp.h index e4daaf13d8..df142a7567 100644 --- a/src/opentimelineio/linearTimeWarp.h +++ b/src/opentimelineio/linearTimeWarp.h @@ -8,9 +8,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief A time warp that applies a linear speed up or slow down across the entire clip. class LinearTimeWarp : public TimeEffect { public: + /// @brief This struct provides the LinearTimeWarp schema. struct Schema { static auto constexpr name = "LinearTimeWarp"; @@ -19,14 +21,22 @@ class LinearTimeWarp : public TimeEffect using Parent = TimeEffect; + /// @brief Create a new linear time warp effect. + /// + /// @param name The name of the time effect object. + /// @param effect_name The name of the time effect. + /// @param time_scalar The amount to scale the time. + /// @param metadata The metadata for the time effect. LinearTimeWarp( std::string const& name = std::string(), std::string const& effect_name = std::string(), double time_scalar = 1, AnyDictionary const& metadata = AnyDictionary()); + /// @brief Return the amount to scale the time. double time_scalar() const noexcept { return _time_scalar; } + /// @brief Set the amount to scale the time. void set_time_scalar(double time_scalar) noexcept { _time_scalar = time_scalar; diff --git a/src/opentimelineio/marker.h b/src/opentimelineio/marker.h index 625bb42fc2..23f10fc9ba 100644 --- a/src/opentimelineio/marker.h +++ b/src/opentimelineio/marker.h @@ -8,9 +8,15 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief A marker indicates a marked range of time on an item in a timeline, +/// usually with a name, color or other metadata. +/// +/// The marked range may have a zero duration. The marked range is in the +/// owning item's time coordinate system. class Marker : public SerializableObjectWithMetadata { public: + /// @brief This struct provides the base set of colors. struct Color { static auto constexpr pink = "PINK"; @@ -26,6 +32,7 @@ class Marker : public SerializableObjectWithMetadata static auto constexpr white = "WHITE"; }; + /// @brief This struct provides the Marker schema. struct Schema { static auto constexpr name = "Marker"; @@ -34,6 +41,13 @@ class Marker : public SerializableObjectWithMetadata using Parent = SerializableObjectWithMetadata; + /// @brief Create a new marker. + /// + /// @param name The name of the marker. + /// @param marked_range The time range of the marker. + /// @param color The color associated with the marker. + /// @param metadata The metadata for the marker. + /// @param comment The text comment for the marker. Marker( std::string const& name = std::string(), TimeRange const& marked_range = TimeRange(), @@ -41,19 +55,25 @@ class Marker : public SerializableObjectWithMetadata AnyDictionary const& metadata = AnyDictionary(), std::string const& comment = std::string()); + /// @brief Return the marker color. std::string color() const noexcept { return _color; } + /// @brief Set the marker color. void set_color(std::string const& color) { _color = color; } + /// @brief Return the marker time range. TimeRange marked_range() const noexcept { return _marked_range; } + /// @brief Set the marker time range. void set_marked_range(TimeRange const& marked_range) noexcept { _marked_range = marked_range; } + /// @brief Return the marker comment. std::string comment() const noexcept { return _comment; } + /// @brief Set the marker comment. void set_comment(std::string const& comment) { _comment = comment; } protected: diff --git a/src/opentimelineio/mediaReference.h b/src/opentimelineio/mediaReference.h index 63fa70c0a6..3787c26638 100644 --- a/src/opentimelineio/mediaReference.h +++ b/src/opentimelineio/mediaReference.h @@ -12,9 +12,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { using namespace opentime; +/// @brief A reference to a piece of media, for example a movie on a clip. class MediaReference : public SerializableObjectWithMetadata { public: + /// @brief This struct provides the MediaReference schema. struct Schema { static auto constexpr name = "MediaReference"; @@ -23,6 +25,12 @@ class MediaReference : public SerializableObjectWithMetadata using Parent = SerializableObjectWithMetadata; + /// @brief Create a new media reference. + /// + /// @param name The name of the media reference. + /// @param available_range The available range of the media reference. + /// @param metadata The metadata for the media reference. + /// @param available_image_bounds The spatial bounds of the media reference. MediaReference( std::string const& name = std::string(), std::optional const& available_range = std::nullopt, @@ -30,23 +38,28 @@ class MediaReference : public SerializableObjectWithMetadata std::optional const& available_image_bounds = std::nullopt); + /// @brief Return the available range of the media reference. std::optional available_range() const noexcept { return _available_range; } + /// @brief Set the available range of the media reference. void set_available_range(std::optional const& available_range) { _available_range = available_range; } + /// @brief Return whether the reference is missing. virtual bool is_missing_reference() const; + /// @brief Return the spatial bounds of the media reference. std::optional available_image_bounds() const { return _available_image_bounds; } + /// @brief Set the spatial bounds of the media reference. void set_available_image_bounds( std::optional const& available_image_bounds) { diff --git a/src/opentimelineio/missingReference.h b/src/opentimelineio/missingReference.h index f64c7449c3..5f24786214 100644 --- a/src/opentimelineio/missingReference.h +++ b/src/opentimelineio/missingReference.h @@ -8,9 +8,14 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief Represents media for which a concrete reference is missing. +/// +/// Note that a missing reference may have useful metadata, even if the +/// location of the media is not known. class MissingReference final : public MediaReference { public: + /// @brief This struct provides the MissingReference schema. struct Schema { static auto constexpr name = "MissingReference"; @@ -19,6 +24,12 @@ class MissingReference final : public MediaReference using Parent = MediaReference; + /// @brief Create a new missing reference. + /// + /// @param name The name of the missing reference. + /// @param available_range The available range of the missing reference. + /// @param metadata The metadata for the missing reference. + /// @param available_image_bounds The spatial bounds for the missing reference. MissingReference( std::string const& name = std::string(), std::optional const& available_range = std::nullopt, diff --git a/src/opentimelineio/safely_typed_any.h b/src/opentimelineio/safely_typed_any.h index 6eae1c5416..2fef66da6c 100644 --- a/src/opentimelineio/safely_typed_any.h +++ b/src/opentimelineio/safely_typed_any.h @@ -3,21 +3,21 @@ #pragma once -/** - * This file/interface exists only so that we can package/unpackage - * types with code compiled in one specific library to avoid the - * type-aliasing problem that any's are subject to. - * - * Specifically, if you put the same type T in an any from two - * different libraries across a shared-library boundary, then - * the actual typeid the any records depends on the library that - * actually packaged the any. Ditto when trying to pull it out. - * - * The solution is to have all the unpacking/packing code for the - * types you care about be instantiated not in headers, but in source - * code, within one common library. That's why the seemingly - * silly code in safely_typed_any.cpp exists. - */ +/// @file safely_typed_any.h +/// +/// This file/interface exists only so that we can package/unpackage +/// types with code compiled in one specific library to avoid the type-aliasing +/// problem that any's are subject to. +/// +/// Specifically, if you put the same type T in an any from two different +/// libraries across a shared-library boundary, then the actual typeid the any +/// records depends on the library that actually packaged the any. Ditto when +/// trying to pull it out. +/// +/// The solution is to have all the unpacking/packing code for the types you +/// care about be instantiated not in headers, but in source code, within one +/// common library. That's why the seemingly silly code in safely_typed_any.cpp +/// exists. #include "opentime/rationalTime.h" #include "opentime/timeRange.h" @@ -27,6 +27,9 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @name Any Create +///@{ + std::any create_safely_typed_any(bool&&); std::any create_safely_typed_any(int&&); std::any create_safely_typed_any(int64_t&&); @@ -42,6 +45,11 @@ std::any create_safely_typed_any(AnyVector&&); std::any create_safely_typed_any(AnyDictionary&&); std::any create_safely_typed_any(SerializableObject*); +///@} + +/// @name Any Casting +///@{ + bool safely_cast_bool_any(std::any const& a); int safely_cast_int_any(std::any const& a); int64_t safely_cast_int64_any(std::any const& a); @@ -59,8 +67,10 @@ SerializableObject* safely_cast_retainer_any(std::any const& a); AnyDictionary safely_cast_any_dictionary_any(std::any const& a); AnyVector safely_cast_any_vector_any(std::any const& a); -// don't use these unless you know what you're doing... +/// @bug Don't use these unless you know what you're doing... AnyDictionary& temp_safely_cast_any_dictionary_any(std::any const& a); AnyVector& temp_safely_cast_any_vector_any(std::any const& a); +///@} + }} // namespace opentimelineio::OPENTIMELINEIO_VERSION diff --git a/src/opentimelineio/serializableCollection.h b/src/opentimelineio/serializableCollection.h index 45da161292..1d4e1f659f 100644 --- a/src/opentimelineio/serializableCollection.h +++ b/src/opentimelineio/serializableCollection.h @@ -12,9 +12,20 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { class Clip; +/// @brief A container which can hold an ordered list of any serializable objects. +/// +/// Note that this is not a Composition nor is it Composable. +/// +/// This container approximates the concept of a bin - a collection of +/// SerializableObjects that do not have any compositional meaning, but can +/// serialize to/from OTIO correctly, with metadata and a named collection. +/// +/// A SerializableCollection is useful for serializing multiple timelines, +/// clips, or media references to a single file. class SerializableCollection : public SerializableObjectWithMetadata { public: + /// @brief This struct provides the SerializableCollection schema. struct Schema { static auto constexpr name = "SerializableCollection"; @@ -23,50 +34,67 @@ class SerializableCollection : public SerializableObjectWithMetadata using Parent = SerializableObjectWithMetadata; + /// @brief Create a new serializable collection. + /// + /// @param name The name of the collection. + /// @param child The list of children in the collection. Note that the + /// collection keeps a retainer to each child. + /// @param metadata The metadata for the collection. SerializableCollection( std::string const& name = std::string(), std::vector children = std::vector(), AnyDictionary const& metadata = AnyDictionary()); + /// @brief Return the list of children. std::vector> const& children() const noexcept { return _children; } + /// @brief Modify the list of children. std::vector>& children() noexcept { return _children; } + /// @brief Set the list of children. void set_children(std::vector const& children); + /// @brief Clear the children. void clear_children(); + /// @brief Insert a child at the given index. Note that the collection + /// keeps a retainer to the child. void insert_child(int index, SerializableObject* child); + /// @brief Set the child at the given index. Note that the collection + /// keeps a retainer to the child. bool set_child( int index, SerializableObject* child, ErrorStatus* error_status = nullptr); + /// @brief Remove the child at the given index. bool remove_child(int index, ErrorStatus* error_status = nullptr); - // Find child clips. - // - // An optional search_range may be provided to limit the search. - // - // The search is recursive unless shallow_search is set to true. + /// @brief Find child clips. + /// + /// @param error_status The return status. + /// @param search_range An optional range to limit the search. + /// @param shallow_search The search is recursive unless shallow_search is + /// set to true. std::vector> find_clips( ErrorStatus* error_status = nullptr, std::optional const& search_range = std::nullopt, bool shallow_search = false) const; - // Find child objects that match the given template type. - // - // An optional search_time may be provided to limit the search. - // - // The search is recursive unless shallow_search is set to true. + /// @brief Find child objects that match the given template type. + /// + /// @param error_status The return status. + /// @param search_range An optional range to limit the search. + /// @param shallow_search The search is recursive unless shallow_search is + /// set to true. template std::vector> find_children( ErrorStatus* error_status = nullptr, diff --git a/src/opentimelineio/serializableObject.h b/src/opentimelineio/serializableObject.h index 7f0dc8dcb3..63b096a038 100644 --- a/src/opentimelineio/serializableObject.h +++ b/src/opentimelineio/serializableObject.h @@ -23,62 +23,90 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { class CloningEncoder; +/// @brief A serializable object. class SerializableObject { public: + /// @brief This struct provides the SerializableObject schema. struct Schema { static auto constexpr name = "SerializableObject"; static int constexpr version = 1; }; + /// @brief Create a new serializable object. SerializableObject(); - /** - * You cannot directly delete a SerializableObject* (or, hopefully, anything - * derived from it, as all derivations are required to protect the destructor). - * - * Instead, call the member function possibly_delete(), which deletes the object - * (and, recursively, the objects owned by this object), provided the objects - * are not under external management (e.g. prevented from being deleted because an - * external scripting system is holding a reference to them). - */ + /// @brief Delete a serializable object. + /// + /// You cannot directly delete a SerializableObject* (or, hopefully, anything + /// derived from it, as all derivations are required to protect the destructor). + /// + /// Instead, call the member function possibly_delete(), which deletes the object + /// (and, recursively, the objects owned by this object), provided the objects + /// are not under external management (e.g. prevented from being deleted because an + /// external scripting system is holding a reference to them). bool possibly_delete(); + /// @brief Serialize this object to a JSON file. + /// + /// @param file_name The file name. + /// @param error_status The return status. + /// @param target_family_label_spec @todo Add comment. + /// @param indent The number of spaces to use for indentation. bool to_json_file( std::string const& file_name, ErrorStatus* error_status = nullptr, const schema_version_map* target_family_label_spec = nullptr, int indent = 4) const; + /// @brief Serialize this object to a JSON string. + /// + /// @param error_status The return status. + /// @param target_family_label_spec @todo Add comment. + /// @param indent The number of spaces to use for indentation. std::string to_json_string( ErrorStatus* error_status = nullptr, const schema_version_map* target_family_label_spec = nullptr, int indent = 4) const; + /// @brief Deserialize this object from a JSON file. + /// + /// @param file_name The file name. + /// @param error_status The return status. static SerializableObject* from_json_file( std::string const& file_name, ErrorStatus* error_status = nullptr); + + /// @brief Deserialize this object from a JSON file. + /// + /// @param input The input string. + /// @param error_status The return status. static SerializableObject* from_json_string( std::string const& input, ErrorStatus* error_status = nullptr); + /// @brief Return whether this object is equivalent to another. bool is_equivalent_to(SerializableObject const& other) const; - // Makes a (deep) clone of this instance. - // - // Descendent SerializableObjects are cloned as well. - // If the operation fails, nullptr is returned and error_status - // is set appropriately. + /// @brief Makes a (deep) clone of this instance. + /// + /// Descendent objects are cloned as well. + /// + /// If the operation fails, nullptr is returned and error_status + /// is set appropriately. SerializableObject* clone(ErrorStatus* error_status = nullptr) const; - // Allow external system (e.g. Python, Swift) to add serializable fields - // on the fly. C++ implementations should have no need for this functionality. + /// @brief Allow external system (e.g. Python, Swift) to add serializable + /// fields on the fly. + /// + /// C++ implementations should have no need for this functionality. AnyDictionary& dynamic_fields() { return _dynamic_fields; } template struct Retainer; + /// @brief This class provides reading functionality. class Reader { public: @@ -403,6 +431,7 @@ class SerializableObject friend class TypeRegistry; }; + /// @brief This class provides writing functionality. class Writer { public: @@ -448,9 +477,9 @@ class SerializableObject } private: + /// Convenience routines for converting various STL structures of specific + /// types to a parallel hierarchy holding std::any. ///@{ - /** Convenience routines for converting various STL structures of specific - types to a parallel hierarchy holding std::anys!. */ template static std::any _to_any(std::vector const& value) @@ -518,6 +547,7 @@ class SerializableObject { return std::any(value); } + ///@} Writer( @@ -567,15 +597,22 @@ class SerializableObject friend class SerializableObject; }; + /// @brief Deserialize from the given reader. virtual bool read_from(Reader&); + + /// @brief Serialize to the given writer. virtual void write_to(Writer&) const; + /// @brief Return whether this schema is unknown. virtual bool is_unknown_schema() const; + /// @brief Return the schema name. std::string schema_name() const { return _type_record()->schema_name; } + /// @brief Return the schema version. int schema_version() const { return _type_record()->schema_version; } + /// @brief This struct provides similar functionality to a smart pointer. template struct Retainer { @@ -646,6 +683,7 @@ class SerializableObject void _managed_release(); public: + /// @brief This struct provides a reference ID. struct ReferenceId { std::string id; @@ -655,12 +693,15 @@ class SerializableObject } }; + /// @todo Add comment. void install_external_keepalive_monitor( std::function monitor, bool apply_now); + /// @brief Return the current reference count. int current_ref_count() const; + /// @brief This struct provides an unknown type. struct UnknownType { std::string type_name; diff --git a/src/opentimelineio/serializableObjectWithMetadata.h b/src/opentimelineio/serializableObjectWithMetadata.h index 3535aa02f5..df680d26b4 100644 --- a/src/opentimelineio/serializableObjectWithMetadata.h +++ b/src/opentimelineio/serializableObjectWithMetadata.h @@ -8,9 +8,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief A serializable object with metadata. class SerializableObjectWithMetadata : public SerializableObject { public: + /// @brief This struct provides the SerializableObjectWithMetadata schema. struct Schema { static auto constexpr name = "SerializableObjectWithMetadata"; @@ -19,16 +21,24 @@ class SerializableObjectWithMetadata : public SerializableObject using Parent = SerializableObject; + /// @brief Create a new serializable object. + /// + /// @param name The object name. + /// @param metadata The metadata for the object. SerializableObjectWithMetadata( std::string const& name = std::string(), AnyDictionary const& metadata = AnyDictionary()); + /// @brief Return the object name. std::string name() const noexcept { return _name; } + /// @brief Set the object name. void set_name(std::string const& name) { _name = name; } + /// @brief Modify the object metadata. AnyDictionary& metadata() noexcept { return _metadata; } + /// @brief Return the object metadata. AnyDictionary metadata() const noexcept { return _metadata; } protected: diff --git a/src/opentimelineio/serialization.h b/src/opentimelineio/serialization.h index 292171db82..ea43cf8ed0 100644 --- a/src/opentimelineio/serialization.h +++ b/src/opentimelineio/serialization.h @@ -13,12 +13,14 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief Serialize JSON data to a string. std::string serialize_json_to_string( const std::any& value, const schema_version_map* schema_version_targets = nullptr, ErrorStatus* error_status = nullptr, int indent = 4); +/// @brief Serialize JSON data to a file. bool serialize_json_to_file( const std::any& value, std::string const& file_name, diff --git a/src/opentimelineio/stack.h b/src/opentimelineio/stack.h index 6645cb7802..3894d91ad4 100644 --- a/src/opentimelineio/stack.h +++ b/src/opentimelineio/stack.h @@ -10,9 +10,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { class Clip; +/// @brief A stack of items in a timeline, for example a stack of tracks in a timelime. class Stack : public Composition { public: + /// @brief This struct provides the Stack schema. struct Schema { static auto constexpr name = "Stack"; @@ -21,6 +23,15 @@ class Stack : public Composition using Parent = Composition; + /// @brief Create a new stack. + /// + /// @param name The name of the stack. + /// @param source_range The source range of the stack. + /// @param metadata The metadata for the stack. + /// @param effects The list of effects for the stack. Note that the + /// the stack keeps a retainer to each effect. + /// @param markers The list of markers for the stack. Note that the + /// the stack keeps a retainer to each marker. Stack( std::string const& name = std::string(), std::optional const& source_range = std::nullopt, @@ -47,11 +58,12 @@ class Stack : public Composition std::optional available_image_bounds(ErrorStatus* error_status) const override; - // Find child clips. - // - // An optional search_range may be provided to limit the search. - // - // The search is recursive unless shallow_search is set to true. + /// @brief Find child clips. + /// + /// @param error_status The return status. + /// @param search_range An optional range to limit the search. + /// @param shallow_search The search is recursive unless shallow_search is + /// set to true. std::vector> find_clips( ErrorStatus* error_status = nullptr, std::optional const& search_range = std::nullopt, diff --git a/src/opentimelineio/stackAlgorithm.h b/src/opentimelineio/stackAlgorithm.h index 7fb22af8a5..8800636109 100644 --- a/src/opentimelineio/stackAlgorithm.h +++ b/src/opentimelineio/stackAlgorithm.h @@ -9,7 +9,10 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief Flatten a stack down to a single track. Track* flatten_stack(Stack* in_stack, ErrorStatus* error_status = nullptr); + +/// @brief Flatten a list of tracks down to a single track. Track* flatten_stack( std::vector const& tracks, ErrorStatus* error_status = nullptr); diff --git a/src/opentimelineio/stringUtils.h b/src/opentimelineio/stringUtils.h index 725abc167e..10a7313c03 100644 --- a/src/opentimelineio/stringUtils.h +++ b/src/opentimelineio/stringUtils.h @@ -12,6 +12,9 @@ using opentime::string_printf; namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @name String Utilities +///@{ + void fatal_error(std::string const& errMsg); std::string type_name_for_error_message(std::type_info const&); @@ -30,4 +33,6 @@ bool split_schema_string( std::string* schema_name, int* schema_version); +///@} + }} // namespace opentimelineio::OPENTIMELINEIO_VERSION diff --git a/src/opentimelineio/timeEffect.h b/src/opentimelineio/timeEffect.h index c901470904..515fd293f6 100644 --- a/src/opentimelineio/timeEffect.h +++ b/src/opentimelineio/timeEffect.h @@ -8,9 +8,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief Base class for all effects that alter the timing of an item. class TimeEffect : public Effect { public: + /// @brief This struct provides the TimeEffect schema. struct Schema { static auto constexpr name = "TimeEffect"; @@ -19,6 +21,11 @@ class TimeEffect : public Effect using Parent = Effect; + /// @brief Create a new time effect. + /// + /// @param name The name of the object. + /// @param effect_name The time effect name. + /// @param metadata The metadata for the time effect. TimeEffect( std::string const& name = std::string(), std::string const& effect_name = std::string(), diff --git a/src/opentimelineio/timeline.h b/src/opentimelineio/timeline.h index ab0f675006..d18c629d83 100644 --- a/src/opentimelineio/timeline.h +++ b/src/opentimelineio/timeline.h @@ -12,9 +12,11 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { class Clip; +/// @brief A timeline contains a stack of tracks. class Timeline : public SerializableObjectWithMetadata { public: + /// @brief This struct provides the Timeline schema. struct Schema { static auto constexpr name = "Timeline"; @@ -23,11 +25,17 @@ class Timeline : public SerializableObjectWithMetadata using Parent = SerializableObjectWithMetadata; + /// @brief Create a new timelime. + /// + /// @param name The timeline name. + /// @param global_start_time The global start time of the timeline. + /// @param metadata The metadata for the timeline. Timeline( std::string const& name = std::string(), std::optional global_start_time = std::nullopt, AnyDictionary const& metadata = AnyDictionary()); + /// @brief Return the timeline stack. Stack* tracks() const noexcept { return _tracks; } /* @@ -35,24 +43,29 @@ class Timeline : public SerializableObjectWithMetadata return _tracks; }*/ + /// @brief Set the timeline stack. void set_tracks(Stack* stack); + /// @brief Return the global start time. std::optional global_start_time() const noexcept { return _global_start_time; } + /// @brief Set the global start time. void set_global_start_time(std::optional const& global_start_time) { _global_start_time = global_start_time; } + /// @brief Return the duration of the timeline. RationalTime duration(ErrorStatus* error_status = nullptr) const { return _tracks.value->duration(error_status); } + /// @brief Return the range of the given child. TimeRange range_of_child( Composable const* child, ErrorStatus* error_status = nullptr) const @@ -60,30 +73,36 @@ class Timeline : public SerializableObjectWithMetadata return _tracks.value->range_of_child(child, error_status); } + /// @brief Return the list of audio tracks. std::vector audio_tracks() const; + + /// @brief Return the list of video tracks. std::vector video_tracks() const; - // Find child clips. - // - // An optional search_range may be provided to limit the search. - // - // The search is recursive unless shallow_search is set to true. + /// @brief Find child clips. + /// + /// @param error_status The return status. + /// @param search_range An optional range to limit the search. + /// @param shallow_search The search is recursive unless shallow_search is + /// set to true. std::vector> find_clips( ErrorStatus* error_status = nullptr, std::optional const& search_range = std::nullopt, bool shallow_search = false) const; - // Find child objects that match the given template type. - // - // An optional search_time may be provided to limit the search. - // - // The search is recursive unless shallow_search is set to true. + /// @brief Find child objects that match the given template type. + /// + /// @param error_status The return status. + /// @param search_range An optional range to limit the search. + /// @param shallow_search The search is recursive unless shallow_search is + /// set to true. template std::vector> find_children( ErrorStatus* error_status = nullptr, std::optional search_range = std::nullopt, bool shallow_search = false) const; + /// @brief Return the spatial bounds of the timeline. std::optional available_image_bounds(ErrorStatus* error_status) const { diff --git a/src/opentimelineio/track.h b/src/opentimelineio/track.h index 32a786c6ab..177a982a8d 100644 --- a/src/opentimelineio/track.h +++ b/src/opentimelineio/track.h @@ -10,21 +10,25 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { class Clip; +/// @brief A track is a composition of a certain kind, like video or audio. class Track : public Composition { public: + /// @brief This struct provides the base set of kinds of tracks. struct Kind { static auto constexpr video = "Video"; static auto constexpr audio = "Audio"; }; + /// @brief This enumeration provides the neighbor gap policy. enum NeighborGapPolicy { never = 0, around_transitions = 1 }; + /// @brief This struct provides the Track schema. struct Schema { static auto constexpr name = "Track"; @@ -33,14 +37,22 @@ class Track : public Composition using Parent = Composition; + /// @brief Create a new track. + /// + /// @param name The track name. + /// @param source_range The source range of the track. + /// @param kind The kind of track. + /// @param metadata The metadata for the track. Track( std::string const& name = std::string(), std::optional const& source_range = std::nullopt, std::string const& kind = Kind::video, AnyDictionary const& metadata = AnyDictionary()); + /// @brief Return this kind of track. std::string kind() const noexcept { return _kind; } + /// @brief Set this kind of track. void set_kind(std::string const& kind) { _kind = kind; } TimeRange range_of_child_at_index( @@ -57,6 +69,7 @@ class Track : public Composition Composable const* child, ErrorStatus* error_status = nullptr) const override; + /// @brief Return the neighbors of the given item. std::pair, Retainer> neighbors_of( Composable const* item, ErrorStatus* error_status = nullptr, @@ -68,11 +81,12 @@ class Track : public Composition std::optional available_image_bounds(ErrorStatus* error_status) const override; - // Find child clips. - // - // An optional search_range may be provided to limit the search. - // - // The search is recursive unless shallow_search is set to true. + /// @brief Find child clips. + /// + /// @param error_status The return status. + /// @param search_range An optional range to limit the search. + /// @param shallow_search The search is recursive unless shallow_search is + /// set to true. std::vector> find_clips( ErrorStatus* error_status = nullptr, std::optional const& search_range = std::nullopt, diff --git a/src/opentimelineio/trackAlgorithm.h b/src/opentimelineio/trackAlgorithm.h index 54ce6d35e5..7173437759 100644 --- a/src/opentimelineio/trackAlgorithm.h +++ b/src/opentimelineio/trackAlgorithm.h @@ -8,6 +8,7 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief Trim the track to the given range. Track* track_trimmed_to_range( Track* in_track, TimeRange trim_range, diff --git a/src/opentimelineio/transition.h b/src/opentimelineio/transition.h index 717826f095..f254f65878 100644 --- a/src/opentimelineio/transition.h +++ b/src/opentimelineio/transition.h @@ -7,16 +7,20 @@ #include "opentimelineio/version.h" namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { - +/// @brief Represents a transition between the two adjacent items in a Track. +/// +/// For example, a cross dissolve or wipe. class Transition : public Composable { public: + /// @brief This struct provides base set of transitions. struct Type { static auto constexpr SMPTE_Dissolve = "SMPTE_Dissolve"; static auto constexpr Custom = "Custom_Transition"; }; + /// @brief This struct provides the Transition schema. struct Schema { static auto constexpr name = "Transition"; @@ -25,6 +29,13 @@ class Transition : public Composable using Parent = Composable; + /// @brief Create a new transition. + /// + /// @param name The transition name. + /// @param transition_type The transition type. + /// @param in_offset The in time offset. + /// @param out_offset The out time offset. + /// @param metadata The metadata for the transition. Transition( std::string const& name = std::string(), std::string const& transition_type = std::string(), @@ -34,22 +45,28 @@ class Transition : public Composable bool overlapping() const override; + /// @brief Return the transition type. std::string transition_type() const noexcept { return _transition_type; } + /// @brief Set the transition type. void set_transition_type(std::string const& transition_type) { _transition_type = transition_type; } + /// @brief Return the transition in time offset. RationalTime in_offset() const noexcept { return _in_offset; } + /// @brief Set the transition in time offset. void set_in_offset(RationalTime const& in_offset) noexcept { _in_offset = in_offset; } + /// @brief Return the transition out time offset. RationalTime out_offset() const noexcept { return _out_offset; } + /// @brief Set the transition out time offset. void set_out_offset(RationalTime const& out_offset) noexcept { _out_offset = out_offset; @@ -57,9 +74,11 @@ class Transition : public Composable RationalTime duration(ErrorStatus* error_status = nullptr) const override; + /// @brief Return the range in the parent's time. std::optional range_in_parent(ErrorStatus* error_status = nullptr) const; + /// @brief Return the range trimmed in the parent's time. std::optional trimmed_range_in_parent(ErrorStatus* error_status = nullptr) const; diff --git a/src/opentimelineio/typeRegistry.h b/src/opentimelineio/typeRegistry.h index a0a6047f7d..4839dfa020 100644 --- a/src/opentimelineio/typeRegistry.h +++ b/src/opentimelineio/typeRegistry.h @@ -19,23 +19,32 @@ class SerializableObject; class Encoder; class AnyDictionary; -// typedefs for the schema downgrading system -// @TODO: should we make version an int64_t? That would match what we can -// serialize natively, since we only serialize 64 bit signed ints. +/// @name Schema Typedefs +/// +/// typedefs for the schema downgrading system. +/// +/// @todo Should we make version an int64_t? That would match what we can +/// serialize natively, since we only serialize 64 bit signed ints. +///@{ + using schema_version_map = std::unordered_map; using label_to_schema_version_map = std::unordered_map; +///@} + extern const label_to_schema_version_map CORE_VERSION_MAP; +/// @brief Type registry. class TypeRegistry { public: - /// TypeRegistry is a singleton. - /// Accesses to its functions are thread-safe. + /// @brief Get the type registry singleton. + /// + /// Access to functions are thread-safe. static TypeRegistry& instance(); - /// Register a new schema. + /// @brief Register a new schema. /// /// This API call should only be needed by developers who are creating a bridge /// to another language (e.g. Python, Swift). In a C++ environment, prefer @@ -49,7 +58,7 @@ class TypeRegistry std::function create, std::string const& class_name = ""); - /// Register a new SerializableObject class + /// @brief Register a new SerializableObject class /// /// If the specified schema_name has already been registered, this function does nothing and returns false. /// If you need to provide an alias for a schema name, se register_type_from_existing_type(). @@ -64,7 +73,7 @@ class TypeRegistry CLASS::Schema::name); } - /// Register a new schema. + /// @brief Register a new schema. /// /// This API call can be used to register an alternate schema name for a class, in /// case a schema name is changed and the old name needs to be allowed as well. @@ -80,7 +89,8 @@ class TypeRegistry /// to another language (e.g. Python, Swift). In a C++ environment, prefer /// the templated form of this call. - /// Register a function that will upgrade the given schema to version_to_upgrade_to. + /// @brief Register a function that will upgrade the given schema to version_to_upgrade_to. + /// /// Note that as a schema is upgraded, older upgrade functions should be kept around; /// the intent is that each upgrade function upgrades the schema from the version /// just before version_to_upgrade_to. (I.e. all registered upgrade functions are @@ -93,8 +103,9 @@ class TypeRegistry int version_to_upgrade_to, std::function upgrade_function); - /// Convenience API for C++ developers. See the documentation of the non-templated - /// register_upgrade_function() for details. + /// @brief Convenience API for C++ developers. + /// + /// See the documentation of the non-templated register_upgrade_function() for details. template bool register_upgrade_function( int version_to_upgrade_to, @@ -106,15 +117,16 @@ class TypeRegistry upgrade_function); } - /// Downgrade function from version_to_downgrade_from to + /// @brief Downgrade function from version_to_downgrade_from to /// version_to_downgrade_from - 1 bool register_downgrade_function( std::string const& schema_name, int version_to_downgrade_from, std::function downgrade_function); - /// Convenience API for C++ developers. See the documentation of the - /// non-templated register_downgrade_function() for details. + /// @brief Convenience API for C++ developers. + /// + /// See the documentation of the non-templated register_downgrade_function() for details. template bool register_downgrade_function( int version_to_upgrade_to, @@ -126,6 +138,7 @@ class TypeRegistry upgrade_function); } + /// @brief Return the instance from the given schema. SerializableObject* instance_from_schema( std::string const& schema_name, int schema_version, @@ -140,13 +153,13 @@ class TypeRegistry error_status); } - // For use by external bridging systems. + /// @brief For use by external bridging systems. bool set_type_record( SerializableObject*, std::string const& schema_name, ErrorStatus* error_status = nullptr); - // for inspecting the type registry, build a map of schema name to version + /// @brief For inspecting the type registry, build a map of schema name to version. void type_version_map(schema_version_map& result); private: diff --git a/src/opentimelineio/unknownSchema.h b/src/opentimelineio/unknownSchema.h index 4ba11087e1..c609930953 100644 --- a/src/opentimelineio/unknownSchema.h +++ b/src/opentimelineio/unknownSchema.h @@ -8,24 +8,32 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief An unknown schema. class UnknownSchema : public SerializableObject { public: + /// @brief This struct provides the UnknownSchema schema. struct Schema { static auto constexpr name = "UnknownSchema"; static int constexpr version = 1; }; + /// @brief Create a new unknown schema. + /// + /// @param original_schema_name The original schema name. + /// @param original_schema_version The original schema version. UnknownSchema( std::string const& original_schema_name, int original_schema_version); + /// @brief Return the original schema name. std::string original_schema_name() const noexcept { return _original_schema_name; } + /// @brief Return the original schema version. int original_schema_version() const noexcept { return _original_schema_version; diff --git a/src/opentimelineio/vectorIndexing.h b/src/opentimelineio/vectorIndexing.h index f14b722429..bffbbdaac9 100644 --- a/src/opentimelineio/vectorIndexing.h +++ b/src/opentimelineio/vectorIndexing.h @@ -7,6 +7,7 @@ namespace opentimelineio { namespace OPENTIMELINEIO_VERSION { +/// @brief Return the adjusted vector index. template constexpr int adjusted_vector_index(int index, V const& vec) noexcept diff --git a/src/opentimelineio/version.h b/src/opentimelineio/version.h index 9c8b8905a2..ba26e76128 100644 --- a/src/opentimelineio/version.h +++ b/src/opentimelineio/version.h @@ -16,9 +16,11 @@ using opentime::TimeRange; using opentime::TimeTransform; }} // namespace opentimelineio::OPENTIMELINEIO_VERSION -/// Convenience macro for the full namespace of OpenTimelineIO API. +/// @brief Convenience macro for the full namespace of OpenTimelineIO API. /// /// This can be used in place of the full namespace, e.g.: +/// /// OTIO_NS::Track* track = new OTIO_NS::Track; +/// /// #define OTIO_NS opentimelineio::OPENTIMELINEIO_VERSION From 93d471a5a25f736ed24ba561f5b0408f087e2358 Mon Sep 17 00:00:00 2001 From: Darby Johnston Date: Tue, 22 Apr 2025 11:23:26 -0700 Subject: [PATCH 2/2] Remove todo Signed-off-by: Darby Johnston --- src/opentimelineio/anyDictionary.h | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/opentimelineio/anyDictionary.h b/src/opentimelineio/anyDictionary.h index 34d2ec8515..4508e90f9b 100644 --- a/src/opentimelineio/anyDictionary.h +++ b/src/opentimelineio/anyDictionary.h @@ -132,10 +132,6 @@ class AnyDictionary : private std::map map::swap(other); } - /// @todo Remove all of these. - /// - ///@{ - /// @brief Return whether the given key has been set. /// /// If key is in this, and the type of key matches the type of result, then @@ -198,8 +194,6 @@ class AnyDictionary : private std::map } } - ///@} - using map::empty; using map::max_size; using map::size;