Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Expanded discussion of -1 wildcard note address mechanism #370

Merged
merged 2 commits into from
Dec 20, 2023
Merged

Expanded discussion of -1 wildcard note address mechanism #370

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3b79854
Expanded discussion of -1 wildcard note address mechanism
baconpaul Dec 18, 2023
12c6094
Address review feedback
baconpaul Dec 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 35 additions & 4 deletions include/clap/events.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,9 +117,37 @@ enum {
};

// Note on, off, end and choke events.
//
// Clap addresses notes and voices using the 4-value tuple
// (port, channel, key, note_id). note on/off/end/choke
abique marked this conversation as resolved.
Show resolved Hide resolved
// events and parameter modulation messages are delivered with
// these values populated.
//
// Values in a note and voice address are either >= 0 if they
// are specified, or -1 to indicate a wildcard. A wildcard
// means a voice with any value in that part of the tuple
// matches the message.
//
// For instance, a (PCKN) of (0, 3, -1, -1) will match all voices
// on channel 3 of port 0. And a PCKN of (-1, 0, 60, -1) will match
// all channel 0 key 60 voices, independent of port or note id.
//
// Especially in the case of note-on note-off pairs, and in the
// absence of voice stacking or polyphonic modulation, a host may
// choose to issue a note id only at note on. So you may see a
// message stream like
//
// CLAP_EVENT_NOTE_ON [0,0,60,184]
// CLAP_EVENT_NOTE_OFF [0,0,60,-1]
//
// and the host will expect the first voice to be released.
// Well constructed plugins will search for voices and notes using
// the entire tuple.
//
// In the case of note choke or end events:
// - the velocity is ignored.
// - key and channel are used to match active notes, a value of -1 matches all.
// - key and channel are used to match active notes
// - note_id is optionally provided by the host
typedef struct clap_event_note {
clap_event_header_t header;

Expand Down Expand Up @@ -153,7 +181,8 @@ typedef struct clap_event_note_expression {

clap_note_expression expression_id;

// target a specific note_id, port, key and channel, -1 for global
// target a specific note_id, port, key and channel, with
// -1 meaning wildcard, per the wildcard discussion above
int32_t note_id;
int16_t port_index;
int16_t channel;
Expand All @@ -169,7 +198,8 @@ typedef struct clap_event_param_value {
clap_id param_id; // @ref clap_param_info.id
void *cookie; // @ref clap_param_info.cookie

// target a specific note_id, port, key and channel, -1 for global
// target a specific note_id, port, key and channel, with
// -1 meaning wildcard, per the wildcard discussion above
int32_t note_id;
int16_t port_index;
int16_t channel;
Expand All @@ -185,7 +215,8 @@ typedef struct clap_event_param_mod {
clap_id param_id; // @ref clap_param_info.id
void *cookie; // @ref clap_param_info.cookie

// target a specific note_id, port, key and channel, -1 for global
// target a specific note_id, port, key and channel, with
// -1 meaning wildcard, per the wildcard discussion above
int32_t note_id;
int16_t port_index;
int16_t channel;
Expand Down