Here is a description of arguments that many of your plugin's functions will need to accept.

magic_api * api

Pointer to a C structure containing pointers to Tux Paint functions and other data that the plugin can (and sometimes should) use. The contents of this struct are described below.

Note: The magic_api struct is defined in the C header file "tp_magic_api.h", which you should include at the top of your plugin's C source file:

#include "tp_magic_api.h"

int which

An index the plugin should use to differentiate different 'Magic' tools, if the plugin provides more than one. (If not, "which" will always be 0.) See "Creating plugins with multiple effects", below.

SDL_Surface * snapshot

A snapshot of the previous Tux Paint canvas, taken when the the mouse was first clicked to activate the current magic tool. If you don't continuously affect the image during one hold of the mouse button, you should base your effects off the contents of this canvas. (That is, read from "snapshot" and write to "canvas", below.)

SDL_Surface * canvas

The current Tux Paint drawing canvas. Your magical effects should end up here!

SDL_Rect * update_rect

A pointer to an SDL 'rectangle' structure that you use to tell Tux Paint what part of the canvas has been updated. If your effect affects a 32x32 area centered around the mouse pointer, you would fill the SDL_Rect as follows:

update_rect->x = x - 16;
update_rect->y = y - 16;
update_rect->w = 32;
update_rect->h = 32;

Or, if your effect changes the entire canvas (e.g., flips it upside-down), you'd fill it as follows:

update_rect->x = 0;
update_rect->y = 0;
update_rect->w = canvas->w;
update_rect->h = canvas->h;

Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than just an "SDL_Rect") because you need to fill in its contents. Since it is a pointer, you access its elements via "->" (arrow) rather than "." (dot).

Your plugin is required to contain, at the least, all of the following functions.

Note: Remember, your plugin's function names must be preceded by your plugin's filename. That is, if your plugin is called "zoom.so" (on Linux) or "zoom.dll" (on Windows), then the names of your functions must begin with "zoom_" (e.g., "zoom_get_name(...)").

Uint32 getpixel(SDL_Surface * surf, int x, int y)

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.)

void putpixel(SDL_Surface * surf, int x, int y, Uint32 pixel)

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.)

Uint32 xorpixel(SDL_Surface * surf, int x, int y)

Applies an XOR (exclusive-or) operation to the pixel at coordinates (x,y) of the SDL_Surface. Applying an XOR again at the same position will return the pixel to the original value. Useful for displaying temporary 'rubberband' lines, outlines, and crosshairs, while utilizing a Magic Tool.

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.)

int in_circle(int x, int y, int radius)

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.

void line(void * api, int which, SDL_Surface * canvas, SDL_Surface * snapshot, int x1, int y1, int x2, int y2, 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.

It sends the 'callback' function the (x,y) coordinates on the line, Tux Paint's "magic_api" struct (as a "void *" pointer which you need to send to it), a 'which' value, represening which of the plugin's 'Magic' tool is being used, and the current and snapshot canvases.

Example prototype of a callback function that may be sent to Tux Paint's "line()" 'Magic' tool plugin helper function:

void exampleCallBack(void * ptr_to_api, int which_tool, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y);

Example use of the "line()" helper (e.g., within a plugin's draw() function):

api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1, exampleCallBack);

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.

char * tp_version

A string containing the version of Tux Paint that's running (e.g., "0.9.34").

int canvas_w
int canvas_h

Returns the width (canvas_w) and height (canvas_h) of the drawing canvas (in pixels).

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.)

Note: If your plugin is installed locally (e.g., in your "~/.tuxpaint/plugins/" directory), rather than globally (system-wide), the "data_directory" value will be different. (e.g., "/home/username/.tuxpaint/plugins/data/").

void playsound(Mix_Chunk * snd, int pan, int dist)

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 of the sound on the left and right speakers, based on the 'pan' and 'dist' values sent to it.

A 'pan' of 128 causes the sound to be played at equal volume on the left and right speakers. A 'pan' of 0 causes it to be played completely on the left, and 255 completely on the right.

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 stopsound(void)

This function stops playing a sound played by playsound(). It is useful to silence effects when the user stops using the tool (in your 'release' function).

int playingsound(void)

