Handles prefetching and caching of video/audio frames for smooth playback. More...

#include <Qt/VideoCacheThread.h>

Inheritance diagram for openshot::VideoCacheThread:

Collaboration diagram for openshot::VideoCacheThread:

Public Member Functions
int	getSpeed () const

bool	isReady ()

void	Play ()
	Set is_playing = true, so run() will begin caching/playback. More...

void	Reader (ReaderBase *new_reader)
	Attach a ReaderBase (e.g. Timeline, FFmpegReader) and begin caching. More...

void	Seek (int64_t new_position)
	Seek to a specific frame (no preroll). More...

void	Seek (int64_t new_position, bool start_preroll)
	Seek to a specific frame and optionally start a preroll (cache reset). More...

void	setSpeed (int new_speed)
	Set playback speed/direction. Positive = forward, negative = rewind, zero = pause. More...

bool	StartThread ()
	Start the cache thread at high priority. Returns true if it’s actually running. More...

void	Stop ()
	Set is_playing = false, effectively pausing playback (caching still runs). More...

bool	StopThread (int timeoutMs=0)
	Stop the cache thread (wait up to timeoutMs ms). Returns true if it stopped. More...

	VideoCacheThread ()
	Constructor: initializes member variables and assumes forward direction on first launch. More...

	~VideoCacheThread () override

Protected Member Functions
bool	clearCacheIfPaused (int64_t playhead, bool paused, CacheBase *cache)
	When paused and playhead is outside current cache, clear all frames. More...

int	computeDirection () const

void	computeWindowBounds (int64_t playhead, int dir, int64_t ahead_count, int64_t timeline_end, int64_t &window_begin, int64_t &window_end) const
	Compute the “window” of frames to cache around playhead. More...

int64_t	getBytes (int width, int height, int sample_rate, int channels, float fps)
	Estimate memory usage for a single frame (video + audio). More...

void	handleUserSeek (int64_t playhead, int dir)
	If userSeeked is true, reset last_cached_index just behind the playhead. More...

bool	prefetchWindow (CacheBase cache, int64_t window_begin, int64_t window_end, int dir, ReaderBase reader)
	Prefetch all missing frames in [window_begin ... window_end] or [window_end ... window_begin]. More...

void	run () override
	Thread entry point: loops until threadShouldExit() is true. More...

Protected Attributes
int64_t	cached_frame_count
	Count of frames currently added to cache. More...

int64_t	current_display_frame
	Currently displayed frame (unused here, reserved). More...

bool	force_directional_cache
	(Reserved for future use). More...

bool	is_playing
	True if playback is “running” (affects thread loop, not caching). More...

std::shared_ptr< Frame >	last_cached_frame
	Last frame pointer added to cache. More...

int64_t	last_cached_index
	Index of the most recently cached frame. More...

int	last_dir
	Last direction sign (+1 forward, –1 backward). More...

int	last_speed
	Last non-zero speed (for tracking). More...

int64_t	min_frames_ahead
	Minimum number of frames considered “ready” (pre-roll). More...

ReaderBase *	reader
	The source reader (e.g., Timeline, FFmpegReader). More...

int64_t	requested_display_frame
	Frame index the user requested. More...

int	speed
	Current playback speed (0=paused, >0 forward, <0 backward). More...

int64_t	timeline_max_frame
	Highest valid frame index in the timeline. More...

bool	userSeeked
	True if Seek(..., true) was called (forces a cache reset). More...

Detailed Description

Handles prefetching and caching of video/audio frames for smooth playback.

This thread continuously maintains a “window” of cached frames in the current playback direction (forward or backward). When paused, it continues to fill that same window; when seeking, it resets to cache around the new position.

Definition at line 33 of file VideoCacheThread.h.

Constructor & Destructor Documentation

◆ VideoCacheThread()

openshot::VideoCacheThread::VideoCacheThread ( )

Constructor: initializes member variables and assumes forward direction on first launch.

Definition at line 26 of file VideoCacheThread.cpp.

◆ ~VideoCacheThread()

openshot::VideoCacheThread::~VideoCacheThread ( )

override

Definition at line 45 of file VideoCacheThread.cpp.

Member Function Documentation

◆ clearCacheIfPaused()

bool openshot::VideoCacheThread::clearCacheIfPaused	(	int64_t	playhead,
		bool	paused,
		CacheBase *	cache
	)

protected

When paused and playhead is outside current cache, clear all frames.

Parameters

playhead	Current requested_display_frame
paused	True if speed == 0
cache	Pointer to CacheBase

Returns: True if ClearAllCache() was invoked.

Definition at line 132 of file VideoCacheThread.cpp.

Referenced by run().

◆ computeDirection()

int openshot::VideoCacheThread::computeDirection ( ) const

protected

Returns: Effective playback direction (+1 forward, –1 backward), preserving last_dir if speed == 0.

Definition at line 120 of file VideoCacheThread.cpp.

Referenced by run().

◆ computeWindowBounds()

