Further expanded plugin API documentation.

Added --pluginprefix and --dataprefix to tp-magic-config script.
Started a glossary section in API documentation.
Added Table of Contents to API documentation.
Added a manpage for tp-magic-config script.

Makefile

@@ -7,7 +7,7 @@
 # bill@newbreedsoftware.com
 # http://www.tuxpaint.org/
 
-# June 14, 2002 - July 24, 2007
+# June 14, 2002 - July 31, 2007
 
 
 # The version number, for release:
@@ -529,6 +529,7 @@ uninstall:	uninstall-i18n
 	-rm $(MAN_PREFIX)/man1/tuxpaint.1.gz
 	-rm $(MAN_PREFIX)/pl/man1/tuxpaint.1.gz
 	-rm $(MAN_PREFIX)/man1/tuxpaint-import.1.gz
+	-rm $(MAN_PREFIX)/man3/tp-magic-config.3.gz
 	-rm -f -r $(CONFDIR)
 	-rm -r $(MAGIC_PREFIX)
 	-rm -r $(INCLUDE_PREFIX)/tuxpaint
@@ -752,6 +753,8 @@ install-man:
 	@echo "...Installing man pages..."
 	@# man1 directory...
 	@install -d $(MAN_PREFIX)/man1
+	@# man3 directory...
+	@install -d $(MAN_PREFIX)/man3
 	@# tuxpaint.1
 	@cp src/manpage/tuxpaint.1 $(MAN_PREFIX)/man1
 	@gzip -f $(MAN_PREFIX)/man1/tuxpaint.1
@@ -766,6 +769,10 @@ install-man:
 	@cp src/manpage/tuxpaint-import.1 $(MAN_PREFIX)/man1/
 	@gzip -f $(MAN_PREFIX)/man1/tuxpaint-import.1
 	@chmod a+rx,g-w,o-w $(MAN_PREFIX)/man1/tuxpaint-import.1.gz
+	@# tp-magic-config.3
+	@cp src/manpage/tp-magic-config.3 $(MAN_PREFIX)/man3/
+	@gzip -f $(MAN_PREFIX)/man3/tp-magic-config.3
+	@chmod a+rx,g-w,o-w $(MAN_PREFIX)/man3/tp-magic-config.3.gz
 
 
 
@@ -930,8 +937,10 @@ tp-magic-config:	src/tp-magic-config.sh.in Makefile
 	@echo "...Generating 'Magic' tool API configuration script..."
 	@sed src/tp-magic-config.sh.in -e s/__VERSION__/$(VER_VERSION)/ \
 		-e s/__APIVERSION__/$(MAGIC_API_VERSION)/ \
-		-e s=__INCLUDE__=$(INCLUDE_PREFIX)/tuxpaint= > \
+		-e s=__INCLUDE__=$(INCLUDE_PREFIX)/tuxpaint= \
-		tp-magic-config
+		-e s=__DATAPREFIX__=$(DATA_PREFIX)= \
+		-e s=__PLUGINPREFIX__=$(MAGIC_PREFIX)= \
+		> tp-magic-config
 
 # Make the "obj" directory to throw the object(s) into:
 # (not necessary any more; bjk 2006.02.20)

docs/CHANGES.txt

@@ -45,11 +45,14 @@ $Id$
 
     * Magic plugin development can be done outside of Tux Paint base
       source-code by using new "tp-magic-config" shell script to query