Call this function to determine whether a magic tool sound effect is still currently playing. Can be used by magic tools that pause and unpause their sounds (see below) to determine whether it's time to start a new sound — call playsound() instead of unpausesound(). A '1' is returned if a sound is playing; '0' otherwise.

Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.

void pausesound(void)

Pauses the magic tool sound effect; it may be unpaused to resume playing. Useful when a magic tool sound is very long; avoid repeatedly playing just a short clip of the beginning when the user draws small strokes by starting (playsound()) and stopping (stopsound()) the sound. Use playingsound() to determine whether you can unpause or must play from the start.

Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.

void unpausesound(void)

Resumes a paused magic tool sound effect, if one was playing.

Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.

void update_progress_bar(void)

Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen). Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.

void special_notify(int flag)

This function notifies Tux Paint of special events. Various values defined in "tp_magic_api.h" can be 'or'ed together (using C's boolean 'or': "|") and sent to this function.

SPECIAL_FLIP

The contents of the canvas has been 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 be stored as part of Tux 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.

SPECIAL_MIRROR

Similar to SPECIAL_FLIP, but for magic tools that mirror the contents of the canvas horizontally.

void retract_undo(void)

Each time the user clicks in the canvas while using your Magic tool, a new snapshot of the canvas is added to the "Undo" history. This allows the user to click "Undo" to return the image to the state it was in just before they clicked with your Magic tool. They may click "Redo" to bring the change back.

However, some more sophisticated Magic tools require one or more steps to take place before the final "effect" is reached. For example, "Filled Polygon" requires placing at least three connected points, then connecting the first and last point together, to create a shape that gets added to the canvas. In the meantime, an interactive preview of the shape — an outline with large dots representing each point — is drawn onto the canvas. (The points may be moved, or even removed, prior to finishing the shape.)

The retract_undo() API function may be used by a Magic tool to tell it to discard the "Undo" snapshot it just took, as a way to prevent previews shown during multi-step actions from appearing on the canvas when using the "Undo" and "Redo" commands.

💡 This is an advanced feature.

Note: Added to Tux Paint 0.9.33; Magic API version 0x0000000A.

float sRGB_to_linear(Uint8 srbg)

Converts an 8-bit sRGB value (one between 0 and 255) to a linear floating point value (between 0.0 and 1.0).

uint8 linear_to_sRGB(float linear)

Converts a linear floating point value (one between 0.0 and 1.0) to an 8-bit sRGB value (between 0 and 255).

void rgbtohsv(Uint8 r, Uint8 g, Uint8 b, float * h, float * s, float * v)

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).

void hsvtorgb(float h, float s, float v, Uint8 * r, Uint8 * g, Uint8 * b)

Converts 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) to 8-bit sRGB values (between 0 and 255).

For more information, refer to the sRGB article at Wikipedia and the HSV Color Space article at Wikipedia.

As a stand-alone command, using the GNU C Compiler and BASH shell, for example:

$ gcc -shared -fpic `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 ("'"). They tell the shell to execute the command within (in this case, "tp-magic-config ..."), and use its output as an argument to the command being executed (in this case, "gcc ...").

A snippet from a Makefile to compile a Tux Paint "Magic" tool plugin might look like this:

CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)

my_plugin.so: my_plugin.c
    gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c

The first line sets up Makefile variable ("CFLAGS") that contains flags for the compiler. "-Wall" asks for all compiler warnings to be shown. "-O2" asks for level 2 optimization. "($shell tp-magic-config --cflags)" runs "tp-magic-config" to retrieve additional compiler flags that "Magic" tool plugins require. (The "$(shell ...)" directive is similar to the ` ("grave") character in the BASH shell examples, above.)

The next line defines a Makefile target, "my_plugin.so", and states that it depends on the C source file "my_plugin.c". (Any time the C file changes, "make" will know to recompile it and produce an updated ".so" file. If the C file hadn't changed, it won't bother recompiling.)

The last line defines the command "make" should run when it determines that it needs to (re)compile the ".so" file. Here, we're using "gcc", with "-shared and "$(CFLAGS)" command-line arguments, like above. "-o my_plugin.so" tells the C compiler that the output file should be "my_plugin.so". The last argument is the C file to compile, in this case "my_plugin.c".

