Added tons of documentation headers to functions in source files.

This commit is contained in:
Johannes Findeisen 2026-10-27 01:58:27 +01:00
commit 4eb2080933
43 changed files with 3953 additions and 43 deletions

View file

@ -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)
{