Lib_Stroppa-Spat7.txt

; SPATIAL LIBRARY FOR STROPPA ANTESCOFO/MAX LIBRARIES
; Last update: 24/02/2016

/* NOTES:
	This library uses an Antescofo map called $initlevels that contains destinations (as key strings)
	and their coordinates (as value tables).
	It should be defined by user.
	
	Definition example:
	$initlevels := map {
	("FadeOut", [0., 0., 0., 0., 0.]),
	("Left", [0., 1., 0., 0., 0.])
	}

*/

; Initialize and (re)construct $source structure
@proc_def ::InitSources($NumberOfSources, $NumberOfSpeakers, $Namespace)
{
	abort (obj::source)
	;; Stores addresses of each object...
	$source := [0.0 | ($NumberOfSources)]	
    ;; (re)instantiate source objects and store them somewhere!
    $t := tab [$x | $x in $NumberOfSources]
    forall $x in $t
    {
    	$source[$x] := obj::source($x, $NumberOfSpeakers, $Namespace)
    }
    print Created @size($source) Spatial Sources with @size($source[1].$coordinates) points 
}

; define $initlevels here in case it is undefined. User definition SHOULD come next (after @include)
if (@is_undef($initlevels))
{
	print SPAT LIB: initlevels was set to empty
	$initlevels := map { }
}

; define $source here in case it is undefined. User definition SHOULD come next (after @include)
if (@is_undef($source))
{
	; defines vector of source addresses
	$source := [0.0 | (10)]		
}

; SOURCE Object Definition

@obj_def source($idn, $npoints, $namespace)
{
	; Create local variables that are specific to each instance of the object
	@local $coordinates, $idnum, $last_action, $prefix_namespace
	;@local $coordinates 		; This is where we store local coordinates of this source. This is always a variable table whose length is equal to # of speakers
	;@local $idnum				; ID Number of the receiver in patch
	;@local $last_action         ; store the address of last action for aborts etc.
	;@local $prefix_namespace	; string used to build send-symbol for Max/pd as $prefix_namespace+$idnum+"-spat"

	;; Object @init is automatically called when the object is created
	@init 
	{
		$idnum := $idn
		$coordinates := [0.0 | ($npoints)]		; create a table of zeros
		$prefix_namespace := $namespace
	}

	;; A broadcasted signal to all instances of source objects. Useful in panics!
	@broadcast reset()
	{
		;; abort ongoing curves or processes
		abort $last_action
	}

	;; Defining an abort will do additional actions when this object is aborted/killed. Useful for specific temrinal operations.
	@abort
	{
		print "Source " ($idnum) " is killed!"
		abort $last_action
	}

	;;;;;;;; User defined methods
	;; goto method will create a curve that goes from $coordinates to $destination in $dur time
	@proc_def goto($destination, $dur)
	{
			curve FlyingEngine   @Grain := 0.05s, 
				@Action := 
				{
					$coordinates := $x  ; store in internal/local coordinates of this source to keep track
					@command($prefix_namespace+$idnum+"-spat") ($x)
				}
			{
				$x
				{
					{ ($coordinates) }	@type "sine_in_out"
					$dur   	{ ($initlevels($destination)) } @type "sine_in_out"
				}
			}
	}

	;; goto_i method: same as goto, but with the possibility to specify the kind of interpolation
	@proc_def goto_i($destination, $dur, $itp)
	{
			curve FlyingEngine   @Grain := 0.05s, 
				@Action := 
				{
					$coordinates := $x  ; store in internal/local coordinates of this source to keep track
					@command($prefix_namespace+$idnum+"-spat") ($x)
				}
			{
				$x
				{
					{ ($coordinates) }	@type "sine_in_out"
					$dur   	{ ($initlevels($destination)) } @type $itp
				}
			}
	}
	;; Random space local method
	;_________________________________________________________________________________________
	/**** Random Granular Spatial Movement Process
	* Arguments:
	*	arg1 $configs: table of string configurations from $initlevels. ex: [ "Front", "Rear", "Right"]
	*	arg2 $grainrange_min:	float - minimum grain time
	*	arg3 $grainrange_max: 	float - maximum grain time
	*	arg4 $stay_percent:		float (0.to 1.) - percentage of staying on selected configuration
	** IMPORTANT: For now, we give time values in relative. Tempo is fixed inside as 60 BPM.
	**				This means that $grainrange_min 0.05 is 50ms
	****/
	@proc_def RandomSpace($configs, $grainrange_min, $grainrange_max, $stay_percent)
	{
		abort $last_action
		;;; Generate first randoms:
		@local $grainsize, $randomconfig
		$grainsize := @random() * ($grainrange_max - $grainrange_min) + $grainrange_min
		;print DEBUG: Initial grain set to ($grainsize)
		
		$last_action :=
		{
			Loop L	$grainsize
			{
				; Generate a random configuration.
				$randomconfig := ($configs[@rand_int(@size($configs))])
				; Make the move, in duration that is (1.0 - $stay_percent). 
				;$Ticket := [$snum, $randomconfig, ($grainsize*(1.0-$stay_percent))]
				_ := $THISOBJ.goto( $randomconfig , ($grainsize *(1.0 - $stay_percent ) ) )
		
				;print "DEBUG: random space with grain" ($grainsize) "on" ($randomconfig)
				; Generate a new period just before this loop is finishes! Looks like a harakiri!
				$grainsize	$grainsize := @random() * ($grainrange_max - $grainrange_min) + $grainrange_min
			}
		}
	}
}

;_________________________________________________________________________________________
; General SPACE Macro to assign movements to sources.
; Arguments:
;	1st argument: source number (integer)
;	2nd argument:	movement type (string) --> must be in the $initlevels map. Must be wrapped in quotations
;	3rd argument: duration (float, or time in second or milli-second: ex. 3.0 or 3.0s or 3.0ms)
@macro_def Space($snum, $stype, $sdur) 
{	
	; Call the specific GOTO method for source object $snum	
	_ := $source[$snum].goto($stype,$sdur)

	;print Initial coordinate of source ($snum) is ($source[$snum].$coordinates)
	;$sdur print Final coordinate of source ($snum) is ($source[$snum].$coordinates)
}

; SPACE_I Macro: same as SPACE with the choice of the interpolation
; Arguments:
;	1st argument: source number (integer)
;	2nd argument:	movement type (string) --> must be in the $initlevels map. Must be wrapped in quotations
;	3rd argument: duration (float, or time in second or milli-second: ex. 3.0 or 3.0s or 3.0ms)
@macro_def Space_i($snum, $stype, $sdur, $itp) 
{	
	; Call the specific GOTO method for source object $snum	
	_ := $source[$snum].goto_i($stype,$sdur, $itp)

	;print Initial coordinate of source ($snum) is ($source[$snum].$coordinates)
	;$sdur print Final coordinate of source ($snum) is ($source[$snum].$coordinates)
}

;FadeOut
@macro_def FadeOut($sourcenum, $dur) 
{ 
	_ := $source[$sourcenum].goto("FadeOut",$dur)
	;abort ($source[$snum])
}



//////////////////////////////////////////////////////////

; SPACE VOCABULARY: SEE EACH CONFIG FILE
;+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++