diff options
Diffstat (limited to 'source/blender/sequencer/SEQ_iterator.h')
| -rw-r--r-- | source/blender/sequencer/SEQ_iterator.h | 154 |
1 files changed, 143 insertions, 11 deletions
diff --git a/source/blender/sequencer/SEQ_iterator.h b/source/blender/sequencer/SEQ_iterator.h index 4de7c09640b..2826e6b75cb 100644 --- a/source/blender/sequencer/SEQ_iterator.h +++ b/source/blender/sequencer/SEQ_iterator.h @@ -63,52 +63,184 @@ typedef struct SeqIterator { bool iterator_initialized; } SeqIterator; +/** + * Utility function for SEQ_ITERATOR_FOREACH macro. + * Ensure, that iterator is initialized. During initialization return pointer to collection element + * and step gset iterator. When this function is called after iterator has been initialized, it + * will do nothing and return true. + * + * \param collection: collection to iterate + * \param iterator: iterator to be initialized + * \param r_seq: pointer to Sequence pointer + * + * \return false when iterator can not be initialized, true otherwise + */ bool SEQ_iterator_ensure(SeqCollection *collection, SeqIterator *iterator, struct Sequence **r_seq); +/** + * Utility function for SEQ_ITERATOR_FOREACH macro. + * Yield collection element + * + * \param iterator: iterator to be initialized + * + * \return collection element or NULL when iteration has ended + */ struct Sequence *SEQ_iterator_yield(SeqIterator *iterator); -/* Callback format for the for_each function below. */ +/** + * Callback format for the for_each function below. + */ typedef bool (*SeqForEachFunc)(struct Sequence *seq, void *user_data); +/** + * Utility function to recursively iterate through all sequence strips in a `seqbase` list. + * Uses callback to do operations on each sequence element. + * The callback can stop the iteration if needed. + * + * \param seqbase: #ListBase of sequences to be iterated over. + * \param callback: query function callback, returns false if iteration should stop. + * \param user_data: pointer to user data that can be used in the callback function. + */ void SEQ_for_each_callback(struct ListBase *seqbase, SeqForEachFunc callback, void *user_data); +/** + * Create new empty strip collection. + * + * \return empty strip collection. + */ SeqCollection *SEQ_collection_create(const char *name); +/** + * Duplicate collection + * + * \param collection: collection to be duplicated + * \return duplicate of collection + */ SeqCollection *SEQ_collection_duplicate(SeqCollection *collection); +/** + * Return number of items in collection. + */ uint SEQ_collection_len(const SeqCollection *collection); +/** + * Check if seq is in collection. + */ bool SEQ_collection_has_strip(const struct Sequence *seq, const SeqCollection *collection); -bool SEQ_collection_append_strip(struct Sequence *seq, SeqCollection *data); -bool SEQ_collection_remove_strip(struct Sequence *seq, SeqCollection *data); +/** + * Add strip to collection. + * + * \param seq: strip to be added + * \param collection: collection to which strip will be added + * \return false if strip is already in set, otherwise true + */ +bool SEQ_collection_append_strip(struct Sequence *seq, SeqCollection *collection); +/** + * Remove strip from collection. + * + * \param seq: strip to be removed + * \param collection: collection from which strip will be removed + * \return true if strip exists in set and it was removed from set, otherwise false + */ +bool SEQ_collection_remove_strip(struct Sequence *seq, SeqCollection *collection); +/** + * Free strip collection. + * + * \param collection: collection to be freed + */ void SEQ_collection_free(SeqCollection *collection); +/** + * Move strips from collection_src to collection_dst. Source collection will be freed. + * + * \param collection_dst: destination collection + * \param collection_src: source collection + */ void SEQ_collection_merge(SeqCollection *collection_dst, SeqCollection *collection_src); +/** + * Remove strips from collection that are also in `exclude_elements`. Source collection will be + * freed. + * + * \param collection: collection from which strips are removed + * \param exclude_elements: collection of strips to be removed + */ void SEQ_collection_exclude(SeqCollection *collection, SeqCollection *exclude_elements); +/** + * Expand collection by running SEQ_query() for each strip, which will be used as reference. + * Results of these queries will be merged into provided collection. + * + * \param seqbase: ListBase in which strips are queried + * \param collection: SeqCollection to be expanded + * \param seq_query_func: query function callback + */ void SEQ_collection_expand(struct ListBase *seqbase, SeqCollection *collection, - void query_func(struct Sequence *seq_reference, - struct ListBase *seqbase, - SeqCollection *collection)); + void seq_query_func(struct Sequence *seq_reference, + struct ListBase *seqbase, + SeqCollection *collection)); +/** + * Query strips from seqbase. seq_reference is used by query function as filter condition. + * + * \param seq_reference: reference strip for query function + * \param seqbase: ListBase in which strips are queried + * \param seq_query_func: query function callback + * \return strip collection + */ SeqCollection *SEQ_query_by_reference(struct Sequence *seq_reference, struct ListBase *seqbase, void seq_query_func(struct Sequence *seq_reference, struct ListBase *seqbase, SeqCollection *collection)); +/** + * Query all selected strips in seqbase. + * + * \param seqbase: ListBase in which strips are queried + * \return strip collection + */ SeqCollection *SEQ_query_selected_strips(struct ListBase *seqbase); +/** + * Query all unselected strips in seqbase. + * + * \param seqbase: ListBase in which strips are queried + * \return strip collection + */ SeqCollection *SEQ_query_unselected_strips(struct ListBase *seqbase); +/** + * Query all strips in seqbase. This does not include strips nested in meta strips. + * + * \param seqbase: ListBase in which strips are queried + * \return strip collection + */ SeqCollection *SEQ_query_all_strips(ListBase *seqbase); +/** + * Query all strips in seqbase and nested meta strips. + * + * \param seqbase: ListBase in which strips are queried + * \return strip collection + */ SeqCollection *SEQ_query_all_strips_recursive(ListBase *seqbase); +/** + * Query strips that are rendered at \a timeline_frame when \a displayed channel is viewed + * + * \param seqbase: ListBase in which strips are queried + * \param timeline_frame: viewed frame + * \param displayed_channel: viewed channel. when set to 0, no channel filter is applied + * \return strip collection + */ SeqCollection *SEQ_query_rendered_strips(ListBase *seqbase, const int timeline_frame, const int displayed_channel); +/** + * Query all effect strips that are directly or indirectly connected to seq_reference. + * This includes all effects of seq_reference, strips used by another inputs and their effects, so + * that whole chain is fully independent of other strips. + * + * \param seq_reference: reference strip + * \param seqbase: ListBase in which strips are queried + * \param collection: collection to be filled + */ void SEQ_query_strip_effect_chain(struct Sequence *seq_reference, struct ListBase *seqbase, SeqCollection *collection); void SEQ_filter_selected_strips(SeqCollection *collection); -/* Utilities to access these as tags. */ -int SEQ_query_rendered_strips_to_tag(ListBase *seqbase, - const int timeline_frame, - const int displayed_channel); - #ifdef __cplusplus } #endif |