OpenCV VideoCapture-backed MatSourceBase that implements IVideoCaptureMatSource. More...

Public Member Functions

VideoCaptureMatSource (VideoCaptureFrameGrabber grabber, IFrameOrientationCorrector orientationCorrector=null)

Initializes a new instance of the VideoCaptureMatSource class.

Task InitializeAsync (VideoCaptureOpenOptions options, CancellationToken cancellationToken=default)

Initializes the source using one-shot video capture open options projected onto RequestedVideoFilePath, Loop, and ApiPreference.

Task InitializeAsync (VideoFileOpenOptions options, CancellationToken cancellationToken=default)

Initializes the source using one-shot video file open options projected onto RequestedVideoFilePath and Loop.

override async Task PauseAsync (CancellationToken cancellationToken=default)

Pauses frame acquisition asynchronously. When already paused, completes immediately without error. When MatSourceState.Initializing, completes immediately without changing state.

Parameters

cancellationToken A token used to cancel the operation.

Returns: A task that completes when playback has been paused.

When State is MatSourceState.Initializing, completes immediately without changing state and logs a one-time warning per process.

override async Task PlayAsync (CancellationToken cancellationToken=default)

Starts or resumes frame acquisition asynchronously. When already playing, completes immediately without error. When MatSourceState.Initializing, completes immediately without changing state.

Parameters

cancellationToken A token used to cancel the operation.

Returns: A task that completes when playback has started.

When State is MatSourceState.Initializing, completes immediately without changing state and logs a one-time warning per process.

override async Task StopAsync (CancellationToken cancellationToken=default)

Stops frame acquisition asynchronously. When already in the ready (not playing) state, completes immediately without error. When MatSourceState.Initializing, completes immediately without changing state.

Parameters

cancellationToken A token used to cancel the operation.

Returns: A task that completes when playback has stopped.

When State is MatSourceState.Initializing, completes immediately without changing state and logs a one-time warning per process.

override void Tick (float deltaTime)

Advances frame acquisition when the source is playing. Sets IMatSource.DidUpdateThisFrame only when a new frame is acquired.

Parameters

deltaTime Elapsed time since the previous tick, in seconds.

Sets DidUpdateThisFrame only when IFrameGrabber.TryGrab returns a new frame. When IFrameGrabber.TryGrab returns false, this tick is a no-op (not an error). Does not call IFrameOrientationCorrector.NotifyDisplayOrientationChanged; the host is responsible for that. Registered DerivedFrames are still evaluated when IFrameGrabber.TryGrab does not succeed so per-tick derived-frame flags such as IDerivedFrame.DidUpdateThisFrame stay in sync. Sources without a native frame rate (for example still images) may throttle Tick in a derived type that implements IMatUpdateFPSControllable.

Public Member Functions inherited from OpenCVForUnity.Extensions.SourceToMat.MatSourceBase

MatSourceBase (IFrameGrabber grabber, IFrameOrientationCorrector orientationCorrector=null)

Initializes a new instance of the MatSourceBase class.

PlaybackRestoreMode CapturePlaybackRestoreMode ()

Captures the current playback state as a PlaybackRestoreMode for re-initialization.

Returns: PlaybackRestoreMode.Playing when playing, PlaybackRestoreMode.Paused when paused, otherwise PlaybackRestoreMode.Ready.

void Dispose ()

async ValueTask DisposeAsync ()

Asynchronously releases resources. Required on single-threaded hosts (for example browser/WebAssembly targets); do not use Dispose on those hosts.

Task InitializeAsync (CancellationToken cancellationToken=default)

Initializes the source asynchronously and leaves playback in MatSourceState.Ready.

Parameters

cancellationToken A token used to cancel the operation.

Returns: A task that completes when initialization finishes.

Task InitializeAsync (PlaybackRestoreMode playbackRestoreMode, CancellationToken cancellationToken=default)

Initializes the source asynchronously and restores the requested playback state before IMatSourceEvents.OnInitialized is raised.

Parameters

playbackRestoreMode	Playback state to apply after the grabber is ready.
cancellationToken	A token used to cancel the operation.

Returns: A task that completes when initialization finishes.

Task ReinitializeAsync (PlaybackRestoreMode playbackRestoreMode, CancellationToken cancellationToken=default)

Releases the source when initialized, then initializes again with the requested playback restore mode.

Parameters

playbackRestoreMode	Playback state to apply after the grabber is ready.
cancellationToken	A token used to cancel the operation.

Returns: A task that completes when re-initialization finishes.

Task ReleaseAsync (CancellationToken cancellationToken=default)

void SyncDerivedFrameBuffersIfStale (IList< string > pendingLayoutChanges=null)

