.. This file is auto-generated by the Sphinx pre-build hook in
   ``docs/source/conf.py`` from ``docs/source/_data/patcher_objects.json``
   and the notes in ``docs/source/_data/patcher_notes/``.
   Do not edit by hand — run ``dart run tool/gen_patcher_snapshot.dart``
   to refresh the JSON from the bound engine and
   ``dart run tool/port_patcher_notes.dart`` to refresh the notes from the
   engine submodule, then rebuild the docs.

Signal generators
=================

Audio-rate sources: oscillators, noise and ramps.

4 objects. Every entry is
pulled directly from the engine registry, which reads the ``ADD_DESCRIPTION``
/ ``INLET_DOC`` / ``OUTLET_DOC`` / ``PARAM_DOC`` macros in the libYSE
source; the longer notes under each summary are ported from the libYSE
documentation. The ``~`` prefix marks DSP / audio-rate objects; ``.`` marks
control-rate objects. Links into the patcher guide (messages, time, data,
files, ...) lead to the libYSE documentation, which also has this
:yse-cpp:`category's page <patcher/objects/signal_generators.html>`.

.. contents::
   :local:
   :depth: 1

``~line``
---------

Linear-ramp generator. Ramps an audio-rate value toward a target over a given time in ms.

:Dart: ``Obj.dLine``
:Kind: DSP (audio-rate)

A float at the left inlet starts a ramp from the current value to that
target. The ramp takes the time last set at the right inlet, so set the time
first. A new time does not change a ramp that is already running, and
sending the target the ramp already has does nothing. With a time of 0 the
output jumps to the target.

The time is counted in whole milliseconds and then rounded to whole audio
blocks; a ramp always lasts at least one block. Within a block the ramp is
smooth, sample by sample.

.. code-block:: text

   [~line 0 20]   left <- 1.   =>   rises from 0 to 1 over 20 ms

``stop`` halts the ramp and holds the output at its current value until the
next target arrives. A new time on its own does not restart it. Any target
after a ``stop``, even the one the ramp was heading for, starts a new ramp
from the held value, taking the full ramp time.

**Inlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Accepts
     - Range
     - Description
   * - 0
     - target
     - FLOAT
     - any float
     - Target value to ramp toward. Also takes 'stop'.
   * - 1
     - time
     - FLOAT
     - 0+ ms
     - Ramp duration in milliseconds, used from the next new target.


**Outlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Type
     - Range
     - Description
   * - 0
     - out
     - BUFFER
     - any float
     - Audio-rate ramp output.


**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 22 18 18 42

   * - Name
     - Default
     - Range
     - Description
   * - target
     - 0
     - any float
     - Initial target value.
   * - time
     - 0
     - 0+ ms
     - Initial ramp time in milliseconds.


``~noise``
----------

White-noise generator. Sends a new block of random samples on every audio block.

:Dart: ``Obj.dNoise``
:Kind: DSP (audio-rate)


**Outlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Type
     - Range
     - Description
   * - 0
     - out
     - BUFFER
     - -1.0 to 1.0
     - White-noise audio output.



``~saw``
--------

Audio-rate sawtooth oscillator. Frequency can be set with a float or modulated with a DSP buffer.

:Dart: ``Obj.dSaw``
:Kind: DSP (audio-rate)

**Inlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Accepts
     - Range
     - Description
   * - 0
     - freq
     - BUFFER, FLOAT
     - 0-20000 Hz
     - Oscillator frequency in Hz. Accepts a DSP buffer (FM) or a float.


**Outlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Type
     - Range
     - Description
   * - 0
     - out
     - BUFFER
     - -1.0 to 1.0
     - Sawtooth wave audio output.


**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 22 18 18 42

   * - Name
     - Default
     - Range
     - Description
   * - frequency
     - 440
     - 0-20000 Hz
     - Initial frequency in Hz.


``~sine``
---------

Audio-rate sine oscillator. Frequency can be set with a float or modulated with a DSP buffer.

:Dart: ``Obj.dSine``
:Kind: DSP (audio-rate)

**Inlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Accepts
     - Range
     - Description
   * - 0
     - freq
     - BUFFER, FLOAT
     - 0-20000 Hz
     - Oscillator frequency in Hz. Accepts a DSP buffer (FM) or a float.


**Outlets**

.. list-table::
   :header-rows: 1
   :widths: 6 18 18 18 40

   * - #
     - Label
     - Type
     - Range
     - Description
   * - 0
     - out
     - BUFFER
     - -1.0 to 1.0
     - Sine wave audio output.


**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 22 18 18 42

   * - Name
     - Default
     - Range
     - Description
   * - frequency
     - 440
     - 0-20000 Hz
     - Initial frequency in Hz.