WIP - Extending Magic plugin API to support complexity

For https://sourceforge.net/p/tuxpaint/feature-requests/247/

Makefile

@@ -4,7 +4,7 @@
 # Various contributors (see AUTHORS.txt)
 # https://tuxpaint.org/
 
-# June 14, 2002 - November 21, 2023
+# June 14, 2002 - December 29, 2023
 
 
 # The version number, for release:
@@ -24,7 +24,7 @@ else
   VER_DATE=$(shell date "+%Y-%m-%d")
 endif
 
-MAGIC_API_VERSION:=0x00000008
+MAGIC_API_VERSION:=0x00000009
 
 # Need to know the OS
 SYSNAME:=$(shell uname -s)

docs/CHANGES.txt

@@ -6,7 +6,7 @@ Copyright (c) 2002-2023
 Various contributors (see below, and AUTHORS.txt)
 https://tuxpaint.org/
 
-2023.December.23 (0.9.32)
+2023.December.29 (0.9.32)
   * New Magic Tools:
     ----------------
     * Vanishing point magic tools:
@@ -32,6 +32,15 @@ https://tuxpaint.org/
           (https://freesound.org/people/mudflea2/sounds/708182/)
           Creative Commons 0 by mudflea2
 
+  * Improvements to Magic tools:
+    ----------------------------
+    * WIP - Support for complexity levels in Magic tools via the plugin API.
+      (Closes https://sourceforge.net/p/tuxpaint/feature-requests/247/)
+      + WIP - Complexity/expertise level may be set via configuration.
+      + WIP - Plugins' "init()" functions are sent a new "complexity_level" argument.
+      + Note: Bumps `TP_MAGIC_API_VERSION` to 0x00000009.
+      Bill Kendrick <bill@newbreedsoftware.com>
+
   * Improvements to "Text" & "Label" tools:
     ---------------------------------------
     * The name and size of the chosen font is shown in the instructions

src/tp_magic_api.h.in

@@ -1,6 +1,8 @@
 #ifndef TP_MAGIC_API_H
 #define TP_MAGIC_API_H
 
+/* src/tp_magic_api.h.in last modified 2023-12-29 */
+
 #include "SDL.h"
 #include "SDL_mixer.h"
 #include "libintl.h"
@@ -185,9 +187,18 @@ enum {
 };
 
 /* Magic-relevant Tux Paint features (which may be reported as disabled) */
+/* (Uint8) */
 
-#define MAGIC_FEATURE_CONTROL 0x00000001
+#define MAGIC_FEATURE_CONTROL 0b00000001
-#define MAGIC_FEATURE_SIZE 0x00000002
+#define MAGIC_FEATURE_SIZE    0b00000010
+
+/* Magic complexity level requested by the user (allowing plugins to simplify) */
+
+enum {
+  MAGIC_COMPLEXITY_ADVANCED,
+  MAGIC_COMPLEXITY_BEGINNER,
+  MAGIC_COMPLEXITY_NOVICE,
+};
 
 #endif
 

src/tuxpaint.c

@@ -22,7 +22,7 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
   (See COPYING.txt)
 
-  June 14, 2002 - December 17, 2023
+  June 14, 2002 - December 29, 2023
 */
 
 #include "platform.h"
@@ -1417,8 +1417,6 @@ static int new_colors_last;
 
 static int disable_template_export;
 
-static Uint8 magic_disabled_features = 0x00000000;
-
 #ifdef NOKIA_770
 static int simple_shapes = 1;
 #else
@@ -1544,6 +1542,9 @@ extern char *GetUserImageDir(void);
 
 #include "tp_magic_api.h"
 
+static Uint8 magic_disabled_features = 0x00000000;
+static Uint8 magic_complexity_level = MAGIC_COMPLEXITY_ADVANCED;
+
 static void update_progress_bar(void);
 static void special_notify(int flags);
 
@@ -1555,13 +1556,13 @@ typedef struct magic_funcs_s
   SDL_Surface *(*get_icon)(magic_api *, int);
   char *(*get_description)(magic_api *, int, int);
   int (*requires_colors)(magic_api *, int);
-   Uint8(*accepted_sizes) (magic_api *, int, int);
+  Uint8(*accepted_sizes) (magic_api *, int, int);
-   Uint8(*default_size) (magic_api *, int, int);
+  Uint8(*default_size) (magic_api *, int, int);
   int (*modes)(magic_api *, int);
   void (*set_color)(magic_api *, int, SDL_Surface *, SDL_Surface *, Uint8, Uint8, Uint8, SDL_Rect *);
   void (*set_size)(magic_api *, int, int, SDL_Surface *, SDL_Surface *, Uint8, SDL_Rect *);
-  int (*init)(magic_api *, Uint32);
+  int (*init)(magic_api *, Uint8, Uint8);
-   Uint32(*api_version) (void);
+  Uint32(*api_version) (void);
   void (*shutdown)(magic_api *);
   void (*click)(magic_api *, int, int, SDL_Surface *, SDL_Surface *, int, int, SDL_Rect *);
   void (*drag)(magic_api *, int, SDL_Surface *, SDL_Surface *, int, int, int, int, SDL_Rect *);
@@ -21667,7 +21668,7 @@ static void load_magic_plugins(void)
               }
               else
               {
-                res = magic_funcs[num_plugin_files].init(magic_api_struct, magic_disabled_features);
+                res = magic_funcs[num_plugin_files].init(magic_api_struct, magic_disabled_features, magic_complexity_level);
 
                 if (res != 0)
                   n = magic_funcs[num_plugin_files].get_tool_count(magic_api_struct);
@@ -30061,7 +30062,7 @@ static void setup(void)
 
   /* Load magic tool plugins: */
 
-  magic_disabled_features = 0x00000000;
+  magic_disabled_features = 0b00000000;
   if (disable_magic_sizes)
   {
     magic_disabled_features |= MAGIC_FEATURE_SIZE;