CLASS:: FoaProximity
summary:: First Order Ambisonic (FOA) proximity effect filter
categories:: Libraries>Ambisonic Toolkit>UGens>FOA>Transformer, UGens>Multichannel>Ambisonics
related:: Classes/FoaNFC, Classes/FoaTransform

DESCRIPTION::
Apply proximity filtering to a First Order Ambisonic signal (B-format).

NOTE::
link::Classes/FoaProximity:: is usually called via the convenience wrapper link::Classes/FoaTransform::.
::


CLASSMETHODS::

METHOD:: ar

argument:: in
The B-format signal, an array: [w, x, y, z]

argument:: distance
The distance, in meters.

warning:: strong::Distance:: = 0 is an invalid value! ::

argument:: mul
Output will be multiplied by this value.

argument:: add
This value will be added to the output.


discussion::

link::Classes/FoaProximity:: facilitates the introduction of the link::http://en.wikipedia.org/wiki/Proximity_effect_(audio)##proximity effect:: to encoded signals. At extremes, the proximity effect introduces a strong bass boost, as well as phase differences. The link::http://en.wikipedia.org/wiki/Proximity_effect_(audio)##proximity effect:: can be an important contributor to perceptions of nearness.

The Ambisonic Toolkit's near-field compensation filter, link::Classes/FoaNFC::, undoes link::Classes/FoaProximity:: given the same strong::distance:: argument.


warning:: As link::Classes/FoaProximity:: includes a 1st-order integration, signals must be highpass filtered before application. link::Classes/HPF:: is usually a suitable choice to control low frequency boost.::



EXAMPLES::

Please see link::Guides/Transforming-FOA#Proximity#this::.
