WIP: Emitter magic tools

Star image so far.  Lots more to do.
For https://sourceforge.net/p/tuxpaint/feature-requests/266/

docs/CHANGES.txt

@@ -7,6 +7,18 @@ Various contributors (see below, and AUTHORS.txt)
 https://tuxpaint.org/
 
 2024.December.25 (0.9.35)
+  * New Magic Tools:
+    ----------------
+    + WIP: Heart, Sparkle, and Star emitters
+      Click and drag to leave a short trail of shapes.
+      - TODO: Hearts
+      - TODO: Sparkles
+      - TODO: Icons
+      - TODO: Sound effects
+      - TODO: Documentation
+      Closes https://sourceforge.net/p/tuxpaint/feature-requests/266/
+      Bill Kendrick <bill@newbreedsoftware.com>
+
   * Text & Label Tool Improvements:
     -------------------------------
     + It is now possible to paste text from the copy/paste clipboard

magic/src/emitter.c

@@ -0,0 +1,325 @@
+/*
+  emitter.c
+
+  "Emitter" Magic Tool Plugin
+  Tux Paint - A simple drawing program for children.
+
+  Copyright (c) 2024-2024 by Bill Kendrick and others; see AUTHORS.txt
+  bill@newbreedsoftware.com
+  https://tuxpaint.org/
+
+  This program is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software
+  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+  (See COPYING.txt)
+
+  Last updated: December 25, 2024
+*/
+
+#include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
+#include "tp_magic_api.h"
+#include "SDL_image.h"
+#include "SDL_mixer.h"
+#include "SDL2_rotozoom.h"
+
+#define EMITTER_QUEUE_SIZE 32
+#define EMITTER_QUEUE_SIZE_SCALE 4
+
+#define EMITTER_DRAW_THRESHOLD 16
+
+enum {
+  EMITTER_HEARTS,
+  EMITTER_SPARKLES,
+  EMITTER_STARS,
+  NUM_EMITTERS
+};
+
+/* Names of the tools (for button labels) */
+char * emitter_names[NUM_EMITTERS] = {
+  gettext_noop("Hearts"),
+  gettext_noop("Sparkles"),
+  gettext_noop("Stars"),
+};
+
+/* For the "Draw a trail of %s ..." descriptions */
+char * emitter_descs[NUM_EMITTERS] = {
+  gettext_noop("hearts"),
+  gettext_noop("sparkles"),
+  gettext_noop("stars"),
+};
+
+/* Our globals: */
+
+static Mix_Chunk *emitter_snds[NUM_EMITTERS];
+int last_x, last_y;
+Uint8 emitter_r, emitter_g, emitter_b;
+int emitter_max_trail_length;
+int emitter_cur_trail_length;
+int emitter_queue_x[EMITTER_QUEUE_SIZE], emitter_queue_y[EMITTER_QUEUE_SIZE];
+SDL_Surface * emitter_images[NUM_EMITTERS][EMITTER_QUEUE_SIZE];
+
+/* Function prototypes: */
+
+Uint32 emitter_api_version(void);
+int emitter_init(magic_api * api, Uint8 disabled_features, Uint8 complexity_level);
+int emitter_get_tool_count(magic_api * api);
+SDL_Surface *emitter_get_icon(magic_api * api, int which);
+char *emitter_get_name(magic_api * api, int which);
+int emitter_get_group(magic_api * api, int which);
+int emitter_get_order(int which);
+char *emitter_get_description(magic_api * api, int which, int mode);
+void emitter_drag(magic_api * api, int which, SDL_Surface * canvas,
+                SDL_Surface * last, int ox, int oy, int x, int y, SDL_Rect * update_rect);
+void emitter_click(magic_api * api, int which, int mode, SDL_Surface * canvas,
+                 SDL_Surface * last, int x, int y, SDL_Rect * update_rect);
+void emitter_release(magic_api * api, int which, SDL_Surface * canvas,
+                   SDL_Surface * last, int x, int y, SDL_Rect * update_rect);
+void emitter_shutdown(magic_api * api);
+void emitter_set_color(magic_api * api, int which, SDL_Surface * canvas,
+                     SDL_Surface * last, Uint8 r, Uint8 g, Uint8 b, SDL_Rect * update_rect);
+int emitter_requires_colors(magic_api * api, int which);
+void emitter_switchin(magic_api * api, int which, int mode, SDL_Surface * canvas);
+void emitter_switchout(magic_api * api, int which, int mode, SDL_Surface * canvas);
+int emitter_modes(magic_api * api, int which);
+Uint8 emitter_accepted_sizes(magic_api * api, int which, int mode);
+Uint8 emitter_default_size(magic_api * api, int which, int mode);
+void emitter_set_size(magic_api * api, int which, int mode, SDL_Surface * canvas, SDL_Surface * last, Uint8 size,
+                    SDL_Rect * update_rect);
+
+
+Uint32 emitter_api_version(void)
+{
+  return (TP_MAGIC_API_VERSION);
+}
+
+
+// No setup required:
+int emitter_init(magic_api *api, Uint8 disabled_features ATTRIBUTE_UNUSED, Uint8 complexity_level ATTRIBUTE_UNUSED)
+{
+  int i, j;
+  char fname[1024];
+
+  for (i = 0; i < NUM_EMITTERS; i++)
+  {
+    snprintf(fname, sizeof(fname), "%ssounds/magic/emitter%d.ogg", api->data_directory, i);
+    emitter_snds[i] = Mix_LoadWAV(fname);
+  }
+
+  for (i = 0; i < NUM_EMITTERS; i++)
+  {
+    snprintf(fname, sizeof(fname), "%simages/magic/emitter%d.png", api->data_directory, 1 /* FIXME */);
+    emitter_images[i][0] = IMG_Load(fname);
+    if (emitter_images[i][0] == NULL)
+    {
+      fprintf(stderr, "Cannot load %s (%d) emitter's image: '%s'\n", emitter_names[i], i, fname);
+      return(0);
+    }
+    for (j = 1; j < EMITTER_QUEUE_SIZE; j++)
+    {
+      int w, h;
+      float w_scale, h_scale;
+
+      w = emitter_images[i][0]->w - (emitter_images[i][0]->w * j / EMITTER_QUEUE_SIZE);
+      h = emitter_images[i][0]->h - (emitter_images[i][0]->h * j / EMITTER_QUEUE_SIZE);
+      w_scale = (float) w / (float) emitter_images[i][0]->w;
+      h_scale = (float) h / (float) emitter_images[i][0]->h;
+
+      emitter_images[i][j] = zoomSurface(emitter_images[i][0], w_scale, h_scale, 1 /* smooth */);
+
+      if (emitter_images[i][j] == NULL)
+      {
+        fprintf(stderr, "Cannot scale %s (%d) emitter's image ('%s') to %d's size: %d x %d\n", emitter_names[i], i, fname, j, w, h);
+        return(0);
+      }
+    }
+  }
+
+  return (1);
+}
+
+// We have multiple tools:
+int emitter_get_tool_count(magic_api *api ATTRIBUTE_UNUSED)
+{
+  return (NUM_EMITTERS);
+}
+
+// Load our icons:
+SDL_Surface *emitter_get_icon(magic_api *api, int which ATTRIBUTE_UNUSED)
+{
+  char fname[1024];
+
+  snprintf(fname, sizeof(fname), "%simages/magic/light.png", api->data_directory); // FIXME
+
+  return (IMG_Load(fname));
+}
+
+// Return our names, localized:
+char *emitter_get_name(magic_api *api ATTRIBUTE_UNUSED, int which)
+{
+  return (strdup(gettext(emitter_names[which])));
+}
+
+int emitter_get_group(magic_api *api ATTRIBUTE_UNUSED, int which ATTRIBUTE_UNUSED)
+{
+  return MAGIC_TYPE_PAINTING;
+}
+
+int emitter_get_order(int which)
+{
+  return 2700 + which;
+}
+
+// Return our descriptions, localized:
+char *emitter_get_description(magic_api *api ATTRIBUTE_UNUSED, int which, int mode ATTRIBUTE_UNUSED)
+{
+  char desc[1024];
+
+  snprintf(desc, sizeof(desc), gettext("Click and drag to draw a trail of %s on your picture."), gettext(emitter_descs[which]));
+  return (strdup(desc));
+}
+
+void emitter_drag(magic_api *api, int which, SDL_Surface *canvas,
+                SDL_Surface *last, int ox, int oy, int x, int y, SDL_Rect *update_rect)
+{
+  int i;
+
+  SDL_BlitSurface(last, NULL, canvas, NULL);
+
+  if (abs(x - last_x) > EMITTER_DRAW_THRESHOLD || abs(y - last_y) > EMITTER_DRAW_THRESHOLD)
+  {
+    if (emitter_cur_trail_length < emitter_max_trail_length - 1)
+    {
+      emitter_cur_trail_length++;
+    }
+    else
+    {
+      for (i = 0; i < emitter_cur_trail_length; i++)
+      {
+        emitter_queue_x[i] = emitter_queue_x[i + 1];
+        emitter_queue_y[i] = emitter_queue_y[i + 1];
+      }
+    }
+
+    emitter_queue_x[emitter_cur_trail_length] = x;
+    emitter_queue_y[emitter_cur_trail_length] = y;
+
+    last_x = x;
+    last_y = y;
+  }
+
+  for (i = 0; i < emitter_cur_trail_length + 1; i++)
+  {
+    int img;
+    SDL_Rect dest;
+
+    img = (emitter_cur_trail_length - i);
+
+    img = img + (rand() % 4) - 2;
+    if (img < 0)
+      img = 0;
+    else if (img >= EMITTER_QUEUE_SIZE)
+      img = EMITTER_QUEUE_SIZE - 1;
+
+    dest.x = emitter_queue_x[i] - emitter_images[which][img]->w / 2;
+    dest.y = emitter_queue_y[i] - emitter_images[which][img]->h / 2;
+    dest.w = emitter_images[which][img]->w;
+    dest.h = emitter_images[which][img]->h;
+
+    dest.x += (rand() % 4) - 2;
+    dest.y += (rand() % 4) - 2;
+
+    SDL_BlitSurface(emitter_images[which][img], NULL, canvas, &dest);
+  }
+
+  update_rect->x = 0;
+  update_rect->y = 0;
+  update_rect->w = canvas->w;
+  update_rect->h = canvas->h;
+
+  api->playsound(emitter_snds[which], (x * 255) / canvas->w, 255);
+}
+
+void emitter_click(magic_api *api, int which, int mode ATTRIBUTE_UNUSED,
+                 SDL_Surface *canvas, SDL_Surface *last, int x, int y, SDL_Rect *update_rect)
+{
+  emitter_queue_x[0] = x;
+  emitter_queue_y[0] = y;
+  emitter_cur_trail_length = 0;
+  last_x = -100;
+  last_y = -100;
+
+  emitter_drag(api, which, canvas, last, x, y, x, y, update_rect);
+}
+
+void emitter_release(magic_api *api, int which,
+                   SDL_Surface *canvas, SDL_Surface *last ATTRIBUTE_UNUSED,
+                   int x, int y ATTRIBUTE_UNUSED, SDL_Rect *update_rect ATTRIBUTE_UNUSED)
+{
+}
+
+void emitter_shutdown(magic_api *api ATTRIBUTE_UNUSED)
+{
+  int i;
+
+  for (i = 0; i < NUM_EMITTERS; i++)
+    Mix_FreeChunk(emitter_snds[i]);
+}
+
+void emitter_set_color(magic_api *api, int which ATTRIBUTE_UNUSED, SDL_Surface *canvas ATTRIBUTE_UNUSED,
+                     SDL_Surface *last ATTRIBUTE_UNUSED, Uint8 r, Uint8 g, Uint8 b,
+                     SDL_Rect *update_rect ATTRIBUTE_UNUSED)
+{
+  emitter_r = r;
+  emitter_g = g;
+  emitter_b = b;
+}
+
+int emitter_requires_colors(magic_api *api ATTRIBUTE_UNUSED, int which ATTRIBUTE_UNUSED)
+{
+  return 1;
+}
+
+void emitter_switchin(magic_api *api ATTRIBUTE_UNUSED,
+                    int which ATTRIBUTE_UNUSED, int mode ATTRIBUTE_UNUSED, SDL_Surface *canvas ATTRIBUTE_UNUSED)
+{
+}
+
+void emitter_switchout(magic_api *api ATTRIBUTE_UNUSED,
+                     int which ATTRIBUTE_UNUSED, int mode ATTRIBUTE_UNUSED, SDL_Surface *canvas ATTRIBUTE_UNUSED)
+{
+}
+
+int emitter_modes(magic_api *api ATTRIBUTE_UNUSED, int which ATTRIBUTE_UNUSED)
+{
+  return (MODE_PAINT);
+}
+
+
+Uint8 emitter_accepted_sizes(magic_api *api ATTRIBUTE_UNUSED, int which ATTRIBUTE_UNUSED, int mode ATTRIBUTE_UNUSED)
+{
+  return EMITTER_QUEUE_SIZE / EMITTER_QUEUE_SIZE_SCALE;
+}
+
+Uint8 emitter_default_size(magic_api *api ATTRIBUTE_UNUSED, int which ATTRIBUTE_UNUSED, int mode ATTRIBUTE_UNUSED)
+{
+  return (EMITTER_QUEUE_SIZE / EMITTER_QUEUE_SIZE_SCALE) / 2;
+}
+
+void emitter_set_size(magic_api *api ATTRIBUTE_UNUSED, int which ATTRIBUTE_UNUSED, int mode ATTRIBUTE_UNUSED,
+                    SDL_Surface *canvas ATTRIBUTE_UNUSED, SDL_Surface *last ATTRIBUTE_UNUSED, Uint8 size,
+                    SDL_Rect *update_rect ATTRIBUTE_UNUSED)
+{
+  emitter_max_trail_length = size * EMITTER_QUEUE_SIZE_SCALE;
+}