void openshot::VideoCacheThread::computeWindowBounds	(	int64_t	playhead,
		int	dir,
		int64_t	ahead_count,
		int64_t	timeline_end,
		int64_t &	window_begin,
		int64_t &	window_end
	)		const

protected

Compute the “window” of frames to cache around playhead.

Parameters

	playhead	Current requested_display_frame
	dir	Effective direction (±1)
	ahead_count	Number of frames ahead/back to cache
	timeline_end	Last valid frame index
[out]	window_begin	Lower bound (inclusive) of caching window
[out]	window_end	Upper bound (inclusive) of caching window

If dir > 0: window = [playhead ... playhead + ahead_count] If dir < 0: window = [playhead – ahead_count ... playhead] Always clamps to [1 ... timeline_end].

Definition at line 145 of file VideoCacheThread.cpp.

Referenced by run().

◆ getBytes()

int64_t openshot::VideoCacheThread::getBytes	(	int	width,
		int	height,
		int	sample_rate,
		int	channels,
		float	fps
	)

protected

Estimate memory usage for a single frame (video + audio).

Parameters

width	Frame width (pixels)
height	Frame height (pixels)
sample_rate	Audio sample rate (e.g. 48000)
channels	Number of audio channels
fps	Frames per second

Returns: Approximate size in bytes for one frame

Definition at line 78 of file VideoCacheThread.cpp.

Referenced by run().

◆ getSpeed()

int openshot::VideoCacheThread::getSpeed ( ) const

inline

Returns: The current speed (1=normal, 2=fast, –1=rewind, etc.)

Definition at line 59 of file VideoCacheThread.h.

◆ handleUserSeek()

void openshot::VideoCacheThread::handleUserSeek	(	int64_t	playhead,
		int	dir
	)

protected

If userSeeked is true, reset last_cached_index just behind the playhead.

Parameters

playhead	Current requested_display_frame
dir	Effective direction (±1)

Definition at line 126 of file VideoCacheThread.cpp.

Referenced by run().

◆ isReady()

bool openshot::VideoCacheThread::isReady ( )

Returns: True if at least min_frames_ahead frames have been cached.

Definition at line 62 of file VideoCacheThread.cpp.

Referenced by openshot::AudioReaderSource::getNextAudioBlock().

◆ Play()

void openshot::VideoCacheThread::Play ( )

Set is_playing = true, so run() will begin caching/playback.

Definition at line 50 of file VideoCacheThread.cpp.

Referenced by Reader().

◆ prefetchWindow()

bool openshot::VideoCacheThread::prefetchWindow	(	CacheBase *	cache,
		int64_t	window_begin,
		int64_t	window_end,
		int	dir,
		ReaderBase *	reader
	)

protected

Prefetch all missing frames in [window_begin ... window_end] or [window_end ... window_begin].

Parameters

cache	Pointer to CacheBase
window_begin	Inclusive lower bound of the window
window_end	Inclusive upper bound of the window
dir	Effective direction (±1)
reader	Pointer to ReaderBase to call GetFrame()

Returns: True if the window was already full (no new frames added)

Internally, this method iterates from last_cached_index + dir toward window_end (or window_begin) and calls GetFrame()/Add() for each missing frame until hitting the window boundary or an OOB. It also breaks early if threadShouldExit() or userSeeked becomes true.

Definition at line 167 of file VideoCacheThread.cpp.

Referenced by run().

◆ Reader()

void openshot::VideoCacheThread::Reader ( ReaderBase * new_reader )

inline

Attach a ReaderBase (e.g. Timeline, FFmpegReader) and begin caching.

Parameters

new_reader

Definition at line 81 of file VideoCacheThread.h.

Referenced by openshot::QtPlayer::Reader().

◆ run()

void openshot::VideoCacheThread::run ( )

overrideprotected

Thread entry point: loops until threadShouldExit() is true.

Definition at line 211 of file VideoCacheThread.cpp.

◆ Seek() [1/2]

void openshot::VideoCacheThread::Seek ( int64_t new_position )

Seek to a specific frame (no preroll).

Definition at line 115 of file VideoCacheThread.cpp.

Referenced by openshot::QtPlayer::Seek().

◆ Seek() [2/2]

void openshot::VideoCacheThread::Seek	(	int64_t	new_position,
		bool	start_preroll
	)

Seek to a specific frame and optionally start a preroll (cache reset).

Parameters

new_position	Frame index to jump to.
start_preroll	If true, forces cache to rebuild around new_position.

Definition at line 107 of file VideoCacheThread.cpp.

◆ setSpeed()

void openshot::VideoCacheThread::setSpeed ( int new_speed )

Set playback speed/direction. Positive = forward, negative = rewind, zero = pause.

Parameters

new_speed If new_speed != 0, last_speed and last_dir are updated. If new_speed == 0, last_dir is left unchanged so that pausing does not flip direction.

Definition at line 67 of file VideoCacheThread.cpp.

Referenced by openshot::QtPlayer::Speed().

◆ StartThread()

