HelpSource/Classes/Ref.schelp

   1 class:: Ref
   2 summary:: a reference to a value
   3 categories:: Core
   4
   5 description::
   6
   7 A Ref holds an object which may be retrieved and altered with the messages value and value_(obj).
   8 The backquote code:: ` :: is a unary operator that is equivalent to calling code::Ref.new(obj)::.
   9
  10 Refs are most commonly used to prevent multi-channel expansion in link::Classes/SynthDef::s and link::Classes/Pattern::s (see link::Classes/Klank:: for an example).
  11 Refs can also be used to simplify the coding of co-routines used in EventStreams (see link::Classes/Proutine:: for an example).
  12
  13 code::
  14
  15 x = Ref(nil);
  16 z = obj.method(x);              // method puts something in reference
  17 x.value.doSomething;    // retrieve value and use it
  18
  19 ::
  20
  21 Ref is also used as a quoting device to protect against multi channel expansion in certain UGens that require Arrays.
  22
  23 classmethods::
  24
  25 method::new
  26
  27 create a Ref of an object.
  28 discussion::
  29 Another syntax:
  30
  31 code::
  32 `5
  33 ::
  34
  35 instancemethods::
  36
  37 method::dereference
  38
  39 Answer the value. This message is also defined in class Object where it just returns the receiver.  Therefore anything.dereference will remove a Ref if there is one. This is slightly different than the value message, because value will also cause functions to evaluate themselves whereas dereference will not.
  40
  41 method::asRef
  42
  43 Answers the receiver. In class Object this message is defined to create a Ref of the object.
  44
  45 method::value
  46
  47 Get or set the value.
  48
  49 method::get
  50
  51 Returns value.
  52
  53 method::set
  54
  55 Sets value.
  56
  57 method::at
  58
  59 Returns code::value.at(index)::
  60
  61 method::put
  62 Executes value.put(index, value)
  63
  64 method::seq
  65
  66 this method is used to return values from within a Routine definition
  67
  68 discussion::
  69 code::
  70 { this.value = output.embedInStream(this.value); }
  71 ::
  72
  73 method::asUGenInput
  74
  75 Returns the Ref - this prevents multi-channel expansion in a SynthDef
  76
  77 method::asControlInput
  78
  79 Returns the value - this is used when sending a Ref as a control value to a server Node.
  80
  81 section::Typical uses of Ref:
  82
  83 subsection::preventing multi-channel expansion
  84
  85 Consult link::Guides/Multichannel-Expansion:: for details on multi-channel expansion in SynthDefs.
  86
  87 Refs prevent multi-channel expansion in a SynthDef, so the array below defines one Klank UGen rather than three.
  88
  89 code::
  90 { Klank.ar(`[[800, 1071, 1153, 1723], nil, [1, 1, 1, 1]], Impulse.ar(2, 0, 0.1)) }.play;
  91 ::
  92
  93 Refs cannot be used reliably to suppress multi-channel expansion within Events and Patterns.
  94 Instead, it is necessary to enclose the array of values in another array:
  95
  96 code::
  97 (
  98         SynthDef(\multi, { | out, freq = #[100,200,300], amp = 0.1, pan = 0, sustain = 1|
  99                 var audio, env;
 100                 env = EnvGen.kr(Env.perc(0.01, sustain), doneAction:2);
 101                 audio = Mix(Saw.ar(freq));
 102                 audio = Pan2.ar(audio * env, pan, amp);
 103                 OffsetOut.ar(out, audio)
 104         }).add;
 105
 106         ( instrument: \multi, freq: [ [500, 501, 700] ], sustain: 2).play
 107
 108 )
 109 ::
 110
 111 code::
 112 (
 113         Pbind(*[
 114                 instrument: \multi,
 115                 freq:   Prand([
 116                                                 [[100, 141, 103] ],
 117                                                 [[100, 310, 190] ],
 118                                                 [[100, 100.1, 110] ],
 119                                 ], inf),
 120                 dur: 0.2,
 121                 sustain: 0.3
 122         ]).play;
 123 )
 124 ::
 125
 126
 127 method::multichannelExpandRef
 128 This method is called internally on inputs to UGens that take multidimensional arrays, like link::Classes/Klank:: and it allows proper multichannel expansion even in those cases. For SequenceableCollection, this returns the collection itself, assuming that it contains already a number of Refs.
 129
 130 argument::rank
 131 The depth at which the list is expanded. For instance the Klank spec has a rank of 2.
 132 code::
 133 `([[[100, 200], 500], nil, [[[0.01, 0.3], 0.8]]]).multichannelExpandRef(2);
 134 [`[[100, 200], nil, [0.2, 0.8]], `[[130, 202], nil, [0.2, 0.5]]].multichannelExpandRef(2);
 135 ::