-      for C compiler flags, which points to where "tp_magic_api.h" header
+      for C compiler flags (which points to where "tp_magic_api.h" header
-      file is installed.
+      file is installed) and directories Tux Paint uses (where plugin '.so'
+      files shoudl be stored, and where Tux Paint's global data files go).
 
     * Magic plugin development docs created.  On Linux/Unix, installed into
-      /usr/[local/]share/docs/tuxpaint-dev/ by default.
+      /usr/[local/]share/docs/tuxpaint-dev/ by default.  (HTML and plaintext.)
+
+    * tp-magic-config man page created.
 
     * Ported existing magic tools to the new Magic tool plug-in system:
       (Blur, Fill, Lighten, Darken, Mirror, Flip, Rainbow, Blocks, Chalk,

magic/docs/README.txt

@@ -6,7 +6,7 @@
                            bill@newbreedsoftware.com
                             http://www.tuxpaint.org/
 
-                          July 5, 2007 - July 28, 2007
+                          July 5, 2007 - July 31, 2007
 
    --------------------------------------------------------------------------
 
@@ -24,6 +24,49 @@ Overview
 
    --------------------------------------------------------------------------
 
+Table of Contents
+
+     * Prequisites
+     * Interfaces
+
+          * 'Magic' tool plugin functions
+
+               * Common arguments to plugin functions
+               * Required Plugin Functions
+
+                    * Plugin "housekeeping" functions
+                    * Plugin event functions
+
+          * Tux Paint Functions and Data
+
+               * Pixel Manipulations
+               * Helper Functions
+               * Informational
+               * Tux Paint System Calls
+               * Color Conversions
+
+          * Helper Macros in "tp_magic_api.h"
+          * Constant Definitions in "tp_magic_api.h"
+
+     * Compiling
+
+          * Linux and other Unix-like Platforms
+          * Windows
+          * Mac OS X
+
+     * Installing
+
+          * Linux and other Unix-like Platforms
+          * Windows
+          * Mac OS X
+
+     * Creating plugins with multiple effects
+     * Example Code
+     * Getting Help
+     * Glossary
+
+   --------------------------------------------------------------------------
+
 Prerequisites
 
      Tux Paint is written in the C programming language, and uses the
@@ -127,7 +170,7 @@ Interfaces
            Because it is a pointer, you access its elements via "->" (arrow)
            rather than "." (dot).
 
-    Required plugin functions:
+    Required Plugin Functions:
 
          Your plugin is required to contain, at the least, all of the
          following functions.
@@ -148,6 +191,7 @@ Interfaces
              and use it.
 
              Note: Called once by Tux Paint, at startup. It is called first.
+
            * int init(magic_api * api)
              The plugin should do any initialization here. Return '1' if
              initialization was successful, or '0' if not (and Tux Paint will
@@ -156,6 +200,7 @@ Interfaces
              Note: Called once by Tux Paint, at startup. It is called first.
              It is called after "api_version()", if Tux Paint believes your
              plugin to be compatible.
+
            * int get_tool_count(magic_api * api)
              This should return the number of Magic tools this plugin
              provides to Tux Paint.
@@ -217,8 +262,9 @@ Interfaces
              Tux Paint will call this function to inform the plugin of the
              RGB values of the currently-selected color in Tux Paint's
              'Colors' palette. (It will be called whenever one of the
-             plguin's Magic tools that accept colors becomes active, or the
+             plugin's Magic tools that accept colors becomes active, and
-             user picks a new color while such a tool is currently active.)
+             whenever the user picks a new color while such a tool is
+             currently active.)
 
            * void click(magic_api * api, int which, SDL_Surface * snapshot,
              SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect)
@@ -227,24 +273,28 @@ Interfaces
              (within the canvas) when the mouse button was clicked.
 
              The plugin should report back what part of the canvas was
-             affected, by filling in the (x,y) and (w,h) values in
+             affected, by filling in the (x,y) and (w,h) elements of
              'update_rect'.
 
              The contents of the drawing canvas immediately prior to the
              mouse button click is stored within the 'snapshot' canvas.
 
            * void drag(magic_api * api, int which, SDL_Surface * snapshot,
-             SDL_Surface * canvas, int ox, int oy, int x, int y, SDL_Rect *
+             SDL_Surface * canvas, int ox, int oy, int x, int y,
-             update_rect)
+             SDL_Rect * update_rect)
              The plugin should apply the appropriate 'Magic' tool on the
              'canvas' surface. The (ox,oy) and (x,y) coordinates are the
              location of the mouse at the beginning and end of the stroke.
+
              Typically, plugins that let the user "draw" effects onto the
-             canvas call the Tux Paint 'Magic' tool plugin "line()" helper
+             canvas utilize Tux Paint's "line()" 'Magic' tool plugin helper
-             function. (See below).
+             function to calculate the points of the line between (ox,oy) and
+             (x,y), and call another function within the plugin to apply the
+             effect at each point. (See "Tux Paint Functions and Data,"
+             below).
 
              The plugin should report back what part of the canvas was
-             affected, by filling in the (x,y) and (w,h) values in
+             affected, by filling in the (x,y) and (w,h) elements of
              'update_rect'.
 
              Note: The contents of the drawing canvas immediately prior to
@@ -259,7 +309,7 @@ Interfaces
              (within the canvas) when the mouse button was released.
 
              The plugin should report back what part of the canvas was
-             affected, by filling in the (x,y) and (w,h) values in
+             affected, by filling in the (x,y) and (w,h) elements of
              'update_rect'.
 
              Note: The contents of the drawing canvas immediately prior to
@@ -271,14 +321,14 @@ Interfaces
 
        Tux Paint provides a number of helper functions that plugins may
        access via the "magic_api" structure, sent to all of the plugin's
-       functions (see above).
+       functions. (See "Required Plugin Functions," above.)
 
     Pixel Manipulations
 
-           * Uint32 getpixel(SDL_Surface * surf, int x, int y) Retreives the
+           * Uint32 getpixel(SDL_Surface * surf, int x, int y)
-             pixel value from the (x,y) coordinates of an SDL_Surface. (You
+             Retreives the pixel value from the (x,y) coordinates of an
-             can use SDL's "SDL_GetRGB()" function to convert the Uint32
+             SDL_Surface. (You can use SDL's "SDL_GetRGB()" function to
-             'pixel' to a set of Uint8 RGB values.)
+             convert the Uint32 'pixel' to a set of Uint8 RGB values.)
 
            * void putpixel(SDL_Surface * surf, int x, int y, Uint32 pixel)
              Sets the pixel value at position (x,y) of an SDL_Surface. (You
@@ -286,6 +336,18 @@ Interfaces
              RGB values to a Uint32 'pixel' value appropriate to the
              destination surface.)
 
+           * SDL_Surface * scale(SDL_Surface * surf, int w, int h,
+             int keep_aspect)
+             This accepts an existing SDL surface and creates a new one
+             scaled to an arbitrary size. (The original surface remains
+             untouched.)
+
+             The "keep_aspect" flag can be set to '1' to force the new
+             surface to stay the same shape (aspect ratio) as the original,
+             meaning it may not be the same width and height you requested.
+             (Check the "->w" and "->h" elements of the output
+             "SDL_Surface *" to determine the actual size.)
+
     Helper Functions
 
            * int in_circle(int x, int y, int radius)
@@ -294,9 +356,9 @@ Interfaces
              '0' otherwise. Useful to create 'Magic' tools that affect the
              canvas with a circular brush shape.
 
-           * void line(int which, SDL_Surface * canvas, SDL_Surface *
+           * void line(int which, SDL_Surface * canvas,
-             snapshot, int x1, int y1, int x2, int y2, int step, FUNC
+             SDL_Surface * snapshot, int x1, int y1, int x2, int y2,
-             callback)
+             int step, FUNC callback)
              This function calculates all points on a line between the
              coordinates (x1,y1) and (x2,y2). Every 'step' iterations, it
              calls the 'callback' function.
@@ -312,6 +374,29 @@ Interfaces
                void exampleCallBack(void * ptr_to_api, int which_tool,
                SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y);
 
+           * Uint8 touched(int x, int y)
+             This function allows you to avoid re-processing the same pixels
+             multiple times when the user drags the mouse across an area of
+             the canvas, thus increasing Tux Paint's response time,
+             especially with math-heavy effects.
+
+             If your effect's "click()", "drag()" and/or "release()"
+             functions take the contents of the source surface ("snapshot")
+             and always create the same results in the desintation surface
+             ("canvas"), you should wrap the effect in a call to
+             "api->touched()".
+
+             This function simply returns whether or not it had already been
+             called for the same (x,y) coordinates, since the user first
+             clicked the mouse. In other words, the first time you call it
+             for a particular (x,y) coordinate, it returns '0'. Future calls
+             will return '1' until the user releases the mouse button.
+
+             Note: Magic effects that continuously affect the destination
+             surface ("canvas") (ignoring the "snapshot surface) have no
+             reason to use this function. The "Blur" and "Smudge" tools that
+             ship with Tux Paint are examples of such effects.
+
     Informational
 
            * char * tp_version
@@ -325,6 +410,20 @@ Interfaces
            * int button_down(void)
              A '1' is returned if the mouse button is down; '0' otherwise.
 
+           * char * data_directory
+             This string contains the directory where Tux Paint's data files
+             are stored. For example, on Linux, this may be
+             "/usr/share/tuxpaint/".
+
+             Magic tools should include an icon (see "get_icon()", above) and
+             are encouraged to include sound effects, it's useful for plugins
+             to know where such things are located.
+
+             When compiling and installing a plugin, the "tp-magic-config"
+             command-line tool should be used to determine where such data
+             should be placed for the installed version of Tux Paint to find
+             them. (See "Installing," below.)
+
     Tux Paint System Calls
 
            * void show_progress_bar(void)
@@ -345,16 +444,17 @@ Interfaces
 
              The 'dist' value affects overall volume. 255 is loudest, and 0
              is silent.
+
              The 'pan' and 'dist' values can be used to simulate location and
              distance of the 'Magic' tool effect.
 
            * void special_notify(int flag)
              This function notifies Tux Paint of special events. Various
-             values defined in "tp_magic_api.h" can be logically 'or'ed ("|")
+             values defined in "tp_magic_api.h" can be 'or'ed together (using
-             together and sent to this function.
+             C's boolean 'or': "|") and sent to this function.
 
-                * SPECIAL_FLIP -- The contents of the canvas has been
+                * SPECIAL_FLIP -- The contents of the canvas has been flipped
-                  flipped.
+                  vertically.
 
                   If a 'Starter' image was used as the basis of this image,
                   it should be flipped too, and a record of the flip should
@@ -362,8 +462,9 @@ Interfaces
                   Additionally, the fact that the starter has been flipped
                   (or unflipped) should be recorded on disk when the current
                   drawing is saved.
+
                 * SPECIAL_MIRROR -- Similar to SPECIAL_FLIP, but for magic
-                  tools that mirror the contents of the canvas.
+                  tools that mirror the contents of the canvas horizontally.
 
     Color Conversions
 
@@ -418,6 +519,30 @@ Interfaces
            Note: This macro is simply a #define of:
            "(min(max(value,lo),hi))".
 
+  Constant Defintions in "tp_magic_api.h":
+
+       The following is a summary of constant values that are set
+       (via "#define") within the 'Magic' tool API header file.
+
+         * TP_MAGIC_API_VERSION
+           This integer value represents which version of the Tux Paint
+           'Magic' tool API the header corresponds to.
+
+           It should be referenced by your magic tool's "api_version()"
+           function, to inform the running copy of Tux Paint whether or not
+           your plugin is compatible.
+
+           Note: This version number does not correspond to Tux Paint's own
+           release number (e.g., "0.9.18"). The API will not change every
+           time a new version of Tux Paint is released, which means plugins
+           compiled for earlier versions of Tux Paint will often run under
+           newer versions.
+
+         * SPECIAL_MIRROR
+           SPECIAL_FLIP
+           These are flags for Tux Paint's "special_notify()" helper
+           function. They are described above.
+
    --------------------------------------------------------------------------
 
 Compiling
@@ -435,7 +560,7 @@ Compiling
        As a stand-alone command, using the GNU C Compiler and BASH shell, for
        example:
 
-         gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so
+         $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so
 
        Note: The characters around the "tp-magic-config" command are a
        grave/backtick/backquote ("`"), and not an apostrophe/single-quote
@@ -445,17 +570,86 @@ Compiling
 
        A snippet from a more generalized Makefile might look like this:
 
-         CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
+         +----------------------------------------------------+
+         | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) |
+         |                                                    |
+         | my_plugin.so: my_plugin.c                          |
+         |    $(CC) -shared $(CFLAGS) -o $@ $<                |
+         +----------------------------------------------------+
 
-         my_plugin.so: my_plugin.c    $(CC) -shared $(CFLAGS) -o $@ $<
+  Windows
 
-       You may then install it globally into: /usr/lib/tuxpaint/plugins/ or
+       TBD
-       /usr/local/lib/tuxpaint/plugins/ (depending on how Tux Paint was
-       installed).
 
-       Or install it locally (for the current user only) into:
+  Mac OS X
-       ~/.tuxpaint/magic/
+
-       (FIXME: As of 2007-07-27, Tux Paint does not look here yet!)
+       TBD
+
+   --------------------------------------------------------------------------
+
+Installing
+
+  Linux and other Unix-like Platforms
+
+       Use the "tp-magic-config --pluginprefix" command, supplied as part of
+       Tux Paint, to determine where the plugin shared object (".so") files
+       should be installed. The value returned by this command will be the
+       global location where the installed version of Tux Paint looks for
+       plugins (e.g., "").
+
+       As stand-alone commands, using the BASH shell, for example:
+
+         # cp my_plugin.so `tp-magic-config --pluginprefix`
+         # chmod 644 `tp-magic-config --pluginprefix`/my_plugin.so
+
+       Additionally, use the "tp-magic-config --dataprefix" command, supplied
+       as part of Tux Paint, to determine where data files (PNG icon,
+       Ogg Vorbis sound effects, etc.) should be installed. The value
+       returned by this command will be the same as the value of the
+       "data_directory" string stored within the "magic_api" structure that
+       your plugin's functions receive.
+
+       Note: Tux Paint's default Magic tool plugins install their data within
+       "magic" subdirectories of Tux Paint's "images" and "sounds" data
+       directories (e.g., "/usr/share/tuxpaint/images/magic/"). You are
+       encouraged to do the same.
+
+       As stand-alone commands, using the BASH shell, for example:
+
+         # cp my_plugin_icon.png `tp-magic-config --dataprefix`/images/magic/
+         # chmod 644 `tp-magic-config
+         --dataprefix`/images/magic/my_plugin_icon.png
+
+    Putting it Together in a Makefile
+
+         A snippet from a more generalized Makefile might look like this:
+
+           +------------------------------------------------------+
+           | PLUGINPREFIX=$(shell tp-magic-config --pluginprefix) |
+           | DATAPREFIX=$(shell tp-magic-config --dataprefix)     |
+           |                                                      |
+           | install:                                             |
+           |    mkdir -p $(PLUGINPREFIX)                          |
+           |    cp *.so $(PLUGINPREFIX)/                          |
+           |    chmod 644 $(PLUGINPREFIX)/*.so                    |
+           |    mkdir -p $(DATAPREFIX)/images/magic               |
+           |    cp *.png $(DATAPREFIX)/images/magic/              |
+           |    chmod 644 $(DATAPREFIX)/images/magic/*.png        |
+           +------------------------------------------------------+
+
+         The first two lines set up Makefile variables that contain the paths
+         returned by the "tp-magic-config" command-line tool.
+
+         Below that is an "install" target in the Makefile. (Invoked by, for
+         example, "$ sudo make install" or "# make install".)
+
+         The "install" target uses "mkdir -p" to make sure that the plugin
+         directory exists, then uses "cp" to copy all plugin (".so") files
+         into it, and invokes "chmod" to make sure they are readable.
+
+         It then does a similar series of commands to install icon files
+         (".png" images) into a subdirectory within Tux Paint's data
+         directory.
 
   Windows
 
@@ -469,14 +663,230 @@ Compiling
 
 Creating plugins with multiple effects
 
-     TBD
+     Plugins for Tux Paint may contain more than one effect. If you have
+     multiple effects that are similar, it may make sense to place them in
+     one plugin file, to reduce overhead and share code.
+
+     These following suggestions can help you create plugins that contain
+     multiple effects:
+
+       * Use a C "enum" to enumerate the effects, and count them.
+
+           enum {
+             ONE_TOOL,
+             ANOTHER_TOOL,
+             AND_YET_ANOTHER_TOOL,
+             NUM_TOOLS };
+
+       * Return the value of "NUM_TOOLS" when "get_tool_count()" is called,
+         and compare "which" values sent to other functions with the other
+         enumerated values.
+
+       * Create arrays of "NUM_TOOLS" length to contain effect-specific data.
+
+           char * my_plugin_snd_filenames[NUM_TOOLS] = {
+             "one.ogg", "another.ogg", "yet_another.ogg" };
+           Mix_Chunk * my_plugin_snds[NUM_TOOLS];
+
+       * Use a C "for"-loop to load or create the effect-specific data (such
+         as loading sound effects during your "init()").
+
+           int i;
+           char fname[1024];
+
+           for (i = 0; i < NUM_TOOLS; i++)
+           {
+             snprintf(fname, sizeof(fname), "%s/%s",
+                 api->data_prefix, my_plugin_snd_filenames[i];
+
+             my_plugin_snds[i] = Mix_LoadWAV(fname);
+           }
+
+       * Similarly, do the same to free them later (such as freeing sound
+         effects during your "shutdown()").
+
+       * Use "which" values sent to your functions as an index into those
+         arrays (e.g., for playing the appropriate sound effect for a tool).
+
+     Note: Even if your plugin currently contains only one effect, it may be
+     useful to follow the steps above so that you can add a new variation of
+     an effect with little effort. ("NUM_TOOLS" will simply be '1', your
+     arrays will be of length '1', etc.)
 
    --------------------------------------------------------------------------
 
 Example Code
 
-     TBD
+     The C source file "tp_magic_example.c" contains a complete example of a
+     plugin with multiple simple effects.
 
    --------------------------------------------------------------------------
 
-   Summary and contact info TBD.
+Getting Help
+
+     For more information, check the Tux Paint website:
+     http://www.tuxpaint.org/, and the Simple DirectMedia Layer library
+     website: http://www.libsdl.org/.
+
+     Additionally, other Tux Paint developers and users can be found on the
+     "tuxpaint-devel" and "tuxpaint-users" mailing lists:
+     http://www.tuxpaint.org/lists/.
+
+   --------------------------------------------------------------------------
+
+Glossary
+
+     * alpha: See "RGBA"
+     * &: See "ampersand"
+     * ampersand: "&". A symbol in C that allows you to refer to the memory
+       address of a variable; that is, a pointer. (For example, consider
+       "int i;". Later, "&i" refers to the memory where "i" is stored, not
+       the value of "i" itself; it is a 'pointer to "i"'.)
+     * API: Application Programming Interface. TBD
+     * argument: TBD
+     * arrow: "->". A symbol in C that references an element within a pointer
+       to a struct.
+     * backquote: See "grave."
+     * backtick: See "grave."
+     * blue: See "RGBA"
+     * boolean 'or': TBD
+     * |: See "boolean 'or'"
+     * .: See "dot"
+     * `: See "grave."
+     * *: See "star"
+     * byte: TBD
+     * callback: TBD
+     * C enumeration: TBD
+     * C function: TBD
+     * C header file: TBD
+     * channel: TBD
+     * click: The action of pressing a button on a mouse.
+     * coordinates: TBD
+     * C pointer: A variable that contains the location of a piece of memory;
+       usually used to 'point' to another variable. Since C functions can
+       only return one value as a result, pointers are often sent to
+       functions to allow the function to change the values of multiple
+       variables. (For example, Tux Paint's "rgbtohsv()" and "hsvtorgb()".)
+     * C structure: TBD
+     * #define: A C statement that defines a substitution that can occur
+       later in the code. Generally used for constant values (e.g.,
+       "#define RADIUS 16"; all instances of "RADIUS" will be replaced with
+       "16"), but can also be used to create macros. Typically placed within
+       C header files.
+     * dimensions: TBD
+     * .dll: See "Shared Object"
+     * dot: ".". A symbol in C that references an element within a struct.
+     * drag: The action of moving a mouse while the button remains held.
+     * element: A variable stored within a C structure. (Example: "w" and "h"
+       elements of SDL_Surface store the surface's width and height,
+       respectively.)
+     * enum: See "C enumeration"
+     * float: See "floating point"
+     * floating point: TBD
+     * format: TBD
+     * free(): A C function that frees (deallocates) memory allocated by
+       other C functions (such as "strdup()").
+     * function: See "C function"
+     * grave: The "`" character; used by the BASH shell to use the output of
+       a command as the command-line arguments to another.
+     * green: See "RGBA"
+     * ->: See "arrow"
+     * .h: See "C header file"
+     * header: See "C header file"
+     * header file: See "C header file"
+     * HSV: TBD
+     * hue: See "HSV"
+     * IMG_Load(): An SDL_image function that loads an image file (e.g., a
+       PNG) and returns it as an "SDL_Surface *".
+     * #include: A C statement that asks the compiler to read the contents of
+       another file (usually a header file).
+     * int: See "integer"
+     * integer: TBD
+     * libSDL: See "Simple DirectMedia Layer"
+     * linear: TBD
+     * macro: TBD
+     * magic_api: A C structure that is passed along to a plugin's functions
+       that exposes data and functions within the running copy of Tux Paint.
+     * Magic tool: One of a number of effects or drawing tools in Tux Paint,
+       made available via the "Magic" tool button.
+     * Mix_Chunk *: (A pointer to) a C structure defined by SDL_mixer that
+       contains a sound.
+     * Mix_FreeChunk(): An SDL_mixer function that frees (deallocates) memory
+       allocated for an SDL_mixer sound 'chunk' ("Mix_Chunk *").
+     * Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV,
+       Ogg Vorbis, etc.) and returns it as a "Mix_Chunk *".
+     * namespace: TBD
+     * Ogg Vorbis: TBD
+     * Plugin: TBD
+     * PNG: TBD
+     * pointer: See "C pointer"
+     * red: See "RGBA"
+     * release: The action of releasing a button on a mouse.
+     * RGBA: "Red, Green, Blue, Alpha." TBD
+     * RGB: See "RBGA"
+     * saturation: See "HSV"
+     * SDL: See "Simple DirectMedia Layer"
+     * SDL_FreeSurface(): An libSDL function that frees (deallocates) memory
+       allocated for an SDL surface ("SDL_Surface *").
+     * SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value
+       (e.g., one returned from the Tux Paint's Magic tool API helper
+       function "getpixel()"), the format of the surface the pixel was taken
+       from, and pointers to three Uint8 variables, will place the Red, Green
+       and Blue (RGB) values of the pixel into the three Uint8 variables.
+       (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g,
+       &b);".)
+     * SDL_MapRGB(): A libSDL function that, given the format of a surface
+       and Uint8 values representing Red, Green and Blue values for a pixel,
+       returns a Uint32 pixel value that can be placed in the surface (e.g.,
+       using Tux Paint's Magic tool API helper function "putpixel()").
+       (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".)
+     * SDL_image: A library on top of libSDL that can load various kinds of
+       image files (e.g., PNG) and return them as an "SDL_Surface *".
+     * SDL_mixer: A library on top of libSDL that can load various kinds of
+       sound files (WAV, Ogg Vorbis, etc.) and play back multiple sounds at
+       once (mix them).
+     * SDL_Rect: A C structure defined by libSDL that represents a
+       rectangular area. It contains elements representing the coordinates of
+       the top left corner of the rectange (x,y) and the dimensions of the
+       rectangle (w,h).
+     * SDL_Surface *: (A pointer to) a C structure defined by libSDL that
+       contains a drawing surface.
+     * Shared Object: A piece of code that's compiled separately from the
+       main application, and loaded dynamically, at runtime.
+     * Simple DirectMedia Layer: A programming library that allows programs
+       portable low level access to a video framebuffer, audio output, mouse,
+       and keyboard.
+     * snprintf(): TBD
+     * .so: See "Shared Object"
+     * sRBG: See "RGBA"
+     * star: "*". A symbol in C that, when used in the declaration of
+       variables (e.g., arguments to a function), denotes that the variable
+       is a pointer. (For example, "int * p;" means that "p" is a pointer to
+       an integer.) When used next to a pointer, it 'dereferences' the
+       variable. (For example, later "*p = 50;" assigns the value of 50 to
+       the memory that "p" points to; it does not change the value of "p",
+       which is still a pointer to an integer. In essence, it changed the
+       integer that's being pointed to.)
+     * strdup(): A C function that allocates enough memory to store a copy of
+       a string, copies the string to it, and returns a "char *" pointer to
+       the new copy.
+     * struct: See "C structure"
+     * The GIMP: An Open Source image manipulation and paint program.
+     * tp_magic_api.h: A header file that defines Tux Paint's Magic tool API.
+       Plugins must '#include' it.
+     * tp-magic-config: A command-line program that provides information
+       about the installed version of Tux Paint to plugin developers (such as
+       what C compiler flags they should compile with, and where plugin
+       shared objects and data files should be installed).
+     * Uint32: A 32-bit, unsigned integer (defined by libSDL). In other
+       words, four bytes that can represent 0 through 4294967295. (Typically
+       used to hold enough information to store three or four bytes
+       representing a pixel's color; i.e., RBGA value).
+     * Uint8: An 8-bit, unsigned integer (defined by libSDL). In other words,
+       a byte that can represent 0 through 255.
+     * unsigned: TBD
+     * value: See "HSV"
+     * variable: TBD
+     * WAV: TBD
+     * (w,h): See "Dimensions"
+     * (x,y): See "Coordinates"

magic/docs/html/README.html

@@ -15,7 +15,7 @@ New Breed Software</p>
 <p><a href="mailto:bill@newbreedsoftware.com">bill@newbreedsoftware.com</a><br>
 <a href="http://www.tuxpaint.org/">http://www.tuxpaint.org/</a></p>
 
-<p>July 5, 2007 - July 28, 2007</p>
+<p>July 5, 2007 - July 31, 2007</p>
 </center>
 
 <hr size=2 noshade>
@@ -38,7 +38,54 @@ concept.)</p>
 
 <hr size=1 noshade>
 
-<h2>Prerequisites</h2>
+<h2>Table of Contents</h2>
+
+<ul>
+<li><a href="prereq">Prequisites</a>
+<li><a href="interfaces">Interfaces</a>
+  <ul>
+  <li><a href="#">'Magic' tool plugin functions</a>
+    <ul>
+    <li><a href="#">Common arguments to plugin functions</a>
+    <li><a href="#">Required Plugin Functions</a>
+      <ul>
+      <li><a href="#">Plugin "housekeeping" functions</a>
+      <li><a href="#">Plugin event functions</a>
+      </ul>
+    </ul>
+  <li><a href="#tpfuncs">Tux Paint Functions and Data</a>
+    <ul>
+    <li><a href="#">Pixel Manipulations</a>
+    <li><a href="#">Helper Functions</a>
+    <li><a href="#">Informational</a>
+    <li><a href="#">Tux Paint System Calls</a>
+    <li><a href="#">Color Conversions</a>
+    </ul>
+  <li><a href="#">Helper Macros in "tp_magic_api.h"</a>
+  <li><a href="#">Constant Definitions in "tp_magic_api.h"</a>
+  </ul>
+<li><a href="#compiling">Compiling</a>
+  <ul>
+  <li><a href="#">Linux and other Unix-like Platforms</a>
+  <li><a href="#">Windows</a>
+  <li><a href="#">Mac OS X</a>
+  </ul>
+<li><a href="#installing">Installing</a>
+  <ul>
+  <li><a href="#">Linux and other Unix-like Platforms</a>
+  <li><a href="#">Windows</a>
+  <li><a href="#">Mac OS X</a>
+  </ul>
+<li><a href="#multiple">Creating plugins with multiple effects</a>
+<li><a href="#">Example Code</a>
+<li><a href="#">Getting Help</a>
+<li><a href="#">Glossary</a>
+</ul>
+
+
+<hr size=1 noshade>
+
+<h2><a name="prereq">Prerequisites</a></h2>
 
 <blockquote>
 
@@ -161,7 +208,7 @@ will need to accept.
   "<code>-&gt;</code>" (arrow) rather than "<code>.</code>" (dot).
 </ul>
 
-<h4>Required plugin functions:</h4>
+<h4><a name="toolfuncs">Required Plugin Functions:</a></h4>
 
 <blockquote>
 
@@ -187,8 +234,9 @@ then the names of your functions must begin with "<code><b>zoom_</b></code>"
   <br>
   <b>Note:</b> Called once by Tux&nbsp;Paint, at startup. It is called
   first.<br>
+  <br>
 
-<li><code><b>int init(magic_api * api)</b></code><br>
+<li><code><b>int init(magic_api&nbsp;*&nbsp;api)</b></code><br>
   The plugin should do any initialization here.
   Return '1' if initialization was successful,
   or '0' if not (and Tux&nbsp;Paint will not present any 'Magic' tools
@@ -197,8 +245,9 @@ then the names of your functions must begin with "<code><b>zoom_</b></code>"
   <b>Note:</b> Called once by Tux&nbsp;Paint, at startup. It is called
   first.  It is called after "<code>api_version()</code>", if
   Tux&nbsp;Paint believes your plugin to be compatible.<br>
+  <br>
 
-<li><code><b>int get_tool_count(magic_api * api)</b></code><br>
+<li><code><b>int get_tool_count(magic_api&nbsp;*&nbsp;api)</b></code><br>
   This should return the number of Magic tools this plugin provides to
   Tux Paint.<br>
   <br>
@@ -206,7 +255,8 @@ then the names of your functions must begin with "<code><b>zoom_</b></code>"
   after your "<code>init()</code>", if it succeeded.<br>
   <br>
 
-<li><code><b>char * get_name(magic_api * api, int which)</b></code><br>
+<li><code><b>char * get_name(magic_api&nbsp;*&nbsp;api,
+  int&nbsp;which)</b></code><br>
   This should return a string containing the name of a magic tool.
   This will appear on the button in the 'Magic' selector within
   Tux&nbsp;Paint.<br>
@@ -218,7 +268,8 @@ then the names of your functions must begin with "<code><b>zoom_</b></code>"
   contain (by your "<code>get_tool_count()</code>").<br>
   <br>
 
-<li><code><b>SDL_Surface * get_icon(magic_api * api, int which)</b></code><br>
+<li><code><b>SDL_Surface * get_icon(magic_api&nbsp;*&nbsp;api,
+  int&nbsp;which)</b></code><br>
   This should return an SDL_Surface containing the icon representing
   the tool.  (A greyscale image with alpha, no larger than 40x40.)
   This will appear on the button in the 'Magic' selector within
@@ -231,7 +282,8 @@ then the names of your functions must begin with "<code><b>zoom_</b></code>"
   contain (by your "<code>get_tool_count()</code>").<br>
   <br>
 
-<li><code><b>char * get_description(magic_api * api, int which)</b></code><br>
+<li><code><b>char * get_description(magic_api&nbsp;*&nbsp;api,
+  int&nbsp;which)</b></code><br>
   This should return a string containing the description of a magic tool.
   This will appear as a help tip, explained by Tux the Penguin, within
   Tux&nbsp;Paint.<br>
@@ -243,7 +295,8 @@ then the names of your functions must begin with "<code><b>zoom_</b></code>"
   contain (by your "<code>get_tool_count()</code>").<br>
   <br>
 
-<li><code><b>int requires_colors(magic_api * api, int which)</b></code><br>
+<li><code><b>int requires_colors(magic_api&nbsp;*&nbsp;api,
+  int&nbsp;which)</b></code><br>
   Return a '1' if the 'Magic' tool accepts colors (the 'Colors' palette in
   Tux&nbsp;Paint will be available), or '0' if not.<br>
   <br>
@@ -251,7 +304,7 @@ then the names of your functions must begin with "<code><b>zoom_</b></code>"
   contain (by your "<code>get_tool_count()</code>").<br>
   <br>
 
-<li><code><b>void shutdown(magic_api * api)</b></code><br>
+<li><code><b>void shutdown(magic_api&nbsp;*&nbsp;api)</b></code><br>
   The plugin should do any cleanup here.  If you allocated any memory
   or used SDL_Mixer to load any sounds during <code>init()</code>,
   for example, you should <code>free()</code> the allocated memory
@@ -265,55 +318,66 @@ then the names of your functions must begin with "<code><b>zoom_</b></code>"
 <h5>Plugin event functions:</h5>
 
 <ul>
-<li><code><b>void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g)
+<li><code><b>void set_color(magic_api&nbsp;*&nbsp;api,
+  Uint8&nbsp;r, Uint8&nbsp;g, Uint8&nbsp;g)
   </b></code><br>
   Tux&nbsp;Paint will call this function to inform the plugin of the
   RGB values of the currently-selected color in Tux&nbsp;Paint's
-  'Colors' palette.  (It will be called whenever one of the plguin's
+  'Colors' palette.  (It will be called whenever one of the plugin's
-  Magic tools that accept colors becomes active, or the user picks a new
+  Magic tools that accept colors becomes active, and whenever the user
-  color while such a tool is currently active.)<br>
+  picks a new color while such a tool is currently active.)<br>
   <br>
 
-<li><code><b>void click(magic_api * api, int which, SDL_Surface * snapshot,
+<li><code><b>void click(magic_api&nbsp;*&nbsp;api, int&nbsp;which,
-    SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect)
+  SDL_Surface&nbsp;*&nbsp;snapshot, SDL_Surface&nbsp;*&nbsp;canvas,
+  int&nbsp;x, int&nbsp;y, SDL_Rect&nbsp;*&nbsp;update_rect)
   </b></code><br>
-  The plugin should apply the appropriate 'Magic' tool on the 'canvas'
+  The plugin should apply the appropriate 'Magic' tool on the
-  surface.  The (x,y) coordinates are where the mouse was (within the canvas)
+  '<code>canvas</code>' surface.  The (x,y) coordinates are where the
-  when the mouse button was clicked.<br>
+  mouse was (within the canvas) when the mouse button was clicked.<br>
   <br>
   The plugin should report back what part of the canvas was affected, by
-  filling in the (x,y) and (w,h) values in 'update_rect'.<br>
+  filling in the (x,y) and (w,h) elements of '<code>update_rect</code>'.<br>
   <br>
   The contents of the drawing canvas immediately prior to the mouse button
-  click is stored within the 'snapshot' canvas.<br>
+  click is stored within the '<code>snapshot</code>' canvas.<br>
   <br>
 
-<li><code><b>void drag(magic_api * api, int which, SDL_Surface * snapshot,
+<li><code><b>void drag(magic_api&nbsp;*&nbsp;api, int&nbsp;which,
-    SDL_Surface * canvas, int ox, int oy, int x, int y,
+  SDL_Surface&nbsp;*&nbsp;snapshot, SDL_Surface&nbsp;*&nbsp;canvas,
-    SDL_Rect * update_rect)</b></code><br>
+  int&nbsp;ox, int&nbsp;oy, int&nbsp;x, int&nbsp;y,
-  The plugin should apply the appropriate 'Magic' tool on the 'canvas'
+  SDL_Rect&nbsp;*&nbsp;update_rect)</b></code><br>
+  The plugin should apply the appropriate 'Magic' tool on the
+  '<code>canvas</code>'
   surface.  The (ox,oy) and (x,y) coordinates are the location of the mouse
-  at the beginning and end of the stroke.  Typically, plugins that let the
+  at the beginning and end of the stroke.<br>
-  user "draw" effects onto the canvas call the Tux&nbsp;Paint 'Magic' tool
+  <br>
-  plugin "<code>line()</code>" helper function. (See below).<br>
+  Typically, plugins that let the user "draw" effects onto the canvas
+  utilize Tux&nbsp;Paint's "<code>line()</code>" 'Magic' tool plugin
+  helper function to calculate the points of the line between (ox,oy)
+  and (x,y), and call another function within the plugin to apply the effect
+  at each point.
+  (See "<a href="#tpfuncs">Tux&nbsp;Paint Functions and Data</a>," below).<br>
   <br>
   The plugin should report back what part of the canvas was affected, by
-  filling in the (x,y) and (w,h) values in 'update_rect'.<br>
+  filling in the (x,y) and (w,h) elements of '<code>update_rect</code>'.<br>
   <br>
   Note: The contents of the drawing canvas immediately prior to the mouse
   button click remains as it was (when the plugin's "<code>click()</code>"
-  function was called), and is still available in the 'snapshot' canvas.<br>
+  function was called), and is still available in the '<code>snapshot</code>'
+  canvas.<br>
   <br>
 
-<li><code><b>void release(magic_api * api, int which, SDL_Surface * snapshot,
+<li><code><b>void release(magic_api&nbsp;*&nbsp;api, int&nbsp;which,
-    SDL_Surface * canvas, int x, int y,
+  SDL_Surface&nbsp;*&nbsp;snapshot, SDL_Surface&nbsp;*&nbsp;canvas,
-    SDL_Rect * update_rect)</b></code><br>
+  int&nbsp;x, int&nbsp;y, SDL_Rect&nbsp;*&nbsp;update_rect)</b></code><br>
-  The plugin should apply the appropriate 'Magic' tool on the 'canvas'
+  The plugin should apply the appropriate 'Magic' tool on the
+  '<code>canvas</code>'
   surface.  The (x,y) coordinates are where the mouse was (within the canvas)
   when the mouse button was released.<br>
   <br>
   The plugin should report back what part of the canvas was affected, by
-  filling in the (x,y) and (w,h) values in 'update_rect'.<br>
+  filling in the (x,y) and (w,h) elements of 'update_rect'.<br>
   <br>
   <b>Note:</b> The contents of the drawing canvas immediately prior to the mouse
   button click remains as it was (when the plugin's "<code>click()</code>"
@@ -331,26 +395,40 @@ then the names of your functions must begin with "<code><b>zoom_</b></code>"
 
 <p>Tux&nbsp;Paint provides a number of helper functions that plugins may
 access via the "<code>magic_api</code>" structure, sent to all of the
-plugin's functions (see above).</p>
+plugin's functions.
+(See "<a href="#toolfuncs">Required Plugin Functions</a>," above.)</p>
 
 <h4>Pixel Manipulations</h4>
 
 <blockquote>
 
 <ul>
-<li><code><b>Uint32 getpixel(SDL_Surface * surf, int x, int y)</b></code>
+<li><code><b>Uint32 getpixel(SDL_Surface&nbsp;*&nbsp;surf,
+  int&nbsp;x, int&nbsp;y)</b></code><br>
   Retreives the pixel value from the (x,y) coordinates of an SDL_Surface.
   (You can use SDL's "SDL_GetRGB()" function to convert the Uint32 'pixel'
   to a set of Uint8 RGB values.)<br>
   <br>
 
-<li><code><b>void putpixel(SDL_Surface * surf, int x, int y, Uint32 pixel)
+<li><code><b>void putpixel(SDL_Surface&nbsp;*&nbsp;surf, int&nbsp;x, int&nbsp;y,
-  </b></code><br>
+  Uint32&nbsp;pixel)</b></code><br>
   Sets the pixel value at position (x,y) of an SDL_Surface.
   (You can use SDL's "SDL_MapRGB()" function to convert a set of Uint8
   RGB values to a Uint32 'pixel' value appropriate to the destination
   surface.)<br>
   <br>
+
+<li><code><b>SDL_Surface * scale(SDL_Surface&nbsp;*&nbsp;surf,
+  int&nbsp;w, int&nbsp;h, int&nbsp;keep_aspect)</b></code><br>
+  This accepts an existing SDL surface and creates a new one scaled to an
+  arbitrary size.  (The original surface remains untouched.)<br>
+  <br>
+  The "<code>keep_aspect</code>" flag can be set to '1' to force the new
+  surface to stay the same shape (aspect&nbsp;ratio) as the original, meaning
+  it may not be the same width and height you requested.  (Check the
+  "<code>-&gt;w</code>" and "<code>-&gt;h</code>" elements of the output
+  "SDL_Surface&nbsp;*" to determine the <i>actual</i> size.)<br>
+  <br>
 </ul>
 
 </blockquote>
@@ -360,15 +438,17 @@ plugin's functions (see above).</p>
 <blockquote>
 
 <ul> 
-<li><code><b>int in_circle(int x, int y, int radius)</b></code><br>
+<li><code><b>int in_circle(int&nbsp;x, int&nbsp;y,
+  int&nbsp;radius)</b></code><br>
   Returns '1' if the (x,y) location is within a circle of a particular
   radius (centered around the origin: (0,0)).  Returns '0' otherwise.
   Useful to create 'Magic' tools that affect the canvas with a circular
   brush shape.<br>
   <br>
 
-<li><code><b>void line(int which, SDL_Surface * canvas, SDL_Surface * snapshot,
+<li><code><b>void line(int&nbsp;which, SDL_Surface&nbsp;* canvas,
-  int x1, int y1, int x2, int y2, int step, FUNC callback)</b></code><br>
+  SDL_Surface&nbsp;*&nbsp;snapshot, int&nbsp;x1, int&nbsp;y1,
+  int&nbsp;x2, int&nbsp;y2, int&nbsp;step, FUNC&nbsp;callback)</b></code><br>
   This function calculates all points on a line between the coordinates
   (x1,y1) and (x2,y2).  Every 'step' iterations, it calls the 'callback'
   function.<br>
@@ -382,9 +462,35 @@ plugin's functions (see above).</p>
   Example prototype of a callback function that may be sent to
   Tux&nbsp;Paint's "<code>line()</code>" 'Magic' tool plugin helper function:
   <blockquote><code>
-    void exampleCallBack(void * ptr_to_api, int which_tool,
+    void exampleCallBack(void&nbsp;*&nbsp;ptr_to_api, int&nbsp;which_tool,
-    SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y);
+    SDL_Surface&nbsp;*&nbsp;canvas, SDL_Surface&nbsp;*&nbsp;snapshot,
+    int&nbsp;x, int&nbsp;y);
   </code></blockquote>
+  <br>
+
+<li><code><b>Uint8 touched(int&nbsp;x, int&nbsp;y)</b></code><br>
+  This function allows you to avoid re-processing the same pixels multiple
+  times when the user drags the mouse across an area of the canvas, thus
+  increasing Tux&nbsp;Paint's response time, especially with math-heavy
+  effects.<br>
+  <br>
+  If your effect's "<code>click()</code>", "<code>drag()</code>" and/or
+  "<code>release()</code>" functions take the contents of the
+  source surface ("<code>snapshot</code>") and always create the same
+  results in the desintation surface ("<code>canvas</code>"), you should
+  wrap the effect in a call to "<code>api-&gt;touched()</code>".<br>
+  <br>
+  This function simply returns whether or not it had already been called for
+  the same (x,y) coordinates, since the user first clicked the mouse.
+  In other words, the first time you call it for a particular (x,y) coordinate,
+  it returns '0'.  Future calls will return '1' until the user releases
+  the mouse button.<br>
+  <br>
+  <b>Note:</b> Magic effects that continuously affect the destination
+  surface ("<code>canvas</code>") (ignoring the "<code>snapshot</code>
+  surface) have no reason to use this function.  The "Blur" and "Smudge"
+  tools that ship with Tux&nbsp;Paint are examples of such effects.<br>
+  <br>
 </ul>
 
 </blockquote>
@@ -410,6 +516,22 @@ plugin's functions (see above).</p>
 <li><code><b>int button_down(void)</b></code><br>
   A '1' is returned if the mouse button is down; '0' otherwise.<br>
   <br>
+
+<li><code><b>char * data_directory</b></code><br>
+  This string contains the directory where Tux&nbsp;Paint's data files are
+  stored.  For example, on Linux, this may be
+  "<code>/usr/share/tuxpaint/</code>".<br>
+  <br>
+  Magic tools should include an icon (see "<code>get_icon()</code>", above)
+  and are encouraged to include sound effects, it's useful for plugins to
+  know where such things are located.<br>
+  <br>
+  When compiling and installing a plugin, the "<code>tp-magic-config</code>"
+  command-line tool should be used to determine where such data should be
+  placed for the installed version of Tux&nbsp;Paint to find them.
+  (See "<a href="#installing">Installing</a>," below.)<br>
+  <br>
+
 </ul>
 
 </blockquote>
@@ -425,45 +547,52 @@ plugin's functions (see above).</p>
   crashed or frozen.<br>
   <br>
 
-<li><code><b>void playsound(Mix_Chunk * snd, int pan, int dist)</b></code><br>
+<li><code><b>void playsound(Mix_Chunk&nbsp;*&nbsp;snd, int&nbsp;pan,
+  int&nbsp;dist)</b></code><br>
   This function plays a sound (one loaded by the SDL helper library
-  "SDL_mixer").  It uses SDL_mixer's "Mix_SetPanning()" to set the volume
+  "SDL_mixer").  It uses SDL_mixer's "<code>Mix_SetPanning()</code>" to set
-  of the sound on the left and right speakers, based on the 'pan' and 'dist'
+  the volume of the sound on the left and right speakers, based on the
-  values sent to it.<br>
+  '<code>pan</code>' and '<code>dist</code>' values sent to it.<br>
   <br>
-  A 'pan' of 128 causes the sound to be played at equal volume on the left
+  A '<code>pan</code>' of 128 causes the sound to be played at equal volume
-  and right speakers.  A 'pan' of 0 causes it to be played completely on the
+  on the left and right speakers.  A '<code>pan</code>' of 0 causes it to be
-  left, and 255 completely on the right.<br>
+  played completely on the left, and 255 completely on the right.<br>
   <br>
-  The 'dist' value affects overall volume.  255 is loudest, and 0 is silent.<br>
+  The '<code>dist</code>' value affects overall volume.  255 is loudest,
-  The 'pan' and 'dist' values can be used to simulate location and distance of
+  and 0 is silent.<br>
-  the 'Magic' tool effect.<br>
+  <br>
+  The '<code>pan</code>' and '<code>dist</code>' values can be used to
+  simulate location and distance of the 'Magic' tool effect.<br>
   <br>
 
-<li><code><b>void special_notify(int flag)</b></code><br>
+<li><a name="special_notify">
+  <code><b>void special_notify(int&nbsp;flag)</b></code>
+  </a><br>
   This function notifies Tux&nbsp;Paint of special events.  Various values
-  defined in "<code>tp_magic_api.h</code>" can be logically 'or'ed
+  defined in "<code>tp_magic_api.h</code>" can be 'or'ed together
-  ("<code>|</code>") together and sent to this function.
+  (using C's boolean 'or': "<code>|</code>") and sent to this function.
   <ul>
   <li><code>SPECIAL_FLIP</code> &mdash; The contents of the canvas has been
-    flipped.<br>
+    flipped vertically.<br>
     <br>
     If a 'Starter' image was used as the basis of this image, it should be
     flipped too, and a record of the flip should be stored as part of
     Tux&nbsp;Paint's undo buffer stack.  Additionally, the fact that the
     starter has been flipped (or unflipped) should be recorded on disk
-    when the current drawing is saved.
+    when the current drawing is saved.<br>
+    <br>
   <li><code>SPECIAL_MIRROR</code> &mdash; Similar to <code>SPECIAL_FLIP</code>,
-    but for magic tools that mirror the contents of the canvas.
+    but for magic tools that mirror the contents of the canvas horizontally.
   </ul>
   <br>
 </ul>
 </blockquote>
 
 <h4>Color Conversions</h4>
+
 <blockquote>
 <ul>
-  <li><code><b>float sRGB_to_linear(Uint8 srbg)</b></code><br>
+  <li><code><b>float sRGB_to_linear(Uint8&nbsp;srbg)</b></code><br>
     Converts an 8-bit sRGB value (one between 0 and 255) to a linear
     floating point value (between 0.0 and 1.0).<br>
     <br>
@@ -472,13 +601,13 @@ plugin's functions (see above).</p>
     <br>
     <br>
 
-  <li><code><b>uint8 linear_to_sRGB(float linear)</b></code><br>
+  <li><code><b>uint8 linear_to_sRGB(float&nbsp;linear)</b></code><br>
     Converts a linear floating point value (one between 0.0 and 1.0) to
     an 8-bit sRGB value (between 0 and 255).<br>
     <br>
 
-  <li><code><b>void rgbtohsv(Uint8 r, Uint8 g, Uint8 b,
+  <li><code><b>void&nbsp;rgbtohsv(Uint8&nbsp;r, Uint8&nbsp;g, Uint8&nbsp;b,
-    float * h, float * s, float * v)</b></code><br>
+  float&nbsp;*&nbsp;h, float&nbsp;*&nbsp;s, float&nbsp;*&nbsp;v)</b></code><br>
     Converts 8-bit sRGB values (between 0 and 255) to floating-point
     HSV (Hue, Saturation and Value) values (Hue between 0.0 and 360.0,
     and Saturation and Value between 0.0 and 1.0).<br>
@@ -507,17 +636,17 @@ and data described above, the <code>tp_magic_api.h</code> C header file
 also contains some helper macros that you may use.</p>
 
 <ul>
-<li><code><b>min(x, y)</b></code><br>
+<li><code><b>min(x,&nbsp;y)</b></code><br>
   The minimum of 'x' and 'y'.  (That is, if 'x' is less than or
   equal to 'y', then the value of 'x' will be used.  If 'y' is less than 'x',
   it will be used.)<br>
   <br>
 
-<li><code><b>max(x, y)</b></code><br>
+<li><code><b>max(x,&nbsp;y)</b></code><br>
   The maximum of 'x' and 'y'.  The opposite of <code>min()</code>.<br>
   <br>
 
-<li><code><b>clamp(lo, value, hi)</b></code><br>
+<li><code><b>clamp(lo,&nbsp;value,&nbsp;hi)</b></code><br>
   A value, clamped to be no smaller than 'lo', and no higher than 'hi'.
   (That is, if 'value' is less than 'lo', then 'lo' will be used;
   if 'value' is greater than 'hi', then 'hi' will be used;
@@ -534,11 +663,43 @@ also contains some helper macros that you may use.</p>
 
 </blockquote>
 
+<h3>Constant Defintions in "<code>tp_magic_api.h</code>":</h3>
+
+<blockquote>
+<p>The following is a summary of constant values that are set
+(via&nbsp;"<code>#define</code>") within the 'Magic' tool API header file.</p>
+
+<ul>
+<li><code><b>TP_MAGIC_API_VERSION</b></code><br>
+  This integer value represents which version of the Tux&nbsp;Paint 'Magic'
+  tool API the header corresponds to.<br>
+  <br>
+  It should be referenced by your magic tool's "<code>api_version()</code>"
+  function, to inform the running copy of Tux&nbsp;Paint whether or not your
+  plugin is compatible.<br>
+  <br>
+  <b>Note:</b> This version number does not correspond to Tux&nbsp;Paint's
+  own release number (e.g., "0.9.18").  The API will not change every time
+  a new version of Tux&nbsp;Paint is released, which means plugins compiled
+  for earlier versions of Tux&nbsp;Paint will often run under newer
+  versions.<br>
+  <br>
+
+<li><code><b>SPECIAL_MIRROR<br>
+  SPECIAL_FLIP</b></code><br>
+  These are flags for Tux&nbsp;Paint's "<code>special_notify()</code>"
+  helper function.  They are described <a href="#special_notify">above</a>.<br>
+  <br>
+
+</ul>
+
+</blockquote>
+
 </blockquote>
 
 <hr size=1 noshade>
 
-<h2>Compiling</h2>
+<h2><a name="compiling">Compiling</a></h2>
 
 <blockquote>
 
@@ -559,7 +720,7 @@ also contains some helper macros that you may use.</p>
 
   <blockquote>
     <p><code>
-      gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so
+      $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so
     </code></p>
   </blockquote>
 
@@ -574,24 +735,116 @@ also contains some helper macros that you may use.</p>
 
   <p>A snippet from a more generalized Makefile might look like this:</p>
 
-  <blockquote>
+  <blockquote><table border=1 cellspacing=0 cellpadding=4><tr><td>
     <p><code>
       CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)<br>
       <br>
-      my_plugin.so:  my_plugin.c
+      my_plugin.so:  my_plugin.c<br>
       &nbsp;&nbsp;&nbsp;$(CC) -shared $(CFLAGS) -o $@ $&lt;
     </code></p>
+  </td></tr></table></blockquote>
+
+  </blockquote>
+
+  <h3>Windows</h3>
+
+  <blockquote>
+  <p>TBD</p>
+  </blockquote>
+
+  <h3>Mac OS X</h3>
+
+  <blockquote>
+  <p>TBD</p>
+  </blockquote>
+
+</blockquote>
+
+<hr size=1 noshade>
+
+<h2><a name="installing">Installing</a></h2>
+
+<blockquote>
+
+  <h3>Linux and other Unix-like Platforms</h3>
+
+  <blockquote>
+  <p>Use the "<code>tp-magic-config&nbsp;--pluginprefix</code>"
+  command, supplied as part of Tux&nbsp;Paint, to determine where the
+  plugin shared&nbsp;object ("<code>.so</code>") files should be installed.
+  The value returned by this command will be the global location where
+  the installed version of Tux&nbsp;Paint looks for plugins
+  (e.g., "<code></code>").</p>
+
+  <p>As stand-alone commands, using the BASH shell, for example:</p>
+
+  <blockquote>
+    <p><code>
+      # cp my_plugin.so `tp-magic-config --pluginprefix`<br>
+      # chmod 644 `tp-magic-config --pluginprefix`/my_plugin.so
+    </code></p>
   </blockquote>
 
-  <p>You may then install it globally into:
+  <p>Additionally, use the "<code>tp-magic-config&nbsp;--dataprefix</code>"
-  <code>/usr/lib/tuxpaint/plugins/</code> or
+  command, supplied as part of Tux&nbsp;Paint, to determine where data files
-  <code>/usr/local/lib/tuxpaint/plugins/</code> (depending on how
+  (PNG icon, Ogg&nbsp;Vorbis sound effects, etc.) should be installed.
-  Tux&nbsp;Paint was installed).</p>
+  The value returned by this command will be the same as the value of the
+  "<code>data_directory</code>" string stored within the
+  "<code>magic_api</code>" structure that your plugin's functions receive.</p>
 
-  <p>Or install it locally (for the current user only) into:
+  <p><b>Note:</b> Tux&nbsp;Paint's default Magic tool plugins install their
-  <code>~/.tuxpaint/magic/</code><br>
+  data within "<code>magic</code>" subdirectories of Tux&nbsp;Paint's
-  (<b>FIXME:</b> As of 2007-07-27, Tux&nbsp;Paint does not look here yet!)</p>
+  "<code>images</code>" and "<code>sounds</code>" data directories (e.g.,
+  "<code>/usr/share/tuxpaint/images/magic/</code>").  You are encouraged to
+  do the same.</p>
 
+  <p>As stand-alone commands, using the BASH shell, for example:</p>
+
+  <blockquote>
+    <p><code>
+      # cp my_plugin_icon.png `tp-magic-config --dataprefix`/images/magic/<br>
+      # chmod 644 `tp-magic-config --dataprefix`/images/magic/my_plugin_icon.png
+    </code></p>
+  </blockquote>
+
+  <h4>Putting it Together in a Makefile</h4>
+
+  <blockquote>
+
+  <p>A snippet from a more generalized Makefile might look like this:</p>
+
+  <blockquote><table border=1 cellspacing=0 cellpadding=4><tr><td>
+    <p><code>
+      PLUGINPREFIX=$(shell tp-magic-config --pluginprefix)<br>
+      DATAPREFIX=$(shell tp-magic-config --dataprefix)<br>
+      <br>
+      install:<br>
+      &nbsp;&nbsp;&nbsp;mkdir -p $(PLUGINPREFIX)<br>
+      &nbsp;&nbsp;&nbsp;cp *.so $(PLUGINPREFIX)/<br>
+      &nbsp;&nbsp;&nbsp;chmod 644 $(PLUGINPREFIX)/*.so<br>
+      &nbsp;&nbsp;&nbsp;mkdir -p $(DATAPREFIX)/images/magic<br>
+      &nbsp;&nbsp;&nbsp;cp *.png $(DATAPREFIX)/images/magic/<br>
+      &nbsp;&nbsp;&nbsp;chmod 644 $(DATAPREFIX)/images/magic/*.png
+    </code></p>
+  </td></tr></table></blockquote>
+
+  <p>The first two lines set up Makefile variables that contain the
+  paths returned by the "<code>tp-magic-config</code>" command-line tool.</p>
+
+  <p>Below that is an "<code>install</code>" target in the Makefile.
+  (Invoked by, for example, "<code>$&nbsp;sudo&nbsp;make&nbsp;install</code>"
+  or "<code>#&nbsp;make&nbsp;install</code>".)</p>
+
+  <p>The "<code>install</code>" target uses "<code>mkdir&nbsp;-p</code>" to
+  make sure that the plugin directory exists, then uses "<code>cp</code>" to
+  copy all plugin ("<code>.so</code>") files into it, and invokes
+  "<code>chmod</code>" to make sure they are readable.</p>
+
+  <p>It then does a similar series of commands to install icon files
+  ("<code>.png</code>"&nbsp;images) into a subdirectory within Tux&nbsp;Paint's
+  data directory.</p>
+
+  </blockquote>
   </blockquote>
 
   <h3>Windows</h3>
@@ -613,7 +866,68 @@ also contains some helper macros that you may use.</p>
 <h2><a name="multiple">Creating plugins with multiple effects</a></h2>
 
 <blockquote>
-TBD
+<p>Plugins for Tux&nbsp;Paint may contain more than one effect.  If you have
+multiple effects that are similar, it may make sense to place them in one
+plugin file, to reduce overhead and share code.</p>
+
+<p>These following suggestions can help you create plugins that contain multiple
+effects:</p>
+
+<ul>
+<li>Use a C "<code>enum</code>" to enumerate the effects, and count them.<br>
+  <blockquote><code>
+    enum {<br>
+    &nbsp;&nbsp;ONE_TOOL,<br>
+    &nbsp;&nbsp;ANOTHER_TOOL,<br>
+    &nbsp;&nbsp;AND_YET_ANOTHER_TOOL,<br>
+    &nbsp;&nbsp;NUM_TOOLS };
+  </code></blockquote>
+
+<li>Return the value of "<code>NUM_TOOLS</code>" when
+  "<code>get_tool_count()</code>" is called, and compare "<code>which</code>"
+  values sent to other functions with the other enumerated values.<br>
+  <br>
+
+<li>Create arrays of "<code>NUM_TOOLS</code>" length to contain effect-specific
+  data.<br>
+  <blockquote><code>
+    char * my_plugin_snd_filenames[NUM_TOOLS] = {<br>
+    &nbsp;&nbsp;"one.ogg", "another.ogg", "yet_another.ogg" };<br>
+    Mix_Chunk * my_plugin_snds[NUM_TOOLS];
+  </code></blockquote>
+
+<li>Use a C "<code>for</code>"-loop to load or create the
+  effect-specific data (such as loading sound effects during your
+  "<code>init()</code>").<br>
+  <blockquote><code>
+    int i;<br>
+    char fname[1024];<br>
+    <br>
+    for (i = 0; i &lt; NUM_TOOLS; i++)<br>
+    {<br>
+    &nbsp;&nbsp;snprintf(fname, sizeof(fname), "%s/%s",<br>
+    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;api->data_prefix, my_plugin_snd_filenames[i];<br>
+    <br>
+    &nbsp;&nbsp;my_plugin_snds[i] = Mix_LoadWAV(fname);<br>
+    }
+  </code></blockquote>
+
+<li>Similarly, do the same to free them later (such as freeing
+  sound effects during your "<code>shutdown()</code>").<br>
+  <br>
+
+<li>Use "<code>which</code>" values sent to your functions as an
+  index into those arrays (e.g., for playing the appropriate sound effect
+  for a tool).<br>
+  <br>
+
+</ul>
+
+<p><b>Note:</b> Even if your plugin currently contains only one effect,
+it may be useful to follow the steps above so that you can add a new
+variation of an effect with little effort.  ("<code>NUM_TOOLS</code>" will
+simply be '1', your arrays will be of length '1', etc.)</p>
+
 </blockquote>
 
 <hr size=1 noshade>
@@ -621,12 +935,128 @@ TBD
 <h2>Example Code</h2>
 
 <blockquote>
-TBD
+  <p>The C source file
+  "<a href="tp_magic_example.c"><code>tp_magic_example.c</code></a>" contains
+  a complete example of a plugin with multiple simple effects.</p>
 </blockquote>
 
 <hr size=1 noshade>
 
-<p>Summary and contact info TBD.</p>
+<h2>Getting Help</h2>
+
+<blockquote>
+
+<p>For more information, check the Tux&nbsp;Paint website:
+<a href="http://www.tuxpaint.org/">http://www.tuxpaint.org/</a>,
+and the Simple&nbsp;DirectMedia&nbsp;Layer&nbsp;library website:
+<a href="http://www.libsdl.org/">http://www.libsdl.org/</a>.</p>
+
+<p>Additionally, other Tux&nbsp;Paint developers and users can be found on the
+"<code>tuxpaint-devel</code>" and "<code>tuxpaint-users</code>"
+mailing lists:
+<a href="http://www.tuxpaint.org/lists/">http://www.tuxpaint.org/lists/</a>.</p>
+
+</blockquote>
+
+<hr size=1 noshade>
+
+<h2>Glossary</h2>
+
+<ul>
+<li><b>alpha:</b> See "RGBA"
+<li><b>&amp;:</b> See "ampersand"
+<li><b>ampersand:</b> "<code>&amp;</code>". A symbol in C that allows you to refer to the memory address of a variable; that is, a pointer. (For example, consider "<code>int&nbsp;i;</code>". Later, "<code>&amp;i</code>" refers to the memory where "<code>i</code>" is stored, not the value of "<code>i</code>" itself; it is a 'pointer to "<code>i</code>"'.)
+<li><b>API:</b> Application Programming Interface. <i>TBD</i>
+<li><b>argument:</b> <i>TBD</i>
+<li><b>arrow:</b> "<code>-&gt;</code>". A symbol in C that references an element within a pointer to a struct.
+<li><b>backquote:</b> See "grave."
+<li><b>backtick:</b> See "grave."
+<li><b>blue:</b> See "RGBA"
+<li><b>boolean 'or':</b> <i>TBD</i>
+<li><b>|:</b> See "boolean 'or'"
+<li><b>.:</b> See "dot"
+<li><b>`:</b> See "grave."
+<li><b>*:</b> See "star"
+<li><b>byte:</b> <i>TBD</i>
+<li><b>callback:</b> <i>TBD</i>
+<li><b>C enumeration:</b> <i>TBD</i>
+<li><b>C function:</b> <i>TBD</i>
+<li><b>C header file:</b> <i>TBD</i>
+<li><b>channel:</b> <i>TBD</i>
+<li><b>click:</b> The action of pressing a button on a mouse.
+<li><b>coordinates:</b> <i>TBD</i>
+<li><b>C pointer:</b> A variable that contains the location of a piece of memory; usually used to 'point' to another variable. Since C functions can only return one value as a result, pointers are often sent to functions to allow the function to change the values of multiple variables. (For example, Tux&nbsp;Paint's "<code>rgbtohsv()</code>" and "<code>hsvtorgb()</code>".)
+<li><b>C structure:</b> <i>TBD</i>
+<li><b>#define:</b> A C statement that defines a substitution that can occur later in the code. Generally used for constant values (e.g., "<code>#define&nbsp;RADIUS&nbsp;16</code>"; all instances of "<code>RADIUS</code>" will be replaced with "<code>16</code>"), but can also be used to create macros. Typically placed within C header files.
+<li><b>dimensions:</b> <i>TBD</i>
+<li><b>.dll:</b> See "Shared Object"
+<li><b>dot:</b> "<code>.</code>". A symbol in C that references an element within a struct.
+<li><b>drag:</b> The action of moving a mouse while the button remains held.
+<li><b>element:</b> A variable stored within a C structure. (Example: "<code>w</code>" and "<code>h</code>" elements of SDL_Surface store the surface's width and height, respectively.)
+<li><b>enum:</b> See "C enumeration"
+<li><b>float:</b> See "floating point"
+<li><b>floating point:</b> <i>TBD</i>
+<li><b>format:</b> <i>TBD</i>
+<li><b>free():</b> A C function that frees (deallocates) memory allocated by other C functions (such as "<code>strdup()</code>").
+<li><b>function:</b> See "C function"
+<li><b>grave:</b> The "<code><font size=+1>`</font></code>" character; used by the BASH shell to use the output of a command as the command-line arguments to another.
+<li><b>green:</b> See "RGBA"
+<li><b>-&gt;:</b> See "arrow"
+<li><b>.h:</b> See "C header file"
+<li><b>header:</b> See "C header file"
+<li><b>header file:</b> See "C header file"
+<li><b>HSV:</b> <i>TBD</i>
+<li><b>hue:</b> See "HSV"
+<li><b>IMG_Load():</b> An SDL_image function that loads an image file (e.g., a PNG) and returns it as an "<code>SDL_Surface&nbsp;*</code>".
+<li><b>#include:</b> A C statement that asks the compiler to read the contents of another file (usually a header file).
+<li><b>int:</b> See "integer"
+<li><b>integer:</b> <i>TBD</i>
+<li><b>libSDL:</b> See "Simple DirectMedia Layer"
+<li><b>linear:</b> <i>TBD</i>
+<li><b>macro:</b> <i>TBD</i>
+<li><b>magic_api:</b> A C structure that is passed along to a plugin's functions that exposes data and functions within the running copy of Tux&nbsp;Paint.
+<li><b>Magic tool</b>: One of a number of effects or drawing tools in Tux&nbsp;Paint, made available via the "Magic" tool button.
+<li><b>Mix_Chunk&nbsp;*:</b> (A pointer to) a C structure defined by SDL_mixer that contains a sound.
+<li><b>Mix_FreeChunk():</b> An SDL_mixer function that frees (deallocates) memory allocated for an SDL_mixer sound 'chunk' ("<code>Mix_Chunk&nbsp;*</code>").
+<li><b>Mix_LoadWAV():</b> An SDL_mixer function that loads a sound file (WAV, Ogg&nbsp;Vorbis, etc.) and returns it as a "<code>Mix_Chunk&nbsp;*</code>".
+<li><b>namespace:</b> <i>TBD</i>
+<li><b>Ogg&nbsp;Vorbis:</b> <i>TBD</i>
+<li><b>Plugin</b>: <i>TBD</i>
+<li><b>PNG:</b> <i>TBD</i>
+<li><b>pointer:</b> See "C pointer"
+<li><b>red:</b> See "RGBA"
+<li><b>release:</b> The action of releasing a button on a mouse.
+<li><b>RGBA:</b> "Red, Green, Blue, Alpha." <i>TBD</i>
+<li><b>RGB:</b> See "RBGA"
+<li><b>saturation:</b> See "HSV"
+<li><b>SDL:</b> See "Simple DirectMedia Layer"
+<li><b>SDL_FreeSurface():</b> An libSDL function that frees (deallocates) memory allocated for an SDL surface ("<code>SDL_Surface&nbsp;*</code>").
+<li><b>SDL_GetRGB():</b> A libSDL function that, given a <code>Uint32</code> pixel value (e.g., one returned from the Tux&nbsp;Paint's Magic tool API helper function "<code>getpixel()</code>"), the format of the surface the pixel was taken from, and pointers to three <code>Uint8</code> variables, will place the Red, Green and Blue (RGB) values of the pixel into the three <code>Uint8</code> variables. (Example: "<code>SDL_GetRGB(getpixel(surf,&nbsp;x,&nbsp;y), surf-&gt;format, &amp;r, &amp;g, &amp;b);</code>".)
+<li><b>SDL_MapRGB():</b> A libSDL function that, given the format of a surface and <code>Uint8</code> values representing Red, Green and Blue values for a pixel, returns a <code>Uint32</code> pixel value that can be placed in the surface (e.g., using Tux&nbsp;Paint's Magic tool API helper function "<code>putpixel()</code>"). (Example: "<code>putpixel(surf, x, y, SDL_MapRGB(surf-&gt;format, r, g, b));</code>".)
+<li><b>SDL_image:</b> A library on top of libSDL that can load various kinds of image files (e.g., PNG) and return them as an "<code>SDL_Surface&nbsp;*</code>".
+<li><b>SDL_mixer:</b> A library on top of libSDL that can load various kinds of sound files (WAV, Ogg&nbsp;Vorbis, etc.) and play back multiple sounds at once (mix them).
+<li><b>SDL_Rect:</b> A C structure defined by libSDL that represents a rectangular area. It contains elements representing the coordinates of the top left corner of the rectange (x,y) and the dimensions of the rectangle (w,h).
+<li><b>SDL_Surface&nbsp;*:</b> (A pointer to) a C structure defined by libSDL that contains a drawing surface.
+<li><b>Shared Object:</b> A piece of code that's compiled separately from the main application, and loaded dynamically, at runtime.
+<li><b>Simple DirectMedia Layer:</b> A programming library that allows programs portable low level access to a video framebuffer, audio output, mouse, and keyboard.
+<li><b>snprintf():</b> <i>TBD</i>
+<li><b>.so:</b> See "Shared Object"
+<li><b>sRBG:</b> See "RGBA"
+<li><b>star:</b> "<code>*</code>". A symbol in C that, when used in the declaration of variables (e.g., arguments to a function), denotes that the variable is a pointer. (For example, "<code>int&nbsp;*&nbsp;p;</code>" means that "<code>p</code>" is a <i>pointer</i> to an integer.) When used next to a pointer, it 'dereferences' the variable. (For example, later "<code>*p&nbsp;=&nbsp;50;</code>" assigns the value of 50 to the memory that "<code>p</code>" points to; it does not change the value of "<code>p</code>", which is still a pointer to an integer. In essence, it changed the integer that's being pointed to.)
+<li><b>strdup():</b> A C function that allocates enough memory to store a copy of a string, copies the string to it, and returns a "<code>char&nbsp;*</code>" pointer to the new copy.
+<li><b>struct:</b> See "C structure"
+<li><b>The GIMP</b>: An Open&nbsp;Source image manipulation and paint program.
+<li><b>tp_magic_api.h:</b> A header file that defines Tux&nbsp;Paint's Magic tool API.  Plugins must '#include' it.
+<li><b>tp-magic-config:</b> A command-line program that provides information about the installed version of Tux&nbsp;Paint to plugin developers (such as what C compiler flags they should compile with, and where plugin shared objects and data files should be installed).
+<li><b>Uint32:</b> A 32-bit, unsigned integer (defined by libSDL). In other words, four bytes that can represent 0 through 4294967295. (Typically used to hold enough information to store three or four bytes representing a pixel's color; i.e., RBGA value).
+<li><b>Uint8:</b> An 8-bit, unsigned integer (defined by libSDL). In other words, a byte that can represent 0 through 255.
+<li><b>unsigned:</b> <i>TBD</i>
+<li><b>value:</b> See "HSV"
+<li><b>variable:</b> <i>TBD</i>
+<li><b>WAV:</b> <i>TBD</i>
+<li><b>(w,h):</b> See "Dimensions"
+<li><b>(x,y):</b> See "Coordinates"
+</ul>
 
 </body></html>
 

src/manpage/tp-magic-config.3

@@ -0,0 +1,86 @@
+.\" tp-magic-config - 2007.07.31
+.TH TP-MAGIC-CONFIG 3 "31 Jul 2007" "2007.07.31" "Tux Paint Import"
+.SH NAME
+tp-magic-config -- Helps creating 'Magic' tool plugins for Tux Paint(1)
+
+.SH SYNOPSYS
+.TP 16
+.B tp-magic-config [\-\-apiversion | \-\-version | \-\-cflags | \-\-pluginprefix | \-\-dataprefix]
+
+.SH DESCRIPTION
+\fItp-magic-config\fP is a simple shell script that responds with various
+pieces of information about the currently-installed version of
+\fITux Paint\fP(1) that are useful when building 'Magic' tool plugins.
+
+.SH OPTIONS
+.TP 8
+.B \-\-apiversion
+Outputs the version of the \fITux Paint\fP 'Magic' tool plugin API that the
+installed copy of \fITux Paint\fP supports. (For API compatibility testing.)
+.TP 8
+.B \-\-version
+Outputs the version of \fITux Paint\fP that \fItp-magic-config\fP
+corresponds to.
+.TP 8
+.B \-\-cflags
+Outputs the compiler flags that \fITux Paint\fP 'Magic' tool plugins should
+be compiled with. (For example, a "\-I" include path option that tells the
+compiler where it can find the plugin API header file, "tp_magic_config.h",
+that plugins must #include.)
+.TP 8
+.B \-\-pluginprefix
+Outputs the directory where the installed copy of \fITux Paint\fP expects
+to find 'Magic' tool plugins (".so" shared objects).
+.TP 8
+.B \-\-dataprefix
+Outputs the directory where the installed copy of \fITux Paint\fP keeps its
+global data files (e.g., "/usr/share/tuxpaint/"). This is the same value that
+plugins will receive in the "data_directory" string within the
+"magic_api" structure sent to the plugins' functions.
+
+.SH SHELL EXAMPLES
+gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so
+.PP
+sudo cp my_plugin.so `tp-magic-config \-\-pluginprefix`
+.PP
+sudo cp my_plugin_icon.png `tp-magic-config \-\-dataprefix`/images/magic/
+
+.SH MAKEFILE EXAMPLE
+MAGIC_CFLAGS=$(shell tp-magic-config --cflags)
+.br
+MAGIC_PREFIX=$(shell tp-magic-config --pluginprefix)
+.br
+DATA_PREFIX=$(shell tp-magic-config --dataprefix)
+.PP
+all: my_plugin.so
+.PP
+my_plugin.so: my_plugin.c
+.PP	$(CC) -shared $(MAGIC_CFLAGS) my_plugin.c -o my_plugin.so
+.PP
+install: install-so install-data
+.PP
+install-so:
+.br
+	mkdir -p $(MAGIC_PREFIX)
+.br
+	cp my_plugin.so $(MAGIC_PREFIX)/
+.br
+	chmod 644 $(MAGIC_PREFIX)/my_plugin.so
+.PP
+install-data:
+.br
+	mkdir -p $(DATA_PREFIX)
+.br
+	cp icons/my_plugin_icon.png $(DATA_PREFIX)/images/magic/
+.br
+	chmod 644 $(DATA_PREFIX)/images/magic/my_plugin_icon.png
+
+.SH AUTHOR
+Bill Kendrick.  <bill@newbreedsoftware.com>
+
+
+.SH "SEE ALSO"
+.BR tuxpaint (1),
+.PP
+And documentation within /usr/[local/]share/doc/tuxpaint/.
+

src/tp-magic-config.sh.in

@@ -25,11 +25,12 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 # (See COPYING.txt)
 
-# Note: "__VERSION__" and "__INCLUDE__" are replaced by values
+# Note: "__VERSION__", "__APIVERSION__", "__INCLUDE__",
-# in Tux Paint's Makefile, via 'sed', by the 'make install-magic-plugin-dev'
+# "__PLUGINPREFIX__" and "__DATAPREFIX__" are replaced by
+# values in Tux Paint's Makefile, via 'sed', by the 'make tp-magic-config'
 # target.
 
-# July 5, 2007 - July 8, 2007
+# July 5, 2007 - July 31, 2007
 
 
 if [ $# -ne 0 ]; then
@@ -45,7 +46,15 @@ if [ $# -ne 0 ]; then
     echo `sdl-config --cflags` -I__INCLUDE__
     exit
   fi
+  if [ $1 = "--dataprefix" ]; then
+    echo "__DATAPREFIX__"
+    exit
+  fi
+  if [ $1 = "--pluginprefix" ]; then
+    echo "__PLUGINPREFIX__"
+    exit
+  fi
 fi
 
-echo "Usage: tp-magic-config [--apiversion] [--version] [--cflags]"
+echo "Usage: tp-magic-config [--apiversion | --version | --cflags | --pluginprefix | --dataprefix]"