CLASS:: FoaEncoderKernel
summary:: First Order Ambisonic (FOA) encoder kernels
categories:: Libraries>Ambisonic Toolkit>FOA>Encoding
related:: Classes/FoaEncoderMatrix, Classes/FoaEncode

DESCRIPTION::
Generates encoding kernels required by the Ambisonic Toolkit's first order encoder, link::Classes/FoaEncode::.

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


CLASSMETHODS::

METHOD:: newSuper
Ambisonic Super Stereo encoder. footnote::See: link::http://en.wikipedia.org/wiki/Ambisonics#Super_stereo::::

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

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

discussion:: The Super Stereo encoding technique is the classic method for encoding stereophonic signals into B-format. 


METHOD:: newUHJ
Ambisonic UHJ stereo encoder. 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:: The UHJ encoder offers access to numerous published recordings footnote:: Nimbus Records' primary output is in Ambisonic UHJ. See: http://en.wikipedia.org/wiki/Nimbus_Records And: http://www.wyastone.co.uk/index.php :: for periphonic (2D) audition.

note:: For optimal performance, use a dual-band decoder ( code::'dual':: ) for monitoring. See discussion link::Classes/FoaDecoderMatrix#decoder_k#here::. ::


METHOD:: newSpread
Frequency spreading mono encoder.

argument:: subjectID
0 to 12. Specifies the number of bands per octave of the frequency spreader. 0 returns 1 band per octave, etc.

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

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

discussion:: The frequency spreading technique encodes a monophonic signal into B-format by smoothly rotating the signal across the soundfield sphere, by frequency.

note:: As the number of bands per octaves increases, more time domain artefacts are introduced. This is usually heard as smearing in time.::


METHOD:: newDiffuse
Frequency diffusion mono encoder.

argument:: subjectID
0 to 5. Specifies the amount of phase dispersion of the frequency diffuser. 0 is low, 5 is high.

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

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

discussion:: The frequency diffusion technique encodes a monophonic signal into B-format by randomising the phase of the signal across the soundfield sphere, by frequency.

note:: As the diffusion increases, more time domain artefacts are introduced. This is usually heard as smearing in time.::


INSTANCEMETHODS::
private:: initPath, initKernel, printOn


METHOD:: kind
Answers the kind of encoder

discussion::

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

// inspect
~encoder.kind

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


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

discussion::

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

// inspect
~encoder.subjectID

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



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

discussion::

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

// inspect
~encoder.dim

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



METHOD:: numChannels
Answers the number of input channels.

discussion::

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

// inspect
~encoder.numChannels

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




METHOD:: dirChannels
Answers the direction of input channels, with angles in radians.

discussion::

code::
// encoder - make sure you boot the server first!!
~encoder = FoaEncoderKernel.newSuper

// inspect
~encoder.dirChannels * 180/pi

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

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

// inspect
~encoder.dirChannels * 180/pi

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


METHOD:: kernel
Answers the encoder kernel.

discussion::

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

// inspect
~encoder.kernel

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




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


discussion::

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

// inspect
~encoder.kernelSize

// don't forget to free!!
~encoder.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/FoaEncode#*ar:: is no longer in use!::



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


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


METHOD:: numOutputs
Answers the number of outputs for the decoder. 3 for 2D and 4 for 3D.


METHOD:: dirOutputs
A convenience method providing polymorphism with link::Classes/FoaDecoderKernel#-dirOutputs::.

returns::

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


EXAMPLES::

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