Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 3 additions & 3 deletions docs/P1C_INTERNAL_SENDS_DAG_20261028.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ One physical input may fan out to multiple strips by explicit selection. Each st

- One `SendDefinition`: source strip, destination strip, pre/post-fader tap, linear send gain, stereo balance and enabled flag.
- `SendRequest::toMaster[channel]`: independent default main-out control (true by default). A sends-only channel can turn off its direct MASTER path, avoiding unwanted double-feed.
- **Cycle detector:** reject CH1→CH2→CH1 and longer loops and self-feedback before activation. A deterministic Kahn topological sort prepares the actual processing order. Enabling a rejected edge leaves the previous plan unchanged.
- **Cycle detector:** reject CH1→CH2→CH1 and longer loops and self-feedback before activation. A deterministic Kahn topological sort prepares the actual processing order. Reverse-order propagation then compiles a 10-bit transitive reachability mask for each source. `upstreamOf(a,b)` tests real directed connectivity in O(1), **not** just whether a happens to precede b in an unrelated topological order. Enabling a rejected edge leaves the previous plan unchanged.
- **Signal correctness:** pre-fader send comes from the *post-FX pre-fader* source buffer; post-fader send comes from *post-fader/post-mute* source buffer, provided by the future host integration. Different tap choices are not silently interchanged. Pre-fader sends intentionally do not follow fader attenuation; final policy for how solo/mute affects pre sends must be explicit in the native mixer host.
- **No implicit feedback or implicit master sends:** MASTER remains downstream of all strips. A MASTER-to-channel return requires a separate latency/feedback-safe graph contract and is deliberately unavailable at P1C.
- Direct send routing is additive to the channel's main output; `toMaster=false` is the way to construct an explicit sends-only source. The actual output stage must respect this flag before the feature is enabled.
Expand All @@ -24,7 +24,7 @@ One physical input may fan out to multiple strips by explicit selection. Each st
All validation, float finite checks, duplicate checks, cycle sorting, output offsets and send gain/pan coefficients are computed **off realtime** by `ChannelSendPlan::compile`. Plan publication is **not** implemented yet. `dispatch` loops only over the active source's outgoing edges and the host-provided fixed sample count, accumulating into preallocated, already-cleared destination buffers. No heap, locks, sample-loop trigonometry, topology scans, telemetry string allocations, graph destruction or plugin creation in this primitive.

The future RT integration must provide correctly scoped scratch buffers:
1. At the start of **each audio block**, clear **every** per-strip destination/incoming-send accumulator exactly once; also prepare each strip's physical input scratch. Use `ChannelRoutingPlan::extract` **before** any internal-send dispatch, because `extract` overwrites scratch. Never clear the destination after an upstream send has already written to it.
1. At the start of **each audio block**, clear **every** per-strip destination/incoming-send accumulator exactly once; also prepare each strip's physical input scratch. Use `ChannelRoutingPlan::extractSource` **before** any internal-send dispatch, because raw extraction overwrites scratch. This input must not be gated by fader zero or MASTER mute; use `extract` only for the legacy post-fader/solo-controlled path. A pre-fader send must still receive its source at fader -∞, with explicit native mute/solo policy applied later. Never clear the destination after an upstream send has already written to it.
2. Walk `topologicalOrder` once, combining that strip's prepared physical input and previously accumulated upstream sends into its *own* preallocated input buffer, then run its VST3 chain exactly once. Capture its post-FX/pre-fader tap.
3. Apply fader/mute/solo/pan to a distinct scratch output, capture its post-fader tap, and dispatch each configured pre/post tap only from the correct buffer. Do not reuse a destination accumulator as a source.
4. `receivesInternalAudio(strip)` is true for any bus-return recipient, **even if its hardware SourceMode is disconnected**. The future host must not skip a return merely because P1A/P1B's physical-only `Strip::active` is false. The return's effective gain/mute/solo state must be applied separately, without processing an invented physical input.
Expand All @@ -35,7 +35,7 @@ Input device masks, hotplug and callback port indices are owned by P1B + forthco

