oak-editor/include/node/track.h

/***

  Oak Video Editor - Non-Linear Video Editor
  Copyright (C) 2026 Oak Team

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.

***/

#ifndef OAK_EDITOR_NODE_TRACK_H
#define OAK_EDITOR_NODE_TRACK_H

#ifndef __cplusplus
#include <stdbool.h>
#endif

#include "node/error.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Opaque handle to a track (olive::Track).
 *
 * The handle IS the C++ object pointer; no wrapper is allocated.
 */
typedef struct OakNodeTrack OakNodeTrack;

/**
 * @brief Opaque handle to a per-type track container (olive::TrackList).
 *
 * Borrowed from oaknode_sequence_get_track_list(); invalidated when the
 * owning sequence is destroyed.
 */
typedef struct OakNodeTrackList OakNodeTrackList;

/**
 * @brief Opaque handle to a block (olive::Block), see node/block.h.
 */
typedef struct OakNodeBlock OakNodeBlock;

/**
 * @brief Opaque handle to a sequence (olive::Sequence), see node/sequence.h.
 */
typedef struct OakNodeSequence OakNodeSequence;

/**
 * @brief Track types, matching olive::Track::Type.
 */
enum OakNodeTrackType {
	OAKNODE_TRACK_TYPE_NONE = -1,
	OAKNODE_TRACK_TYPE_VIDEO = 0,
	OAKNODE_TRACK_TYPE_AUDIO = 1,
	OAKNODE_TRACK_TYPE_SUBTITLE = 2,
	OAKNODE_TRACK_TYPE_COUNT = 3
};

/* Re-declared here so track.h is self-contained; see node/node.h. */
typedef struct OakNodeNode OakNodeNode;

/**
 * @brief Borrowed cast from a track handle to its node handle.
 * NULL for NULL.
 */
OakNodeNode *oaknode_track_as_node(OakNodeTrack *track);

/* ---------------------------------------------------------------- Track */

/**
 * @brief Create a track of the given type (OakNodeTrackType value).
 *
 * The caller owns the track until it is added to a track list; a track
 * that was never added must be released with oaknode_track_free().
 *
 * @return Track handle, or NULL on invalid type / allocation failure.
 */
OakNodeTrack *oaknode_track_create(int type);

/**
 * @brief Destroy a track. No-op on NULL.
 *
 * The track must have been removed from its track list first.
 */
void oaknode_track_free(OakNodeTrack *track);

/**
 * @brief Track type (OakNodeTrackType values).
 *
 * @return OAKNODE_OK or OAKNODE_E_INVALID.
 */
int oaknode_track_get_type(OakNodeTrack *track, int *type);
int oaknode_track_set_type(OakNodeTrack *track, int type);

/**
 * @brief Track height in internal units (olive::Track::get/set_track_height).
 */
int oaknode_track_get_height(OakNodeTrack *track, double *height);
int oaknode_track_set_height(OakNodeTrack *track, double height);

/**
 * @brief Track height in pixels (converted through the default font height).
 */
int oaknode_track_get_height_in_pixels(OakNodeTrack *track, int *height);
int oaknode_track_set_height_in_pixels(OakNodeTrack *track, int height);

/**
 * @brief Default / minimum track heights in pixels (static).
 */
int oaknode_track_get_default_height_in_pixels(void);
int oaknode_track_get_minimum_height_in_pixels(void);

/**
 * @brief Index of the track inside its track list.
 */
int oaknode_track_get_index(OakNodeTrack *track, int *index);
int oaknode_track_set_index(OakNodeTrack *track, int index);

/**
 * @brief Mute / lock flags.
 */
int oaknode_track_get_muted(OakNodeTrack *track, int *muted);
int oaknode_track_set_muted(OakNodeTrack *track, int muted);
int oaknode_track_get_locked(OakNodeTrack *track, int *locked);
int oaknode_track_set_locked(OakNodeTrack *track, int locked);

/**
 * @brief Track reference as a (type, index) pair (olive::Track::Reference).
 */
int oaknode_track_get_reference(OakNodeTrack *track, int *type, int *index);

/**
 * @brief Total length of the track (end of the last block).
 */
int oaknode_track_get_length(OakNodeTrack *track, int *numerator,
							 int *denominator);

/**
 * @brief Owning sequence as a borrowed handle (NULL when trackless).
 */
int oaknode_track_get_sequence(OakNodeTrack *track, OakNodeSequence **out);

/* ------------------------------------------------------- Track blocks */

/**
 * @brief Number of blocks on the track.
 */
int oaknode_track_get_block_count(OakNodeTrack *track, int *count);

/**
 * @brief Borrowed handle to the block at `index`.
 *
 * @return OAKNODE_OK, OAKNODE_E_INVALID or OAKNODE_E_NOT_FOUND.
 */
int oaknode_track_get_block_at(OakNodeTrack *track, int index,
							   OakNodeBlock **out);

/**
 * @brief Append/prepend/insert primitives (olive::Track::*_block).
 *
 * The track takes over graph membership of the block; the block must have
 * a valid length before insertion.
 *
 * @return OAKNODE_OK or OAKNODE_E_INVALID.
 */
int oaknode_track_append_block(OakNodeTrack *track, OakNodeBlock *block);
int oaknode_track_prepend_block(OakNodeTrack *track, OakNodeBlock *block);
int oaknode_track_insert_block_at_index(OakNodeTrack *track,
										OakNodeBlock *block, int index);
