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

View file

@ -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;