## Tests / boundaries

`tests/channel_send_plan_test.cpp` verifies: zero-send defaults, deterministic 10-strip order, pre vs post taps, send pan and gain, fan-out, fan-in, main-out disable, cycle/self-loop rejection, duplicate edge prevention, invalid indices, gain, pan and tap, disabled edges, over-capacity, transaction rollback and invalid buffer guard, plus audio-return activity with no physical port. Windows Release `assert` is kept enabled even under `NDEBUG` so CTest is meaningful. No redundant GitHub Action matrix.
`tests/channel_send_plan_test.cpp` verifies: zero-send defaults, deterministic 10-strip order, pre vs post taps, send pan and gain, fan-out, fan-in, main-out disable, cycle/self-loop rejection, duplicate edge prevention, invalid indices, gain, pan and tap, disabled edges, over-capacity, transaction rollback and invalid buffer guard, plus audio-return activity with no physical port. Windows Release `assert` is kept enabled even under `NDEBUG` so CTest is meaningful. The integration regression also compiles a real one-port `ChannelRoutingPlan` with source fader zero, proves `extractSource` remains nonzero while master accumulation is silent, and routes a live pre-fader send (plus stereo-to-mono fold and muted-source source read). No redundant GitHub Action matrix.

The planned GUI should offer a compact SOURCE chooser and channel Sends inspector. Only show a real send selection when both source and destination are native connected buses; all routed requests use native ACK/reject. No full DOM redraw on pointer movements and no fake meter.

Expand Down
21 changes: 21 additions & 0 deletions docs/P1D_PREFADER_SOURCE_DAG_RECONCILIATION_20261028.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# P1D reconciliation: real pre-fader source taps and DAG connectivity (2026-10-28)

Latest baseline: `main@d30cf35dc74991286547765ec9927e356273785b`, including the concurrently merged P1D `PreparedMixerBlock` offline DSP executor and the PR #101 lean Windows gate. This patch is the *non-overlapping corrective subset* of the former routing integration PR #112. Never merge PR #112 wholesale: its old CMake/Windows list would drop P1D's `ARMixPreparedMixerBlockTests` from latest main.

## Source and MASTER must have separate eligibility
The original P1A `Plan::extract` intentionally returns silence when `p.active=false`, which includes `faderLinear=0` and mute/solo exclusion. But a **pre-fader** send or an FX input must be able to read the physical source even when the post-fader MASTER contribution is off.

- New `Plan::extractSource` reads **only actual, validated physical input pointers** in preallocated stereo scratch independent of fader/mute/solo state, fails closed to zero for invalid or disconnected physical sources. `ChannelRoutingPlan::extractSource` additionally honors configured stereo→mono format folding. No fake audio or invented physical channel.
- Existing `extract` and `accumulate` preserve legacy post-fader/mute/solo/master output gating. This avoids changing existing P1A/B runtime semantics.
- `PreparedMixerBlock::process` in P1D was already designed to sum raw hardware directly into preallocated buffers *before* fader, so its working fader-zero/pre-send behavior and sample ordering are untouched. This additive API helps forthcoming live source/FX adapters follow the same correct boundary.

## Prepared send graph: rank is not reachability
`ChannelSendPlan::upstreamOf(a,b)` formerly returned true merely when topological rank(a) preceded rank(b), even for disconnected subgraphs. Its name must mean **a real directed path**. At off-RT `compile()` time, compute a 10-bit descendant mask for each node in reverse topological order, using direct outgoing edges plus each child's already-compiled descendants. `upstreamOf` becomes constant-time, bounded, no dynamic memory, no RT graph walk. Cycle rejection remains the existing Kahn gate.