int oaknode_track_insert_block_after(OakNodeTrack *track, OakNodeBlock *block,
									 OakNodeBlock *before);
int oaknode_track_insert_block_before(OakNodeTrack *track, OakNodeBlock *block,
									  OakNodeBlock *after);

/**
 * @brief Remove `block` and shift all subsequent blocks earlier
 * (olive::Track::ripple_remove_block). The block is NOT deleted; ownership
 * returns to the caller.
 */
int oaknode_track_ripple_remove_block(OakNodeTrack *track, OakNodeBlock *block);

/**
 * @brief Replace `old_block` with `new_block`; both must have equal lengths.
 */
int oaknode_track_replace_block(OakNodeTrack *track, OakNodeBlock *old_block,
								OakNodeBlock *new_block);

/**
 * @brief Index of `block` in the track's block array, or OAKNODE_E_NOT_FOUND.
 */
int oaknode_track_get_block_index(OakNodeTrack *track, OakNodeBlock *block,
								  int *index);

/**
 * @brief Block strictly containing `time` (in < time < out), or
 * OAKNODE_E_NOT_FOUND.
 */
int oaknode_track_get_block_containing_time(OakNodeTrack *track, int numerator,
											int denominator,
											OakNodeBlock **out);

/**
 * @brief Block visible at `time` (in <= time < out), or OAKNODE_E_NOT_FOUND.
 */
int oaknode_track_get_visible_block_at_time(OakNodeTrack *track, int numerator,
											int denominator,
											OakNodeBlock **out);

/**
 * @brief Whether the [in, out) range holds no block or only a gap
 * (olive::Track::is_range_free). `is_free` receives 1/0.
 */
int oaknode_track_is_range_free(OakNodeTrack *track, int in_num, int in_den,
								int out_num, int out_den, int *is_free);

/* ------------------------------------------------------------ TrackList */

/**
 * @brief Track list type (OakNodeTrackType values).
 */
/**
 * @brief Nearest block lookups (Track::nearest_block_before_or_at /
 * nearest_block_after_or_at). *out is a borrowed handle or NULL.
 */
int oaknode_track_get_nearest_block_before_or_at(OakNodeTrack *track,
		int numerator, int denominator, OakNodeBlock **out);
int oaknode_track_get_nearest_block_after_or_at(OakNodeTrack *track,
		int numerator, int denominator, OakNodeBlock **out);

/**
 * @brief Borrowed sequence owning this track list.
 */
int oaknode_tracklist_get_sequence(OakNodeTrackList *list,
								   OakNodeSequence **out);

/**
 * @brief The list's track input id on the parent sequence
 * (e.g. "track_in_0"). Two-stage string getter.
 */
int oaknode_tracklist_get_track_input_id(OakNodeTrackList *list,
										 char *buf, int buf_size);

/**
 * @brief Live input-array append/remove on the parent sequence for this
 * list's track input (TrackList::array_append/array_remove_last()).
 */
int oaknode_tracklist_array_append(OakNodeTrackList *list);
int oaknode_tracklist_array_remove_last(OakNodeTrackList *list);

/**
 * @brief Map a cached track index to the input-array element index
 * (TrackList::get_array_index_from_cache_index()).
 */
int oaknode_tracklist_get_array_index_from_cache_index(
	OakNodeTrackList *list, int cache_index, int *out_index);

int oaknode_tracklist_get_type(OakNodeTrackList *list, int *type);

/**
 * @brief Number of connected tracks.
 */
int oaknode_tracklist_get_track_count(OakNodeTrackList *list, int *count);

/**
 * @brief Borrowed handle to the track at `index`.
 *
 * @return OAKNODE_OK, OAKNODE_E_INVALID or OAKNODE_E_NOT_FOUND.
 */
int oaknode_tracklist_get_track_at(OakNodeTrackList *list, int index,
								   OakNodeTrack **out);

/**
 * @brief Combined length of the longest track in the list.
 */
int oaknode_tracklist_get_total_length(OakNodeTrackList *list, int *numerator,
									   int *denominator);

/**
 * @brief Size of the underlying input array (>= track count; may contain
 * disconnected slots).
 */
int oaknode_tracklist_get_array_size(OakNodeTrackList *list, int *size);

/**
 * @brief Add `track` to the list (non-undoable primitive).
 *
 * Mirrors the graph steps of TimelineAddTrackCommand::redo() minus the
 * auto-merge: the track is parented to the list's graph (when any),
 * inherits the previous track's height, a new array slot is appended and
 * the track is connected to it. The sequence's flat track cache and
 * lengths are refreshed before returning.
 *
 * @return OAKNODE_OK or OAKNODE_E_INVALID.
 */
int oaknode_tracklist_add_track(OakNodeTrackList *list, OakNodeTrack *track);

/**
 * @brief Remove `track` from the list (non-undoable primitive).
 *
 * Disconnects the track from its array slot and removes the slot
 * (Node::input_array_remove). The track is NOT deleted; ownership returns
 * to the caller.
 *
 * @return OAKNODE_OK, OAKNODE_E_INVALID or OAKNODE_E_NOT_FOUND.
 */
int oaknode_tracklist_remove_track(OakNodeTrackList *list,
								   OakNodeTrack *track);

#ifdef __cplusplus
}
#endif

#endif //OAK_EDITOR_NODE_TRACK_H