CLASS:: FoaDecoderKernel
summary:: First Order Ambisonic (FOA) decoder kernels
categories:: Libraries>Ambisonic Toolkit>FOA>Decoding
related:: Classes/FoaDecoderMatrix, Classes/FoaDecode

DESCRIPTION::
Generates decoding kernels required by the Ambisonic Toolkit's first order decoder, link::Classes/FoaDecode::.

note:: The ATK kernels are required for kernel decoding. Please see the instructions link::http://www.ambisonictoolkit.net/wiki/tiki-index.php?page=Downloads#ATK_Kernels#here:: for installation. ::


CLASSMETHODS::

METHOD:: newUHJ
Ambisonic UHJ stereo decoder. footnote::See: link::http://en.wikipedia.org/wiki/Ambisonic_UHJ_format::::

argument:: kernelSize
256, 512, 1024, 2048, 4096, 8192

argument:: server
link::Classes/Server:: on which to load kernel.

discussion:: For production work targeting stereo output, the authors advise using UHJ, as Ambisonic UHJ stereo is the native Ambisonic stereo format.



METHOD:: newSpherical
Synthetic spherical head model HRTF footnote::See: R. O. Duda, "Modeling head related transfer functions," in Proceedings of the Twenty-Seventh Annual Asilomar Conference on Signals, Systems and Computers, Asilomar, CA, 1993.:: decoder, equalised for the diffuse field.

argument:: subjectID
0 to 9

argument:: server
link::Classes/Server:: on which to load kernel.

discussion::
link::#-newSpherical:: models a sphere only, and is equivalent to placing a pair of spaced, sphere baffled microphones in the soundfield. With no pinnae and no body, elevation cues are not present.

The strong::subjectID:: argument varies to suit listener head width, with 0 the smallest and 9 the largest head. The user is advised to audition to find a suitable choice.



METHOD:: newListen
Measured HRTF decoder, with measurements from IRCAM's link::http://recherche.ircam.fr/equipes/salles/listen/##Listen HRTF database:: footnote::See: link::http://recherche.ircam.fr/equipes/salles/listen/:::: equalised for the diffuse field.

argument:: subjectID
1002 to 1059 (51 in total) warning:: strong::subjectID::s are not entirely contiguous.::

argument:: server
link::Classes/Server:: on which to load kernel.

discussion::
The user is advised to audition strong::subjectID::s to find a suitable choice. If an invalid strong::subjectID:: is chosen, valid choices are returned.


code::
// Boot desired server first...
// ... choose an invalid subject
~encoder = FoaDecoderKernel.newListen(0)

// make sure you scroll up to see the resulting valid subjects!
::

warning:: The link::http://recherche.ircam.fr/equipes/salles/listen/##Listen HRTF database:: is measured at link::Classes/SampleRate:: = 44.1kHz. Make sure your link::Classes/Server:: is set to this rate.::



METHOD:: newCIPIC
Measured HRTF decoder, with measurements from the University of California Davis' link::http://interface.cipic.ucdavis.edu/sound/hrtf.html##CIPIC HRTF database:: footnote::See: link::http://interface.cipic.ucdavis.edu/sound/hrtf.html:::: equalised for the diffuse field.

argument:: subjectID
3 to 165 (45 in total) warning:: strong::subjectID::s are not entirely contiguous.::

argument:: server
link::Classes/Server:: on which to load kernel.


discussion::
The link::http://interface.cipic.ucdavis.edu/sound/hrtf.html##CIPIC HRTF database:: provides two link::http://www.gras.dk/00012/00330/##KEMAR dummy:: measurements. strong::subjectID:: = 21 is the large pinnae dummy and strong::subjectID:: = 165 is the small pinnae dummy.

The user is advised to audition strong::subjectID::s to find a suitable choice. If an invalid strong::subjectID:: is chosen, valid choices are returned.

code::
// Boot desired server first...
// ... choose an invalid subject
~encoder = FoaDecoderKernel.newCIPIC(0)

// make sure you scroll up to see the resulting valid subjects!
::


warning:: The link::http://interface.cipic.ucdavis.edu/sound/hrtf.html##CIPIC HRTF database:: is measured at link::Classes/SampleRate:: = 44.1kHz. Make sure your link::Classes/Server:: is set to this rate.::




INSTANCEMETHODS::
private:: initPath, initKernel, printOn


METHOD:: kind
Answers the kind of decoder

discussion::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.kind

// don't forget to free!!
~decoder.free
::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.kind

// don't forget to free!!
~decoder.free
::



METHOD:: subjectID
Answers the strong::subjectID:: of the decoder

discussion::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.subjectID

// don't forget to free!!
~decoder.free
::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.subjectID

// don't forget to free!!
~decoder.free
::



METHOD:: dim
Answers the number of decoder dimensions: 2D or 3D.

discussion::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newSpherical

// inspect
~decoder.dim

// don't forget to free!!
~decoder.free
::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.dim

// don't forget to free!!
~decoder.free
::


METHOD:: numChannels
Answers the number of loudspeaker (or headphone) feeds (output channels).

discussion::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.numChannels

// don't forget to free!!
~decoder.free
::




METHOD:: dirChannels
Answers the direction of loudspeaker (or headphone) feeds, with angles in radians.


discussion::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.dirChannels * 180/pi

// don't forget to free!!
~decoder.free
::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.dirChannels * 180/pi

// don't forget to free!!
~decoder.free
::



METHOD:: kernel
Answers the decoder kernel.

discussion::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.kernel

// don't forget to free!!
~decoder.free
::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.kernel

// don't forget to free!!
~decoder.free
::


METHOD:: kernelSize
Answers the strong::kernelSize::.

discussion::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.kernelSize

// don't forget to free!!
~decoder.free
::

code::
// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.kernelSize

// don't forget to free!!
~decoder.free
::




METHOD:: free
Free the kernel.

discussion:: Release the kernel buffer's memory on the server and return the bufferID back to the server's buffer number allocator for future reuse.

warning:: Only free the kernel when the link::Classes/FoaDecode#*ar:: is no longer in use!::



METHOD:: numOutputs
A synonym for link::#-numChannels::


METHOD:: dirOutputs
A synonym for link::#-dirChannels::


METHOD:: numInputs
Answers the number of inputs for the decoder. 3 for 2D and 4 for 3D.



METHOD:: dirInputs
A convenience method providing polymorphism with link::Classes/FoaEncoderKernel#-dirInputs::.

returns::

list::
## for 2D: code:: [ inf, inf, inf ] ::
## for 3D: code:: [ inf, inf, inf , inf ] ::
::


EXAMPLES::

Please see link::Classes/FoaDecode#Examples::.