Re-applies derived frame outputs whose buffers are stale relative to the current source layout or derived settings.

bool TryGetMeta (string key, out object value)

Attempts to get a meta property value by key.

Parameters

key	The meta key.
value	When this method returns `true`, the retrieved value; otherwise the default value.

Returns: true when the key is supported and a value is available; otherwise false.

bool TrySetMeta (string key, object value)

Attempts to set a meta property value by key.

Parameters

key	The meta key.
value	The value to set.

Returns: true when the key is supported and the value was applied; otherwise false.

Public Member Functions inherited from OpenCVForUnity.Extensions.SourceToMat.IMatSource

Public Member Functions inherited from OpenCVForUnity.Extensions.SourceToMat.IMatMetaProperties

Public Member Functions inherited from OpenCVForUnity.Extensions.SourceToMat.IMatSourceTickable

Public Member Functions inherited from OpenCVForUnity.Extensions.SourceToMat.IMatSourceReinitializable

Protected Member Functions
override void	SyncGrabberBeforeOpen ()
	Copies source-specific `Requested*` settings onto the injected grabber immediately before IFrameGrabber.OpenAsync. Derived file-based sources override this hook; the default is a no-op.

Protected Member Functions inherited from OpenCVForUnity.Extensions.SourceToMat.MatSourceBase
void	ClearDidUpdateThisFrame ()
	Clears DidUpdateThisFrame for the current tick.

virtual SourceToMatColorFormat	InferGrabberColorFormat (Mat workingMat)
	Resolves the grabber frame color format used for output conversion. Override in derived sources when channel order is known and differs from InferColorFormat.

void	RaiseError (SourceToMatErrorCode errorCode, string message)
	Raises OnErrorOccurred with the specified error code and message.

void	StopPlayingCore ()
	Stops playback without async overhead. Shared by StopAsync and derived Tick handlers.

Properties
int	ApiPreference `[get]`
	Gets the OpenCV `Videoio` API preference used when opening the capture. Set only via Options.VideoCaptureOpenOptions during initialization.

float	FPS `[get]`
	Gets the current playback frame rate in frames per second.

int	FrameCount `[get]`
	Gets the total frame count of the video.

int	FrameIndex `[get, set]`
	Gets or sets the current frame index.

float	FramePosRatio `[get, set]`
	Gets or sets the current frame position as a ratio from 0.0 to 1.0.

bool	Loop `[get, set]`
	Gets or sets whether the video loops after reaching the end.

string	RequestedVideoFilePath = string.Empty `[get, set]`
	Gets or sets the requested video file path.

Properties inherited from OpenCVForUnity.Extensions.SourceToMat.MatSourceBase
SourceToMatColorFormat	BaseColorFormat `[get]`
	Gets the native color format produced by the underlying grabber before output conversion.

DerivedFrameCollection	DerivedFrames `[get]`
	Gets the optional derived frame collection. When empty, tick processing matches the source layer only.

bool	DidUpdateThisFrame `[get]`

bool	FlipHorizontal `[get, set]`
	Gets or sets whether to flip the image horizontally.

bool	FlipVertical `[get, set]`
	Gets or sets whether to flip the image vertically.

Mat	FrameMat `[get]`

int	Height `[get]`
	Gets the current frame height in pixels.

int	InitTimeoutMs `[get, set]`
	Gets or sets the initialization wait timeout in milliseconds.

bool	IsInitialized `[get]`
	Gets a value indicating whether the source has been initialized and is ready for playback control. Does not include MatSourceState.Initializing.

bool	IsInitializing `[get]`
	Gets a value indicating whether initialization is in progress (MatSourceState.Initializing).

bool	IsPaused `[get]`
	Gets a value indicating whether frame acquisition is paused.

bool	IsPlaying `[get]`
	Gets a value indicating whether frame acquisition is active.

Task	LifecycleTask `[get]`
	Gets a task that completes when the current lifecycle operation finishes. Queued operations run sequentially; this reflects the tail of that chain.

SourceToMatColorFormat	OutputColorFormat `[get, set]`
	Gets or sets the output color format. When changed after initialization, the output FrameMat channel layout (Mat type) may change and implementations that raise IMatSourceEvents.OnFrameMatLayoutChanged do so after the new layout is committed.

bool	Rotate90Degree `[get, set]`
	Gets or sets whether to rotate the image 90 degrees clockwise. When changed after initialization, the output IMatSource.FrameMat layout (width, height) changes and implementations that raise IMatSourceEvents.OnFrameMatLayoutChanged do so after the new layout is committed.

MatSourceState	State `[get]`
	Gets the current lifecycle state.

int	Width `[get]`
	Gets the current frame width in pixels.

