cleaned up a number of patches; renamed all to the standard -help.pd format; added some more ideas to the style guide; finished up lists_vs_anythings

svn path=/trunk/; revision=2841

1 files changed, 185 insertions, 0 deletions

diff --git a/doc/pddp/swap-help.pd b/doc/pddp/swap-help.pd
new file mode 100644
index 00000000..a6b539ca
--- /dev/null
+++ b/doc/pddp/swap-help.pd
@@ -0,0 +1,185 @@
+#N canvas 0 0 625 631 12;

+#X obj 104 572 pddp;

+#X obj 8 8 cnv 15 90 586 empty empty empty 20 12 0 14 -233017 -66577

+0;

+#X text 37 47 INLETS:;

+#X obj 54 18 swap;

+#X text 108 18 - SWAP TWO NUMBERS \, RESPECTING RIGHT-TO-LEFT ORDER

+;

+#X obj 285 470 swap;

+#X floatatom 175 429 5 0 0 0 - - -;

+#X floatatom 372 437 5 0 0 0 - - -;

+#X floatatom 312 497 5 0 0 0 - - -;

+#X floatatom 263 497 5 0 0 0 - - -;

+#X msg 243 427 42 7;

+#X obj 119 438 bng 15 250 50 0 empty empty "bang" 0 -6 0 8 -262144

+-1 -1;

+#X msg 290 415 42 7 3 4;

+#X floatatom 506 491 5 0 0 0 - - -;

+#X floatatom 454 490 5 0 0 0 - - -;

+#X msg 454 436 bang;

+#X obj 454 460 swap 12;

+#X text 37 62 - LEFT:;

+#X text 28 263 - RIGHT:;

+#X text 104 63 Float - A float at the left inlet will send the number

+to the right outlet and then send the number at the right inlet to

+the left outlet.;

+#X text 104 117 Bang - A bang at the left inlet will force [swap] to

+send its values to the outlets \, in reverse order. The value from

+the left inlet will be sent to the right outlet then the value at the

+right inlet will be sent out the left outlet.;

+#X text 104 188 List - A list at the left inlet will update the values

+of both of [swap]'s inlets and send the numbers to the outlets in reverse

+order. Note that lists of 3 or more elements will be truncated.;

+#X text 104 264 Float - A float at the right inlet is stored for later

+use. It will be sent to the left outlet when a float or bang is received

+in the left inlet.;

+#X text 104 317 One - [swap] accepts a single float as a creation argument

+which initializes the first value to be sent out the left outlet.;

+#X text 104 370 Two - outputs the float values of the two inlets in

+reverse order when a float \, list \, or bang is received at the left

+inlet.;

+#X text 371 418 float;

+#X text 174 410 float;

+#X text 244 409 list;

+#X text 428 510 creation argument;

+#N canvas 59 0 397 246 Related_Objects 0;

+#X text 25 11 Native Pd Objects;

+#X text 23 92 Externals and other object libraries;

+#X obj 42 48 pack;

+#X obj 104 48 unpack;

+#X text 30 126 [split];

+#X restore 104 522 pd Related_Objects;

+#N canvas 60 0 581 620 More_Info 0;

+#X msg 38 54 42 7;

+#X obj 38 79 swap;

+#X floatatom 38 105 5 0 0 0 - - -;

+#X floatatom 97 105 5 0 0 0 - - -;

+#X obj 38 129 pack f f;

+#X obj 38 153 print;

+#N canvas 154 0 649 595 millers_note-off_parser 0;

+#X obj 27 18 notein;

+#X text 103 14 [notein] is an object which receives incoming MIDI data

+from a MIDI instrument. The three outlets are PITCH \, VELOCITY \,

+and MIDI CHANNEL from left to right. It is important to note however

+that the data is outputted from right to left. Which means that the

+first piece of information to be sent out the object is the MIDI CHANNEL.

+;

+#X obj 26 117 swap;

+#X obj 26 156 pack;

+#X obj 26 200 route 0;

+#X floatatom 26 228 5 0 0 0 - - -;

+#X text 102 117 Here \, [swap] is used to store the VELOCITY until

+the PITCH information comes from [notein]. The next step will pack

+the two together...but we have to ensure that [pack] receives the two

+numbers in the correct order: PITCH first \, then VELOCITY. This way

+\, using [route] we can determine whether or not this incoming MIDI

+data is a "note-off" signal (i.e. VELOCITY = 0).;

+#X obj 26 250 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1

+-1;

+#X obj 46 312 notein;

+#X obj 47 352 pack;

+#X obj 47 377 route 0;

+#X floatatom 47 402 5 0 0 0 - - -;

+#X obj 47 420 bng 15 250 50 0 empty empty empty 0 -6 0 8 -262144 -1

