Improved 'New' and 'Open' interfaces. ('Open' dialog no longer includes

Starter images; 'New' now brings up a selection dialog showing 'Starter'
images and color choices.)
New images can be given solid background colors (which the 'Eraser' tool
erases to).
Improved --usage output.
Added support for "--papersize help" to list papersizes available via libpaper.
Some Magic tools that apply an affect once per click-and-drag no longer
recalculate the effect on pixels that have already been affected (until mouse
button is released and clicked again).

docs/CHANGES.txt

@@ -10,6 +10,22 @@ $Id$
 
 
 2007.July.19 (0.9.18)
+  * Interface Improvements:
+    -----------------------
+    * Improved 'New' and 'Open' interface:
+      + 'Open' dialog no longer includes 'Starter' images
+      + 'New' now brings up a selection dialog showing 'Starter' images
+        and color choices
+      + New images can be given solid background colors
+        (which the 'Eraser' tool erases to)
+
+  * Documentation Imrpovements:
+    ---------------------------
+    * Improved --usage output.
+
+    * Added support for "--papersize help" to list papersizes available
+      via libpaper.
+
   * System-Related Improvements:
     ----------------------------
     * Added an API for developing Magic tools as plug-ins.
@@ -31,6 +47,11 @@ $Id$
       (Blur, Fill, Lighten, Darken, Mirror, Flip, Rainbow, Blocks, Chalk,
       Grass, Negative, Tint, Smudge, Drip, Cartoon, Brick (large & small))
 
