pdlua graphics

doc/graphics.txt

@@ -0,0 +1,111 @@
+pdlua graphics
+===
+
+pdlua's graphics allow you to draw basic vector graphics and receive mouse events on pure-data and plugdata. Drawing functions are prefixed with 'gfx.', and should only be called from within the "paint" function
+
+You can enable GUI mode by setting the self.gui variable in the constructor, like this:
+
+function yourclass:initialize(sel, atoms)
+    self.inlets = 1
+    self.gui = 1
+    return true
+end
+
+Painting:
+--------------
+You can paint by defining the "paint" function, for example: 
+
+function yourclass:paint()
+    gfx.set_color(250, 200, 240)
+    gfx.fill_all()
+end
+
+
+Mouse Events:
+--------------
+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:
+
+function yourclass:mouse_down(x, y)
+    pd.post(tostring(x))
+    pd.post(tostring(y))
+end
+
+
+API overview
+--------------
+-- Callback functions you can define
+paint()                                                             -- Paint callback. This is the only place where you're allowed to call any of the paint functions
+pd:Class:mouse_down(x, y)                                           -- Mouse down callback, called when the mouse is clicked
+pd:Class:mouse_up(x, y)                                             -- Mouse up callback, called when the mouse button is released
+pd:Class:mouse_move(x, y)                                           -- Mouse move callback, called when the mouse is moved while not being down
+pd:Class:mouse_drag(x, y)                                           -- Mouse drag callback, called when the mouse is moved while also being down
+
+-- Functions you can call
+pd:Class:repaint()                                                  -- Request a repaint, after this the "paint" callback will occur
+
+gfx.set_size(w, h)                                                  -- Sets the size of the drawing object.
+
+gfx.set_color(r, g, b, a=1.0)                                       -- Sets the color for the next drawing operation.
+
+gfx.fill_ellipse(x, y, w, h)                                        -- Draws a filled ellipse at the specified position and size.
+gfx.stroke_ellipse(x, y, w, h, line_width)                          -- Draws the outline of an ellipse at the specified position and size.
+
+gfx.fill_rect(x, y, w, h)                                           -- Draws a filled rectangle at the specified position and size.
+gfx.stroke_rect(x, y, w, h, line_width)                             -- Draws the outline of a rectangle at the specified position and size.
+
+gfx.fill_rounded_rect(x, y, w, h, corner_radius)                    -- Draws a filled rounded rectangle at the specified position and size.
+gfx.troke_rounded_rect(x, y, w, h, corner_radius, line_width)       -- Draws the outline of a rounded rectangle at the specified position and size.
+
+gfx.draw_line(x1, y1, x2, y2)                                       -- Draws a line between two points.
+gfx.draw_text(text, x, y, w, fontsize)                              -- Draws text at the specified position and size.
+
+gfx.start_path(x, y)                                                -- Initiates a new path at the specified point.
+gfx.line_to(x, y)                                                   -- Adds a line segment to the current path.
+gfx.quad_to(x1, y1, x2, y2)                                         -- Adds a quadratic Bezier curve to the current path.
+gfx.cubic_to(x1, y1, x2, y2, x3, y)                                 -- Adds a cubic Bezier curve to the current path.
+gfx.close_path()                                                    -- Closes the current path.
+gfx.stroke_path(line_width)                                         -- Draws the outline of the current path with the specified line width.
+gfx.fill_path()                                                     -- Fills the current path.
+
+gfx.fill_all()                                                      -- 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)
+
+gfx.translate(tx, ty)                                               -- Translates the coordinate system by the specified amounts.
+gfx.scale(sx, sy)                                                   -- Scales the coordinate system by the specified factors. This will always happen after the translation
+gfx.reset_transform()                                               -- Resets current scale and translation
+
+
+Basic example
+---------------------
+
+-- Create an object named "example"
+local example = pd.Class:new():register("example")
+
+function example:initialize(sel, atoms)
+    self.inlets = 1
+    self.circle_x = 10
+    self.circle_y = 10
+
+     -- Enabled GUI mode
+    self.gui = 1
+    return true
+end
+
+-- Receive mouse drag events
+function example:mouse_drag(x, y)
+    -- Set circle position
+    self.circle_x = x - 15
+    self.circle_y = y - 15
+
+    -- Request a repaint
+    self:repaint() 
+end
+
+function example:paint()
+    -- Fill background with color
+    gfx.set_color(255, 0, 0, 1)
+    gfx.fill_all()
+
+    -- Draw an ellipse
+    gfx.set_color(0, 255, 0, 1)
+    gfx.fill_ellipse(self.circle_x, self.circle_y, 30, 30)
+end

pd.lua

@@ -20,11 +20,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 
 -- storage for Pd C<->Lua interaction
 pd._classes = { } -- take absolute paths and turn them into classes