Properties inherited from OpenCVForUnity.Extensions.SourceToMat.IMatSource
Properties inherited from OpenCVForUnity.Extensions.SourceToMat.IMatTransformable
Properties inherited from OpenCVForUnity.Extensions.SourceToMat.IMatSourceDerivedFrames
Properties inherited from OpenCVForUnity.Extensions.SourceToMat.IVideoCaptureMatSource
Properties inherited from OpenCVForUnity.Extensions.SourceToMat.IVideoFileMatSource

Additional Inherited Members
Events inherited from OpenCVForUnity.Extensions.SourceToMat.MatSourceBase
Action< string >	OnDerivedFrameLayoutChanged

Action	OnDisposed

Action< SourceToMatErrorCode, string >	OnErrorOccurred

Action	OnFrameMatLayoutChanged

Action	OnFrameMatUpdated

Action	OnInitialized

Action	OnReleased

Events inherited from OpenCVForUnity.Extensions.SourceToMat.IMatSourceEvents
Action< string >	OnDerivedFrameLayoutChanged
	Occurs after initialization when a derived frame output layout (columns, rows, type) changes without removing the derived frame, on the thread that commits the layout change. Not raised on the first derived layout establishment during IMatSource.InitializeAsync. At invocation, the derived frame's `FrameMat` matches the committed output layout. Layout-affecting settings updates may commit immediately without waiting for the next IMatSourceTickable.Tick.

Action	OnDisposed
	Occurs when IDisposable.Dispose or IAsyncDisposable.DisposeAsync completes and the source enters MatSourceState.Destroyed.

Action< SourceToMatErrorCode, string >	OnErrorOccurred
	Occurs for expected runtime failures with a SourceToMatErrorCode and message, on the thread that detected the failure.

Action	OnFrameMatLayoutChanged
	Occurs after initialization when the output IMatSource.FrameMat layout (cols, rows, type) changes without a full release cycle, on the thread that commits the layout change. Not raised on the first layout establishment during IMatSource.InitializeAsync. When derived frames are registered, their output buffers are synced to the new primary layout before this event is raised.

Action	OnFrameMatUpdated
	Occurs at the end of IMatSourceTickable.Tick when IMatSource.DidUpdateThisFrame is `true` for that tick, after any registered derived frames are evaluated.

Action	OnInitialized
	Occurs when an initialization cycle completes and playback state (Ready / Playing / Paused) is determined, on the thread that completes the underlying async operation.

Action	OnReleased
	Occurs when IMatSource.ReleaseAsync completes and the source returns to MatSourceState.Uninitialized, on the thread that completes the underlying async operation.

Detailed Description

OpenCV VideoCapture-backed MatSourceBase that implements IVideoCaptureMatSource.

ConfigureAwait(false) is used only after MatSourceBase.PlayAsync, MatSourceBase.PauseAsync, and MatSourceBase.StopAsync complete (post-restore playback-state chain). It is not used before grabber open/close on initialization paths.

Constructor & Destructor Documentation

◆ VideoCaptureMatSource()

OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.VideoCaptureMatSource	(	VideoCaptureFrameGrabber	grabber,
		IFrameOrientationCorrector	orientationCorrector = null )

Initializes a new instance of the VideoCaptureMatSource class.

Parameters

grabber	The OpenCV video capture grabber.
orientationCorrector	Optional orientation corrector.

Member Function Documentation

◆ InitializeAsync() [1/2]

Task OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.InitializeAsync	(	VideoCaptureOpenOptions	options,
		CancellationToken	cancellationToken = default )

Initializes the source using one-shot video capture open options projected onto RequestedVideoFilePath, Loop, and ApiPreference.

Parameters

options	Video capture open options to project before initialization.
cancellationToken	A token used to cancel the operation.

Returns: A task that completes when initialization finishes.

◆ InitializeAsync() [2/2]

Task OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.InitializeAsync	(	VideoFileOpenOptions	options,
		CancellationToken	cancellationToken = default )

Initializes the source using one-shot video file open options projected onto RequestedVideoFilePath and Loop.

Parameters

options	Video file open options to project before initialization.
cancellationToken	A token used to cancel the operation.

Returns: A task that completes when initialization finishes.

◆ PauseAsync()

override async Task OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.PauseAsync ( CancellationToken cancellationToken = default )

virtual

Pauses frame acquisition asynchronously. When already paused, completes immediately without error. When MatSourceState.Initializing, completes immediately without changing state.

Parameters

cancellationToken A token used to cancel the operation.

Returns: A task that completes when playback has been paused.

When State is MatSourceState.Initializing, completes immediately without changing state and logs a one-time warning per process.

Reimplemented from OpenCVForUnity.Extensions.SourceToMat.MatSourceBase.

