Pgs¶
PGS Inter-Script Communication Protocol
Import¶
import "_IVLS/std-library/nodes/components/pgs.ksp"Node: Stl.PGS¶
Uses: Init
Overview¶
PGS Inter-Script Communication Protocol
Structured PGS-based task dispatch system for coordinating multiple Kontakt script slots.
LIBRARY: Stl.PGS
Scripts using this node are isolated from PGS events by default and only respond when the
PGS Meta Packet is marked ready and addressed to their slot. Tasks are sent by writing
a task ID and destination slot to the meta packet; receiving scripts poll the ready flag
to decide whether to act.
Includes a queue system (pgs.queue_task / pgs.LCB) for sending multiple tasks in
rapid succession across LCB ticks.
API¶
Nodes¶
| Name | Description |
|---|---|
node Stl.PGS |
PGS-based inter-script task dispatch node. |
Defines¶
| Name | Description |
|---|---|
define PGS.GLOBAL_SIGNAL |
Sentinel value for broadcast tasks that should be processed by all script slots. |
define PGS_CONDITION.TASK_READY |
Condition that is TRUE when the PGS Meta Packet holds a ready task addressed to ... |
define PGS_MAX_KEY_LENGTH |
Maximum number of index slots in a single PGS key. |
define SUBLIME_CALC.GET_MAX_PGS_KEYS(size) |
Calculates the minimum number of PGS keys required to hold the given data size. |
Const Blocks¶
| Name | Description |
|---|---|
const meta_packet |
Index constants for reading and writing the PGS Meta Packet key slots. |
const tasks |
Built-in task ID constants shared across all scripts using this protocol. |
Functions¶
| Name | Description |
|---|---|
pgs.end_task() |
Clears the PGS Meta Packet and lowers the ready flag to signal task completion. |
pgs.get_task_dest() -> return |
Reads the destination slot from the PGS Meta Packet. |
pgs.get_task_id() -> return |
Reads the task ID from the PGS Meta Packet. |
pgs.LCB() |
LCB handler for the PGS task queue. |
pgs.process_queue() |
Pops the next task and destination from the queues and dispatches via pgs.send_t... |
pgs.queue_task(task_id, dest_slot) |
Enqueues a task for sequential dispatch via pgs.LCB. |
pgs.send_task(task_id, dest_slot) |
Writes task_id and dest_slot into the PGS Meta Packet and raises the ready flag. |
pgs.shove_task(task_id, dest_slot) |
Sends a PGS task and yields for 1 ms so consecutive calls each trigger a respons... |
Nodes¶
node Stl.PGS¶
Callbacks: Init
PGS-based inter-script task dispatch node. Initializes the meta packet key and task queues.
Preconditions: This is an internal call inside lib.ICB()
Defines¶
define PGS.GLOBAL_SIGNAL¶
Sentinel value for broadcast tasks that should be processed by all script slots.
define PGS_CONDITION.TASK_READY¶
Condition that is TRUE when the PGS Meta Packet holds a ready task addressed to the current script slot.
define PGS_MAX_KEY_LENGTH¶
Maximum number of index slots in a single PGS key.
define SUBLIME_CALC.GET_MAX_PGS_KEYS(size)¶
Calculates the minimum number of PGS keys required to hold the given data size.
| Parameter | Type | Description |
|---|---|---|
size |
integer | number of values to store across PGS key slots |
Post: (integer) - number of PGS keys needed to accommodate size values
Const Blocks¶
const meta_packet¶
Index constants for reading and writing the PGS Meta Packet key slots. TASK_FLAG is managed internally; do not write to it directly.
const tasks¶
Built-in task ID constants shared across all scripts using this protocol. Projects may extend with additional task IDs defined per product.
Functions¶
pgs.end_task()¶
Clears the PGS Meta Packet and lowers the ready flag to signal task completion.
Preconditions: All PGS response code for the task must be executed before calling this.
pgs.get_task_dest() -> return¶
Reads the destination slot from the PGS Meta Packet.
Returns: return — destination slot currently recorded in the PGS Meta Packet
pgs.get_task_id() -> return¶
Reads the task ID from the PGS Meta Packet.
Returns: return — task ID currently recorded in the PGS Meta Packet
pgs.LCB()¶
LCB handler for the PGS task queue. Pops and sends one queued task per call.
Preconditions: Place this in the LCB. Call frequency must be managed by the developer.
pgs.process_queue()¶
Pops the next task and destination from the queues and dispatches via pgs.send_task.
pgs.queue_task(task_id, dest_slot)¶
Enqueues a task for sequential dispatch via pgs.LCB.
| Parameter | Type | Description |
|---|---|---|
task_id |
integer | task identifier, defined per-project |
dest_slot |
integer | destination script slot, defined per-project |
pgs.send_task(task_id, dest_slot)¶
Writes task_id and dest_slot into the PGS Meta Packet and raises the ready flag.
Preconditions: Only one PGS task can be sent in a callback sequentially. Use pgs.queue_task() for sequential PGS tasks.
| Parameter | Type | Description |
|---|---|---|
task_id |
integer | task identifier, defined per-project |
dest_slot |
integer | destination script slot, defined per-project |
pgs.shove_task(task_id, dest_slot)¶
Sends a PGS task and yields for 1 ms so consecutive calls each trigger a response.
Preconditions: NOT wait-safe. Unlike send_task, may be called repeatedly within the same callback.
| Parameter | Type | Description |
|---|---|---|
task_id |
integer | task identifier, defined per-project |
dest_slot |
integer | destination script slot, defined per-project |
Example¶
// TODO: Add usage example