Round Robins¶
Provides multi-dimensional round-robin sample selection for the IVLS voice
Import¶
import "_IVLS/std-library/nodes/voice-logics/round-robins.ksp"Node: Stl.RoundRobins¶
Uses: Init, TransportStart, NotePass
Overview¶
Provides multi-dimensional round-robin sample selection for the IVLS voice system. Round-robin position is computed from one or more voice fields that together form a composite index into a pre-seeded shuffle table.
Architecture:
- Products register voice fields as RR dimensions via register_field(), each
with an upper limit (field width). The node caches a dimension-factor array
so the composite index can be recomputed in O(D) time per note.
- A pre-loaded seed array (rr.main_seed) stores shuffled position sequences
for each possible RR limit (up to MAX_LIMIT). On each note, query_rr()
reads the current seed position for the composite index and advance_rr()
increments the counter modulo SEED_LENGTH.
- Counters are reset on TransportStart so playback always begins at a
predictable RR position.
- The hooks.get_max_rr() virtual must be overridden by the product to return
the applicable RR limit for a given voice.
Constants¶
| Constant | Value | Description |
|---|---|---|
rr.MAX_IDX |
100000 |
integer |
rr.MAX_DIMS |
64 |
integer |
rr.SEED_LENGTH |
4096 |
integer |
rr.MAX_LIMIT |
32 |
integer |
API¶
Nodes¶
| Name | Description |
|---|---|
node Stl.RoundRobins |
Stl.RoundRobins Selects round-robin sample positions using a pre-seeded shuffle ... |
Functions¶
| Name | Description |
|---|---|
ivls.RoundRobins.advance_rr(vo) |
Advances the round-robin counter for the given voice's composite RR index by one... |
ivls.RoundRobins.hooks.get_max_rr(vo) -> rr_max |
Default hook returning 0 for the maximum RR limit. |
ivls.RoundRobins.query_rr(vo) -> rr_pos |
Returns the current round-robin sample position for the given voice by looking u... |
ivls.RoundRobins.query_rr_idx(vo) -> idx |
Computes the composite scalar RR index for a voice by combining its registered d... |
ivls.RoundRobins.recache() |
Rebuilds the dimension-factor cache from the current FieldDimensions and FieldWi... |
ivls.RoundRobins.register_field(field, rr_limit) |
Registers a voice field as a round-robin dimension with the given limit. |
ivls.RoundRobins.set_rr(vo, rr_pos) |
Sets the round-robin counter for the given voice's composite RR index to a speci... |
Nodes¶
node Stl.RoundRobins¶
Callbacks: Init, TransportStart, NotePass
Stl.RoundRobins Selects round-robin sample positions using a pre-seeded shuffle table indexed by composite voice-field dimensions.
Functions¶
ivls.RoundRobins.advance_rr(vo)¶
Advances the round-robin counter for the given voice's composite RR index by one step, wrapping at SEED_LENGTH.
| Parameter | Type | Description |
|---|---|---|
vo |
integer | Voice object reference whose RR counter should advance |
Side effects:
| Name | Type | Purpose |
|---|---|---|
| rr_idx | integer | Composite RR index computed from voice dimension fields |
| max | integer | Declared but unused; likely vestigial |
ivls.RoundRobins.hooks.get_max_rr(vo) -> rr_max¶
Default hook returning 0 for the maximum RR limit. Products must override this to supply the applicable RR limit for the given voice.
| Parameter | Type | Description |
|---|---|---|
vo |
integer | Voice object reference to query |
Returns: rr_max — Maximum round-robin limit for the voice (default: 0)
ivls.RoundRobins.query_rr(vo) -> rr_pos¶
Returns the current round-robin sample position for the given voice by looking up the shuffled seed at the composite RR index and current counter value.
| Parameter | Type | Description |
|---|---|---|
vo |
integer | Voice object reference to query |
Returns: rr_pos — Current RR sample position, or -1 if the RR index is invalid
Side effects:
| Name | Type | Purpose |
|---|---|---|
| rr_idx | integer | Composite RR index computed from voice dimension fields |
| max | integer | Maximum RR limit for the voice, retrieved via hook |
ivls.RoundRobins.query_rr_idx(vo) -> idx¶
Computes the composite scalar RR index for a voice by combining its registered dimension field values using the cached stride factors.
| Parameter | Type | Description |
|---|---|---|
vo |
integer | Voice object reference to compute the index for |
Returns: idx — Composite RR array index, or -1 if any field value is out of bounds
Side effects:
| Name | Type | Purpose |
|---|---|---|
| i | integer | Loop variable iterating over registered dimensions |
| v | integer | Voice field value for the current dimension |
ivls.RoundRobins.recache()¶
Rebuilds the dimension-factor cache from the current FieldDimensions and FieldWidths lists. Each entry stores the stride for its dimension so composite RR indices can be computed with a single accumulator loop.
Side effects:
| Name | Type | Purpose |
|---|---|---|
| i | integer | Loop variable iterating over registered dimensions |
| width | integer | Running product of dimension widths used to build stride values |
ivls.RoundRobins.register_field(field, rr_limit)¶
Registers a voice field as a round-robin dimension with the given limit.
| Parameter | Type | Description |
|---|---|---|
field |
integer | Voice field index to use as an RR dimension |
rr_limit |
integer | Upper bound (exclusive) for values in this dimension |
ivls.RoundRobins.set_rr(vo, rr_pos)¶
Sets the round-robin counter for the given voice's composite RR index to a specific position, wrapped at SEED_LENGTH.
| Parameter | Type | Description |
|---|---|---|
vo |
integer | Voice object reference whose RR counter should be set |
rr_pos |
integer | Target seed position to assign (will be wrapped modulo SEED_LENGTH) |
Side effects:
| Name | Type | Purpose |
|---|---|---|
| rr_idx | integer | Composite RR index computed from voice dimension fields |
| max | integer | Declared but unused; likely vestigial |
Example¶
// TODO: Add usage example