Skip to content

Voiceops

Ivls.VoiceOps

Import

import "_IVLS/source/nodes/VoiceOps.ksp"

Node: Ivls.VoiceOps

Uses: Init

Overview

Ivls.VoiceOps

LIBRARY MODULE

Voice lifecycle and relationship operations for IVLS.

  • Functions for firing, releasing, and reparenting voices
  • Doubly-linked sibling tree management for parent-child voice relationships
  • Runtime binding/unbinding and branch pruning utilities
  • node_prunable and node_no_off per-node flag arrays and the IVLS.NODE_PRUNABLE macro

API

Nodes

Name Description
node Ivls.VoiceOps Node that implements all voice lifecycle and relationship operations used by the...

Defines

Name Description
define IVLS.NODE_PRUNABLE(#node#, #bool#) Sets the prunable flag for a named node at compile time.

Macros

Name Description
end_for_each_child Closes a for_each_child loop.
for_each_child(#v#) Opens a loop over all direct children of voice #v#.

Functions

Name Description
ivls.add_child_to_parent(vo_new_ch, vo_pa) Inserts vo_new_ch as the new head child of vo_pa, pushing any existing first chi...
ivls.clone_voice(vo, nenv) Creates a copy of vo, refurbishes it, and fires it as a new child of vo's parent.
ivls.move_children(old_parent, new_parent) Moves all children from old_parent to new_parent, connecting the two child lists...
ivls.prune_branch_to_voice(vo) Walks up the voice tree from vo, finding the highest prunable ancestor with no s...
ivls.release_voice(v) Releases voice v by dispatching a VOICE_OFF input through the processing pipelin...
ivls.release_voice_children(v) Releases all auto-release children of voice v.
ivls.reparent_voice(v, r) Binds voice v to runtime r.
ivls.reparent_voice_to_voice(vo, vo_pa) Unparents vo from its current parent and re-attaches it under vo_pa.
ivls.restore_parent(v) Removes voice v from its runtime and restores autonomous ownership.
ivls.unparent_children(vo) Detaches all children of vo and re-parents them to the omni voice.
ivls.unparent_voice(vo) Detaches vo from its parent and re-parents it to the omni voice.

Nodes

node Ivls.VoiceOps

Callbacks: Init

Node that implements all voice lifecycle and relationship operations used by the IVLS engine.

Defines

define IVLS.NODE_PRUNABLE(#node#, #bool#)

Sets the prunable flag for a named node at compile time.

Parameter Description
#node# Node name identifier
#bool# Boolean value to assign (TRUE or FALSE)

Macros

end_for_each_child

Closes a for_each_child loop.

for_each_child(#v#)

Opens a loop over all direct children of voice #v#. Must be closed with end_for_each_child().

Parameter Description
#v# Parent voice reference to iterate children of

Side effects:

Name Type Purpose
parent integer Stores the parent voice reference for the loop
iter_child integer Current child voice being iterated
sibling integer Next right sibling, cached before body executes

Functions

ivls.add_child_to_parent(vo_new_ch, vo_pa)

Inserts vo_new_ch as the new head child of vo_pa, pushing any existing first child to the right sibling position.

Parameter Type Description
vo_new_ch integer Voice reference to add as child
vo_pa integer Voice reference of the parent

ivls.clone_voice(vo, nenv)

Creates a copy of vo, refurbishes it, and fires it as a new child of vo's parent. If vo is bound to a runtime, the clone is also bound to the same runtime. Stores the cloned voice reference in NodeEnv[nenv].sentVoice.

Parameter Type Description
vo integer Voice reference to clone
nenv integer NodeEnv reference used for error reporting and output

Side effects: | Name | Type | Purpose | |------|------|---------| | cloned_vo | integer | Reference to the newly created Voice copy |

ivls.move_children(old_parent, new_parent)

Moves all children from old_parent to new_parent, connecting the two child lists, then releases old_parent.

Parameter Type Description
old_parent integer Voice whose children are being moved
new_parent integer Voice that will adopt the children

Side effects: | Name | Type | Purpose | |------|------|---------| | last_child | integer | Tracks the last child iterated from old_parent to stitch sibling lists |

ivls.prune_branch_to_voice(vo)

Walks up the voice tree from vo, finding the highest prunable ancestor with no siblings that is not bound to a runtime.

Parameter Type Description
vo integer Voice reference from which pruning begins

Side effects: | Name | Type | Purpose | |------|------|---------| | rel | integer | Cursor tracking the current ancestor being evaluated |

ivls.release_voice(v)

Releases voice v by dispatching a VOICE_OFF input through the processing pipeline.

Parameter Type Description
v integer Voice reference to release

ivls.release_voice_children(v)

Releases all auto-release children of voice v.

Parameter Type Description
v integer Voice reference whose auto-release children should be released

ivls.reparent_voice(v, r)

Binds voice v to runtime r.

Parameter Type Description
v integer Voice reference to bind
r integer Runtime reference to bind the voice to

ivls.reparent_voice_to_voice(vo, vo_pa)

Unparents vo from its current parent and re-attaches it under vo_pa.

Parameter Type Description
vo integer Voice reference to reparent
vo_pa integer Target parent Voice reference

Side effects: | Name | Type | Purpose | |------|------|---------| | vo_buffer | integer | Local copy of vo used to safely call unparent before add |

ivls.restore_parent(v)

Removes voice v from its runtime and restores autonomous ownership.

Parameter Type Description
v integer Voice reference to restore to autonomous ownership

ivls.unparent_children(vo)

Detaches all children of vo and re-parents them to the omni voice.

Parameter Type Description
vo integer Voice reference whose children should be unparented

ivls.unparent_voice(vo)

Detaches vo from its parent and re-parents it to the omni voice.

Parameter Type Description
vo integer Voice reference to unparent

Example

// TODO: Add usage example

See Also