net.beadsproject.beads.ugens
Class Spatial

java.lang.Object
  extended by net.beadsproject.beads.core.Bead
      extended by net.beadsproject.beads.core.UGen
          extended by net.beadsproject.beads.ugens.Spatial

public class Spatial
extends UGen

A mixer for a speaker config in any number of dimensions (we haven't tested D>3 yet). Add sources (UGens) and control their locations using other UGens. Locations are changed on a per-channel basis, so that multichannel files can be located in the mixer independently. We follow the 'right-handed' ordering of the axes: http://en.wikipedia.org/wiki/Cartesian_coordinate_system#Orientation_and_handedness The default speaker numbering is as follows: first layout speakers 1-4 on the ground in clockwise order (2D and 3D) then layout speakers 5-8 so that they are above 1-4 respectively. Then according to the 'right-handed' ordering: the x-axis follows the line joining 1 and 4 the y-axis follows the line joining 1 and 2 the z-axis follows the line joining 1 and 5

Author:
ollie

Nested Class Summary
 
Nested classes/interfaces inherited from class net.beadsproject.beads.core.UGen
UGen.OutputInitializationRegime, UGen.OutputPauseRegime
 
Field Summary
 
Fields inherited from class net.beadsproject.beads.core.UGen
bufferSize, bufIn, bufOut, context, ins, outputInitializationRegime, outputPauseRegime, outs
 
Constructor Summary
Spatial(AudioContext context, int dimensions)
          Instantiates a new Spatial with given AudioContext and dimensions.
Spatial(AudioContext context, int dimensions, float sphereDiameter)
          Instantiates a new Spatial with given AudioContext and sphereDiameter.
Spatial(AudioContext context, int dimensions, float[][] locations)
          Instantiates a new Spatial with given AudioContext, dimensions and locations.
Spatial(AudioContext context, int dimensions, float[][] locations, float sphereDiameter)
          Instantiates a new Spatial with the given AudioContext, dimensions, locations and sphereDiamater.
 
Method Summary
 void addInput(int inputIndex, UGen source, int outputIndex)
          This overrides addInput(UGen) by adding a new 'source' sound to the spatialisation.
 void addInput(UGen source)
          This overrides addInput(UGen) by adding a new 'source' sound to the spatialisation.
 void addInput(UGen source, UGen[][] controllers)
          Adds a new source sound with the given UGen controllers for controlling its position.
 void calculateBuffer()
          Called by the signal chain to update this UGen's ouput data.
 void clearInputConnections()
          Clear all of this UGen's input connections.
static float distance(float[] a, float[] b)
          Gets the Euclidian distance between two positions.
 int getNumberOfConnectedUGens(int index)
          Gets the number of UGens connected at the specified input index of this UGen.
 int getNumberOfSources()
           
 void removeAllConnections(UGen sourceUGen)
          Disconnects the specified UGen from this UGen at all inputs.
 void removeSource(UGen source)
          Removes the source.
 void setCurve(float curve)
          Sets the curve.
 void setLocation(UGen source, int channel, float[] newPos)
          Sets the location of a UGen at the give channel with glide.
 void setSpeakerPositions(float[][] locations)
          Sets the speaker positions.
 void setSphereDiameter(float sd)
          Sets the sphere diameter.
static float[][] speakerPositionsFromFile(java.lang.String file, int dimensions)
          Gets speaker positions from file.
 
Methods inherited from class net.beadsproject.beads.core.UGen
addDependent, clearDependents, containsInput, crossfadeInput, getConnectedInputs, getContext, getEnvelopes, getIns, getNumberOfDependents, getOutBuffer, getOuts, getTimeTakenLastUpdate, getValue, getValue, getValueDouble, getValueDouble, initializeOuts, isTimerMode, isUpdated, noInputs, pause, printInBuffers, printInputList, printOutBuffers, removeConnection, removeDependent, setOutsToPause, setTimerMode, setValue, update, zeroIns, zeroOuts
 
Methods inherited from class net.beadsproject.beads.core.Bead
getKillListener, getName, isDeleted, isPaused, kill, message, messageReceived, setKillListener, setName, start, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Spatial

public Spatial(AudioContext context,
               int dimensions)
Instantiates a new Spatial with given AudioContext and dimensions. The default speaker config for the dimensionality is used, and the default sphereDiameter (equal to Math.sqrt(dimensions)).

Parameters:
context - the context
dimensions - the dimensions

Spatial

public Spatial(AudioContext context,
               int dimensions,
               float sphereDiameter)
Instantiates a new Spatial with given AudioContext and sphereDiameter.

Parameters:
context - the AudioContext.
dimensions - the number of dimensions, between 1 and 3.
sphereDiameter - the sphere diameter.

Spatial

public Spatial(AudioContext context,
               int dimensions,
               float[][] locations)
Instantiates a new Spatial with given AudioContext, dimensions and locations. The locations array is an array of the form float[speakerNumber][dimension].

Parameters:
context - the context.
dimensions - the dimensions.
locations - the locations.

Spatial

public Spatial(AudioContext context,
               int dimensions,
               float[][] locations,
               float sphereDiameter)
Instantiates a new Spatial with the given AudioContext, dimensions, locations and sphereDiamater. The locations array is an array of the form float[speakerNumber][dimension].

Parameters:
context - the context
dimensions - the dimensions
locations - the locations
sphereDiameter - the sphere diameter
Method Detail

setSphereDiameter

public void setSphereDiameter(float sd)
Sets the sphere diameter. This is the distance beyond which sound is attenuated to zero.

Parameters:
sd - the new sphere diameter.

speakerPositionsFromFile

public static float[][] speakerPositionsFromFile(java.lang.String file,
                                                 int dimensions)
Gets speaker positions from file. File data must correspond to given dimensions.

Parameters:
file - the file.
dimensions - the dimensions.
Returns:
the speaker locations.

setSpeakerPositions

public void setSpeakerPositions(float[][] locations)
Sets the speaker positions. The locations array is an array of the form float[speakerNumber][dimension].

Parameters:
locations - the new speaker positions.

distance

public static float distance(float[] a,
                             float[] b)
Gets the Euclidian distance between two positions.

Parameters:
a - the a
b - the b
Returns:
the float

addInput

public void addInput(UGen source)
This overrides addInput(UGen) by adding a new 'source' sound to the spatialisation.

Overrides:
addInput in class UGen
Parameters:
source - the UGen to connect to this UGen.

addInput

public void addInput(int inputIndex,
                     UGen source,
                     int outputIndex)
This overrides addInput(UGen) by adding a new 'source' sound to the spatialisation.

Overrides:
addInput in class UGen
Parameters:
inputIndex - the input of this UGen to connect to.
source - the UGen to connect to this UGen.
outputIndex - the output of the connecting UGen with which to make the connection.

addInput

public void addInput(UGen source,
                     UGen[][] controllers)
Adds a new source sound with the given UGen controllers for controlling its position. The array of controllers is of the form UGen[channel][dimension] where channel is the output channel of the source UGen, treated as a point source in the space and dimension is the axis along which the controller UGen is controlling position.

Parameters:
source - the source.
controllers - the controllers.

setLocation

public void setLocation(UGen source,
                        int channel,
                        float[] newPos)
Sets the location of a UGen at the give channel with glide. This assumes the UGen's position is not being controlled by other external UGens.

Parameters:
source - the source
channel - the channel
newPos - the new pos

removeSource

public void removeSource(UGen source)
Removes the source.

Parameters:
source - the source

clearInputConnections

public void clearInputConnections()
Description copied from class: UGen
Clear all of this UGen's input connections.

Overrides:
clearInputConnections in class UGen

removeAllConnections

public void removeAllConnections(UGen sourceUGen)
Description copied from class: UGen
Disconnects the specified UGen from this UGen at all inputs.

Overrides:
removeAllConnections in class UGen
Parameters:
sourceUGen - the UGen to disconnect.

setCurve

public void setCurve(float curve)
Sets the curve. The curve defines the attenuation from each speaker from 1 when the source is next to the speaker to zero when the source is at sphereDiamater away from the speaker or further. The curve defines the exponent of the attenuation, such that numbers greater than 1 drop more rapidly near the speaker whilst numbers less than 1 (greater than zero please) drop more gently.

Parameters:
curve - the new curve

calculateBuffer

public void calculateBuffer()
Description copied from class: UGen
Called by the signal chain to update this UGen's ouput data. Subclassses of UGen should implement the UGen's DSP perform routine here. In general this involves grabbing data from UGen.bufIn and putting data into UGen.bufOut in some way. UGen.bufIn and UGen.bufOut are 2D arrays of floats of the form float[numChannels][bufferSize]. The length of the buffers is given by UGen.bufferSize, and the number of channels of the input and output buffers are given by UGen.ins and UGen.outs respectively.

Specified by:
calculateBuffer in class UGen

getNumberOfConnectedUGens

public int getNumberOfConnectedUGens(int index)
Description copied from class: UGen
Gets the number of UGens connected at the specified input index of this UGen.

Overrides:
getNumberOfConnectedUGens in class UGen
Parameters:
index - index of input to inspect.
Returns:
number of UGen outputs connected to that input.

getNumberOfSources

public int getNumberOfSources()