Class NoteBuffer

Namespace

Celeritas.Core

Assembly

Celeritas.dll

A fixed-capacity, native-memory buffer of notes stored as a structure of arrays (pitch, offset, duration, velocity). Offsets and durations are in whole-note units. Must be disposed to release the unmanaged allocation.

public sealed class NoteBuffer : IDisposable

Inheritance

object

NoteBuffer

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

NoteBuffer(int)

Allocates a buffer that can hold up to capacity notes.

public NoteBuffer(int capacity)

Parameters

capacity int

Maximum number of notes; must be positive.

Exceptions

ArgumentOutOfRangeException

capacity is not positive.

OutOfMemoryException

The required allocation exceeds the process address space.

Properties

Capacity

Maximum number of notes the buffer can hold.

public int Capacity { get; }

Property Value

int

Count

Number of notes currently stored.

public int Count { get; }

Property Value

int

PitchReadOnlySpan

Alias for PitchesReadOnly.

public ReadOnlySpan<int> PitchReadOnlySpan { get; }

Property Value

ReadOnlySpan<int>

PitchSpan

Alias for Pitches.

public Span<int> PitchSpan { get; }

Property Value

Span<int>

Pitches

Writable span over the stored MIDI pitches (length Count).

public Span<int> Pitches { get; }

Property Value

Span<int>

Exceptions

ObjectDisposedException

The buffer has been disposed.

PitchesReadOnly

Read-only span over the stored MIDI pitches (length Count).

public ReadOnlySpan<int> PitchesReadOnly { get; }

Property Value

ReadOnlySpan<int>

Exceptions

ObjectDisposedException

The buffer has been disposed.

Velocities

Writable span over the stored velocities (length Count).

public Span<float> Velocities { get; }

Property Value

Span<float>

Exceptions

ObjectDisposedException

The buffer has been disposed.

VelocitiesReadOnly

Read-only span over the stored velocities (length Count).

public ReadOnlySpan<float> VelocitiesReadOnly { get; }

Property Value

ReadOnlySpan<float>

Exceptions

ObjectDisposedException

The buffer has been disposed.

VelocityReadOnlySpan

Alias for VelocitiesReadOnly.

public ReadOnlySpan<float> VelocityReadOnlySpan { get; }

Property Value

ReadOnlySpan<float>

VelocitySpan

Alias for Velocities.

public Span<float> VelocitySpan { get; }

Property Value

Span<float>

Methods

Add(in NoteEvent)

Appends a note event to the buffer.

public void Add(in NoteEvent note)

Parameters

note NoteEvent

Exceptions

ObjectDisposedException

The buffer has been disposed.

InvalidOperationException

The buffer is at capacity.

AddNote(int, Rational, Rational, float)

Appends a note to the buffer.

public void AddNote(int pitch, Rational offset, Rational duration, float velocity = 0.8)

Parameters

pitch int

MIDI pitch number.

offset Rational

Start offset in whole-note units.

duration Rational

Duration in whole-note units.

velocity float

Velocity (default 0.8).

Exceptions

ObjectDisposedException

The buffer has been disposed.

InvalidOperationException

The buffer is at capacity.

AddRange(ReadOnlySpan<NoteEvent>)

Appends a batch of note events to the buffer.

public void AddRange(ReadOnlySpan<NoteEvent> notes)

Parameters

notes ReadOnlySpan<NoteEvent>

Exceptions

ObjectDisposedException

The buffer has been disposed.

InvalidOperationException

The notes would exceed the buffer's capacity.

Clear()

Fast reset for reuse (does not zero memory)

public void Clear()

Dispose()

Releases the buffer's unmanaged memory.

public void Dispose()

~NoteBuffer()

Releases the unmanaged pitch buffer if Dispose() was not called.

protected ~NoteBuffer()

Get(int)

Returns the full note event (pitch, offset, duration, velocity) at index.

public NoteEvent Get(int index)

Parameters

index int

Returns

NoteEvent

Exceptions

ObjectDisposedException

The buffer has been disposed.

ArgumentOutOfRangeException

index is outside [0, Count).

GetChords()

Legacy chord analysis that allocates a List<T>. Groups consecutive notes that share the same start offset into one chord per offset. Requires the buffer to be sorted by offset — call Sort() first (appending notes only in nondecreasing offset order also counts as sorted).

public List<(Rational Time, ushort Mask)> GetChords()

Returns

List<(Rational Time, ushort Mask)>

Exceptions

ObjectDisposedException

The buffer has been disposed.

InvalidOperationException

The buffer is not sorted by offset.

GetChords(Span<(Rational Time, ushort Mask)>)

Zero-allocation chord analysis. Groups consecutive notes that share the same start offset into one chord per offset. Requires the buffer to be sorted by offset — call Sort() first (appending notes only in nondecreasing offset order also counts as sorted).

If output is shorter than the number of distinct offsets, the result is silently truncated to output.Length chords (span-API convention); the return value is the number of chords actually written. Size output to Count to guarantee no truncation.

public int GetChords(Span<(Rational Time, ushort Mask)> output)

Parameters

output Span<(Rational Time, ushort Mask)>

Returns

int

The number of chords written to output.

Exceptions

ObjectDisposedException

The buffer has been disposed.

InvalidOperationException

The buffer is not sorted by offset.

GetDuration(int)

Returns the duration (whole-note units) of the note at index.

public Rational GetDuration(int index)

Parameters

index int

Returns

Rational

Exceptions

ObjectDisposedException

The buffer has been disposed.

ArgumentOutOfRangeException

index is outside [0, Count).

GetOffset(int)

Returns the start offset (whole-note units) of the note at index.

public Rational GetOffset(int index)

Parameters

index int

Returns

Rational

Exceptions

ObjectDisposedException

The buffer has been disposed.

ArgumentOutOfRangeException

index is outside [0, Count).

GetVelocity(int)

Returns the velocity of the note at index.

public float GetVelocity(int index)

Parameters

index int

Returns

float

Exceptions

ObjectDisposedException

The buffer has been disposed.

ArgumentOutOfRangeException

index is outside [0, Count).

PitchAt(int)

Returns the MIDI pitch at index.

public int PitchAt(int index)

Parameters

index int

Returns

int

Exceptions

ObjectDisposedException

The buffer has been disposed.

ArgumentOutOfRangeException

index is outside [0, Count).

SetPitch(int, int)

Sets the MIDI pitch at index to value.

public void SetPitch(int index, int value)

Parameters

index int

value int

Exceptions

ObjectDisposedException

The buffer has been disposed.

ArgumentOutOfRangeException

index is outside [0, Count).

Sort()

Sorts the notes in place by ascending start offset (stable on ties). Sorting (or appending notes only in nondecreasing offset order) makes the buffer eligible for GetChords() and its span overload.

public void Sort()

Exceptions

ObjectDisposedException

The buffer has been disposed.