+pd._fullpaths = { }
 pd._pathnames = { } -- look up absolute path by creation name
 pd._objects = { }
 pd._clocks = { }
 pd._receives = { }
 pd._loadpath = ""
+pd._currentpath = ""
 
 -- add a path to Lua's "require" search paths
 pd._setrequirepath = function(path)
@@ -77,6 +79,47 @@ pd._dispatcher = function (object, inlet, sel, atoms)
   end
 end
 
+pd._dsp = function (object, samplerate, blocksize)
+  local obj = pd._objects[object]
+  if nil ~= obj and type(obj.dsp) == "function" then
+    pd._objects[object]:dsp(samplerate, blocksize)
+  end
+end
+
+pd._perform_dsp = function (object, ...)
+  local obj = pd._objects[object]
+  if nil ~= obj and type(obj.perform) == "function" then
+    return pd._objects[object]:perform(...)
+  end
+end
+
+-- repaint method dispatcher
+pd._repaint = function (object)
+  local obj = pd._objects[object]
+  if nil ~= obj and type(obj.repaint) == "function" then
+    obj:repaint();
+  end
+end
+
+-- mouse event dispatcher
+pd._mouseevent = function (object, x, y, event_type)
+  if nil ~= pd._objects[object] then
+    local obj = pd._objects[object]
+    if event_type == 0 and type(obj.mouse_down) == "function" then
+      obj:mouse_down(x, y)
+    end
+    if event_type == 1 and type(obj.mouse_up) == "function" then
+      obj:mouse_up(x, y)
+    end
+    if event_type == 2 and type(obj.mouse_move) == "function" then
+      obj:mouse_move(x, y)
+    end
+    if event_type == 3 and type(obj.mouse_drag) == "function" then
+      obj:mouse_drag(x, y)
+    end
+  end
+end
+
 -- clock method dispatcher
 pd._clockdispatch = function (c)
   if nil ~= pd._clocks[c] then
@@ -92,6 +135,15 @@ pd._whoami = function (object)
   end
 end
 
+--whereami method dispatcher
+pd._whereami = function(name)
+    if nil ~= pd._fullpaths[name] then
+      return pd._fullpaths[name]
+    end
+
+    return nil
+end
+
 --class method dispatcher
 pd._get_class = function (object)
   if nil ~= pd._objects[object] then
@@ -263,10 +315,19 @@ function pd.Class:register(name)
   else
     regname = name
   end
+
+  --pd._fullpaths[regname] = pd._currentpath or (fullname .. ".pd_lua")
+  if pd._currentpath == nil or pd._currentpath == '' then
+    pd._fullpaths[regname] = fullname .. ".pd_lua"
+  else
+    pd._fullpaths[regname] = pd._currentpath
+  end
+
   pd._pathnames[regname] = fullname
   pd._classes[fullname] = self       -- record registration
   self._class = pd._register(name)  -- register new class
   self._name = name
+  self._path = pd._fullpaths[regname]
   self._loadpath = fullpath
   if name == "pdlua" then
     self._scriptname = "pd.lua"
@@ -284,6 +345,9 @@ function pd.Class:construct(sel, atoms)
   if self:initialize(sel, atoms) then
     pd._createinlets(self._object, self.inlets)
     pd._createoutlets(self._object, self.outlets)
+    if type(self.paint) == "function" then
+        pd._creategui(self._object)
+    end
     self:postinitialize()
     return self
   else
@@ -336,6 +400,25 @@ end
 
 function pd.Class:initialize(sel, atoms) end
 
+function pd.Class:repaint()
+  if type(self.paint) == "function" then
+    local g = _gfx_internal.gfx_new()
+    local can_paint = _gfx_internal.start_paint();
+    if can_paint then
+        self:paint(g);
+        _gfx_internal.end_paint();
+    end
+  end
+end
+
+function pd.Class:get_size()
+    return _gfx_internal.get_size()
+end
+
+function pd.Class:set_size(width, height)
+    return _gfx_internal.set_size(width, height)
+end
+
 function pd.Class:postinitialize() end
 
 function pd.Class:finalize() end
@@ -348,6 +431,7 @@ function pd.Class:dofilex(file)
   local pathsave = pd._loadpath
   pd._loadname = nil
   pd._loadpath = self._loadpath
+  pd._currentpath = file
   local f, path = pd._dofilex(self._class, file)
   pd._loadname = namesave
   pd._loadpath = pathsave
@@ -362,6 +446,7 @@ function pd.Class:dofile(file)
   local pathsave = pd._loadpath
   pd._loadname = nil
   pd._loadpath = self._loadpath
+  pd._currentpath = file
   local f, path = pd._dofile(self._object, file)
   pd._loadname = namesave
   pd._loadpath = pathsave
@@ -376,6 +461,10 @@ function pd.Class:whoami()
   return self._scriptname or self._name
 end
 