+-1;

+#X text 122 308 The goal of the Miller's example at the bottom left

+\, is to retrieve "note-off" signals from [notein]. To do that \, we

+have to test the incoming data for pitches with a velocity of zero.

+To do that \, we are packing up the incoming PITCH and VELOCITY data

+and sending them to [route]...in effect we achieve the following:;

+#X text 98 420 IF velocity = 0 THEN "bang";

+#X text 127 445 In the example above \, the [pack] object will output

+a list as soon as the VELOCITY information comes from [notein]. As

+a result \, the list will be outputted from pack BEFORE the PITCH information

+is retrieved. [swap] is used to solve this problem by making sure that

+the VELOCITY and PITCH are both received before packing them up and

+sending them to the [route] object.;

+#X text 50 248 This will "bang" only when velocity = 0;

+#X text 22 282 THIS IS WHY THE ALTERNATIVE DOESN'T WORK?;

+#X connect 0 0 2 0;

+#X connect 0 1 2 1;

+#X connect 2 0 3 0;

+#X connect 2 1 3 1;

+#X connect 3 0 4 0;

+#X connect 4 0 5 0;

+#X connect 5 0 7 0;

+#X connect 8 0 9 1;

+#X connect 8 1 9 0;

+#X connect 9 0 10 0;

+#X connect 10 0 11 0;

+#X connect 11 0 12 0;

+#X restore 28 569 pd millers_note-off_parser;

+#X floatatom 44 319 5 0 0 0 - - -;

+#X floatatom 94 319 5 0 0 0 - - -;

+#X floatatom 143 319 5 0 0 0 - - -;

+#X floatatom 112 440 5 0 0 0 - - -;

+#X floatatom 161 440 5 0 0 0 - - -;

+#X floatatom 211 440 5 0 0 0 - - -;

+#X msg 37 243 2 2500 9 420;

+#X obj 43 289 unpack f f f f;

+#X floatatom 193 319 5 0 0 0 - - -;

+#X text 14 10 [swap] is most commonly used to change the order of a

+list. This trick is best suited for a PAIR of numbers.;

+#X obj 166 345 swap;

+#X obj 139 370 swap;

+#X obj 112 394 swap;

+#X obj 196 378 swap;

+#X obj 169 403 swap;

+#X obj 228 408 swap;

+#X floatatom 262 440 5 0 0 0 - - -;

+#X text 230 345 This could quickly become ridiculous!;

+#X msg 165 245 1 2 3 4;

+#X msg 254 258 0 200 3333 1111;

+#X text 14 477 In other settings \, the [swap] object is useful as

+a timing mechanism to ensure that two numbers arrive at their destination

+in a particular order. Miller Puckette provided an excellent example

+of [swap] used to build a 'note-off parser'.;

+#X text 14 185 Lists that are longer than two elements could be sorted

+this way \, but the structure quickly becomes unmanageable. It's probably

+better to find an alternative method.;

+#X connect 0 0 1 0;

+#X connect 1 0 2 0;

+#X connect 1 1 3 0;

+#X connect 2 0 4 0;

+#X connect 3 0 4 1;

+#X connect 4 0 5 0;

+#X connect 7 0 19 0;

+#X connect 8 0 18 0;

+#X connect 9 0 17 0;

+#X connect 13 0 14 0;

+#X connect 14 0 7 0;

+#X connect 14 1 8 0;

+#X connect 14 2 9 0;

+#X connect 14 3 15 0;

+#X connect 15 0 17 1;

+#X connect 17 0 18 1;

+#X connect 17 1 20 1;

+#X connect 18 0 19 1;

+#X connect 18 1 20 0;

+#X connect 19 0 10 0;

+#X connect 19 1 21 0;

+#X connect 20 0 21 1;

+#X connect 20 1 22 1;

+#X connect 21 0 11 0;

+#X connect 21 1 22 0;

+#X connect 22 0 12 0;

+#X connect 22 1 23 0;

+#X connect 25 0 14 0;

+#X connect 26 0 14 0;

+#X restore 104 547 pd More_Info;

+#X text 152 573 - Dave Sabine \, November 12 \, 2002;

+#X text 13 317 ARGUMENTS:;

+#X text 29 369 OUTLETS:;

+#X text 20 427 EXAMPLES:;

+#X text 21 522 SEE ALSO:;

+#X connect 5 0 9 0;

+#X connect 5 1 8 0;

+#X connect 6 0 5 0;

+#X connect 7 0 5 1;

+#X connect 10 0 5 0;

+#X connect 11 0 5 0;

+#X connect 12 0 5 0;

+#X connect 15 0 16 0;

+#X connect 16 0 14 0;

+#X connect 16 1 13 0;