+    * Some Magic tools that apply an affect once per click-and-drag no
+      longer recalculate the effect on pixels that have already been
+      affected (until mouse button is released and clicked again).
+      Improves performance, especially where heavy math is used.
+
     * Began adding support for using SDL_Pango, a wrapper to Pango,
       a library for layout and rendering of text, with an emphasis on
       internationalization.  (The hope is to improve support for languages
@@ -41,8 +62,9 @@ $Id$
       or both a TTF_Font and a SDLPango_Context, depending on whether
       SDL_Pango is being used, and how the font was loaded.
 
-      Can be disabled (will use older SDL_ttf-based code) by building with
-      "make nopango".
+      Can be disabled (will use older SDL_ttf-based code only) by building with
+      "make nopango".  Note: A modified SDL_Pango.h header file is included
+      with Tux Paint, to work around a compile issue with SDL_Pango 0.1.2's.
 
   * New Brushes
     -----------

magic/src/blocks_chalk_drip.c

@@ -120,8 +120,10 @@ void blocks_chalk_drip_linecb(void * ptr, int which,
     x = (x / 4) * 4;
     y = (y / 4) * 4;
 
-    for (yy = y - 8; yy < y + 8; yy = yy + 4)
+    if (!api->touched(x, y))
     {
+      for (yy = y - 8; yy < y + 8; yy = yy + 4)
+      {
       for (xx = x - 8; xx < x + 8; xx = xx + 4)
       {
         Uint32 pix[16];
@@ -167,6 +169,7 @@ void blocks_chalk_drip_linecb(void * ptr, int which,
 
         SDL_FillRect(canvas, &dest, SDL_MapRGB(canvas->format, r, g, b));
       }
+      }
     }
   }
   else if (which == TOOL_CHALK)

magic/src/emboss.c

@@ -73,24 +73,27 @@ void do_emboss(void * ptr, int which, SDL_Surface * canvas, SDL_Surface * last,
     {
       if (api->in_circle(xx, yy, 16))
       {
-        SDL_GetRGB(api->getpixel(last, x + xx, y + yy), last->format, &r1, &g1, &b1);
-        SDL_GetRGB(api->getpixel(last, x + xx + 2, y + yy + 2), last->format, &r2, &g2, &b2);
+        if (!api->touched(x + xx, y + yy))
+        {
+          SDL_GetRGB(api->getpixel(last, x + xx, y + yy), last->format, &r1, &g1, &b1);
+          SDL_GetRGB(api->getpixel(last, x + xx + 2, y + yy + 2), last->format, &r2, &g2, &b2);
 
-        avg1 = (r1 + g1 + b1) / 3;
-        avg2 = (r2 + g2 + b2) / 3;
+          avg1 = (r1 + g1 + b1) / 3;
+          avg2 = (r2 + g2 + b2) / 3;
 
-	api->rgbtohsv(r1, g1, b1, &h, &s, &v);
+	  api->rgbtohsv(r1, g1, b1, &h, &s, &v);
 
-        r = 128 + (((avg1 - avg2) * 3) / 2);
-        if (r < 0) r = 0;
-        if (r > 255) r = 255;
-        g = b = r;
+          r = 128 + (((avg1 - avg2) * 3) / 2);
+          if (r < 0) r = 0;
+          if (r > 255) r = 255;
+          g = b = r;
 
-	v = (r / 255.0);
+	  v = (r / 255.0);
 
-	api->hsvtorgb(h, s, v, &r1, &g1, &b1);
+	  api->hsvtorgb(h, s, v, &r1, &g1, &b1);
 
-        api->putpixel(canvas, x + xx, y + yy, SDL_MapRGB(canvas->format, r1, g1, b1));
+          api->putpixel(canvas, x + xx, y + yy, SDL_MapRGB(canvas->format, r1, g1, b1));
+        }
       }
     }
   }

magic/src/fade_darken.c

@@ -93,7 +93,8 @@ void do_fade_darken(void * ptr, int which,
   {
     for (xx = x - 16; xx < x + 16; xx++)
     {
-      if (api->in_circle(xx - x, yy - y, 16))
+      if (api->in_circle(xx - x, yy - y, 16) &&
+	  !api->touched(xx, yy))
       {
         SDL_GetRGB(api->getpixel(last, xx, yy), last->format, &r, &g, &b);
 

magic/src/glasstile.c

@@ -91,6 +91,9 @@ void do_glasstile(void * ptr, int which, SDL_Surface * canvas, SDL_Surface * las
   x = ((x / (GT_SIZE * 2)) * (GT_SIZE * 2)) + (GT_SIZE / 2);
   y = ((y / (GT_SIZE * 2)) * (GT_SIZE * 2)) + (GT_SIZE / 2);
 
+  if (api->touched(x, y))
+    return;
+
 
   /* Apply the effect: */
 

magic/src/tint.c

@@ -75,19 +75,22 @@ void do_tint(void * ptr, int which, SDL_Surface * canvas, SDL_Surface * last,
     {
       if (api->in_circle(xx - x, yy - y, 16))
       {
-        /* Get original pixel: */
+        if (!api->touched(xx, yy))
+        {
+          /* Get original pixel: */
 
-        SDL_GetRGB(api->getpixel(last, xx, yy), last->format, &r, &g, &b);
+          SDL_GetRGB(api->getpixel(last, xx, yy), last->format, &r, &g, &b);
 
-        old = api->sRGB_to_linear(r) * 0.2126 +
-          api->sRGB_to_linear(g) * 0.7152 +
-          api->sRGB_to_linear(b) * 0.0722;
+          old = api->sRGB_to_linear(r) * 0.2126 +
+            api->sRGB_to_linear(g) * 0.7152 +
+            api->sRGB_to_linear(b) * 0.0722;
 
-        api->putpixel(canvas, xx, yy,
+          api->putpixel(canvas, xx, yy,
                  SDL_MapRGB(canvas->format,
                             api->linear_to_sRGB(rd * old),
                             api->linear_to_sRGB(gd * old),
                             api->linear_to_sRGB(bd * old)));
+        }
       }
     }
   }

src/manpage/tuxpaint.1

@@ -1,5 +1,5 @@
-.\" tuxpaint.1 - 2007.07.14
-.TH TUXPAINT 1 "14 July 2007" "0.9.18" "Tux Paint"
+.\" tuxpaint.1 - 2007.07.24
+.TH TUXPAINT 1 "24 July 2007" "0.9.18" "Tux Paint"
 .SH NAME
 tuxpaint -- A drawing program for young children.
 
@@ -18,7 +18,7 @@ tuxpaint -- A drawing program for young children.
 [\-\-noprint]
 [\-\-printdelay=\fISECONDS\fP]
 [\-\-printcfg]
-[\-\-papersize=\fIPAPERSIZE\fP]
+[\-\-papersize \fIPAPERSIZE\fP | \-\-papersize help]
 [\-\-simpleshapes]
 [\-\-uppercase]
 [\-\-grab]
@@ -157,7 +157,7 @@ be loaded when \fITux Paint\fP starts up, and setting changes will be saved
 for next time.
 
 .TP 8
-.B \-\-papersize=\fIPAPERSIZE\fP
+.B \-\-papersize \fIPAPERSIZE\fP
 (Only when PostScript printing is used \- not Windows, Mac OS X or BeOS.)
 Ask \fITux Paint\fP to generate PostScript of a particular paper size.
 Valid sizes are those supported by libpaper.  See papersize(5).

src/tp_magic_api.h.in

@@ -4,6 +4,9 @@
 #include "SDL.h"
 #include "SDL_mixer.h"
 
+
+/* min() and max() variable comparisons: */
+
 #ifdef __GNUC__
 // This version has strict type checking for safety.
 // See the "unnecessary" pointer comparison. (from Linux)
@@ -22,31 +25,109 @@
 #define max(a,b) (((a) > (b)) ? (a) : (b))
 #endif
 
+
+/* clamp() returns 'value', unless it's less than 'lo' or greater than 'hi',
+   in which cases it returns 'lo' or 'hi', respectively: */
+
 #define clamp(lo,value,hi)    (min(max(value,lo),hi))
 
+
+/* Flags you can send to 'special_notify' */
+
+/* The image has been mirrored (so starter should be, too) */
+/* (as of API version 0x00000001) */
+
 #define SPECIAL_MIRROR	0x0001
+
+/* The image has been flipped (so starter should be, too) */
+/* (as of API version 0x00000001) */
 #define SPECIAL_FLIP	0x0002
 
+
 typedef struct magic_api_t {
+  /* A string containing the current version of Tux Paint (e.g., "0.9.18") */
   char * tp_version;
+
+  /* A string containing Tux Paint's data directory
+     (e.g., "/usr/local/share/tuxpaint/") */
   char * data_directory;
+
+  /* Call to have Tux Paint draw (and animate) its progress bar */
   void (*update_progress_bar)(void);
+
+  /* Call to request special events; see "SPECIAL_..." flags, above */
   void (*special_notify)(int);
+
+  /* Converts an RGB byte to a linear float */
   float (*sRGB_to_linear)(Uint8);
+
+  /* Converts a linear float to an RGB byte */
   Uint8 (*linear_to_sRGB)(float);
+
+  /* Returns whether an (x,y) location is within a circle of a particular
+     radius (centered around the origin: (0,0)); useful for creating tools
+     that have a circular 'brush' */
   int (*in_circle)(int,int,int);
+
+  /* Receives an SDL pixel value from the surface at an (x,y) location;
+     use "SDL_GetRGB()" to convert the Uint32 into a Uint8 RGB values;
+     NOTE: Use SDL_LockSurface() on the surface before doing (a batch of)
+     this call!  Use SDL_UnlockSurface() when you're done.
+     SDL_MustLockSurface() can tell you whether a surface needs to be locked. */
   Uint32 (*getpixel)(SDL_Surface *, int, int);
+
+  /* Assigns an SDL pixel value on a surface at an (x,y) location;
+     use "SDL_MapRGB()" to convert a triplet of Uint8 RGB values to a Uint32;
+     NOTE: Use SDL_LockSurface() on the surface before doing (a batch of)
+     this call!  Use SDL_UnlockSurface() when you're done.
+     SDL_MustLockSurface() can tell you whether a surface needs to be locked. */
   void (*putpixel)(SDL_Surface *, int, int, Uint32);
+
+  /* Asks Tux Paint to play a sound (one loaded via SDL_mixer library);
+     the first value is for left/right panning (0 is left, 128 is center,
+     255 is right); the second value is for total volume (0 is off, 255 is
+     loudest) */
   void (*playsound)(Mix_Chunk *, int, int);
+
+  /* Asks Tux Paint to calculate a line between (x1,y1) and (x2,y2);
+     every 'step' iterations, it will call your callback function
+     (which must accept a 'which' integer for which tool is being used,
+     'last' and current ('canvas') SDL_Surfaces, and an (x,y) position) */
   void (*line)(int, SDL_Surface *, SDL_Surface *, int, int, int, int, int, void (*)(void *, int, SDL_Surface *, SDL_Surface *, int, int));
+
+  /* Returns whether the mouse button is down */
   int (*button_down)(void);
+
+  /* Converts RGB bytes into HSV floats */
   void (*rgbtohsv)(Uint8, Uint8, Uint8, float *, float *, float *);
+
+  /* Converts HSV floats into RGB bytes */
   void (*hsvtorgb)(float, float, float, Uint8 *, Uint8 *, Uint8 *);
+
+  /* Holds Tux Paint's canvas dimensions */
   int canvas_w;
   int canvas_h;
+
+  /* Returns a new surface containing the scaled contents of an input
+     surface, scaled to, at maximum, w x h dimensions
+     (keeping aspect ratio, if requested; check the return surface's
+     'w' and 'h' elements to confirm the actual size) */
   SDL_Surface * (*scale)(SDL_Surface *, int, int, int);
+
+  /* Returns whether a particular position of the canvas has been labeled
+     as 'touched,' since the mouse was first clicked; this function ALSO
+     assigns the position as touched, until the next time the mouse is
+     clicked; useful for not applying the same effect from 'last' to 'canvas'
+     more than once per click-and-drag sequence */
+  Uint8 (*touched)(int, int);
 } magic_api;
 
+
+/* The version of the Tux Paint Magic tool API you are being compiled
+   against.  Your 'XYZ_api_version()' should return this value.
+   If Tux Paint deems you compatible, it will call your 'XYZ_init()' (etc.)
+   and you will be active. */
+
 #define TP_MAGIC_API_VERSION __APIVERSION__
 
 #endif