+function pd.Class:in_1__reload()
+  self:dofile(self._path)
+end
+
 function pd.Class:get_class() -- accessor for t_class*
   return self._class or nil
 end
@@ -392,7 +481,6 @@ function lua:in_1_load(atoms)  -- execute a script
   self:dofile(atoms[1])
 end
 
-
 local luax = pd.Class:new():register("pdluax")  -- classless lua externals (like [pdluax foo])
 
 function luax:initialize(sel, atoms)          -- motivation: pd-list 2007-09-23
@@ -421,4 +509,7 @@ function luax:initialize(sel, atoms)          -- motivation: pd-list 2007-09-23
   end
 end
 
+DATA = 0
+SIGNAL = 1
+Colors = {background = 0, foreground = 1, outline = 2}
 -- fin pd.lua

pdlua-help.pd

@@ -1,35 +1,33 @@
-#N canvas 467 36 561 528 10;
+#N canvas 466 36 564 576 10;
 #X declare -lib pdlua -path pdlua;
 #X declare -path pdlua/examples;
-#X msg 55 227 load hello.lua;
 #X text 16 358 See also:;
-#X obj 351 234 hello;
 #X obj 55 257 pdlua;
 #X obj 81 359 pdluax hello;
-#X obj 4 397 cnv 3 550 3 empty empty inlets 8 12 0 13 #dcdcdc #000000 0;
-#X obj 4 432 cnv 3 550 3 empty empty outlets 8 12 0 13 #dcdcdc #000000 0;
-#X obj 4 467 cnv 3 550 3 empty empty arguments 8 12 0 13 #dcdcdc #000000 0;
-#X obj 143 406 cnv 17 3 17 empty empty 0 5 9 0 16 #dcdcdc #9c9c9c 0;
-#X obj 4 500 cnv 15 552 21 empty empty empty 20 12 0 14 #e0e0e0 #202020 0;
-#X text 243 442 NONE;
-#X text 243 477 NONE;
-#X text 177 407 load <symbol>;
+#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 151 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 252 42 2 100 100;
+#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 302 42 1 0 0;
+#X coords 0 1 100 -1 299 39 1 0 0;
 #X restore 3 3 graph;
 #X text 390 233 <- 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 [delcare]:, f 80;
 #X text 75 114 loading [pdlua] from [declare] -->;
-#X text 261 407 - load and run a '*.lua' file;
-#X text 334 346 Details on writting lua externals ----->, f 23;
+#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 loads files as arguments), f 20;
 #X obj 290 115 declare -lib pdlua -path pdlua;
@@ -152,16 +150,16 @@
 #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;
+#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;
+#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;
+#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;
+#X coords 0 1 100 -1 451 2163 1 0 0;
 #X restore 46 82 graph;
 #X text 69 21 Find basic instructions/examples below on how to write externals in Lua. For a detailed tutorial \, check the 'pdlua/tutorial' folder for a PDF documente. 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;
@@ -175,5 +173,33 @@
 #X connect 110 0 65 0;
 #X connect 111 0 65 0;
 #X connect 112 0 67 0;
-#X restore 438 364 pd quickstart;
-#X connect 0 0 3 0;
+#X restore 446 359 pd quickstart;
+#N canvas 21 133 772 759 graphics 0;
+#X obj 8 77 hello-gui;
+#X text 8 323 You can enable GUI mode by setting the self.gui variable in the constructor \, like this:;
+#X text 8 366 function yourclass:initialize(sel \, atoms);
+#X text 25 383 self.gui = 1;
+#X text 24 415 return true;
+#X text 7 433 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 25 526 g.set_color(250 \, 200 \, 240);
+#X text 25 543 g.fill_all();
+#X text 23 400 self.set_size(100 \, 100);
+#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 8 816 pd:Class:repaint() \; \; 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:paint(g) \; \; g.set_size(w \, h) \; 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.start_path(x \, y) \; g.line_to(x \, y) \; g.quad_to(x1 \, y1 \, x2 \, y2) \; g.cubic_to(x1 \, y1 \, x2 \, y2 \, x3 \, y) \; g.close_path() \; g.stroke_path(line_width) \; g.fill_path() \; \; g.fill_all() \; \; g.translate(tx \, ty) \; g.scale(sx \, sy) \; g.reset_transform() \;, f 58;
+#X text 353 816 -- Request a repaint \, after this the "paint" callback will occur \; \; -- 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 \; \; \; \; -- Paint callback The argument "g" is the graphics context that you can call these drawing functions on: -- Sets the size of the drawing object. \; -- Sets the color for the next drawing operation. \; \; -- 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. \; \; -- 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. \; \; -- 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 \;, f 134;
+#X restore 446 409 pd graphics;
+#X text 324 384 Details on how to create GUI objects ------->, f 18;
+#X obj 342 227 hello;
+#X msg 55 227 load hello-gui.pd_lua;
+#X connect 31 0 1 0;