Class TimedDataSource<T>

A base class that implements the default behaviour for a ITimedDataSource.

Inheritance
Object
TimedDataSource<T>
Namespace: Unity.LiveCapture
Syntax
[Serializable]
public abstract class TimedDataSource<T> : ITimedDataSource, IRegistrable
Type Parameters
Name Description
T

The type used to store the data for a frame.

Properties

BufferSize

The current buffer size.

Declaration
public int BufferSize { get; set; }
Property Value
Type Description
Int32
Implements

Enabled

Is the data source ready to buffer samples.

Declaration
public bool Enabled { get; }
Property Value
Type Description
Boolean

FrameRate

The number of data samples per second.

Declaration
public FrameRate FrameRate { get; set; }
Property Value
Type Description
FrameRate
Implements

Interpolator

The interpolator to use when presenting values between frame samples.

Declaration
public IInterpolator<T> Interpolator { get; set; }
Property Value
Type Description
IInterpolator<T>

IsSynchronized

Signal to the data source whether it is being synchronized via PresentAt(FrameTimeWithRate).

Declaration
public bool IsSynchronized { get; set; }
Property Value
Type Description
Boolean
Implements
Remarks

When true, the data source should disable its own update mechanism.

MaxBufferSize

The maximum size of the sample buffer, if limited.

Declaration
public virtual int? MaxBufferSize { get; }
Property Value
Type Description
Nullable<Int32>
Implements

MinBufferSize

The minimum size of the sample buffer, if limited.

Declaration
public virtual int? MinBufferSize { get; }
Property Value
Type Description
Nullable<Int32>
Implements

Offset

The time offset applied to sample timecodes, in frames.

Declaration
public FrameTime Offset { get; set; }
Property Value
Type Description
FrameTime
Implements
Remarks

The frame duration corresponds to the FrameRate of this source. This value should typically match the time delay between timecode generation and data sampling.

SourceObject

The object that owns this data source.

Declaration
public Object SourceObject { get; set; }
Property Value
Type Description
Object

Synchronizer

The ISynchronizer controlling this source.

Declaration
public ISynchronizer Synchronizer { get; set; }
Property Value
Type Description
ISynchronizer
Implements
Remarks

In most cases you can simply implement this as an auto-property. The default synchronizer implementation automatically assigns this property when you call AddDataSource(ITimedDataSource).

Methods

AddSample(in T, in FrameTimeWithRate)

Adds a new data sample to the buffer.

Declaration
public void AddSample(in T value, in FrameTimeWithRate time)
Parameters
Type Name Description
T value

The sample value to add.
FrameTimeWithRate time

The time of the sample.
See Also

AddSampleWithGeneratedTime(in T)

Adds a new data sample to the buffer.

Declaration
public FrameTimeWithRate AddSampleWithGeneratedTime(in T value)
Parameters
Type Name Description
T value

The sample value to add.
Returns
Type Description
FrameTimeWithRate

The generated sample time.
Remarks

Use this when a device does not provide timecode information with the samples, and instead relies on genlock to facilitate synchronization. When this data source is assigned to a synchronizer, a timecode will be generated using the synchronizer's presentation time. This should usually be called once per frame. When called multiple times in a single frame, the new value will overwrite any previous values submitted for the current frame.

See Also

ClearBuffer()

Removes all frames from the data buffer.

Declaration
public void ClearBuffer()

Disable()

Deactivates the data source.

Declaration
public virtual void Disable()

Enable()

Activates the data source.

Declaration
public virtual void Enable()

GenerateFrameTime(in FrameRate)

Gets a time based on the current engine time.

Declaration
public static FrameTimeWithRate GenerateFrameTime(in FrameRate frameRate)
Parameters
Type Name Description
FrameRate frameRate

The frame rate of the frame sequence.
Returns
Type Description
FrameTimeWithRate

The generated time.

GetSamplesInRange(FrameTime, FrameTime)

Retrieves the buffered samples that lie in a time range.

Declaration
public IEnumerable<(FrameTime time, T value)> GetSamplesInRange(FrameTime from, FrameTime to)
Parameters
Type Name Description
FrameTime from

The start time of the range, expressed relative to the FrameRate.
FrameTime to

The end time of the range, expressed relative to the FrameRate.
Returns
Type Description
IEnumerable<(T1, T2)<FrameTime, T>>

An iterator that returns all samples in the specified range.
Remarks

The range bounds are inclusive.

TryGetBufferRange(out FrameTime, out FrameTime)

Gets the frame time of the newest and oldest samples buffered by the data source.

Declaration
public bool TryGetBufferRange(out FrameTime oldestSample, out FrameTime newestSample)
Parameters
Type Name Description
FrameTime oldestSample

The frame time of the oldest buffered sample, or langword_csharp_default if there are no buffered samples.
FrameTime newestSample

The frame time of the newest buffered sample, or langword_csharp_default if there are no buffered samples.
Returns
Type Description
Boolean

true if there are any buffered samples; otherwise, false.
Implements
Remarks

The frame duration corresponds to the FrameRate of this source.

TryGetSample(FrameTime, out T)

Retrieves a sample from the buffer at the specified time.

Declaration
public TimedSampleStatus TryGetSample(FrameTime frame, out T value)
Parameters
Type Name Description
FrameTime frame

The time to retrieve the sample data for, expressed relative to the FrameRate.
T value
Returns
Type Description
TimedSampleStatus

The status of the retrieved sample.
Remarks

If there isn't a sample at the specified time, the following occurs:

a) if the time is bounded by the oldest and newest samples contained in the buffer, sampleValue is set to the nearest sample and returns Ok.
b) if the time is outside of the buffer but there is at least one buffered sample, sampleValue is set to the newest or oldest buffered sample (whichever is closer) and returns Behind or Ahead respectively.
c) otherwise, returns DataMissing and sets sampleValue to langword_csharp_default.

Events

FramePresented

An event invoked when this source presents a synchronized frame.

Declaration
public event Action<T, FrameTimeWithRate> FramePresented
Event Type
Type Description
Action<T, FrameTimeWithRate>
Remarks

This will only invoked when IsSynchronized is true.

  • The first parameter is the sample value for the presented frame.
  • The second parameter is the sample time for the presented frame.

Explicit Interface Implementations

IRegistrable.FriendlyName

Get a human-readable name for the instance.

Declaration
string IRegistrable.FriendlyName { get; }
Returns
Type Description
String
Implements

IRegistrable.Id

Get the unique identifier for this instance.

Declaration
string IRegistrable.Id { get; }
Returns
Type Description
String
Implements
Remarks

The ID should not be null or empty, and is expected to remain constant for the life of the instance.

ITimedDataSource.PresentAt(FrameTimeWithRate)

Applies the data for a given timecode to the scene.

Declaration
TimedSampleStatus ITimedDataSource.PresentAt(FrameTimeWithRate presentTime)
Parameters
Type Name Description
FrameTimeWithRate presentTime

The timecode to present.
Returns
Type Description
TimedSampleStatus

A status representing the ability of the source to present at the requested timecode.
Implements

ITimedDataSource.UndoTarget

The object to record to the undo stack when the user modifies the properties of this data source.

Declaration
Object ITimedDataSource.UndoTarget { get; }
Returns
Type Description
Object
Implements
Remarks

To enable undo when using the synchronization windows, this must be the object that stores the serialized state for this data source. When null, this data source will not support undo operations.