From f3ece28a10e0319eecc55124f515a4df9a34cedd Mon Sep 17 00:00:00 2001 From: minjaesong Date: Thu, 14 May 2026 01:07:40 +0900 Subject: [PATCH] taud: pattern ditto eff --- TAUD_NOTE_EFFECTS.md | 81 ++++++++++++++++ .../torvald/tsvm/peripheral/AudioAdapter.kt | 97 ++++++++++++++++++- 2 files changed, 176 insertions(+), 2 deletions(-) diff --git a/TAUD_NOTE_EFFECTS.md b/TAUD_NOTE_EFFECTS.md index da1438b..f7d1cff 100644 --- a/TAUD_NOTE_EFFECTS.md +++ b/TAUD_NOTE_EFFECTS.md @@ -735,6 +735,87 @@ Peak at maximum settings: $7F × $FF >> 9 = $3F — the full panning range. Retr --- +## 7 $xxyy — Pattern Ditto + +**Plain.** A per-channel "fill the rest from above" marker: the engine copies the **$xx rows immediately preceding this cell on the same channel** and pastes them $yy times starting on this row. The destination block therefore covers `$xx × $yy` rows beginning at the ditto row inclusive. Any field (note, instrument, vol-column, pan-column, effect) that the composer has explicitly written into a destination row stays put and patches the corresponding field of the copied source cell — empty fields fall through to the source. The ditto opcode itself is consumed by the marker on its arming row; the rest of that row's columns are patched from the source as usual, so an empty arming row plays back identically to the first row of the source block. + +For example, with `7 $1003` on row 16, rows 16..63 replay the contents of rows 0..15 three times. A `D $0400` punched onto row 22 simply overrides the effect column on that destination row; its note/vol/pan still come from the source row 6 (since (22 − 16) mod 16 = 6, and 0 + 6 = source row 6). + +Boundary rules: + +- The block stops at the end of the pattern: a ditto whose nominal span would overflow the pattern's row count clips silently at the final row. +- `$xx = $00`, `$yy = $00`, and any `$xx` greater than the row index on which the ditto sits are all treated as no-ops — there is nothing valid to copy from. +- A `7` cell appearing inside a source block is **not** recursively expanded: when that source row is pasted into a destination, its effect column is treated as empty. This keeps expansion single-pass and prevents unbounded nesting. +- Flow-control effects (B, C, S$Bx, S$Ex) that fall inside a source block still fire when their copy lands on a destination row, since the engine sees them as ordinary effect cells after expansion. Composers and converters should avoid placing S$Bx loop bounds wholly inside a ditto'd range — the loop counter is per-voice and the same destination row would be revisited twice with the same state. + +**Compatibility.** Unique to Taud — no ST3/IT/PT equivalent. The effect has no memory. + +**Implementation.** Per-voice state, all reset on pattern change alongside the existing pattern-loop / fine-pattern-delay clears: + +- `dittoActive: bool` +- `dittoSourceStart: int` — first row of the source block (inclusive) +- `dittoLength: int` — $xx, the block size +- `dittoEndRow: int` — last destination row (inclusive) + +At the very top of `applyTrackerRow`, before the per-voice reset of row-scope state, build an effective cell view for each voice: + +``` +raw = patternRows[V.pattern][N] # stored cell on row N for voice V +isArmer = (raw.effect == 0x7 and raw.effectArg != 0) + +if isArmer: + length = (raw.effectArg >> 8) & 0xFF + repeats = raw.effectArg & 0xFF + if length > 0 and repeats > 0 and length <= N: + V.dittoSourceStart = N - length + V.dittoLength = length + V.dittoEndRow = min(N + length * repeats - 1, patternLength - 1) + V.dittoActive = true + # else: malformed argument — fall through with dittoActive unchanged + +armRow = V.dittoSourceStart + V.dittoLength # always equals the row that armed this ditto + +if V.dittoActive and armRow <= N <= V.dittoEndRow: + srcRow = V.dittoSourceStart + ((N - V.dittoSourceStart) mod V.dittoLength) + src = patternRows[V.pattern][srcRow] + + cell.note = (raw.note != 0xFFFF) ? raw.note : src.note + cell.instrument = (raw.instrument != 0) ? raw.instrument : src.instrument + + # SEL_FINE / 0 is the canonical no-op encoding for the vol- and pan-columns; + # any other (selector, value) pair is a write and patches the source. + cell.vol, cell.volEff = (raw.volEff, raw.vol) != (SEL_FINE, 0) + ? (raw.vol, raw.volEff) + : (src.vol, src.volEff) + cell.pan, cell.panEff = (raw.panEff, raw.pan) != (SEL_FINE, 0) + ? (raw.pan, raw.panEff) + : (src.pan, src.panEff) + + # On the armer row, the 7-opcode is consumed by the marker, so for effect-column + # patching purposes the destination is treated as empty. Source 7-opcodes never + # propagate (no recursive expansion). + destOp, destArg = isArmer ? (0, 0) : (raw.effect, raw.effectArg) + if destOp != 0: + cell.effect, cell.effectArg = destOp, destArg + elif src.effect != 0x7: + cell.effect, cell.effectArg = src.effect, src.effectArg + else: + cell.effect, cell.effectArg = 0, 0 + +else: + cell = raw +``` + +The four ditto fields are not cleared at the natural end of the destination range; they simply stop matching the gating condition once `N` advances past `dittoEndRow`, and a later armer cell in the same pattern overwrites them in place. Explicit clears happen only on cue advance (B / C / natural pattern end) and full playhead reset, alongside the existing pattern-loop counters in `resetPatternLoopState` / `resetParams`. + +The rest of `applyTrackerRow` then dispatches on `cell` exactly as for an undittoed row — note triggering, vol/pan column application, and effect handling are unchanged. The expansion mutates the in-memory cell view only; the stored pattern data is never rewritten. + +Pattern-delay (S$Ex) re-runs `applyTrackerRow` on the same `N` — the ditto bookkeeping is idempotent across those re-entries because `dittoActive`, `dittoSourceStart`, `dittoLength`, and `dittoEndRow` already encode the destination range, and the armer guard `length <= N` makes repeated arming on the same row a no-op (the new state is identical to the old). The `armRow <= N` half of the gating condition is what protects against an S$Bx pattern-loop that jumps back to a row sitting strictly before the armer: rather than synthesising from a phantom source slot, the engine falls through to the raw cell. + +Effect dispatch sees the synthesised effect, never the literal `7` opcode of the armer cell — `OP_7` therefore exists in the engine's opcode table only as an explicit no-op for the rare malformed-armer fallthrough (`length == 0`, `repeats == 0`, or `length > N`). + +--- + ## 8 $xyzz — Bitcrusher **Plain.** Applies a bitcrusher to the current voice. The crusher has two independent stages — a sample-rate reducer (`zz`, sample-and-hold) and a bit-depth quantiser (`y`) — and shares its clipping mode (`x`) with effect 9 (Overdrive). The two stages are orthogonal: enabling either is sufficient to engage the effect, and either can be active alone. diff --git a/tsvm_core/src/net/torvald/tsvm/peripheral/AudioAdapter.kt b/tsvm_core/src/net/torvald/tsvm/peripheral/AudioAdapter.kt index e407842..029b86d 100644 --- a/tsvm_core/src/net/torvald/tsvm/peripheral/AudioAdapter.kt +++ b/tsvm_core/src/net/torvald/tsvm/peripheral/AudioAdapter.kt @@ -1279,6 +1279,7 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) { private object EffectOp { const val OP_NONE = 0x00 const val OP_1 = 0x01 + const val OP_7 = 0x07 const val OP_8 = 0x08 const val OP_9 = 0x09 const val OP_A = 0x0A @@ -2224,9 +2225,69 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) { val patNum = cue.patterns[vi] if (patNum == 0xFFF) continue val patIdx = patNum.coerceIn(0, 4095) - val row = playdata[patIdx][ts.rowIndex] + val rawRow = playdata[patIdx][ts.rowIndex] val voice = ts.voices[vi] + // ── Pattern Ditto (effect 7) row-time expansion ── + // See TAUD_NOTE_EFFECTS.md §7. Arm the destination range when this row + // carries a 7-opcode with a valid argument; then, if the current row + // sits inside an active destination block, synthesise an effective cell + // that combines the source-block cell with any explicit fields the + // composer punched into the destination row. + val n = ts.rowIndex + val isArmer = (rawRow.effect == EffectOp.OP_7 && rawRow.effectArg != 0) + if (isArmer) { + val length = (rawRow.effectArg ushr 8) and 0xFF + val repeats = rawRow.effectArg and 0xFF + if (length > 0 && repeats > 0 && length <= n) { + val patLen = (cue.instruction as? PlayInstPatLen)?.rows ?: 64 + voice.dittoSourceStart = n - length + voice.dittoLength = length + voice.dittoEndRow = minOf(n + length * repeats - 1, patLen - 1) + voice.dittoActive = true + } + // else: malformed — leave any previously-armed ditto state alone. + } + + val dittoArmRow = voice.dittoSourceStart + voice.dittoLength + val row: TaudPlayData = + if (voice.dittoActive && n in dittoArmRow..voice.dittoEndRow) { + val rel = (n - voice.dittoSourceStart) % voice.dittoLength + val srcRow = voice.dittoSourceStart + rel + val src = playdata[patIdx][srcRow] + + // Vol- / pan-column "no-op" sentinel is SEL_FINE (3) with value 0. + val volIsSet = !(rawRow.volumeEff == 3 && rawRow.volume == 0) + val panIsSet = !(rawRow.panEff == 3 && rawRow.pan == 0) + + // On the armer row, the 7-opcode is consumed by the marker, so + // for effect-column patching purposes the destination is treated + // as empty. Source 7-opcodes never propagate (no recursive + // expansion). + val destOp = if (isArmer) 0 else rawRow.effect + val destArg = if (isArmer) 0 else rawRow.effectArg + val effOp: Int + val effArg: Int + when { + destOp != 0 -> { effOp = destOp; effArg = destArg } + src.effect != EffectOp.OP_7 -> { effOp = src.effect; effArg = src.effectArg } + else -> { effOp = 0; effArg = 0 } + } + + TaudPlayData( + note = if (rawRow.note != 0xFFFF) rawRow.note else src.note, + instrment = if (rawRow.instrment != 0) rawRow.instrment else src.instrment, + volume = if (volIsSet) rawRow.volume else src.volume, + volumeEff = if (volIsSet) rawRow.volumeEff else src.volumeEff, + pan = if (panIsSet) rawRow.pan else src.pan, + panEff = if (panIsSet) rawRow.panEff else src.panEff, + effect = effOp, + effectArg = effArg, + ) + } else { + rawRow + } + // Reset per-row transient state. voice.cutAtTick = -1 voice.noteDelayTick = -1 @@ -2347,6 +2408,16 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) { private fun applyEffectRow(ts: TrackerState, playhead: Playhead, voice: Voice, vi: Int, op: Int, rawArg: Int) { when (op) { EffectOp.OP_NONE -> {} + EffectOp.OP_7 -> { + // 7 $xxyy — Pattern Ditto. See TAUD_NOTE_EFFECTS.md §7. + // The opcode is a marker only; the row-time expansion in + // [applyTrackerRow] consumes the armer cell and substitutes the + // effective row from the source block, so by the time dispatch + // reaches here either (a) the cell was an armer and we already + // overwrote the synthesised row's effect to 0 / source effect, + // or (b) we hit a malformed 7-cell (length == 0 or repeats == 0 + // or length > N) — both cases are no-ops at dispatch time. + } EffectOp.OP_1 -> { // 1 $xx00 — Global behaviour flags byte in the high byte (see TAUD_NOTE_EFFECTS.md §1). // bits 0-1 (ff): 0=linear pitch, 1=Amiga period, 2=linear frequency (Hz/tick), @@ -3054,11 +3125,18 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) { playhead.position = ts.cuePos } - // Per TAUD_NOTE_EFFECTS.md §S$Bx00: on pattern change reset loop_start_row and loop_count. + // Per-pattern voice state reset, called on every cue advance (B / C / natural end). + // - S$Bx pattern-loop counters (TAUD_NOTE_EFFECTS.md §S$Bx00). + // - Pattern-ditto (effect 7) destination range — the source block lives in the + // pattern we are leaving and must not bleed into the next one (§7). private fun resetPatternLoopState(ts: TrackerState) { for (voice in ts.voices) { voice.loopStartRow = 0 voice.loopCount = 0 + voice.dittoActive = false + voice.dittoSourceStart = 0 + voice.dittoLength = 0 + voice.dittoEndRow = 0 } } @@ -3599,6 +3677,17 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) { var loopStartRow = 0 var loopCount = 0 + // Pattern ditto (effect 7) — per-channel state. See TAUD_NOTE_EFFECTS.md §7. + // dittoActive is the master gate; while true, rows in + // [dittoSourceStart + dittoLength .. dittoEndRow] are expanded by copying + // the cells from the source block (dittoSourceStart .. dittoSourceStart + + // dittoLength − 1) and patching in any non-empty fields from the raw + // destination cell. All four reset on cue advance (B / C / natural end). + var dittoActive = false + var dittoSourceStart = 0 + var dittoLength = 0 + var dittoEndRow = 0 + // Tempo slide (T $00xy) — per-channel because T is a per-channel effect, but we apply globally via playhead. var tempoSlideDir = 0 // 0 = none, -1 = down, +1 = up var tempoSlideAmount = 0 @@ -3841,6 +3930,10 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) { it.glissandoOn = false it.loopStartRow = 0 it.loopCount = 0 + it.dittoActive = false + it.dittoSourceStart = 0 + it.dittoLength = 0 + it.dittoEndRow = 0 it.funkSpeed = 0 it.funkAccumulator = 0 it.funkWritePos = 0