.. _signalDoc:

.. index:: single: signal

============
Signal Block
============

Declares a **signal block** or a **signal block bundle** using the keyword ``signal``.

* Declaration_
* `Ports Table`_
* Description_
* `Code Examples`_

.. figure:: Images/SignalBlock.png
   :scale: 100%
   :alt: Signal Block
   :align: center

----

Declaration
===========

::
	
	# signal block
	signal LABEL {
		default:	0.0
		rate:		AudioRate
		reset:		MasterReset
		meta:		none
	}

	
	# signal block input bundle
	signal LABEL [SIZE] {
		default:	0.0 | [ 0.0, ... ]
		rate:		AudioRate
		reset:		MasterReset
		meta:		none
	}

**LABEL**
	:definition:	the label of the block
	
**SIZE**
	:definition:	the size of the block bundle
	:port type:	constant integer port (CIP)
	
----
	
Ports Table
===========

+------+-------------+-----------+---------------------+------------+------------+-----------------+---------------+
|      |             |           |                     |            |            |                 |               |
+------+-------------+-----------+---------------------+------------+------------+-----------------+---------------+
| Port | Name        | Direction | Type                | Connection | Access     | Default         | Required      | 
+======+=============+===========+=====================+============+============+=================+===============+
| 1    | input       | input     | SIP, SRP :sup:`(2)` | single     | >> LABEL   | ``none``        | no :sup:`(1)` |
|      |             |           |                     |            +------------+                 |               |
|      |             |           |                     |            | assignment |                 |               |
+------+-------------+-----------+---------------------+------------+------------+-----------------+---------------+
| 2    | output      | output    | SIP, SRP :sup:`(2)` | multiple   | LABEL >>   | ``none``        | no :sup:`(1)` |
|      |             |           |                     |            +------------+                 |               |
|      |             |           |                     |            | assignment |                 |               |
+------+-------------+-----------+---------------------+------------+------------+-----------------+---------------+
| 3    | ``default`` | input     | CIP, CRP            | single     | property   | ``0.0``         | yes           |
+------+-------------+-----------+---------------------+------------+------------+-----------------+---------------+
| 4    | ``rate``    | input     | CIP                 | single     | property   | ``AudioRate``   | yes           |
+------+-------------+-----------+---------------------+------------+------------+-----------------+---------------+
| 5    | ``reset``   | input     | CBP                 | single     | property   | ``MasterReset`` | yes           |
+------+-------------+-----------+---------------------+------------+------------+-----------------+---------------+
| 6    | ``meta``    | input     | CSP                 | single     | property   | ``none``        | no            |
+------+-------------+-----------+---------------------+------------+------------+-----------------+---------------+

:CBP:	constant boolean port

:CIP:	constant integer port

:CRP:	constant real port

:CSP:	constant string port

:SIP:	stream integer port

:SRP:	stream real port
	
:LABEL:	block label	

:sup:`1` Warning issued during compilation if the port is left unconnected.

:sup:`2` The port's type is the same as the ``default`` port's type. They are CRP by default.
	
----
	
Description
===========

Signal blocks can operate in synchronous and asynchronous mode. 

When the ``rate`` port is set to an integer value, the signal block operates in synchronous mode. It samples its input port at the set rate and updates its output ports with the sampled value for the duration of the sampling period.

When the ``rate`` is set to ``none`` the signal block operates in asynchronous mode. When the value at its input changes the block updates its output value with the new value and holds that value until the next change in the input value.

The type of the input and output ports is set by the ``default`` ports value. If the ``default`` port is set to a :ref:`real <Real>` value (default) the input and output ports are :ref:`CRP <CRP>`. If the ``default`` port is set to as :ref:`integer <Integer>` value the input and output ports are :ref:`CIP <CIP>`.


Code Examples
=============

The following code declares a signal block called 'Microphone'. The signal block's input port is connected to ``AudioIn[1]``.

::

	signal Microphone {
		default:	0.0
		rate:		AudioRate
		reset:		MasterReset
		meta:		'Input signal from the microphone sampled at the default audio sampling rate.'
	}

	AudioIn[1] >> Microphone;

The following code declares a signal block bundle called 'LineIn'. The signal block bundle's inputs are connected to ``AudioIn1[1]`` and ``AudioIn[2]``.

::

	signal LineIn [2] {
		default:	0.0
		rate:		AudioRate
		reset:		MasterReset
		meta:		'Stereo Input.'
	}

	AudioIn[1:2] >> LineIn;