bool openshot::VideoCacheThread::StartThread ( )

Start the cache thread at high priority. Returns true if it’s actually running.

Start the cache thread at high priority, and return true if it’s actually running.

Definition at line 92 of file VideoCacheThread.cpp.

◆ Stop()

void openshot::VideoCacheThread::Stop ( )

Set is_playing = false, effectively pausing playback (caching still runs).

Definition at line 56 of file VideoCacheThread.cpp.

Referenced by openshot::QtPlayer::Stop().

◆ StopThread()

bool openshot::VideoCacheThread::StopThread ( int timeoutMs = 0 )

Stop the cache thread (wait up to timeoutMs ms). Returns true if it stopped.

Stop the cache thread, waiting up to timeoutMs ms. Returns true if it actually stopped.

Definition at line 101 of file VideoCacheThread.cpp.

Member Data Documentation

◆ cached_frame_count

int64_t openshot::VideoCacheThread::cached_frame_count

protected

Count of frames currently added to cache.

Definition at line 171 of file VideoCacheThread.h.

Referenced by isReady(), and prefetchWindow().

◆ current_display_frame

int64_t openshot::VideoCacheThread::current_display_frame

protected

Currently displayed frame (unused here, reserved).

Definition at line 170 of file VideoCacheThread.h.

◆ force_directional_cache

bool openshot::VideoCacheThread::force_directional_cache

protected

(Reserved for future use).

Definition at line 177 of file VideoCacheThread.h.

◆ is_playing

bool openshot::VideoCacheThread::is_playing

protected

True if playback is “running” (affects thread loop, not caching).

Definition at line 166 of file VideoCacheThread.h.

Referenced by Play(), run(), and Stop().

◆ last_cached_frame

std::shared_ptr<Frame> openshot::VideoCacheThread::last_cached_frame

protected

Last frame pointer added to cache.

Definition at line 160 of file VideoCacheThread.h.

◆ last_cached_index

int64_t openshot::VideoCacheThread::last_cached_index

protected

Index of the most recently cached frame.

Definition at line 179 of file VideoCacheThread.h.

Referenced by handleUserSeek(), prefetchWindow(), and run().

◆ last_dir

int openshot::VideoCacheThread::last_dir

protected

Last direction sign (+1 forward, –1 backward).

Definition at line 164 of file VideoCacheThread.h.

Referenced by computeDirection(), run(), and setSpeed().

◆ last_speed

int openshot::VideoCacheThread::last_speed

protected

Last non-zero speed (for tracking).

Definition at line 163 of file VideoCacheThread.h.

Referenced by setSpeed().

◆ min_frames_ahead

int64_t openshot::VideoCacheThread::min_frames_ahead

protected

Minimum number of frames considered “ready” (pre-roll).

Definition at line 173 of file VideoCacheThread.h.

Referenced by isReady(), and run().

◆ reader

ReaderBase* openshot::VideoCacheThread::reader

protected

The source reader (e.g., Timeline, FFmpegReader).

Definition at line 176 of file VideoCacheThread.h.

Referenced by clearCacheIfPaused(), prefetchWindow(), Reader(), and run().

◆ requested_display_frame

int64_t openshot::VideoCacheThread::requested_display_frame

protected

Frame index the user requested.

Definition at line 169 of file VideoCacheThread.h.

Referenced by run(), and Seek().

◆ speed

int openshot::VideoCacheThread::speed

protected

Current playback speed (0=paused, >0 forward, <0 backward).

Definition at line 162 of file VideoCacheThread.h.

Referenced by computeDirection(), getSpeed(), run(), and setSpeed().

◆ timeline_max_frame

int64_t openshot::VideoCacheThread::timeline_max_frame

protected

Highest valid frame index in the timeline.

Definition at line 174 of file VideoCacheThread.h.

◆ userSeeked

bool openshot::VideoCacheThread::userSeeked

protected

True if Seek(..., true) was called (forces a cache reset).

Definition at line 167 of file VideoCacheThread.h.

Referenced by prefetchWindow(), run(), and Seek().

The documentation for this class was generated from the following files:

Qt/VideoCacheThread.h
Qt/VideoCacheThread.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ VideoCacheThread()

◆ ~VideoCacheThread()

Member Function Documentation

◆ clearCacheIfPaused()

◆ computeDirection()

◆ computeWindowBounds()

◆ getBytes()

◆ getSpeed()

◆ handleUserSeek()

◆ isReady()

◆ Play()

◆ prefetchWindow()

◆ Reader()

◆ run()

◆ Seek() [1/2]

◆ Seek() [2/2]

◆ setSpeed()

◆ StartThread()

◆ Stop()

◆ StopThread()

Member Data Documentation

◆ cached_frame_count

◆ current_display_frame

◆ force_directional_cache

◆ is_playing

◆ last_cached_frame

◆ last_cached_index

◆ last_dir

◆ last_speed

◆ min_frames_ahead

◆ reader

◆ requested_display_frame

◆ speed

◆ timeline_max_frame

◆ userSeeked