.. This file is auto-generated by the Sphinx pre-build hook in ``documentation/source/conf.py`` from ``documentation/source/_data/patcher_objects.json`` and the notes in ``documentation/source/_data/patcher_notes/``. Do not edit by hand — re-run ``python yse.py dump-patcher-meta`` to refresh the JSON, then ``make html`` to re-render this page. Subpatchers =========== Subpatchers and the inlets and outlets that form their boundary. 5 objects. Every entry is pulled directly from the engine source via the ``ADD_DESCRIPTION`` / ``INLET_DOC`` / ``OUTLET_DOC`` / ``PARAM_DOC`` macros (see :file:`YseEngine/patcher/pObject.h`). The ``~`` prefix marks DSP / audio-rate objects; ``.`` marks control-rate objects. .. contents:: :local: :depth: 1 ``.inlet`` ---------- A message inlet of the subpatcher it is in. With index N, whatever the parent sends to the subpatcher's inlet N comes out of this object, inside the subpatcher. :Kind: Control-rate The argument is the index: which inlet of the enclosing subpatcher this object is (default 0). Messages and signals share one numbering per side, so ``.inlet 0`` and ``~inlet 1`` give a subpatcher two inlets. Two boundary objects with the same index are not an error, but only one of them is used, and which one is not defined. A cord is attached to the boundary object, not to its number. Changing the index later does not move cords that already exist. These index rules apply to all four boundary objects; see :doc:`/patcher/subpatchers`. Bang, int, float and list cross unchanged. A message box's text arrives as the bang, number or list it spells, and a word command such as ``stop`` arrives as a list. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - from parent - FLOAT, INT, BANG, LIST - — - Receives what the parent patch sends to the subpatcher's inlet with this index. A cord connected to that inlet lands here. Bang, int, float and list. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - ANY - — - The incoming message, unchanged, inside the subpatcher. An int stays an int, a list a list. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - index - 0 - 0+ - Which inlet of the enclosing subpatcher this object is, shared with ~inlet. Give every boundary object its own number. ``.outlet`` ----------- A message outlet of the subpatcher it is in. With index N, whatever arrives here leaves the subpatcher through its outlet N. :Kind: Control-rate The index rules and what crosses are as for ``.inlet``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - from patch - FLOAT, INT, BANG, LIST - — - A message from inside the subpatcher, to send out of it. Bang, int, float and list. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - to parent - ANY - — - The subpatcher's outlet with this index, seen from the parent. A cord the parent connects to that outlet starts here. The message leaves unchanged. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - index - 0 - 0+ - Which outlet of the enclosing subpatcher this object is, shared with ~outlet. Give every boundary object its own number. ``patcher`` ----------- A subpatcher: groups part of a patch into one object that the parent connects to by pin number. Its pins are the .inlet, .outlet, ~inlet and ~outlet objects placed inside it. :Kind: Control-rate A ``patcher`` object has no inlets, outlets or arguments of its own. Create its contents with ``CreateObject`` on the same patcher and move them inside with ``SetContainer``. Its pins are the boundary objects among its direct contents: inlet N is the ``.inlet`` or ``~inlet`` with index N, and outlet N the ``.outlet`` or ``~outlet`` with index N. Connect to the subpatcher by pin number, as to any object. Subpatchers nest, and nesting costs the audio thread nothing. Deleting a subpatcher deletes everything inside it. On load, the contents fire their ``.loadbang`` objects together with the rest of the patch, in no set order. Names are not local: a ``.r freq`` inside a subpatcher hears every ``freq`` in the whole patcher. :doc:`/patcher/subpatchers` explains how to build, connect, save and edit subpatchers. ``~inlet`` ---------- A signal inlet of the subpatcher it is in. With index N, the signal the parent connects to the subpatcher's inlet N comes out of this object, inside the subpatcher. :Kind: DSP (audio-rate) The index and numbering rules are those of ``.inlet``. The signal is passed on without being copied, so crossing a boundary adds no cost that grows with the block size or the nesting depth. When the parent connects nothing to this inlet, nothing comes out. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - from parent - BUFFER - -1.0 to 1.0 - Receives the signal the parent patch connects to the subpatcher's inlet with this index. Audio only: a message arriving here is dropped. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - out - BUFFER - -1.0 to 1.0 - The incoming signal, unchanged, inside the subpatcher. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - index - 0 - 0+ - Which inlet of the enclosing subpatcher this object is, shared with .inlet. Give every boundary object its own number. ``~outlet`` ----------- A signal outlet of the subpatcher it is in. With index N, the signal that arrives here leaves the subpatcher through its outlet N. :Kind: DSP (audio-rate) The index and numbering rules are those of ``.inlet``, and the signal is passed on as by ``~inlet``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - from patch - BUFFER - -1.0 to 1.0 - A signal from inside the subpatcher, to send out of it. Audio only: a message arriving here is dropped. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - to parent - BUFFER - -1.0 to 1.0 - The subpatcher's outlet with this index, seen from the parent. The signal leaves unchanged. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - Name - Default - Range - Description * - index - 0 - 0+ - Which outlet of the enclosing subpatcher this object is, shared with .outlet. Give every boundary object its own number.