adf56ef7e9
Magic tool documentation now split into separate files, and referenced (as a directory) from README, so that users can find docs to any additional tools (ones not included by default with Tux Paint) that are installed. Added new --datadir option, to separate path to brushes/stamps/etc. from that of saved files. Improved docs on where savedir default is. Made sure --help, man tuxpaint, and OPTIONS docs all covered all command-line options. Noted SDL_Pango makes locale-specific fonts unnecessary. Added "--plugindocprefix" option to tp-magic-config, for where docs should go. Improved plugin API documentation. Improved layout of man pages a little.
1227 lines
50 KiB
HTML
1227 lines
50 KiB
HTML
<!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 - August 2, 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>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">Glossary</a>
|
|
</ul>
|
|
|
|
|
|
<hr size=1 noshade>
|
|
|
|
<h2><a name="prereq">Prerequisites</a></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.
|
|
(See "<a href="#compiling">Compiling</a>", below.)</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><a name="toolfuncs">Required Plugin Functions:</a></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>
|
|
<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>
|
|
<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 plugin's
|
|
Magic tools that accept colors becomes active, and whenever 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
|
|
'<code>canvas</code>' 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) 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 '<code>snapshot</code>' 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
|
|
'<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.<br>
|
|
<br>
|
|
Typically, plugins that let the user "draw" effects onto the canvas
|
|
utilize Tux 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 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) 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 '<code>snapshot</code>'
|
|
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
|
|
'<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) 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>"
|
|
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 "<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><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)</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 * surf,
|
|
int w, int h, int 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 ratio) as the original, meaning
|
|
it may not be the same width and height you requested. (Check the
|
|
"<code>->w</code>" and "<code>->h</code>" elements of the output
|
|
"SDL_Surface *" to determine the <i>actual</i> size.)<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>
|
|
<br>
|
|
|
|
<li><code><b>Uint8 touched(int x, int 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 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->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 Paint are examples of such effects.<br>
|
|
<br>
|
|
</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>
|
|
|
|
<li><code><b>char * data_directory</b></code><br>
|
|
This string contains the directory where Tux 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 Paint to find them.
|
|
(See "<a href="#installing">Installing</a>," below.)<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 "<code>Mix_SetPanning()</code>" to set
|
|
the volume of the sound on the left and right speakers, based on the
|
|
'<code>pan</code>' and '<code>dist</code>' values sent to it.<br>
|
|
<br>
|
|
A '<code>pan</code>' of 128 causes the sound to be played at equal volume
|
|
on the left and right speakers. A '<code>pan</code>' of 0 causes it to be
|
|
played completely on the left, and 255 completely on the right.<br>
|
|
<br>
|
|
The '<code>dist</code>' value affects overall volume. 255 is loudest,
|
|
and 0 is silent.<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><a name="special_notify">
|
|
<code><b>void special_notify(int flag)</b></code>
|
|
</a><br>
|
|
This function notifies Tux Paint of special events. Various values
|
|
defined in "<code>tp_magic_api.h</code>" can be 'or'ed together
|
|
(using C's boolean 'or': "<code>|</code>") and sent to this function.
|
|
<ul>
|
|
<li><code>SPECIAL_FLIP</code> — The contents of the canvas has been
|
|
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 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.<br>
|
|
<br>
|
|
<li><code>SPECIAL_MIRROR</code> — Similar to <code>SPECIAL_FLIP</code>,
|
|
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>
|
|
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>
|
|
|
|
<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 "<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 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 Paint whether or not your
|
|
plugin is compatible.<br>
|
|
<br>
|
|
<b>Note:</b> 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.<br>
|
|
<br>
|
|
|
|
<li><code><b>SPECIAL_MIRROR<br>
|
|
SPECIAL_FLIP</b></code><br>
|
|
These are flags for Tux 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><a name="compiling">Compiling</a></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>Use the "<code>tp-magic-config --cflags</code>" command,
|
|
supplied as part of Tux Paint — or in some cases, as part of a
|
|
"Tux Paint 'Magic' Tool Plugin Development package" —
|
|
to provide additional command-line flags to your C compiler that will help
|
|
it build your plugin.</p>
|
|
|
|
<h4>Command-Line Example</h4>
|
|
|
|
<blockquote>
|
|
|
|
<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><a name="grave"><b>Note:</b></a>
|
|
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>
|
|
|
|
</blockquote>
|
|
|
|
<h4>Makefile Example</h4>
|
|
|
|
<blockquote>
|
|
|
|
<p>A snippet from a Makefile to compile a Tux Paint "Magic" tool
|
|
plugin might look like this:</p>
|
|
|
|
<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<br>
|
|
gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c
|
|
</code></p>
|
|
</td></tr></table></blockquote>
|
|
|
|
<p>The first line sets up Makefile variable ("<code>CFLAGS</code>") that
|
|
contains flags for the compiler. "<code>-Wall</code>" asks for all compiler
|
|
warnings to be shown. "<code>-O2</code>" asks for level 2 optimization.
|
|
"<code>($shell tp-magic-config --cflags)</code>" runs
|
|
"<code>tp-magic-config</code>" to retrieve additional compiler flags that
|
|
"Magic" tool plugins require. (The "<code>$(shell ...)</code>"
|
|
directive is similar to the <a href="#grave"><b><font size=+1>`</font></b>
|
|
("grave")</a> character in the BASH shell examples, above.)</p>
|
|
|
|
<p>The next line defines a Makefile target, "<code>my_plugin.so</code>",
|
|
and states that it <i>depends on</i> the C source file
|
|
"<code>my_plugin.c</code>". (Any time the C file changes, "<code>make</code>"
|
|
will know to recompile it and produce an updated "<code>.so</code>" file.
|
|
If the C file hadn't changed, it won't bother recompiling.)</p>
|
|
|
|
<p>The last line defines the command "<code>make</code>" should
|
|
run when it determines that it needs to (re)compile the "<code>.so</code>"
|
|
file. Here, we're using "<code>gcc</code>", with "<code>-shared</code> and
|
|
"<code>$(CFLAGS)</code>" command-line arguments, like above.
|
|
"<code>-o my_plugin.so</code>" tells the C compiler that the output file
|
|
should be "<code>my_plugin.so</code>". The last argument is the C file to
|
|
compile, in this case "<code>my_plugin.c</code>".</p>
|
|
|
|
<p><b>Note:</b> Commands listed below a Makefile target should be
|
|
intented using a single <b>tab</b> character.</p>
|
|
|
|
</blockquote>
|
|
|
|
<h4>Advanced Makefile</h4>
|
|
|
|
<blockquote>
|
|
|
|
<p>An even more generalized Makefile might look like this:</p>
|
|
|
|
<blockquote><table border=1 cellspacing=0 cellpadding=4><tr><td>
|
|
<p><code>
|
|
CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)<br>
|
|
<br>
|
|
my_plugin_1.so: my_plugin_1.c<br>
|
|
$(CC) -shared $(CFLAGS) -o $@ $<<br>
|
|
<br>
|
|
my_plugin_2.so: my_plugin_2.c<br>
|
|
$(CC) -shared $(CFLAGS) -o $@ $<
|
|
</code></p>
|
|
</td></tr></table></blockquote>
|
|
|
|
<p>As before, there are lines that define the command "<code>make</code>"
|
|
should run when it determines that it needs to (re)compile the
|
|
"<code>.so</code>" file(s). However, more general terms are used...</p>
|
|
|
|
<p>"<code>$(CC)</code>" gets expanded to your default C compiler (e.g.,
|
|
"<code>gcc</code>"). "<code>-shared</code> and "<code>$(CFLAGS)</code>"
|
|
are command-line arguments to the compiler, like above.
|
|
"<code>-o $@</code>" tells the C compiler what the output file
|
|
should be; "<code>make</code>" replaces "<code>$@</code>" with the name
|
|
of the target, in this case "<code>my_plugin_1.so</code>" or
|
|
"<code>my_plugin_2.so</code>". And finally,
|
|
the last argument is the C file to compile; "<code>make</code>" replaces
|
|
it with the target's dependency, in this case
|
|
"<code>my_plugin_1.c</code>" or "<code>my_plugin_2.c</code>".</p>
|
|
|
|
</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</code>" command-line tool, supplied as
|
|
part of Tux Paint — or in some cases, as part of a "Tux
|
|
Paint 'Magic' Tool Plugin Development package" — to determine
|
|
where your plugins' files should go.</p>
|
|
|
|
<h4>Shared Object</h4>
|
|
|
|
<blockquote>
|
|
|
|
<p>Use "<code>tp-magic-config --pluginprefix</code>"
|
|
to determine where the plugin shared object ("<code>.so</code>")
|
|
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., "<code>/usr/lib/tuxpaint/plugins</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<br>
|
|
</code></p>
|
|
</blockquote>
|
|
|
|
<p><b>Note:</b> See the <a href="#grave">note above regarding the
|
|
"<font size=+1><b>`</b></font>" (grave) character</a>.</p>
|
|
|
|
</blockquote>
|
|
|
|
<h4>Documentation</h4>
|
|
|
|
<blockquote>
|
|
<p>Use the "<code>tp-magic-config --plugindocprefix</code>"
|
|
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</p>
|
|
(e.g., "<code>/usr/share/doc/tuxpaint/magic-docs</code>").</p>
|
|
|
|
<p><b>Note:</b> It's best to include both HTML and plain-text versions
|
|
of your documentation. An "<code>html</code>" subdirectory exists within
|
|
the "<code>magic-docs</code>" directory, and is where the HTML versions
|
|
should go.</p>
|
|
|
|
<p>As stand-alone commands, using the BASH shell, for example:</p>
|
|
|
|
<blockquote>
|
|
<p><code>
|
|
# cp my_plugin.html `tp-magic-config --plugindocprefix`/html<br>
|
|
# cp my_plugin.txt `tp-magic-config --plugindocprefix`
|
|
</code></p>
|
|
</blockquote>
|
|
|
|
<p><b>Note:</b> See the <a href="#grave">note above regarding the
|
|
"<font size=+1><b>`</b></font>" (grave) character</a>.</p>
|
|
|
|
</blockquote>
|
|
|
|
<h4>Icons, Sounds and other Data Files</h4>
|
|
|
|
<blockquote>
|
|
|
|
<p>Use the "<code>tp-magic-config --dataprefix</code>"
|
|
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
|
|
"<code>data_directory</code>" string stored within the
|
|
"<code>magic_api</code>" structure that your plugin's functions receive.</p>
|
|
|
|
<p><b>Note:</b> Tux Paint's default Magic tool plugins install their
|
|
data within "<code>magic</code>" subdirectories of Tux Paint's
|
|
"<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>
|
|
|
|
<p><b>Note:</b> See the <a href="#grave">note above regarding the
|
|
"<font size=+1><b>`</b></font>" (grave) character</a>.</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>
|
|
PLUGINDOCPREFIX=$(shell tp-magic-config --plugindocprefix)<br>
|
|
DATAPREFIX=$(shell tp-magic-config --dataprefix)<br>
|
|
<br>
|
|
install:<br>
|
|
#<br>
|
|
# Install plugin<br>
|
|
mkdir -p $(PLUGINPREFIX)<br>
|
|
cp *.so $(PLUGINPREFIX)/<br>
|
|
chmod 644 $(PLUGINPREFIX)/*.so<br>
|
|
#<br>
|
|
# Install icons<br>
|
|
mkdir -p $(DATAPREFIX)/images/magic<br>
|
|
cp icons/*.png $(DATAPREFIX)/images/magic/<br>
|
|
chmod 644 $(DATAPREFIX)/images/magic/*.png<br>
|
|
#<br>
|
|
# Install sound effects<br>
|
|
mkdir -p $(DATAPREFIX)/sounds/magic<br>
|
|
cp sounds/*.ogg $(DATAPREFIX)/sounds/magic/<br>
|
|
chmod 644 $(DATAPREFIX)/sounds/magic/*.ogg<br>
|
|
#<br>
|
|
# Install docs<br>
|
|
mkdir -p $(PLUGINDOCPREFIX)/html<br>
|
|
cp docs/*.html $(PLUGINDOCPREFIX)/html/<br>
|
|
cp docs/*.txt $(PLUGINDOCPREFIX)/<br>
|
|
chmod 644 $(PLUGINDOCPREFIX)/html/*.html<br>
|
|
chmod 644 $(PLUGINDOCPREFIX)/*.txt<br>
|
|
</code></p>
|
|
</td></tr></table></blockquote>
|
|
|
|
<p>The first three lines set up Makefile variables that contain the
|
|
paths returned by the "<code>tp-magic-config</code>" command-line tool.
|
|
(The "<code>$(shell ...)</code>" directive is similar to the
|
|
<a href="#grave"><b><font size=+1>`</font></b> ("grave")</a> character
|
|
in the BASH shell examples, above.)</p>
|
|
|
|
<p>Below that is an "<code>install</code>" target in the Makefile.
|
|
(Invoked by, for example, "<code>$ sudo make install</code>"
|
|
or "<code># make install</code>".)</p>
|
|
|
|
<p>The "<code>install</code>" target uses "<code>mkdir -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>" images) and sound effects
|
|
("<code>.ogg</code>" files) into subdirectories within Tux Paint's
|
|
data directory, and to install documentation
|
|
("<code>.html</code>" and "<code>.txt</code>" files) within Tux Paint's
|
|
documentation directory.</p>
|
|
|
|
</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="multiple">Creating plugins with multiple effects</a></h2>
|
|
|
|
<blockquote>
|
|
<p>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.</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>
|
|
ONE_TOOL,<br>
|
|
ANOTHER_TOOL,<br>
|
|
AND_YET_ANOTHER_TOOL,<br>
|
|
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>
|
|
"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 < NUM_TOOLS; i++)<br>
|
|
{<br>
|
|
/* Becomes, for example, "/usr/share/tuxpaint/sounds/magic/one.ogg" */<br>
|
|
<br>
|
|
snprintf(fname, sizeof(fname), "%s/sounds/magic/%s",<br>
|
|
api->data_prefix, my_plugin_snd_filenames[i];<br>
|
|
<br>
|
|
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>
|
|
<blockquote><code>
|
|
int i;<br>
|
|
<br>
|
|
for (i = 0; i < NUM_TOOLS; i++)<br>
|
|
Mix_FreeChunk(my_plugin_snds[i]);
|
|
</code></blockquote>
|
|
|
|
<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>
|
|
|
|
<h2>Example Code</h2>
|
|
|
|
<blockquote>
|
|
<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>
|
|
|
|
<h2>Getting Help</h2>
|
|
|
|
<blockquote>
|
|
|
|
<p>For more information, check the Tux Paint website:
|
|
<a href="http://www.tuxpaint.org/">http://www.tuxpaint.org/</a>,
|
|
and the Simple DirectMedia Layer library website:
|
|
<a href="http://www.libsdl.org/">http://www.libsdl.org/</a>.</p>
|
|
|
|
<p>Additionally, other Tux 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><a name="glossary">Glossary</a></h2>
|
|
|
|
<ul>
|
|
<li><b>alpha:</b> See "RGBA"
|
|
<li><b>&:</b> See "ampersand"
|
|
<li><b>ampersand:</b> "<code>&</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 i;</code>". Later, "<code>&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>-></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 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 RADIUS 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>gcc:</b> <i>TBD</i> (See also the "<code>gcc(1)</code>" <i>man page</i>)
|
|
<li><b>GNU C Compiler:</b> See "gcc"
|
|
<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>->:</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 *</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 Paint.
|
|
<li><b>make:</b> <i>TBD</i>
|
|
<li><b>Makefile:</b> <i>TBD</i>
|
|
<li><b>Magic tool</b>: One of a number of effects or drawing tools in Tux Paint, made available via the "Magic" tool button.
|
|
<li><b>Mix_Chunk *:</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 *</code>").
|
|
<li><b>Mix_LoadWAV():</b> An SDL_mixer function that loads a sound file (WAV, Ogg Vorbis, etc.) and returns it as a "<code>Mix_Chunk *</code>".
|
|
<li><b>namespace:</b> <i>TBD</i>
|
|
<li><b>OGG</b>: See "Ogg Vorbis"
|
|
<li><b>Ogg Vorbis:</b> <i>TBD</i> (See also: "WAV")
|
|
<li><b>Plugin</b>: <i>TBD</i>
|
|
<li><b>PNG:</b> <i>TBD</i> (See also the "<code>png(5)</code> <i>man page</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 *</code>"). (See also the "<code>SDL_FreeSurface(3)</code>" <i>man page</i>)
|
|
<li><b>SDL_GetRGB():</b> A libSDL function that, given a <code>Uint32</code> pixel value (e.g., one returned from the Tux 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, x, y), surf->format, &r, &g, &b);</code>".) (See also the "<code>SDL_GetRGB(3)</code>" <i>man page</i>)
|
|
<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 Paint's Magic tool API helper function "<code>putpixel()</code>"). (Example: "<code>putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));</code>".) (See also the "<code>SDL_MapRGB(3)</code>" <i>man page</i>)
|
|
<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 *</code>".
|
|
<li><b>SDL_mixer:</b> 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).
|
|
<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). (See also the "<code>SDL_Rect(3)</code>" <i>man page</i>)
|
|
<li><b>SDL_Surface *:</b> (A pointer to) a C structure defined by libSDL that contains a drawing surface. (See also the "<code>SDL_Surface(3)</code>" <i>man page</i>)
|
|
<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. (See also: <a href="http://www.libsdl.org/">http://www.libsdl.org/</a>)
|
|
<li><b>snprintf():</b> <i>TBD</i> (See also the "<code>snprintf(3)</code>" <i>man page</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 * 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 = 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 *</code>" pointer to the new copy. (See also the "<code>strdup(3)</code>" <i>man page</i>)
|
|
<li><b>struct:</b> See "C structure"
|
|
<li><b>The GIMP</b>: An Open Source image manipulation and paint program.
|
|
<li><b>tp_magic_api.h:</b> A header file that defines Tux 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 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). (See also the "<code>tp-magic-config(3)</code>" <i>man page</i>.)
|
|
<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> (See also "Ogg Vorbis")
|
|
<li><b>(w,h):</b> See "Dimensions"
|
|
<li><b>(x,y):</b> See "Coordinates"
|
|
</ul>
|
|
|
|
</body></html>
|
|
|