Added tons of documentation headers to functions in source files.
This commit is contained in:
parent
0f04e056b2
commit
4eb2080933
43 changed files with 3953 additions and 43 deletions
|
|
@ -32,6 +32,15 @@ struct xtc_midi_plan {
|
|||
uint64_t cutoff[16], next_position, age;
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief Decodes a complete note or all-notes-off MIDI message into a block event.
|
||||
*
|
||||
* @param bytes Borrowed MIDI message bytes.
|
||||
* @param size Number of message bytes.
|
||||
* @param offset Sample offset within the current block.
|
||||
* @param out Receives the operation result.
|
||||
* @return XTC_OK on success, or an error code describing the failure.
|
||||
*/
|
||||
xtc_result xtc_midi_decode(const unsigned char *bytes, size_t size, unsigned int offset, xtc_midi_event *out)
|
||||
{
|
||||
xtc_midi_event e;
|
||||
|
|
@ -54,6 +63,13 @@ xtc_result xtc_midi_decode(const unsigned char *bytes, size_t size, unsigned int
|
|||
return XTC_OK;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Orders note endpoints by position and endpoint delta for overlap counting.
|
||||
*
|
||||
* @param left Borrowed sort element to compare.
|
||||
* @param right Borrowed sort element to compare.
|
||||
* @return Negative, zero, or positive according to endpoint ordering.
|
||||
*/
|
||||
static int compare_endpoint(const void *left, const void *right)
|
||||
{
|
||||
const endpoint *a = left, *b = right;
|
||||
|
|
@ -62,6 +78,11 @@ static int compare_endpoint(const void *left, const void *right)
|
|||
return a->change - b->change; /* End before start at the same sample. */
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Clears live voices, scheduling continuity, and panic suppression.
|
||||
*
|
||||
* @param p Instrument plan and its single-owner runtime state.
|
||||
*/
|
||||
void xtc_midi_plan_reset(xtc_midi_plan *p)
|
||||
{
|
||||
if (!p)
|
||||
|
|
@ -72,6 +93,14 @@ void xtc_midi_plan_reset(xtc_midi_plan *p)
|
|||
p->age = 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Compiles scheduled notes and mixer state into a bounded sine-instrument plan.
|
||||
*
|
||||
* @param project Project model; borrowed for this call.
|
||||
* @param rate Sample rate in hertz.
|
||||
* @param out Receives the newly allocated object; caller owns it on success.
|
||||
* @return XTC_OK on success, or an error code describing the failure.
|
||||
*/
|
||||
xtc_result xtc_midi_plan_create(const xtc_project *project, unsigned int rate, xtc_midi_plan **out)
|
||||
{
|
||||
xtc_midi_plan *p;
|
||||
|
|
@ -155,11 +184,23 @@ xtc_result xtc_midi_plan_create(const xtc_project *project, unsigned int rate, x
|
|||
return XTC_OK;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Releases scheduled notes and instrument state; accepts NULL.
|
||||
*
|
||||
* @param p Instrument plan and its single-owner runtime state.
|
||||
*/
|
||||
void xtc_midi_plan_destroy(xtc_midi_plan *p)
|
||||
{
|
||||
free(p);
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Clears live voices and suppresses already-started scheduled notes on one MIDI channel.
|
||||
*
|
||||
* @param p Instrument plan and its single-owner runtime state.
|
||||
* @param channel MIDI channel, 0 to 15.
|
||||
* @param position Absolute sample position at the start of the block.
|
||||
*/
|
||||
static void channel_off(xtc_midi_plan *p, unsigned int channel, uint64_t position)
|
||||
{
|
||||
size_t i;
|
||||
|
|
@ -169,6 +210,12 @@ static void channel_off(xtc_midi_plan *p, unsigned int channel, uint64_t positio
|
|||
p->cutoff[channel] = position == UINT64_MAX ? position : position + 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Silences live voices and suppresses scheduled notes already started at the given position.
|
||||
*
|
||||
* @param p Instrument plan and its single-owner runtime state.
|
||||
* @param position Absolute sample position at the start of the block.
|
||||
*/
|
||||
void xtc_midi_plan_panic(xtc_midi_plan *p, uint64_t position)
|
||||
{
|
||||
unsigned int c;
|
||||
|
|
@ -179,6 +226,13 @@ void xtc_midi_plan_panic(xtc_midi_plan *p, uint64_t position)
|
|||
p->next_position = position;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Applies a live MIDI event, stealing the oldest voice when necessary.
|
||||
*
|
||||
* @param p Instrument plan and its single-owner runtime state.
|
||||
* @param e MIDI event to apply.
|
||||
* @param position Absolute sample position at the start of the block.
|
||||
*/
|
||||
static void event(xtc_midi_plan *p, const xtc_midi_event *e, uint64_t position)
|
||||
{
|
||||
size_t i, slot = SIZE_MAX;
|
||||
|
|
@ -218,6 +272,15 @@ static void event(xtc_midi_plan *p, const xtc_midi_event *e, uint64_t position)
|
|||
p->voices[slot].age = p->age++;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Accumulates scheduled and live sine voices over an event-free sample interval.
|
||||
*
|
||||
* @param p Instrument plan and its single-owner runtime state.
|
||||
* @param position Absolute sample position at the start of the block.
|
||||
* @param out Destination sample buffer with room for the requested frames.
|
||||
* @param right Destination right-channel buffer; NULL selects mono rendering.
|
||||
* @param frames Number of audio frames.
|
||||
*/
|
||||
static void segment(xtc_midi_plan *p, uint64_t position, float *out, float *right, size_t frames)
|
||||
{
|
||||
size_t i, j;
|
||||
|
|
@ -253,6 +316,18 @@ static void segment(xtc_midi_plan *p, uint64_t position, float *out, float *righ
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Renders scheduled and live MIDI with sample-offset events and track gain and pan.
|
||||
*
|
||||
* @param p Instrument plan and its single-owner runtime state.
|
||||
* @param position Absolute sample position at the start of the block.
|
||||
* @param events Borrowed MIDI events sorted by sample offset.
|
||||
* @param count Number of MIDI events.
|
||||
* @param out Destination sample buffer with room for the requested frames.
|
||||
* @param right Destination right-channel buffer; NULL selects mono rendering.
|
||||
* @param frames Number of audio frames.
|
||||
* @return XTC_OK on success, or an error code describing the failure.
|
||||
*/
|
||||
xtc_result xtc_midi_plan_render_stereo(xtc_midi_plan *p, uint64_t position, const xtc_midi_event *events, size_t count,
|
||||
float *out, float *right, size_t frames)
|
||||
{
|
||||
|
|
@ -285,6 +360,17 @@ xtc_result xtc_midi_plan_render_stereo(xtc_midi_plan *p, uint64_t position, cons
|
|||
return XTC_OK;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Renders scheduled and live MIDI to mono without stereo pan attenuation.
|
||||
*
|
||||
* @param p Instrument plan and its single-owner runtime state.
|
||||
* @param position Absolute sample position at the start of the block.
|
||||
* @param events Borrowed MIDI events sorted by sample offset.
|
||||
* @param count Number of MIDI events.
|
||||
* @param out Destination sample buffer with room for the requested frames.
|
||||
* @param frames Number of audio frames.
|
||||
* @return XTC_OK on success, or an error code describing the failure.
|
||||
*/
|
||||
xtc_result xtc_midi_plan_render(xtc_midi_plan *p, uint64_t position, const xtc_midi_event *events, size_t count,
|
||||
float *out, size_t frames)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -2,6 +2,16 @@
|
|||
#include "../graph/graph_internal.h"
|
||||
#include <string.h>
|
||||
|
||||
/**
|
||||
* @brief Adds a MIDI clip and ensures an instrument output route exists.
|
||||
*
|
||||
* @param p Project model; borrowed for this call.
|
||||
* @param track Stable track identifier.
|
||||
* @param start Start position in musical ticks.
|
||||
* @param length Duration in musical ticks.
|
||||
* @param out Receives the operation result.
|
||||
* @return XTC_OK on success, or an error code describing the failure.
|
||||
*/
|
||||
xtc_result xtc_project_add_midi_clip(xtc_project *p, uint64_t track, uint64_t start, uint64_t length, uint64_t *out)
|
||||
{
|
||||
xtc_project *c = NULL;
|
||||
|
|
@ -40,6 +50,13 @@ xtc_result xtc_project_add_midi_clip(xtc_project *p, uint64_t track, uint64_t st
|
|||
return r;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Copies the number of notes in the project.
|
||||
*
|
||||
* @param p Project model; borrowed for this call.
|
||||
* @param out Receives the operation result.
|
||||
* @return XTC_OK on success, or an error code describing the failure.
|
||||
*/
|
||||
xtc_result xtc_project_note_count(const xtc_project *p, size_t *out)
|
||||
{
|
||||
if (!p || !out)
|
||||
|
|
@ -48,6 +65,14 @@ xtc_result xtc_project_note_count(const xtc_project *p, size_t *out)
|
|||
return XTC_OK;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Copies a note snapshot selected by dense list index.
|
||||
*
|
||||
* @param p Project model; borrowed for this call.
|
||||
* @param i Zero-based index in the dense list.
|
||||
* @param out Receives the operation result.
|
||||
* @return XTC_OK on success, or an error code describing the failure.
|
||||
*/
|
||||
xtc_result xtc_project_get_note(const xtc_project *p, size_t i, xtc_note_info *out)
|
||||
{
|
||||
if (!p || !out)
|
||||
|
|
@ -58,6 +83,18 @@ xtc_result xtc_project_get_note(const xtc_project *p, size_t i, xtc_note_info *o
|
|||
return XTC_OK;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Validates a note's MIDI fields and range within a MIDI clip source.
|
||||
*
|
||||
* @param p Project model; borrowed for this call.
|
||||
* @param clip Stable clip identifier.
|
||||
* @param start Start position in musical ticks.
|
||||
* @param length Duration in musical ticks.
|
||||
* @param pitch MIDI note number, 0 to 127.
|
||||
* @param velocity MIDI note velocity, 1 to 127.
|
||||
* @param channel MIDI channel, 0 to 15.
|
||||
* @return XTC_OK on success, or an error code describing the failure.
|
||||
*/
|
||||
static xtc_result valid_note(const xtc_project *p, uint64_t clip, uint64_t start, uint64_t length, unsigned int pitch,
|
||||
unsigned int velocity, unsigned int channel)
|
||||
{
|
||||
|
|
@ -73,6 +110,19 @@ static xtc_result valid_note(const xtc_project *p, uint64_t clip, uint64_t start
|
|||
return XTC_OK;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Adds a validated MIDI note with a new stable identifier.
|
||||
*
|
||||
* @param p Project model; borrowed for this call.
|
||||
* @param clip Stable clip identifier.
|
||||
* @param start Start position in musical ticks.
|
||||
* @param length Duration in musical ticks.
|
||||
* @param pitch MIDI note number, 0 to 127.
|
||||
* @param velocity MIDI note velocity, 1 to 127.
|
||||
* @param channel MIDI channel, 0 to 15.
|
||||
* @param out Receives the operation result.
|
||||
* @return XTC_OK on success, or an error code describing the failure.
|
||||
*/
|
||||
xtc_result xtc_project_add_note(xtc_project *p, uint64_t clip, uint64_t start, uint64_t length, unsigned int pitch,
|
||||
unsigned int velocity, unsigned int channel, uint64_t *out)
|
||||
{
|
||||
|
|
@ -98,6 +148,18 @@ xtc_result xtc_project_add_note(xtc_project *p, uint64_t clip, uint64_t start, u
|
|||
return XTC_OK;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Replaces a note's source range, pitch, velocity, and channel after validation.
|
||||
*
|
||||
* @param p Project model; borrowed for this call.
|
||||
* @param id Stable identifier of the object to find or edit.
|
||||
* @param start Start position in musical ticks.
|
||||
* @param length Duration in musical ticks.
|
||||
* @param pitch MIDI note number, 0 to 127.
|
||||
* @param velocity MIDI note velocity, 1 to 127.
|
||||
* @param channel MIDI channel, 0 to 15.
|
||||
* @return XTC_OK on success, or an error code describing the failure.
|
||||
*/
|
||||
xtc_result xtc_project_edit_note(xtc_project *p, uint64_t id, uint64_t start, uint64_t length, unsigned int pitch,
|
||||
unsigned int velocity, unsigned int channel)
|
||||
{
|
||||
|
|
@ -121,6 +183,13 @@ xtc_result xtc_project_edit_note(xtc_project *p, uint64_t id, uint64_t start, ui
|
|||
return XTC_OK;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Removes a note selected by stable identifier.
|
||||
*
|
||||
* @param p Project model; borrowed for this call.
|
||||
* @param id Stable identifier of the object to find or edit.
|
||||
* @return XTC_OK on success, or an error code describing the failure.
|
||||
*/
|
||||
xtc_result xtc_project_remove_note(xtc_project *p, uint64_t id)
|
||||
{
|
||||
size_t i;
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue