bw_note_queue

Simple data structure that helps keeping track of note on/off events and pressed key status.

It is not concerned with timing.

Examples

Here you can download one or more example VST3 plugins for Windows, macOS and Linux. Source code of the audio engine(s) is included in the archive(s).

VST® is a trademark of Steinberg Media Technologies GmbH, registered in Europe and other countries.

API

Module type: Utility

bw_note_queue_status

typedef struct {
	char  pressed;
	float velocity;
} bw_note_queue_status;

Note status:

• pressed: whether the note is pressed (non-0) or not (0);
• velocity: velocity in [0.f, 1.f] or otherwise negative to indicate unknown / not available.

bw_note_queue_event

typedef struct {
	unsigned char note;
	char          went_off;
} bw_note_queue_event;

Note on/off event:

• note: note number in [0, 127];
• went_off: whether a note off event fired on the same note (non-0) or not (0) -- see bw_note_queue.

bw_note_queue

typedef struct {
	bw_note_queue_event  events[128];
	bw_note_queue_status status[128];
	unsigned char        n_events;
	unsigned char        n_pressed;
} bw_note_queue;

Note on/off event queue and pressed key status:

• events: events since the reset/clear -- the order is not meaningful and it contains maximum one event per note number, so that the last event added for a given note overwrites the previous if it exists; went_off is set to non-0 in case of a note off event or when overwriting an event whose went_off was already non-0;
• status: current status of all notes;
• n_events: number of elements in events;
• n_pressed: number of currently pressed keys.

bw_note_queue_reset()

static inline void bw_note_queue_reset(
	bw_note_queue * BW_RESTRICT queue);

Clears both the event queue (no events) and the note statuses (all notes off, all velocities 0.f) in queue.

bw_note_queue_clear()

static inline void bw_note_queue_clear(
	bw_note_queue * BW_RESTRICT queue);

Clears the event queue (no events) in queue without affecting the note statuses.

bw_note_queue_add()

static inline void bw_note_queue_add(
	bw_note_queue * BW_RESTRICT queue,
	unsigned char               note,
	char                        pressed,
	float                       velocity,
	char                        force_went_off);

Adds a new event to queue with the specified note number, pressed value, and velocity.

If force_went_off is set to non-0, went_off is always set to non-0.

bw_note_queue_all_notes_off()

static inline void bw_note_queue_all_notes_off(
	bw_note_queue * BW_RESTRICT queue,
	float                       velocity);

Turns all notes off in queue, adding note off events as needed with the given velocity.

bw_note_queue_is_valid()

static inline char bw_note_queue_is_valid(
	const bw_note_queue * BW_RESTRICT queue);

Tries to determine whether queue is valid and returns non-0 if it seems to be the case and 0 if it is certainly not. False positives are possible, false negatives are not.

queue must at least point to a readable memory block of size greater than or equal to that of bw_note_queue.

C++ wrapper

Brickworks::NoteQueue

class NoteQueue {
public:
	NoteQueue();
	
	void clear();

	void add(
		unsigned char note,
		bool          pressed,
		float         velocity,
		bool          forceWentOff);
	
	bw_note_queue queue;
};

Changelog

• Version 1.1.0:
  • Added bw_note_queue_all_notes_off().
  • Added support for BW_INCLUDE_WITH_QUOTES, BW_NO_CXX, and BW_CXX_NO_EXTERN_C.
  • Fixed bug in bw_note_queue_is_valid() which erroneously marked queue with 128 pressed notes or 128 events as invalid.
  • Fixed typo in the documentation of bw_note_queue_reset().
• Version 1.0.1:
  • Now using BW_NULL.
• Version 1.0.0:
  • Removed redundant status member from bw_note_queue_event.
  • Possibly improved memeory layout of bw_note_queue.
  • Moved C++ code to C header.
  • Removed usage of reserved identifiers and designated initializers.
  • Clarified ambiguity in the documentation of bw_note_queue_status.
• Version 0.6.0:
  • Added debugging code.
  • Removed dependency on bw_config.
• Version 0.5.0:
  • First release.