## Tests and safety
- Release CTest `TenChannelAcyclicPrePostSends` now checks fader=0 RAW input→PRE send while post-fader/MASTER remains zero, raw muted-source extraction, stereo-input→mono-fader-zero fold, multi-hop DAG reachability and negative ordered-but-disconnected pairs.
- Existing P1D `TenChannelEndToEndPreparedAudioRender` test already confirms actual offline 10-strip audio processing, pre/post sends and zero-fader behavior; preserve it, its CMake target and main's Windows build target list **unchanged**.
- This patch changes NO `src/Main.cpp`, `src/LiveAudioEngine.h`, `PreparedMixerBlock.h`, JUCE callback, VST3 engine, FX Orbit, meter CSS/JS, Windows CI paths, packaging or active audio.
- P1D remains device-independent execution; **CH2–10 live audio, real device identity, graph epoch/ACK, per-strip VST3 negotiation and #15 clean hardware qualification remain TODO**. No claim of native DAW audio activation or hardware FPS improvements from CI.

Consolidation lineage: original stacked #108 → #110 → #111 was integrated by P1D before this correction. The unrelated PR #112 should be closed as superseded, never force-merged after P1D. `main` latest source-of-truth wins.
30 changes: 20 additions & 10 deletions engine/core/ChannelRoutingContract.h
Original file line number Diff line number Diff line change
Expand Up @@ -154,24 +154,34 @@ struct ChannelRoutingPlan final {
return true;
}

// Audio thread: consume *preallocated* stereo scratch supplied by caller.
// No format/device queries, allocation, mutex, trigonometry, or I/O here.
// Raw source input for FX and PRE-FADER taps. Keep fader and mute/solo
// policies separate, including stereo -> mono fold before the plugin.
bool extractSource(int strip, const float* const* input, int availableCallbackInputs,
float* left, float* right, int frames) const noexcept {
if (!base.extractSource(strip,input,availableCallbackInputs,left,right,frames))
return false;
foldIfMono(strip,left,right,frames);
return true;
}
// Post-fader/master compatibility path (inactive strips remain silent).
bool extract(int strip, const float* const* input, int availableCallbackInputs,
float* left, float* right, int frames) const noexcept {
if (!base.extract(strip, input, availableCallbackInputs, left, right, frames))
if (!base.extract(strip,input,availableCallbackInputs,left,right,frames))
return false;
if (foldStereoToMono[strip]) {
for (int i = 0; i < frames; ++i) {
const float mono = 0.5f * (left[i] + right[i]);
left[i] = mono;
right[i] = mono;
}
}
foldIfMono(strip,left,right,frames);
return true;
}
void accumulate(int strip, const float* left, const float* right,
float* masterL, float* masterR, int frames) const noexcept {
base.accumulate(strip, left, right, masterL, masterR, frames);
}
private:
void foldIfMono(int strip,float* left,float* right,int frames) const noexcept {
if (!foldStereoToMono[strip]) return;
for(int i=0;i<frames;++i) {
const float mono=0.5f*(left[i]+right[i]);
left[i]=mono;right[i]=mono;
}
}
};
} // namespace armix::mixer
20 changes: 19 additions & 1 deletion engine/core/ChannelSendPlan.h
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,9 @@ struct ChannelSendPlan final {
std::array<int,stripCount+1> outgoingOffset {};
std::array<int,stripCount> topologicalOrder {};
std::array<int,stripCount> orderRank {};
// True graph reachability, not mere topological rank. Bounded ten-bit
// descendants per source, computed only during non-RT plan compilation.
std::array<std::uint16_t,stripCount> downstreamMask {};
std::array<bool,stripCount> toMaster {};
// A strip can be a BUS RETURN even without any physical input; do not
// gate these strips on ChannelRoutingPlan::Strip::active (physical only).
Expand Down Expand Up @@ -137,6 +140,20 @@ struct ChannelSendPlan final {
j<candidate.outgoingOffset[found+1];++j)
--indegree[candidate.orderedEdges[j].destination];
}
// Reverse topological order ensures each child's transitive mask
// is final before publishing its parent's mask. 10 strips < 16 bits.
for(int k=stripCount-1;k>=0;--k) {
const int source=candidate.topologicalOrder[k];
std::uint16_t reachable=0;
for(int e=candidate.outgoingOffset[source];
e<candidate.outgoingOffset[source+1];++e) {
const int child=candidate.orderedEdges[e].destination;
reachable=static_cast<std::uint16_t>(
reachable | (std::uint16_t{1} << child) |
candidate.downstreamMask[child]);
}
candidate.downstreamMask[source]=reachable;
}
destination=candidate;
return true;
}
Expand Down Expand Up @@ -170,7 +187,8 @@ struct ChannelSendPlan final {
}
bool upstreamOf(int source,int destination) const noexcept {
return source>=0&&source<stripCount&&destination>=0&&
destination<stripCount&&orderRank[source]<orderRank[destination];
destination<stripCount&&source!=destination&&
(downstreamMask[source] & (std::uint16_t{1} << destination))!=0;
}
};
} // namespace armix::mixer
24 changes: 19 additions & 5 deletions engine/core/MixerRoutingPlan.h
Original file line number Diff line number Diff line change
Expand Up @@ -116,13 +116,15 @@ struct Plan final {
return true;
}