◆ PlayAsync()

override async Task OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.PlayAsync ( CancellationToken cancellationToken = default )

virtual

Starts or resumes frame acquisition asynchronously. When already playing, completes immediately without error. When MatSourceState.Initializing, completes immediately without changing state.

Parameters

cancellationToken A token used to cancel the operation.

Returns: A task that completes when playback has started.

When State is MatSourceState.Initializing, completes immediately without changing state and logs a one-time warning per process.

Reimplemented from OpenCVForUnity.Extensions.SourceToMat.MatSourceBase.

◆ StopAsync()

override async Task OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.StopAsync ( CancellationToken cancellationToken = default )

virtual

Stops frame acquisition asynchronously. When already in the ready (not playing) state, completes immediately without error. When MatSourceState.Initializing, completes immediately without changing state.

Parameters

cancellationToken A token used to cancel the operation.

Returns: A task that completes when playback has stopped.

When State is MatSourceState.Initializing, completes immediately without changing state and logs a one-time warning per process.

Reimplemented from OpenCVForUnity.Extensions.SourceToMat.MatSourceBase.

◆ SyncGrabberBeforeOpen()

override void OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.SyncGrabberBeforeOpen ( )

protectedvirtual

Copies source-specific Requested* settings onto the injected grabber immediately before IFrameGrabber.OpenAsync. Derived file-based sources override this hook; the default is a no-op.

Reimplemented from OpenCVForUnity.Extensions.SourceToMat.MatSourceBase.

◆ Tick()

override void OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.Tick ( float deltaTime )

virtual

Advances frame acquisition when the source is playing. Sets IMatSource.DidUpdateThisFrame only when a new frame is acquired.

Parameters

deltaTime Elapsed time since the previous tick, in seconds.

Sets DidUpdateThisFrame only when IFrameGrabber.TryGrab returns a new frame. When IFrameGrabber.TryGrab returns false, this tick is a no-op (not an error). Does not call IFrameOrientationCorrector.NotifyDisplayOrientationChanged; the host is responsible for that. Registered DerivedFrames are still evaluated when IFrameGrabber.TryGrab does not succeed so per-tick derived-frame flags such as IDerivedFrame.DidUpdateThisFrame stay in sync. Sources without a native frame rate (for example still images) may throttle Tick in a derived type that implements IMatUpdateFPSControllable.

Reimplemented from OpenCVForUnity.Extensions.SourceToMat.MatSourceBase.

Property Documentation

◆ ApiPreference

int OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.ApiPreference

get

Gets the OpenCV Videoio API preference used when opening the capture. Set only via Options.VideoCaptureOpenOptions during initialization.

Implements OpenCVForUnity.Extensions.SourceToMat.IVideoCaptureMatSource.

◆ FPS

float OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.FPS

get

Gets the current playback frame rate in frames per second.

Implements OpenCVForUnity.Extensions.SourceToMat.IVideoFileMatSource.

◆ FrameCount

int OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.FrameCount

get

Gets the total frame count of the video.

Implements OpenCVForUnity.Extensions.SourceToMat.IVideoFileMatSource.

◆ FrameIndex

int OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.FrameIndex

getset

Gets or sets the current frame index.

Implements OpenCVForUnity.Extensions.SourceToMat.IVideoFileMatSource.

◆ FramePosRatio

float OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.FramePosRatio

getset

Gets or sets the current frame position as a ratio from 0.0 to 1.0.

Implements OpenCVForUnity.Extensions.SourceToMat.IVideoFileMatSource.

◆ Loop

bool OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.Loop

getset

Gets or sets whether the video loops after reaching the end.

Implements OpenCVForUnity.Extensions.SourceToMat.IVideoFileMatSource.

◆ RequestedVideoFilePath

string OpenCVForUnity.Extensions.SourceToMat.VideoCaptureMatSource.RequestedVideoFilePath = string.Empty

getset

Gets or sets the requested video file path.

Implements OpenCVForUnity.Extensions.SourceToMat.IVideoFileMatSource.

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

OpenCVForUnity/Assets/OpenCVForUnity/Scripts/Extensions/SourceToMat/MatSources/VideoCaptureMatSource.cs

Public Member Functions

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ VideoCaptureMatSource()

Member Function Documentation

◆ InitializeAsync() [1/2]

◆ InitializeAsync() [2/2]

◆ PauseAsync()

◆ PlayAsync()

◆ StopAsync()

◆ SyncGrabberBeforeOpen()

◆ Tick()

Property Documentation

◆ ApiPreference

◆ FPS

◆ FrameCount

◆ FrameIndex

◆ FramePosRatio

◆ Loop

◆ RequestedVideoFilePath