Note: Commands listed below a Makefile target should be intented using a single tab character.

An even more generalized Makefile might look like this:

CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)

my_plugin_1.so: my_plugin_1.c
    $(CC) -shared $(CFLAGS) -o $@ $<

my_plugin_2.so: my_plugin_2.c
    $(CC) -shared $(CFLAGS) -o $@ $<

As before, there are lines that define the command "make" should run when it determines that it needs to (re)compile the ".so" file(s). However, more general terms are used...

"$(CC)" gets expanded to your default C compiler (e.g., "gcc"). "-shared" and "$(CFLAGS)" are command-line arguments to the compiler, like above. "-o $@" tells the C compiler what the output file should be; "make" replaces "$@" with the name of the target, in this case "my_plugin_1.so" or "my_plugin_2.so". And finally, the last argument is the C file to compile; "make" replaces "$<" with the target's dependency, in this case "my_plugin_1.c" or "my_plugin_2.c".

Use "tp-magic-config --pluginprefix" 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 copy of Tux Paint looks for plugins (e.g., "/usr/lib/tuxpaint/plugins").

Alternatively, you may use "tp-magic-config --localpluginprefix" to find out where Tux Paint expects to find local plugins for the current user (e.g., "/home/username/.tuxpaint/plugins").

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

Note: See the note above regarding the "`" (grave) character.

Use the "tp-magic-config --plugindocprefix" command to determine where documentation for your "Magic" tools should go. The value returned by this command will be the location where the documentation to the installed copy of Tux Paint is stored. The main documentation includes a link to a folder where "Magic" tools' documentation is expected to be installed

Note: It's best to include both HTML and plain-text versions of your documentation. An "html" subdirectory exists within the "magic-docs" directory, and is where the HTML versions should go.

As stand-alone commands, using the BASH shell, for example:

# cp my_plugin.html `tp-magic-config --plugindocprefix`/html
# cp my_plugin.txt `tp-magic-config --plugindocprefix`

Note: See the note above regarding the "`" (grave) character.

Note: Currently, there is no "--localplugindocprefix" option.

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 (e.g., "/usr/share/tuxpaint/").

For locally-installed plugins (for the current user only), use "tp-magic-config --localdataprefix". It will return the value of "data_directory" string that locally-installed plugins will see within their "magic_api" structure (e.g., "/home/username/.tuxpaint/plugins/data/").

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

Note: See the note above regarding the "`" (grave) character.

A snippet from a more generalized Makefile might look like this:

PLUGINPREFIX=$(shell tp-magic-config --pluginprefix)
PLUGINDOCPREFIX=$(shell tp-magic-config --plugindocprefix)
DATAPREFIX=$(shell tp-magic-config --dataprefix)

install:
    #
    # Install plugin
    mkdir -p $(PLUGINPREFIX)
    cp *.so $(PLUGINPREFIX)/
    chmod 644 $(PLUGINPREFIX)/*.so
    #
    # Install icons
    mkdir -p $(DATAPREFIX)/images/magic
    cp icons/*.png $(DATAPREFIX)/images/magic/
    chmod 644 $(DATAPREFIX)/images/magic/*.png
    #
    # Install sound effects
    mkdir -p $(DATAPREFIX)/sounds/magic
    cp sounds/*.ogg $(DATAPREFIX)/sounds/magic/
    chmod 644 $(DATAPREFIX)/sounds/magic/*.ogg
    #
    # Install docs
    mkdir -p $(PLUGINDOCPREFIX)/html
    cp docs/*.html $(PLUGINDOCPREFIX)/html/
    cp docs/*.txt $(PLUGINDOCPREFIX)/
    chmod 644 $(PLUGINDOCPREFIX)/html/*.html
    chmod 644 $(PLUGINDOCPREFIX)/*.txt


The first three lines set up Makefile variables that contain the paths returned by the "tp-magic-config" command-line tool. (The "$(shell ...)" directive is similar to the ` ("grave") character in the BASH shell examples, above.)

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) and sound effects (".ogg" files) into subdirectories within Tux Paint's data directory, and to install documentation (".html" and ".txt" files) within Tux Paint's documentation directory.

Note: The above Makefile example assumes the user will have priveleges to install Tux Paint plugins system-wide.