// RT: read one physical input source into preallocated stereo FX scratch.
// Stereo processors can consume both channels before accumulate().
bool extract(int strip,const float* const* inputs,int availableInputs,
float* left,float* right,int frames) const noexcept {
// RT: raw physical extraction for PRE-FADER sends / pre-FX processing.
// Hardware ownership is independent of current fader/mute/solo: at -inf dB
// a pre-fader send can still receive real input. The future caller owns
// explicit pre-send mute/solo policy. No DSP graph is activated here.
bool extractSource(int strip,const float* const* inputs,int availableInputs,
float* left,float* right,int frames) const noexcept {
if (!left || !right || frames<=0 || strip<0 || strip>=stripCount) return false;
const auto& route=strips[strip];
const bool valid=route.active && inputs &&
const bool valid=route.mode!=SourceMode::disconnected && inputs &&
route.inputA>=0 && route.inputA<availableInputs &&
route.inputB>=0 && route.inputB<availableInputs &&
inputs[route.inputA] && inputs[route.inputB];
Expand All @@ -135,6 +137,18 @@ struct Plan final {
return true;
}

// Compatibility extraction for the post-fader/solo-controlled mix path.
// Maintain old muted/zero-fader semantics for existing P1A/P1B clients.
bool extract(int strip,const float* const* inputs,int availableInputs,
float* left,float* right,int frames) const noexcept {
if (!left || !right || frames<=0 || strip<0 || strip>=stripCount) return false;
if (!strips[strip].active) {
std::fill_n(left,frames,0.f);std::fill_n(right,frames,0.f);
return false;
}
return extractSource(strip,inputs,availableInputs,left,right,frames);
}

// RT: mix one channel's POST-FX scratch onto the master accumulator.
void accumulate(int strip,const float* left,const float* right,
float* masterL,float* masterR,int frames) const noexcept {
Expand Down
62 changes: 62 additions & 0 deletions tests/channel_send_plan_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,12 @@ int main() {
assert(plan.upstreamOf(0,1));
assert(plan.upstreamOf(1,3));
assert(plan.upstreamOf(2,3));
assert(plan.upstreamOf(0,3)); // transitive 0 -> 1 -> 3
assert(!plan.upstreamOf(0,2)); // topological order != graph edge
assert(!plan.upstreamOf(1,2));
assert(!plan.upstreamOf(3,0));
assert(!plan.upstreamOf(0,0));
assert(!plan.upstreamOf(-1,3));
const std::array<float,3> one {1.f,-.25f,.75f};
const std::array<float,3> two {.5f,.25f,-.5f};
std::array<std::array<float,3>,stripCount> l{},r{};
Expand Down Expand Up @@ -107,6 +113,62 @@ int main() {
cfg.sends[i]={i,i+1,SendTap::postFader,1.f,0.f,true};
assert(ChannelSendPlan::compile(cfg,plan,err));
for(int i=0;i<stripCount;++i)assert(plan.topologicalOrder[i]==i);
assert(plan.upstreamOf(0,9) && !plan.upstreamOf(9,0));
cfg.sends[cfg.count++]={9,0,SendTap::postFader,1.f,0.f,true};
assert(!ChannelSendPlan::compile(cfg,plan,err)&&err.fault==SendFault::cycleDetected);

// Cross-module regression: fader=-infinity MUST NOT gate PRE-FADER sends.
// Raw source access and post-fader/master activity are independent.
ChannelRoutingConfig physical;
physical.stripsAndMaster.strips[0]={SourceMode::mono,0,-1,0.f,0.f,false,false};
ChannelRoutingPlan sourcePlan;
LayoutError layoutError;
constexpr std::array<int,1> enabledPort{0};
assert(ChannelRoutingPlan::compile(physical,enabledPort,sourcePlan,layoutError));
assert(!sourcePlan.base.strips[0].active);
const std::array<float,2> mic {.8f,-.4f};
const float* capture[]={mic.data()};
std::array<float,2> rawL{},rawR{},postL{},postR{},mixL{},mixR{};
assert(sourcePlan.extractSource(0,capture,1,rawL.data(),rawR.data(),2));
assert(close(rawL[0],.8f)&&close(rawR[0],.8f));
assert(!sourcePlan.extract(0,capture,1,postL.data(),postR.data(),2));
assert(close(postL[0],0.f)&&close(postR[0],0.f));
sourcePlan.accumulate(0,rawL.data(),rawR.data(),mixL.data(),mixR.data(),2);
assert(close(mixL[0],0.f)&&close(mixR[0],0.f));

SendRequest preOnly;
preOnly.count=1;
preOnly.toMaster[0]=false;
preOnly.sends[0]={0,1,SendTap::preFader,1.f,0.f,true};
ChannelSendPlan prePlan;
assert(ChannelSendPlan::compile(preOnly,prePlan,err));
std::array<std::array<float,2>,stripCount> recvL{},recvR{};
std::array<float*,stripCount> recvLp{},recvRp{};
for(int i=0;i<stripCount;++i) {
recvLp[i]=recvL[i].data();recvRp[i]=recvR[i].data();
}
prePlan.dispatch(0,SendTap::preFader,rawL.data(),rawR.data(),
recvLp.data(),recvRp.data(),2);
assert(close(recvL[1][0],.8f)&&close(recvR[1][0],.8f));
prePlan.dispatch(0,SendTap::postFader,postL.data(),postR.data(),
recvLp.data(),recvRp.data(),2);
assert(close(recvL[1][0],.8f)&&close(recvR[1][0],.8f));

// Pre-send mute/solo policy must be deliberately applied by its caller.
// Even a muted source retains raw physical input; MASTER stays quiet.
physical.stripsAndMaster.strips[0].mute=true;
assert(ChannelRoutingPlan::compile(physical,enabledPort,sourcePlan,layoutError));
assert(sourcePlan.extractSource(0,capture,1,rawL.data(),rawR.data(),2));
assert(!sourcePlan.extract(0,capture,1,postL.data(),postR.data(),2));

// Source stereo folded into MONO even with a zero fader (before FX/send).
constexpr std::array<int,2> stereoPorts{0,1};
physical.stripsAndMaster.strips[0]={SourceMode::stereo,0,1,0.f,0.f,false,false};
physical.formats[0]=ChannelFormat::mono;
assert(ChannelRoutingPlan::compile(physical,stereoPorts,sourcePlan,layoutError));
const std::array<float,2> side {-.2f,.4f};
const float* stereoCapture[]={mic.data(),side.data()};
assert(sourcePlan.extractSource(0,stereoCapture,2,rawL.data(),rawR.data(),2));
assert(close(rawL[0],.3f)&&close(rawR[0],.3f));
assert(!sourcePlan.extract(0,stereoCapture,2,postL.data(),postR.data(),2));
}
Loading