Purge

---

A large instrument library might contain thousands of sample groups, but at any given moment only a fraction of them are actually needed. Keeping everything loaded wastes RAM and slows down the host. Purging unloads unused groups from memory and reloads them when needed -- a standard optimization in professional Kontakt instruments.

IVLS provides Stl.Purge, a standard library node that manages the purge cycle. It exposes a simple model: you tell it which groups should be loaded, and it handles the actual purge operations.

The Purge Cycle

---

Stl.Purge works through a hidden UI switch bound to MIDI CC 122. When the switch fires (either from user interaction or programmatically), the node runs a three-step cycle:

1. Reset all group states to the default group state
2. Run cb Purge on your product node, letting you mark specific groups as loaded
3. Compare the desired state against the actual purge state of each group, and purge or load as needed

The first step uses purge.default_group_state -- a variable that controls the baseline. The SDK default is TRUE (all groups loaded). Products that want conservative memory usage override this to OFF, then selectively enable only the groups they need.

The cb Purge Callback

---

Your product responds to the purge cycle through cb Purge. Inside this callback, you set entries in the purge.group_states[] array to indicate which groups should be loaded:

node MyPurge:
    cb Init:
        { Override default: start with everything unloaded }
        purge.default_group_state := OFF

    cb Purge:
        { Load only the groups for sounds the user has selected }
        declare i
        for i := 0 to num_keys - 1
            if my_keys[i].sound_id > -1
                purge.group_states[get_group_idx(my_keys[i].sound_id)] := ON
            end if
        end for
end node

Before your cb Purge runs, the framework has already filled purge.group_states[] with purge.default_group_state for every group. Your job is simply to set specific entries to ON for groups that should remain in memory.

There is also a purge.group_gates[] array that acts as a secondary multiplier. The final state for each group is group_states[i] * group_gates[i]. Gates default to ON; you can use them to add additional conditions without overriding the main state logic.

Triggering a Purge

---

To run the purge cycle from code, call purge.execute():

purge.execute()

This internally fires set_controller(122, 127), which triggers the hidden UI switch and runs the full cycle. You typically call this after any action that changes which sounds are loaded -- browser selection, preset load, articulation change.

Default Group State

---

The choice between TRUE (everything loaded) and OFF (nothing loaded) as the default is a product-level decision:

• TRUE (SDK default) -- all groups start loaded. Your cb Purge marks groups to unload. Good for instruments where most groups are used most of the time.
• OFF (conservative) -- no groups start loaded. Your cb Purge marks groups to load. Good for large instruments where only a small fraction of content is active at once.

In practice, most production instruments use the conservative approach:

purge.default_group_state := OFF

Console-Driven Purge

---

If your instrument uses the Console-K7 mixer (covered in the next chapter), you can trigger purge in response to console events. For example, when a channel is disabled, purge its groups:

function console.ui_cb.response(ch, slot, type)
    select type
        case console.ui.cb_type.CHANNEL_ENABLED
            purge.execute()
    end select
end function

This keeps memory usage in sync with the mixer state -- disabled channels free their samples automatically.

---

Purge is a simple but important optimization. Stl.Purge provides the infrastructure: the hidden CC trigger, the group state arrays, the comparison-and-purge loop. Your product provides the intelligence: which groups should be loaded given the current instrument state. Set purge.default_group_state, fill in cb Purge, and call purge.execute() when the state changes.