<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>Creating Tux Paint Magic Tool Plugins</title>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#FF0000"
alink="#FF00FF">
<center>
<h1>Creating Tux Paint Magic Tool Plugins</h1>
<p>Copyright 2007-2007 by Bill Kendrick and others<br>
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>
</center>
<hr size=2 noshade>
<h2>Overview</h2>
<blockquote>
<p>Beginning with version 0.9.18, Tux Paint's 'Magic' tools were converted
from routines that lived within the application itself, to a set of 'plugins'
that are loaded when Tux Paint starts up.</p>
<p>This division allows more rapid development of 'Magic' tools, and allows
programmers to create and test new tools without needing to integrate them
within the main Tux Paint source code. (Users of more professional
graphics tools, such as The GIMP, should be familiar with this plugin
concept.)</p>
</blockquote>
<hr size=1 noshade>
<h2>Prerequisites</h2>
<blockquote>
<p>Tux Paint is written in the
<a href="http://en.wikipedia.org/wiki/C_(programming_language)">C programming
language</a>, and uses the
Simple DirectMedia Layer library ('libSDL', or simply 'SDL';
available from <a href="http://www.libsdl.org/">http://www.libsdl.org/</a>).
Therefore, for the moment at least, one must understand the C language and
how to compile C-based programs. Familiarity with the SDL API is highly
recommended, but some basic SDL concepts will be covered in this document.</p>
</blockquote>
<hr size=1 noshade>
<h2>Interfaces</h2>
<blockquote>
<p>Those who create 'Magic' tool plugins for Tux Paint must provide
some interfaces (C functions) that Tux Paint may invoke.</p>
<p>Tux Paint utilizes SDL's "SDL_LoadObject()" and "SDL_LoadFunction()"
routines to load plugins (shared objects files; e.g., "<code>.so</code>"
files on Linux or "<code>.dll</code>" files on Windows) and find the
functions within.</p>
<p>In turn, Tux Paint provides a number of helper functions that the
plugin may (or sometimes is required to) use. This is exposed as a C
structure (or "<code>struct</code>") which contains pointers to functions
and other data inside Tux Paint. A pointer to this structure gets
passed along to the plugin's functions as an argument when Tux Paint
invokes them.</p>
<p>Plugins should <code>#include</code> the C header file
"<code>tp_magic_api.h</code>", which exposes the 'Magic' tool plugin API.
Also, when you run the C compiler to build a plugin, you should use the
command-line tool "<code>tp-magic-config</code>" to get the appropriate
compiler flags (such as where the compiler can find the Tux Paint
plugin header file, as well as SDL's header files) for building a plugin.</p>
<p>The C header file and command-line tool mentioned above are included
with Tux Paint — or in some cases, as part of a "Tux Paint
'Magic' Tool Plugin Development package".</p>
<h3>'Magic' tool plugin functions</h3>
<blockquote>
<p>'Magic' tool plugins <i>must</i> contain the functions listed below.
<b>Note:</b> To avoid 'namespace' collisions, each function's name must
start with the shared object's filename (e.g., "blur.so" or "blur.dll"
would have functions whose names begin with "<code>blur_</code>"). <i>This
includes private functions</i> (ones not used by Tux Paint directly),
unless you declare those as '<code>static</code>'.</p>
<h4>Common arguments to plugin functions:</h4>
Here is a description of arguments that many of your plugin's functions
will need to accept.
<ul>
<li><code><b>magic_api * api</b></code><br>
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 <a href="#tpfuncs">described below</a>.<br>
<br>
Note: The <code>magic_api</code> struct is defined in the C header file
"<code>tp_magic_api.h</code>", which you should include at the top of your
plugin's C source file:
<blockquote><code>
#include "tp_magic_api.h"
</code></blockquote>
<li><code><b>int which</b></code><br>
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 <a href="#multiple">"Creating plugins with multiple effects"</a>,
below.<br>
<br>
<li><code><b>SDL_Surface * snapshot</b></code><br>
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 "<code>snapshot</code>" and write to
"<code>canvas</code>", below.)<br>
<br>
<li><code><b>SDL_Surface * canvas</b></code><br>
The current Tux Paint drawing canvas. Your magical effects should end
up here!<br>
<br>
<li><code><b>SDL_Rect * update_rect</b></code><br>
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:
<blockquote><code>
update_rect->x = x - 16;<br>
update_rect->y = y - 16;<br>
update_rect->w = 32;<br>
update_rect->h = 32;
</code></blockquote>
Or, if your effect changes the entire canvas (e.g., flips it upside-down),
you'd fill it as follows:
<blockquote><code>
update_rect->x = 0;<br>
update_rect->y = 0;<br>
update_rect->w = canvas->w;<br>
update_rect->h = canvas->h;
</code></blockquote>
Note: "<code>update_rect</code>" is a C pointer
(an "<code>SDL_Rect *</code>" rather than just an
"<code>SDL_Rect</code>") because you need to fill in its contents.
Because it is a pointer, you access its elements via
"<code>-></code>" (arrow) rather than "<code>.</code>" (dot).
</ul>
<h4>Required plugin functions:</h4>
<blockquote>
<p>Your plugin is required to contain, at the least, all of the
following functions.</p>
<p><b>Note:</b> Remember, your plugin's function names must be
preceded by your plugin's filename. That is, if your plugin is called
"<code>zoom.so</code>" (on Linux) or "<code>zoom.dll</code>" (on Windows),
then the names of your functions must begin with "<code><b>zoom_</b></code>"
(e.g., "<code>zoom_get_name(...)</code>").</p>
<h5>Plugin "housekeeping" functions:</h5>
<ul>
<li><code><b>Uint32 api_version(void)</b></code><br>
The plugin should return an integer value representing the version of
the Tux Paint 'Magic' tool plugin API the plugin was built against.
The safest thing to do is return the value of
<code>TP_MAGIC_API_VERSION</code>, which is defined in
"<code>tp_magic_api.h</code>". If Tux Paint deems your plugin to
be compatible, it will go ahead and use it.<br>
<br>
<b>Note:</b> Called once by Tux Paint, at startup. It is called
first.<br>
<li><code><b>int init(magic_api * api)</b></code><br>
The plugin should do any initialization here.
Return '1' if initialization was successful,
or '0' if not (and Tux Paint will not present any 'Magic' tools
from the plugin).<br>
<br>
<b>Note:</b> Called once by Tux Paint, at startup. It is called
first. It is called after "<code>api_version()</code>", if
Tux Paint believes your plugin to be compatible.<br>
<li><code><b>int get_tool_count(magic_api * api)</b></code><br>
This should return the number of Magic tools this plugin provides to
Tux Paint.<br>
<br>
<b>Note:</b> Called once by Tux Paint, at startup. It is called
after your "<code>init()</code>", if it succeeded.<br>
<br>
<li><code><b>char * get_name(magic_api * api, int 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 Paint.<br>
<br>
Tux Paint will <code>free()</code> the string upon exit, so you should
wrap it in a C <code>strdup()</code> call.<br>
<br>
<b>Note:</b> Called once for each Magic tool your plugin claims to
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>
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
Tux Paint.<br>
<br>
Tux Paint will free ("<code>SDL_FreeSurface()</code>") the surface upon
exit.<br>
<br>
<b>Note:</b> Called once for each Magic tool your plugin claims to
contain (by your "<code>get_tool_count()</code>").<br>
<br>
<li><code><b>char * get_description(magic_api * api, int 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 Paint.<br>
<br>
Tux Paint will <code>free()</code> the string upon exit, so you should
wrap it in a C <code>strdup()</code> call.<br>
<br>
<b>Note:</b> Called once for each Magic tool your plugin claims to
contain (by your "<code>get_tool_count()</code>").<br>
<br>
<li><code><b>int requires_colors(magic_api * api, int which)</b></code><br>
Return a '1' if the 'Magic' tool accepts colors (the 'Colors' palette in
Tux Paint will be available), or '0' if not.<br>
<br>
<b>Note:</b> Called once for each Magic tool your plugin claims to
contain (by your "<code>get_tool_count()</code>").<br>
<br>
<li><code><b>void shutdown(magic_api * 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
and <code>Mix_FreeChunk()</code> the sounds here.<br>
<br>
<b>Note:</b> This function is called once, when Tux Paint exits.<br>
<br>
</ul>
<h5>Plugin event functions:</h5>
<ul>
<li><code><b>void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g)
</b></code><br>
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 user 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,
SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect)
</b></code><br>
The plugin should apply the appropriate 'Magic' tool on the 'canvas'
surface. The (x,y) coordinates are where the 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>
<br>
The contents of the drawing canvas immediately prior to the mouse button
click is stored within the 'snapshot' canvas.<br>
<br>
<li><code><b>void drag(magic_api * api, int which, SDL_Surface * snapshot,
SDL_Surface * canvas, int ox, int oy, int x, int y,
SDL_Rect * update_rect)</b></code><br>
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 "<code>line()</code>" helper function. (See 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>
<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>
<br>
<li><code><b>void release(magic_api * api, int which, SDL_Surface * snapshot,
SDL_Surface * canvas, int x, int y,
SDL_Rect * update_rect)</b></code><br>
The plugin should apply the appropriate 'Magic' tool on the 'canvas'
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>
<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>"
function was called), and is still available in the 'snapshot' canvas.<br>
<br>
</ul>
</blockquote>
</blockquote>
<h3><a name="tpfuncs">Tux Paint Functions and Data</a></h3>
<blockquote>
<p>Tux 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>
<h4>Pixel Manipulations</h4>
<blockquote>
<ul>
<li><code><b>Uint32 getpixel(SDL_Surface * surf, int x, int y)</b></code>
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)
</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>
</ul>
</blockquote>
<h4>Helper Functions</h4>
<blockquote>
<ul>
<li><code><b>int in_circle(int x, int y, int 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,
int x1, int y1, int x2, int y2, int step, FUNC 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>
<br>
It sends the 'callback' function the (x,y) coordinates on the line,
Tux Paint's "<code>magic_api</code>" struct (as a
"<code>void *</code>" pointer), a 'which' value, represening which
of the plugin's 'Magic' tool is being used, and the current and snapshot
canvases.<br>
<br>
Example prototype of a callback function that may be sent to
Tux Paint's "<code>line()</code>" 'Magic' tool plugin helper function:
<blockquote><code>
void exampleCallBack(void * ptr_to_api, int which_tool,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y);
</code></blockquote>
</ul>
</blockquote>
<h4>Informational</h4>
<blockquote>
<ul>
<li><code><b>char * tp_version</b></code><br>
A string containing the version of Tux Paint that's running
(e.g., "0.9.18").<br>
<br>
<li><code><b>int canvas_w</b></code>
Returns the width of the drawing canvas.<br>
<br>
<li><code><b>int canvas_h</b></code>
Returns the height of the drawing canvas.<br>
<br>
<li><code><b>int button_down(void)</b></code><br>
A '1' is returned if the mouse button is down; '0' otherwise.<br>
<br>
</ul>
</blockquote>
<h4>Tux Paint System Calls</h4>
<blockquote>
<ul>
<li><code><b>void show_progress_bar(void)</b></code><br>
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.<br>
<br>
<li><code><b>void playsound(Mix_Chunk * snd, int pan, int 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
of the sound on the left and right speakers, based on the 'pan' and 'dist'
values sent to it.<br>
<br>
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.<br>
<br>
The 'dist' value affects overall volume. 255 is loudest, and 0 is silent.<br>
The 'pan' and 'dist' 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>
This function notifies Tux Paint of special events. Various values
defined in "<code>tp_magic_api.h</code>" can be logically 'or'ed
("<code>|</code>") together and sent to this function.
<ul>
<li><code>SPECIAL_FLIP</code> — The contents of the canvas has been
flipped.<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 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.
<li><code>SPECIAL_MIRROR</code> — Similar to <code>SPECIAL_FLIP</code>,
but for magic tools that mirror the contents of the canvas.
</ul>
<br>
</ul>
</blockquote>
<h4>Color Conversions</h4>
<blockquote>
<ul>
<li><code><b>float sRGB_to_linear(Uint8 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>
<b>See also:</b>
<a href="http://en.wikipedia.org/wiki/SRGB">sRGB article at Wikipedia</a>.
<br>
<br>
<li><code><b>uint8 linear_to_sRGB(float 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,
float * h, float * s, float * 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>
<br>
<b>See also:</b>
<a href="http://en.wikipedia.org/wiki/HSV_color_space">HSV Color Space
article at Wikipedia</a>.<br>
<br>
<li><code><b>void hsvtorgb(float h, float s, float v,
Uint8 * r, Uint8 * g, Uint8 * b)</b></code><br>
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).<br>
<br>
</ul>
</blockquote>
</blockquote>
<h3>Helper Macros in "<code>tp_magic_api.h</code>":</h3>
<blockquote>
<p>Along with the "<code>magic_api</code>" C structure containing functions
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>
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>
The maximum of 'x' and 'y'. The opposite of <code>min()</code>.<br>
<br>
<li><code><b>clamp(lo, value, 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;
otherwise, 'value' will be used.)<br>
<br>
<b>Example:</b> <code>red = clamp(0, n, 255);</code><br>
Tries to set 'red' to be the value of 'n', but without allowing it to
become less than 0 or greater than 255.<br>
<br>
<b>Note:</b> This macro is simply a <code>#define</code> of:
"<code>(min(max(value,lo),hi))</code>".<br>
<br>
</ul>
</blockquote>
</blockquote>
<hr size=1 noshade>
<h2>Compiling</h2>
<blockquote>
<h3>Linux and other Unix-like Platforms</h3>
<blockquote>
<p>Use the C compiler's "<code>-shared</code>" command-line option to generate
a shared object file ("<code>.so</code>") based on your 'Magic' tool
plugin's C source code.</p>
<p>Additionally, use the "<code>tp-magic-config --cflags</code>" command,
supplied as part of Tux Paint, to provide additional command-line
flags to your C compiler that will help it build your plugin.</p>
<p>As a stand-alone command, using the GNU C Compiler and BASH shell,
for example:</p>
<blockquote>
<p><code>
gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so
</code></p>
</blockquote>
<p><b>Note:</b> The characters around the "<code>tp-magic-config</code>"
command are a grave/backtick/backquote
("<code><b><font size=+1>`</font></b></code>"), and
not an apostrophe/single-quote ("<code><b><font size=+1>'</font></b></code>").
They tell the shell to execute the command within (in this case,
"<code>tp-magic-config ...</code>"), and use its output
as an argument to the command being executed (in this case,
"<code>gcc ...</code>").</p>
<p>A snippet from a more generalized Makefile might look like this:</p>
<blockquote>
<p><code>
CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)<br>
<br>
my_plugin.so: my_plugin.c
$(CC) -shared $(CFLAGS) -o $@ $<
</code></p>
</blockquote>
<p>You may then install it globally into:
<code>/usr/lib/tuxpaint/plugins/</code> or
<code>/usr/local/lib/tuxpaint/plugins/</code> (depending on how
Tux Paint was installed).</p>
<p>Or install it locally (for the current user only) into:
<code>~/.tuxpaint/magic/</code><br>
(<b>FIXME:</b> As of 2007-07-27, Tux Paint does not look here yet!)</p>
</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="multiple">Creating plugins with multiple effects</a></h2>
<blockquote>
TBD
</blockquote>
<hr size=1 noshade>
<h2>Example Code</h2>
<blockquote>
TBD
</blockquote>
<hr size=1 noshade>
<p>Summary and contact info TBD.</p>
</body></html>
