-
Notifications
You must be signed in to change notification settings - Fork 10
/
pdlua-help.pd
194 lines (194 loc) · 15.7 KB
/
pdlua-help.pd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
#N canvas 466 36 561 610 10;
#X declare -lib pdlua -path pdlua;
#X declare -path pdlua/examples;
#X text 16 358 See also:;
#X obj 55 257 pdlua;
#X obj 81 359 pdluax hello;
#X obj 6 446 cnv 3 550 3 empty empty inlets 8 12 0 13 #dcdcdc #000000 0;
#X obj 6 481 cnv 3 550 3 empty empty outlets 8 12 0 13 #dcdcdc #000000 0;
#X obj 6 516 cnv 3 550 3 empty empty arguments 8 12 0 13 #dcdcdc #000000 0;
#X obj 145 455 cnv 17 3 17 empty empty 0 5 9 0 16 #dcdcdc #9c9c9c 0;
#X obj 6 549 cnv 15 552 21 empty empty empty 20 12 0 14 #e0e0e0 #202020 0;
#X text 245 491 NONE;
#X text 245 526 NONE;
#X text 179 456 load <symbol>;
#X text 191 226 <-- load and run a Lua file;
#X text 91 257 <-- global interface to pdlua;
#X obj 306 4 cnv 15 250 40 empty empty empty 12 13 0 18 #7c7c7c #e0e4dc 0;
#N canvas 382 141 749 319 (subpatch) 0;
#X coords 0 -1 1 1 249 39 2 100 100;
#X restore 305 3 pd;
#X obj 315 18 cnv 10 10 10 empty empty Load\ externals\ written\ in\ Lua 0 6 2 20 #7c7c7c #e0e4dc 0;
#X obj 3 3 cnv 15 301 42 empty empty pdlua 20 20 2 37 #e0e0e0 #000000 0;
#N canvas 0 22 450 278 (subpatch) 0;
#X coords 0 1 100 -1 299 39 1 0 0;
#X restore 3 3 graph;
#X text 390 243 <- right click for help or open, f 16;
#X text 22 60 [pdlua] registers a loader that allows Pd externals written in Lua (with the .pd_lua extension) to be loaded. To guarantee Pd will load these externals \, you should load [pdlua] as a library \, either at startup or with [declare]:, f 80;
#X text 75 114 loading [pdlua] from [declare] -->;
#X text 263 456 - load and run a '*.lua' file;
#X text 324 344 Details on writting lua externals ----->, f 23;
#X text 23 291 The [hello] object above is loaded from a 'hello.pd_lua' file. You can also provide help files for it and right click on it to ask for them. Right click also allows you to open the .pd_lua file if your system has a known application for it., f 80;
#X text 164 353 (this version creates objects from .pd_luax files), f 20;
#X obj 290 115 declare -lib pdlua -path pdlua;
#X text 23 146 If you also create [pdlua] as an object as below \, a global interface is created to load and run "*.lua" files via the 'load' message. Make sure that Pd is aware of the paths where your .pd_lua externals and .lua files are - you can also use declare for this (see that above we also include '-path pdlua' so it finds the 'hello' external and its help file)., f 80;
#N canvas 567 120 718 519 quickstart 0;
#X obj 47 83 cnv 15 450 140 empty empty pdlua\ HOWTO 20 12 0 15 #dfdfdf #000000 0;
#X obj 47 224 cnv 15 450 140 empty empty -\ Class\ Creation: 20 12 0 14 #cccccc #000000 0;
#X obj 47 365 cnv 15 450 300 empty empty -\ Object\ Initialization: 20 12 0 14 #dfdfdf #000000 0;
#X obj 47 666 cnv 15 450 120 empty empty empty 20 12 0 14 #cccccc #404040 0;
#X obj 47 787 cnv 15 450 170 empty empty empty 20 12 0 14 #dfdfdf #404040 0;
#X obj 47 1661 cnv 15 450 100 empty empty -\ Sending\ To\ Receivers: 20 12 0 14 #dfdfdf #000000 0;
#X obj 47 1762 cnv 15 450 120 empty empty -\ Receivers: 20 12 0 14 #cccccc #000000 0;
#X text 65 113 The Lua loader included in -lib pdlua allows externals for Pd to be written in the Lua programming language. (www.lua.org), f 65;
#X text 65 145 If you try to create an object [foo] in Pd \, Pd checks if the class "foo" exists. If it doesn't \, it tries to load an external file that "probably" will contain code for "foo". The Lua loader adds support for loading "foo.pd_lua" when you try to create [foo]., f 65;
#X obj 47 958 cnv 15 450 70 empty empty -\ Object\ Finalization: 20 12 0 14 #cccccc #000000 0;
#X text 76 309 This creates a new Pd class called "foo". The 'local' declaration is optional \, but recommended -- without it \, 'foo' is global \, which means any Lua code can modify it (possibly by accident)., f 61;
#X text 75 251 The first expression/statement in the text file "foo.pd_lua" should be of the form:;
#X obj 47 1029 cnv 15 450 400 empty empty -\ Inlet\ Methods: 20 12 0 14 #dfdfdf #000000 0;
#X text 65 486 or equivalently:;
#X obj 47 1430 cnv 15 450 230 empty empty -\ Sending\ To\ Outlets: 20 12 0 14 #cccccc #000000 0;
#X text 65 390 Then you can add methods to the Pd class. The most important one is 'initialize' \, which is executed when a new object is created:, f 65;
#X text 81 598 [foo a b 1 2 3 c];
#X text 65 569 'sel' is the class name \, 'atoms' are the creation arguments in a Lua table. For example a Pd object, f 61;
#X text 66 616 would have sel equal to "foo" and the atoms:;
#X text 65 670 Being a method \, 'initialize' has a 'self' variable (which is the object to be created) \, and if you want your objects to have inlets or outlets you need need to set those fields in this method (Pd doesn't support changing the number of inlets or outlets after an object is created):;
#X text 65 769 The default inlet/outlet counts are 0;
#X text 65 792 The return value of 'initialize' is used to allow objects to fail to create (for example \, if the creation arguments are bad). Most of the time you will 'return true' \, but if you really can't create then you can 'return false'.;
#X text 65 980 The 'finalize' method is called when the object is deleted by Pd. You can clean up stuff here if needed. The default implementation does nothing.;
#X text 65 1690 You can send messages to receivers like this:;
#X text 66 1842 Remember to clean up your receivers in object:finalize() \, or weird things will happen., f 57;
#X obj 47 1883 cnv 15 450 120 empty empty -\ Clocks: 20 12 0 14 #dfdfdf #000000 0;
#X obj 47 2004 cnv 15 450 140 empty empty -\ Miscellaneous\ Object\ Methods: 20 12 0 14 #cccccc #000000 0;
#X text 66 1909 You can bind methods to clocks \, for timing based on Pd's logical clock.;
#X text 66 1952 Remember to clean up your clocks in object:finalize() \, or weird things will happen.;
#X text 65 2024 Execute a Lua file using Pd's path to find it:;
#X text 65 2066 Report an error to Pd's console:;
#X obj 47 2145 cnv 15 450 80 empty empty -\ Miscellaneous\ Functions: 20 12 0 14 #dfdfdf #000000 0;
#X text 65 2169 Print a string to Pd's console:;
#X text 65 2206 Note that pd.post() should not really be used for errors.;
#X text 65 1784 You can bind methods to receivers \, to get messages from [send receiver]., f 52;
#X obj 83 284 cnv 15 300 20 empty empty empty 15 10 0 14 #ffffff #202020 0;
#X obj 82 427 cnv 15 300 50 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X obj 82 505 cnv 15 300 50 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X text 89 429 function foo:initialize(sel \, atoms);
#X text 90 442 -- code;
#X text 90 456 end;
#X text 90 509 foo.initialize = function (self \, sel \, atoms);
#X text 89 523 -- code;
#X text 90 536 end;
#X obj 122 894 cnv 15 300 50 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X obj 82 736 cnv 15 300 30 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X text 82 635 {"a" \, "b" \, 1 \, 2 \, 3 \, "c"};
#X text 90 736 self.inlets = 1;
#X text 129 896 function foo:postinitialize();
#X text 129 910 -- code;
#X text 130 925 end;
#X obj 82 2042 cnv 15 300 20 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X obj 82 2085 cnv 15 300 20 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X obj 82 2186 cnv 15 300 20 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X text 90 2044 self:dofile("filename");
#X text 90 2088 self:error("message");
#X text 90 2188 pd.post("a string");
#X obj 514 1698 bng 20 250 50 0 empty empty empty 17 7 0 10 #dfdfdf #000000 #000000;
#X floatatom 632 1814 3 0 0 0 - - - 0;
#X text 66 1821 See doc/examples/lreceive.pd_lua for details.;
#X text 81 1738 See doc/examples/lsend.pd_lua for details.;
#X text 66 1937 See doc/examples/ldelay.pd_lua for details.;
#X obj 514 1730 lsend splat-1;
#X obj 549 1705 lsend splat-2;
#X obj 509 1784 lreceive splat- 1 2 3;
#X obj 534 1930 ldelay 1000;
#X text 65 1054 Each inlet should have at least one method that will be called when an item it can handle arrives at that input.;
#X obj 91 1139 cnv 15 300 50 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X text 98 1143 function foo:in_1_float(f);
#X text 97 1156 -- code;
#X text 99 1169 end;
#X text 75 1273 A "gimme" method for [foo] accepts any input:;
#X obj 92 1488 cnv 15 300 20 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X text 99 1492 self:outlet(2 \, "bang" \, {});
#X text 65 1467 This will cause the second outlet to emit a bang:;
#X obj 92 1548 cnv 15 300 20 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X text 65 1527 This will cause the second outlet to emit a float:;
#X text 99 1552 self:outlet(2 \, "float" \, {123});
#X obj 92 1608 cnv 15 300 40 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X text 65 1586 This will cause the first outlet to emit a list:;
#X text 99 1629 self:outlet(1 \, "list" \, somelist);
#X text 99 1612 self.somelist = {some items in a list};
#X text 75 1195 A "stop" method for inlet 2 of [foo]:;
#X text 65 1084 The name of the method is constructed as "in_n_selector" where n is the inlet number (starting from 1) and selector is a type such as "float" or "bang" \, or a selector name such as "start". Here is a float method for [foo] inlet 1:;
#X obj 72 1707 cnv 15 360 20 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X text 78 1709 pd.send("receiver" \, "selector" \, {"a" \, "message" \, 1 \, 2 \, 3});
#X text 75 1350 A method for symbols on any input:;
#X text 65 846 If you need to do things after the Pd object is created \, but before control is returned to Pd \, (such as registering receivers or clocks) you can use the 'postinitialize' method:;
#X text 65 2106 This will allow the object to be highlighted from Pd's menu using Find->Find Last Error.;
#X text 90 752 self.outlets = 2;
#X text 65 1449 Use self:outlet(outlet_number \, type \, table);
#X text 102 287 local foo = pd.Class:new():register("foo");
#X obj 91 1216 cnv 15 300 50 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X obj 91 1294 cnv 15 300 50 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X obj 91 1371 cnv 15 300 50 empty empty empty 20 12 0 14 #ffffff #404040 0;
#X text 97 1233 -- code;
#X text 99 1246 end;
#X text 97 1311 -- code;
#X text 99 1324 end;
#X text 98 1298 function foo:in_1(sel \, atoms);
#X text 98 1220 function foo:in_2_stop();
#X text 97 1388 -- code;
#X text 99 1401 end;
#X text 98 1375 function foo:in_n_symbol(i \, s);
#X obj 509 1814 route bang float;
#X obj 509 1841 bng 20 250 50 0 empty empty empty 17 7 0 10 #dfdfdf #000000 #000000;
#X floatatom 555 1844 5 0 0 0 - - - 0;
#X msg 549 1672 100;
#X msg 587 1672 1000;
#X obj 534 1900 bng 20 250 50 0 empty empty empty 17 7 0 10 #dfdfdf #000000 #000000;
#X obj 534 1955 bng 20 250 50 0 empty empty empty 17 7 0 10 #dfdfdf #000000 #000000;
#X obj 46 2226 cnv 17 450 20 empty empty empty 20 12 0 14 #cccccc #404040 0;
#X text 71 2229 (modified from doc/examples/pdlua/lua.txt by mrpeach 2011/10/06), f 64;
#N canvas 0 22 450 278 (subpatch) 0;
#X coords 0 1 100 -1 167 101 1 0 0;
#X restore 497 1661 graph;
#N canvas 0 22 450 278 (subpatch) 0;
#X coords 0 1 100 -1 167 120 1 0 0;
#X restore 497 1762 graph;
#N canvas 0 22 450 278 (subpatch) 0;
#X coords 0 1 100 -1 167 121 1 0 0;
#X restore 497 1882 graph;
#N canvas 0 22 450 278 (subpatch) 0;
#X coords 0 1 100 -1 451 2163 1 0 0;
#X restore 46 82 graph;
#X text 69 16 Find basic instructions/examples below on how to write externals in Lua. For further details \, see 'pd-lua-intro.pdf' in the 'pdlua/tutorial' folder. You can also find this tutorial online at: https://agraef.github.io/pd-lua/tutorial/pd-lua-intro.html, f 66;
#X obj 515 1624 declare -path pdlua/examples;
#X text 549 1602 Examples from:;
#X connect 107 0 108 0;
#X connect 110 0 65 0;
#X restore 446 359 pd quickstart;
#N canvas 106 35 1079 707 graphics 0;
#X obj 8 77 hello-gui;
#X text 8 376 function yourclass:initialize(sel \, atoms);
#X text 24 409 return true;
#X text 7 427 end;
#X text 8 457 -------------- Painting: --------------;
#X text 8 480 You can paint by defining the "paint" function \, for example:;
#X text 8 561 end;
#X text 8 604 -------------- Mouse Events: --------------;
#X text 8 633 You can receive mouse events by defining the "mouse_down" \, "mouse_up" \, "mouse_move" and "mouse_drag" functions. Both pass the x \, y coordinates as arguments. For example:;
#X text 8 743 end;
#X text 8 691 function yourclass:mouse_down(x \, y);
#X text 25 708 pd.post(tostring(x));
#X text 25 725 pd.post(tostring(y));
#X text 8 788 -------------- API: --------------;
#X text 8 509 function yourclass:paint(g);
#X text 8 11 pdlua's graphics allow you to draw basic vector graphics and receive mouse events on pure-data and plugdata. Drawing functions need to be called on the graphics context class \, which is passed into the paint() function as the first argument., f 72;
#X text 25 526 g:set_color(250 \, 200 \, 240);
#X text 25 543 g:fill_all();
#X text 8 323 Graphics mode is enabled automatically by defining the paint method \, see below. You can also set the size in the constructor (or in any other function) \, like this:;
#X text 23 394 self:set_size(100 \, 100);
#X text 8 816 pd:Class:mouse_down(x \, y) \; pd:Class:mouse_up(x \, y) \; pd:Class:mouse_move(x \, y) \; pd:Class:mouse_drag(x \, y) \; \; pd:Class:set_size(w \, h) \; width \, height = pd:Class:get_size() \; \; pd:Class:repaint() \; pd:Class:paint(g) \; \; g:set_color(r \, g \, b \, a=1.0) \; \; g:fill_ellipse(x \, y \, w \, h) \; g:stroke_ellipse(x \, y \, w \, h \, line_width) \; g:fill_rect(x \, y \, w \, h) \; g:stroke_rect(x \, y \, w \, h \, line_width) \; g:fill_rounded_rect(x \, y \, w \, h \, corner_radius) \; g:stroke_rounded_rect(x \, y \, w \, h \, corner_radius \, line_width) \; \; g:draw_line(x1 \, y1 \, x2 \, y2) \; g:draw_text(text \, x \, y \, w \, fontsize) \; \; g:fill_all() \; \; g:translate(tx \, ty) \; g:scale(sx \, sy) \; g:reset_transform() \; \; p = Path(x \, y) \; p:line_to(x \, y) \; p:quad_to(x1 \, y1 \, x2 \, y2) \; p:cubic_to(x1 \, y1 \, x2 \, y2 \, x3 \, y) \; p:close_path() \; \; g:stroke_path(p \, line_width) \; g:fill_path(p) \;, f 58;
#X text 373 818 -- Mouse down callback \, called when the mouse is clicked \; -- Mouse up callback \, called when the mouse button is released \; -- Mouse move callback \, called when the mouse is moved while not being down \; -- Mouse drag callback \, called when the mouse is moved while also being down \; \; -- Set object size \; -- Get object size \; \; -- Request a repaint \, after this the "paint" callback will occur \; -- Paint callback The argument "g" is the graphics context that you can call these drawing functions on: \; -- Sets the color for the next drawing operation. Colors are in range 0-255 \, optional alpha is in range 0-1 \; \; -- Draws a filled ellipse at the specified position and size. \; -- Draws the outline of an ellipse at the specified position and size. \; -- Draws a filled rectangle at the specified position and size. \; -- Draws the outline of a rectangle at the specified position and size. \; -- Draws a filled rounded rectangle at the specified position and size. \; -- Draws the outline of a rounded rectangle at the specified position and size. \; \; \; -- Draws a line between two points. \; -- Draws text at the specified position and size. \; \; -- Fills the entire drawing area with the current color. Also will draw an object outline in the style of the host (ie. pure-data or plugdata) \; \; -- Translates the coordinate system by the specified amounts. \; -- Scales the coordinate system by the specified factors. This will always happen after the translation \; -- Resets current scale and translation \; \; -- Initiates a new path at the specified point. \; -- Adds a line segment to the current path. \; -- Adds a quadratic Bezier curve to the current path. \; -- Adds a cubic Bezier curve to the current path. \; -- Closes the current path. \; \; -- Draws the outline of the current path with the specified line width. \; -- Fills the current path. \;, f 115;
#X restore 446 409 pd graphics;
#X text 324 384 Details on how to create GUI objects ------->, f 18;
#X obj 342 247 hello;
#X msg 55 227 load hello-gui.pd_lua;
#X connect 31 0 1 0;