1659 lines
65 KiB
Text
1659 lines
65 KiB
Text
Tux Paint
|
|
version 0.9.35
|
|
|
|
### Magic Tool Plugin API Documentation ###
|
|
|
|
Copyright © 2007-2025 by various contributors; see AUTHORS.txt.
|
|
https://tuxpaint.org/
|
|
|
|
January 12, 2025
|
|
|
|
+--------------------------------------------------+
|
|
| Table of Contents |
|
|
|--------------------------------------------------|
|
|
| * Prequisites |
|
|
| * Interfaces |
|
|
| + 'Magic' tool plugin functions |
|
|
| o Common arguments to plugin functions |
|
|
| o Required Plugin Functions |
|
|
| # Plugin "housekeeping" functions |
|
|
| # Plugin event functions |
|
|
| + Tux Paint Functions and Data |
|
|
| o Pixel Manipulations |
|
|
| o Helper Functions |
|
|
| o Informational |
|
|
| o Sound Functions |
|
|
| o Tux Paint System Calls |
|
|
| o Color Conversions |
|
|
| + Helper Macros in "tp_magic_api.h" |
|
|
| + Constant Definitions in "tp_magic_api.h" |
|
|
| * Compiling |
|
|
| + Linux and other Unix-like Platforms |
|
|
| + Windows |
|
|
| + macOS |
|
|
| * Installing |
|
|
| + Linux and other Unix-like Platforms |
|
|
| + Windows |
|
|
| + macOS |
|
|
| * Creating plugins with multiple effects |
|
|
| * Example Code |
|
|
| * Getting Help |
|
|
| * Glossary |
|
|
+--------------------------------------------------+
|
|
|
|
Overview
|
|
|
|
Tux Paint's 'Magic' tools come as a set of 'plugins' which are loaded when Tux
|
|
Paint starts up.
|
|
|
|
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 GIMP, should be familiar with this plugin concept.)
|
|
|
|
Prerequisites
|
|
|
|
Tux Paint is written in the C programming language, and uses the Simple
|
|
DirectMedia Layer library ('libSDL', or simply 'SDL'; available from https://
|
|
www.libsdl.org/). 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.
|
|
|
|
Interfaces
|
|
|
|
Those who create 'Magic' tool plugins for Tux Paint must provide some
|
|
interfaces (C functions) that Tux Paint may invoke.
|
|
|
|
Tux Paint utilizes SDL's "SDL_LoadObject()" and "SDL_LoadFunction()" routines
|
|
to load plugins (shared objects files; e.g., ".so" files on Linux or ".dll"
|
|
files on Windows) and find the functions within.
|
|
|
|
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
|
|
"struct") 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.
|
|
|
|
Plugins should #include the C header file "tp_magic_api.h", 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 "tp-magic-config" 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 "Compiling",
|
|
below.)
|
|
|
|
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".
|
|
|
|
### 'Magic' tool plugin functions ###
|
|
|
|
'Magic' tool plugins must contain the functions listed below. Note: 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 "blur_"). This includes private functions (ones not used by
|
|
Tux Paint directly), unless you declare those as 'static'.
|
|
|
|
## Common arguments to plugin functions ##
|
|
|
|
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).
|
|
|
|
|
|
## Required Plugin Functions ##
|
|
|
|
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(...)").
|
|
|
|
# Plugin "housekeeping" functions #
|
|
|
|
→ Uint32 api_version(void) ←
|
|
|
|
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 TP_MAGIC_API_VERSION, which is defined
|
|
in "tp_magic_api.h". If Tux Paint deems your plugin to be compatible, it
|
|
will go ahead and use it.
|
|
|
|
Note: Called once by Tux Paint, at startup. It is called first.
|
|
|
|
|
|
|
|
→ int init(magic_api * api, Uint8 disabled_features, Uint8 complexity_level) ←
|
|
|
|
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).
|
|
|
|
Note: Called once by Tux Paint, at startup. It is called after "api_version
|
|
()", if Tux Paint believes your plugin to be compatible.
|
|
|
|
The disabled_features value contains bits set for any Tux Paint features
|
|
relevant to Magic tools which have been disabled in this session. Test
|
|
using the C bitwise 'and' operator, '&'. The features are defined in
|
|
tp_magic_api.h:
|
|
o MAGIC_FEATURE_CONTROL: Magic tool controls (paint vs fullscreen)
|
|
(--nomagiccontrols)
|
|
o MAGIC_FEATURE_SIZE: Magic tool size (--nomagicsizes)
|
|
Your Magic tool(s) may wish to react differently depending on whether one
|
|
or more features have been disabled. (For example, the "Brick" Magic tool
|
|
always offered two tool variations: large and small. With the addition of
|
|
the size feature, only one tool is necessary. However, with the size option
|
|
disabled, the plugin is able to revert back to providing two separate
|
|
tools.)
|
|
|
|
The complexity_level variable contains the "complexity level" that Tux
|
|
Paint magic tools may offer — that is, the expertise level of the user. The
|
|
levels are defined in tp_magic_api.h:
|
|
o MAGIC_COMPLEXITY_NOVICE (0): Novice (--complexity=novice)
|
|
o MAGIC_COMPLEXITY_BEGINNER (1): Beginner (--complexity=beginner)
|
|
o MAGIC_COMPLEXITY_ADVANCED (2): Advanced (default) (--complexity=
|
|
advanced)
|
|
Your Magic tool(s) may wish to react differently depending on the expertise
|
|
level of the user, either simplifying how each tool works, or excluding one
|
|
or all of them entirely. (For example, the 1-, 2-, and 3-point perspective
|
|
toolsets are totally inactive when in "novice" mode. In "beginner" mode,
|
|
the drawing tools are available, but the tools to edit the vanishing point
|
|
positions are disabled; the default vanishing points are used. In fact, in
|
|
"beginner" mode, an additional 3-point perspective drawing tool appears,
|
|
with alternative vanishing points.)
|
|
|
|
Note: Changed most recently in Tux Paint 0.9.32; Magic API version
|
|
0x00000009.
|
|
|
|
|
|
|
|
→ int get_tool_count(magic_api * api) ←
|
|
|
|
This should return the number of Magic tools this plugin provides to Tux
|
|
Paint.
|
|
|
|
Note: Called once by Tux Paint, at startup. It is called after your "init()
|
|
", if it succeeded.
|
|
|
|
Note: You may wish to resond differently, based on whether certain features
|
|
have been disabled (e.g., 'paint' versus 'entire picture' controls, or
|
|
'Magic sizes' controls).
|
|
|
|
|
|
|
|
→ int modes(magic_api * api, int which) ←
|
|
|
|
This lets you tell Tux Paint what modes your tool can be used in; either as
|
|
a tool the user can paint with, or a tool that affects the entire drawing
|
|
at once.
|
|
|
|
You must return a value that's some combination of one or more of available
|
|
modes:
|
|
o MODE_PAINT - freehand paint (click and drag)
|
|
o MODE_FULLSCREEN - applies to full image with one click
|
|
o MODE_PAINT_WITH_PREVIEW - freehand paint, with preview (click and drag)
|
|
o MODE_ONECLICK - applies to an area around the mouse, with one click
|
|
e.g., if your tool is only one that the user can paint with, return
|
|
"MODE_PAINT". If the user can do both, return "MODE_PAINT |
|
|
MODE_FULLSCREEN" to tell Tux Paint it can do both.
|
|
|
|
Note: Called once for each Magic tool your plugin claims to contain (by
|
|
your "get_tool_count()").
|
|
|
|
Note: Added to Tux Paint 0.9.21; Magic API version 0x00000002.
|
|
|
|
|
|
|
|
→ char * get_name(magic_api * api, int which) ←
|
|
|
|
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.
|
|
|
|
Tux Paint will free() the string upon exit, so you should wrap it in a C
|
|
strdup() call.
|
|
|
|
Note: Called once for each Magic tool your plugin claims to contain (by
|
|
your "get_tool_count()").
|
|
|
|
|
|
|
|
→ int get_group(magic_api * api, int which) ←
|
|
|
|
Use this to group tools together within sections of the 'Magic' selector. A
|
|
number of groups are pre-defined within an enum found in "tp_magic_api.h":
|
|
o MAGIC_TYPE_DISTORTS — Tools that distort the shape of the image, like
|
|
Blur, Emboss, and Ripples
|
|
o MAGIC_TYPE_COLOR_FILTERS — Tools that mostly affect the colors of the
|
|
image without distortion, like Darken, Negative, and Tint
|
|
o MAGIC_TYPE_PICTURE_WARPS — Tools that warp or move the entire picture,
|
|
like Shift, Flip, and Waves
|
|
o MAGIC_TYPE_PAINTING — Tools that generally paint new content at the
|
|
cursor position, like Grass, Bricks, and Rails
|
|
o MAGIC_TYPE_PATTERN_PAINTING — Tools that paint in multiple places at
|
|
once, like Kaleidoscope and the Symmetry tools
|
|
o MAGIC_TYPE_PICTURE_DECORATIONS — Tools that apply decorations to the
|
|
entire picture, like Blinds and Checkboard
|
|
o MAGIC_TYPE_ARTISTIC — Special-purpose artistic tools, like Flower, the
|
|
String tools, and the Rainbow-arc-drawing tools.
|
|
|
|
Note: Called once for each Magic tool your plugin claims to contain (by
|
|
your "get_tool_count()").
|
|
|
|
Note: Added to Tux Paint 0.9.27; Magic API version 0x00000005.
|
|
|
|
|
|
|
|
→ SDL_Surface * get_icon(magic_api * api, int which) ←
|
|
|
|
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.
|
|
|
|
Tux Paint will free ("SDL_FreeSurface()") the surface upon exit.
|
|
|
|
Note: Called once for each Magic tool your plugin claims to contain (by
|
|
your "get_tool_count()").
|
|
|
|
|
|
|
|
→ char * get_description(magic_api * api, int which, int mode) ←
|
|
|
|
This should return a string containing the description of how to use a
|
|
particular magic tool. This will appear as a help tip, explained by Tux the
|
|
Penguin, within Tux Paint.
|
|
|
|
Tux Paint will free() the string upon exit, so you should wrap it in a C
|
|
strdup() call.
|
|
|
|
Note: For each Magic tool your plugin claims to contain (reported by your
|
|
"get_tool_count()" function), this function will be called for each mode
|
|
the tool claims to support (reported by your "modes()" function).
|
|
|
|
In other words, if your plugin contains two tools, one which works in paint
|
|
mode only, and the other that works in both paint mode and full-image mode,
|
|
your plugin's "get_description()" will be called three times.
|
|
|
|
|
|
|
|
→ int requires_colors(magic_api * api, int which) ←
|
|
|
|
Return a '1' if the 'Magic' tool accepts colors (the 'Colors' palette in
|
|
Tux Paint will be available), or '0' if not.
|
|
|
|
Note: Called once for each Magic tool your plugin claims to contain (by
|
|
your "get_tool_count()").
|
|
|
|
|
|
|
|
→ Uint8 accepted_sizes(magic_api * api, int which, int mode) ←
|
|
|
|
Return how many size variations the 'Magic' tool accepts, in the given mode
|
|
(i.e., 'MODE_PAINT' or 'MODE_FULLSCREEN). Return a '0' if the 'Magic' tool
|
|
should not offer sizing options. Returning '1' is the same as returning
|
|
'0'.
|
|
|
|
Note: For each Magic tool your plugin claims to contain (reported by your
|
|
"get_tool_count()" function), this function will be called for each mode
|
|
the tool claims to support (reported by your "modes()" function).
|
|
|
|
Note: Added to Tux Paint 0.9.30; Magic API version 0x00000008.
|
|
|
|
|
|
|
|
→ Uint8 default_size(magic_api * api, int which, int mode) ←
|
|
|
|
Return the default size the 'Magic' tool should start out with, in the
|
|
given mode. This will be the default setting for the tool the first time it
|
|
is used during a Tux Paint session. If Tux Paint is being invoked with the
|
|
sizing option disabled, this will be the only size requested by Tux Paint.
|
|
Return a number between '1' and the amount you returned in accepted_sizes
|
|
().
|
|
|
|
Note: For each Magic tool your plugin claims to contain (reported by your
|
|
"get_tool_count()" function), this function will be called for each mode
|
|
the tool claims to support (reported by your "modes()" function).
|
|
|
|
Note: Added to Tux Paint 0.9.30; Magic API version 0x00000008.
|
|
|
|
|
|
|
|
→ void shutdown(magic_api * api) ←
|
|
|
|
The plugin should do any cleanup here. If you allocated any memory or used
|
|
SDL_Mixer to load any sounds during init(), for example, you should free()
|
|
the allocated memory and Mix_FreeChunk() the sounds here.
|
|
|
|
Note: This function is called once, when Tux Paint exits.
|
|
|
|
|
|
|
|
|
|
# Plugin event functions #
|
|
|
|
→ void switchin(magic_api * api, int which, int mode, SDL_Surface * snapshot,
|
|
SDL_Surface * canvas)
|
|
void switchout(magic_api * api, int which, int mode, SDL_Surface * snapshot,
|
|
SDL_Surface * canvas) ←
|
|
|
|
switchin() is called whenever one of the plugin's Magic tools becomes
|
|
active, and switchout() is called whenever one becomes inactive. This can
|
|
be because the user just clicked a specific Magic tool (the current one is
|
|
switched-out, and a new one is switched-in).
|
|
|
|
It can also happen when user leaves/returns from the selection of "Magic"
|
|
tools when doing some other activity (i.e., using a different tool, such as
|
|
"Text" or "Brush", activating a momentary tool, such as "Undo" and "Redo",
|
|
or returning from a dialog — possibly with a new picture when it switches
|
|
back — such as "Open", "New" or "Quit"). In this case, the same Magic tool
|
|
is first 'switched-out', and then 'switched-back-in', usually moments
|
|
later.
|
|
|
|
Finally, it can also happen when the user changes the 'mode' of a tool
|
|
(i.e., from paint mode to full-image mode). First switchout() is called for
|
|
the old mode, then switchin() is called for the new mode.
|
|
|
|
These functions allow users to interact in complicated was with Magic tools
|
|
(for example, a tool that lets the user draw multiple freehand strokes, and
|
|
then uses that as input such as handwriting — normally, the user could
|
|
click somewhere in the canvas to tell the Magic tool they are 'finished',
|
|
but if they switch to another tool, the Magic tool may want to undo any
|
|
temporary changes to the canvas).
|
|
|
|
These functions could also be used to streamline certain effects; a
|
|
behind-the-scenes copy of the entire canvas could be altered in some way
|
|
when the user first switches to the canvas, and then pieces of that copy
|
|
could be drawn on the canvas when they draw with the Magic tool.
|
|
|
|
Note: Added to Tux Paint 0.9.21; Magic API version 0x00000002.
|
|
|
|
|
|
|
|
→ void set_color(magic_api * api, int which, SDL_Surface * canvas, SDL_Surface
|
|
* last, Uint8 r, Uint8 g, Uint8 b, SDL_Rect * update_rect) ←
|
|
|
|
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.)
|
|
|
|
Generally, Magic tools will not alter the canvas in any way when receiving
|
|
an updated color, but it is possible. (For example, the "Zoom" and
|
|
"Perspective" tools apply effects which uses the current color choice as a
|
|
solid background. The effects may be adjusted with subsequent click/drag
|
|
operations, but you may also adjust the background color, without altering
|
|
the zoom level or perspective, by simply picking a new color.)
|
|
|
|
Note: Changed most recently in Tux Paint 0.9.29; Magic API version
|
|
0x00000007.
|
|
|
|
|
|
|
|
→ void set_size(magic_api * api, int which, int mode, SDL_Surface * canvas,
|
|
SDL_Surface * last, Uint8 size, SDL_Rect * update_rect) ←
|
|
|
|
Tux Paint will call this function to inform the plugin of the 'Magic' tool
|
|
size option chosen. (It will be called whenever one of the plugin's Magic
|
|
tools that accept sizes becomes active, and whenever the user picks a new
|
|
size while such a tool is currently active.)
|
|
|
|
Generally, Magic tools will not alter the canvas in any way when receiving
|
|
an updated size, but it is possible.
|
|
|
|
Note: Added to Tux Paint 0.9.30; Magic API version 0x00000008.
|
|
|
|
|
|
|
|
→ void click(magic_api * api, int which, int mode, SDL_Surface * snapshot,
|
|
SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect) ←
|
|
|
|
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, and you are told which 'mode' your tool
|
|
is in (i.e., 'MODE_PAINT' or 'MODE_FULLSCREEN).
|
|
|
|
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'.
|
|
|
|
The contents of the drawing canvas immediately prior to the mouse button
|
|
click is stored within the 'snapshot' canvas.
|
|
|
|
|
|
|
|
→ void drag(magic_api * api, int which, SDL_Surface * snapshot, SDL_Surface *
|
|
canvas, int ox, int oy, int x, int y, SDL_Rect * update_rect) ←
|
|
|
|
The plugin should apply the appropriate 'Magic' tool on the 'canvas'
|
|
surface. The (ox,oy) and (x,y) coordinates are the location of the mouse at
|
|
the beginning and end of the stroke.
|
|
|
|
Typically, plugins that let the user "draw" effects onto the canvas utilize
|
|
Tux Paint's "line()" '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 "Tux Paint
|
|
Functions and Data," below).
|
|
|
|
The plugin should report back what part of the canvas was affected, by
|
|
filling in the (x,y) and (w,h) elements of 'update_rect'.
|
|
|
|
Note: The contents of the drawing canvas immediately prior to the mouse
|
|
button click remains as it was (when the plugin's "click()" function was
|
|
called), and is still available in the 'snapshot' canvas.
|
|
|
|
|
|
|
|
→ void release(magic_api * api, int which, SDL_Surface * snapshot, SDL_Surface
|
|
* canvas, int x, int y, SDL_Rect * update_rect) ←
|
|
|
|
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.
|
|
|
|
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'.
|
|
|
|
Note: The contents of the drawing canvas immediately prior to the mouse
|
|
button click remains as it was (when the plugin's "click()" function was
|
|
called), and is still available in the 'snapshot' canvas.
|
|
|
|
|
|
|
|
|
|
### Tux Paint Functions and Data ###
|
|
|
|
Tux Paint provides a number of helper functions that plugins may access via the
|
|
"magic_api" structure, sent to all of the plugin's functions. (See "Required
|
|
Plugin Functions," above.)
|
|
|
|
## Pixel Manipulations ##
|
|
|
|
→ 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.)
|
|
|
|
|
|
## Helper Functions ##
|
|
|
|
→ 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.
|
|
|
|
|
|
|
|
|
|
## Informational ##
|
|
|
|
→ char * tp_version ←
|
|
A string containing the version of Tux Paint that's running (e.g.,
|
|
"0.9.35").
|
|
|
|
→ 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/").
|
|
|
|
|
|
|
|
|
|
## Sound Functions ##
|
|
|
|
→ 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.
|
|
|
|
|
|
|
|
|
|
## Tux Paint System Calls ##
|
|
|
|
→ 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.
|
|
|
|
|
|
|
|
|
|
## Color Conversions ##
|
|
|
|
→ 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.
|
|
|
|
### Helper Macros in "tp_magic_api.h" ###
|
|
|
|
Along with the "magic_api" C structure containing functions and data
|
|
described above, the tp_magic_api.h C header file also contains some helper
|
|
macros that you may use.
|
|
|
|
→ min(x, y)
|
|
max(x, y) ←
|
|
The minimum (min) or maxinum (max) of 'x' and 'y'. For example, min()
|
|
will return the value of 'x' if it is less than or equal to 'y',
|
|
otherwise it will return 'y'.
|
|
|
|
→ clamp(lo, value, hi) ←
|
|
|
|
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.)
|
|
|
|
Example: red = clamp(0, n, 255); will set the variable 'red' to be the
|
|
value of the variable 'n', but without allowing it to become less than
|
|
0 or greater than 255.
|
|
|
|
Note: This macro is simply a #define of: "(min(max(value,lo),hi))".
|
|
|
|
|
|
|
|
|
|
### Constant Definitions in "tp_magic_api.h" ###
|
|
|
|
The following is a summary of constant values that are set (via "#define")
|
|
within the 'Magic' tool API header file.
|
|
|
|
→ TP_MAGIC_API_VERSION ←
|
|
|
|
This integer value represents which version of the Tux Paint 'Magic'
|
|
tool API the header corresponds to.
|
|
|
|
It should be referenced by your magic tool's "api_version()" function,
|
|
to inform the running copy of Tux Paint whether or not your plugin is
|
|
compatible.
|
|
|
|
Note: This version number does not correspond to Tux Paint's own
|
|
release number (e.g., "0.9.35"). The API will not change every time a
|
|
new version of Tux Paint is released, which means plugins compiled for
|
|
earlier versions of Tux Paint will often run under newer versions.
|
|
|
|
|
|
|
|
→ SPECIAL_MIRROR
|
|
SPECIAL_FLIP ←
|
|
These are flags for Tux Paint's "special_notify()" helper function.
|
|
They are described above.
|
|
|
|
|
|
Compiling
|
|
|
|
### Linux and other Unix-like Platforms ###
|
|
|
|
Use the C compiler's "-shared" command-line option to generate a shared
|
|
object file (".so") based on your 'Magic' tool plugin's C source code.
|
|
|
|
Use the "tp-magic-config --cflags" 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.
|
|
|
|
## Command-Line Example ##
|
|
|
|
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 ...").
|
|
|
|
## Makefile Example ##
|
|
|
|
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.
|
|
|
|
## Advanced Makefile ##
|
|
|
|
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".
|
|
|
|
### Windows ###
|
|
|
|
TBD
|
|
|
|
### macOS ###
|
|
|
|
TBD
|
|
|
|
Installing
|
|
|
|
### Linux and other Unix-like Platforms ###
|
|
|
|
Use the "tp-magic-config" 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.
|
|
|
|
## Shared Object ##
|
|
|
|
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.
|
|
|
|
## Documentation ##
|
|
|
|
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
|
|
|
|
(e.g., "/usr/share/doc/tuxpaint/magic-docs").
|
|
|
|
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.
|
|
|
|
## Icons, Sounds and other Data Files ##
|
|
|
|
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.
|
|
|
|
## Putting it Together in a Makefile ##
|
|
|
|
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.
|
|
|
|
### Windows ###
|
|
|
|
TBD
|
|
|
|
### macOS ###
|
|
|
|
TBD
|
|
|
|
Creating plugins with multiple effects
|
|
|
|
Plugins for Tux Paint may contain more than one effect. If you have
|
|
multiple effects that are similar, it may make sense to place them in one
|
|
plugin file, to reduce overhead and share code.
|
|
|
|
These following suggestions can help you create plugins that contain
|
|
multiple effects:
|
|
o Use a C "enum" to enumerate the effects, and count them.
|
|
|
|
enum {
|
|
ONE_TOOL,
|
|
ANOTHER_TOOL,
|
|
AND_YET_ANOTHER_TOOL,
|
|
NUM_TOOLS };
|
|
|
|
o Return the value of "NUM_TOOLS" when "get_tool_count()" is called, and
|
|
compare "which" values sent to other functions with the other
|
|
enumerated values.
|
|
o Create arrays of "NUM_TOOLS" length to contain effect-specific data.
|
|
|
|
char * my_plugin_snd_filenames[NUM_TOOLS] = {
|
|
"one.ogg", "another.ogg", "yet_another.ogg" };
|
|
Mix_Chunk * my_plugin_snds[NUM_TOOLS]");
|
|
|
|
o Use a C "for"-loop to load or create the effect-specific data (such as
|
|
loading sound effects during your "init()").
|
|
|
|
int i;
|
|
char fname[1024];
|
|
|
|
for (i = 0; i < NUM_TOOLS; i++)
|
|
{
|
|
/* Becomes, for example, "/usr/share/tuxpaint/sounds/magic/
|
|
one.ogg" */
|
|
|
|
snprintf(fname, sizeof(fname), "%s/sounds/magic/%s",
|
|
api->data_prefix, my_plugin_snd_filenames[i]);
|
|
|
|
my_plugin_snds[i] = Mix_LoadWAV(fname);
|
|
}
|
|
|
|
o Similarly, do the same to free them later (such as freeing sound
|
|
effects during your "shutdown()").
|
|
|
|
int i;
|
|
|
|
for (i = 0; i < NUM_TOOLS; i++)
|
|
Mix_FreeChunk(my_plugin_snds[i]);
|
|
|
|
o Use "which" values sent to your functions as an index into those arrays
|
|
(e.g., for playing the appropriate sound effect for a tool).
|
|
|
|
Note: Even if your plugin currently contains only one effect, it may be
|
|
useful to follow the steps above so that you can add a new variation of an
|
|
effect with little effort. ("NUM_TOOLS" will simply be '1', your arrays
|
|
will be of length '1', etc.)
|
|
|
|
Example Code
|
|
|
|
The C source file "tp_magic_example.c" contains a complete example of a
|
|
plugin with multiple simple effects.
|
|
|
|
Getting Help
|
|
|
|
For more information, check the Tux Paint website: https://tuxpaint.org/,
|
|
and the Simple DirectMedia Layer library website: http://www.libsdl.org/.
|
|
|
|
Additionally, other Tux Paint developers and users can be found on the
|
|
"tuxpaint-devel" and "tuxpaint-users" mailing lists: https://tuxpaint.org/
|
|
lists/.
|
|
|
|
Glossary
|
|
|
|
→ & ←
|
|
See "ampersand"
|
|
|
|
→ * ←
|
|
See "star"
|
|
|
|
→ -> ←
|
|
See "arrow"
|
|
|
|
→ . ←
|
|
See "dot"
|
|
|
|
→ ` ←
|
|
See "grave"
|
|
|
|
→ alpha ←
|
|
See "RGBA"
|
|
|
|
→ ampersand (bitwise operator) ←
|
|
"&". A symbol in C that acts as a bitwise "and" operator. Only bits set
|
|
in both values will be returned. For example, "11 & 6" compares the
|
|
binary values '1011' to '0110'. Only the bit in the 2's place is set,
|
|
so the result is 2 ('0010').
|
|
See also: "bit"
|
|
|
|
→ ampersand (pointers) ←
|
|
"&". A symbol in C that allows you to refer to the memory address of a
|
|
variable; that is, a pointer. (For example, consider "int i;". Later, "
|
|
&i" refers to the memory where "i" is stored, not the value of "i"
|
|
itself; it is a 'pointer to "i"'.)
|
|
See also: "star"
|
|
|
|
→ API ←
|
|
Application Programming Interface. Definition not yet presented.
|
|
|
|
→ argument ←
|
|
A value sent to a function.
|
|
|
|
→ arrow ←
|
|
"->". A symbol in C that references an element within a pointer to a
|
|
struct.
|
|
|
|
→ backquote / backtick ←
|
|
See "grave"
|
|
|
|
→ BASH ←
|
|
The "Bourne Again Shell", a Unix shell and command language.
|
|
|
|
→ bit ←
|
|
"Binary digit." Bits are the basic storage unit in a computer's memory,
|
|
disk, networking, etc. They represent either 0 or 1. (Compared to a
|
|
decimal digit, which can be anything between 0 and 9.) Just as a series
|
|
of decimal digits can represent a larger number (e.g., "1" and "5" is
|
|
fifteen (15)), so can bits (e.g., "1" and "0", is two). In decimal, we
|
|
go from right to left: ones place, tens place, hundreds place,
|
|
thousands place, etc. In binary, it is: ones place, twos place, fours
|
|
place, eights place, etc.
|
|
See also: "byte"
|
|
|
|
→ blue ←
|
|
See "RGBA"
|
|
|
|
→ boolean 'or' ←
|
|
A mathematical operation that results in a true value if either operand
|
|
is true. ("1 | 0", "0 | 1" and "1 | 1" all result in "1". "0 | 0"
|
|
results in "0".)
|
|
See also: "bit"
|
|
|
|
→ byte ←
|
|
A unit of memory made up of 8 bits. As a signed value, it can represent
|
|
-128 through 127. As an unsigned value, it can represent 0 through 255.
|
|
As a series of bits, for example, the byte "00001100" represents the
|
|
decimal value 12.
|
|
See also: "bit"
|
|
|
|
→ C enumeration ←
|
|
A construct in C that allows you to label numeric values (usually
|
|
starting at 0 and incrementing by one). (e.g., "enum { ONE, TWO, THREE
|
|
};"
|
|
|
|
→ C function / C function prototype / C header file ←
|
|
Definition not yet presented.
|
|
See also: "C function prototype"
|
|
|
|
→ C pointer ←
|
|
A variable that contains the location of a piece of memory; usually
|
|
used to 'point' to another variable. Since C functions can only return
|
|
one value as a result, pointers are often sent to functions to allow
|
|
the function to change the values of multiple variables. (For example,
|
|
Tux Paint's "rgbtohsv()" and "hsvtorgb()".)
|
|
|
|
→ C structure ←
|
|
A construct in C that allows you to declare a new variable 'type' which
|
|
may contain other types within. For example, SDL's "SDL_Rect" contains
|
|
four integer values, the coordinates of the rectangle (X,Y), and its
|
|
dimensions (width and height).
|
|
|
|
→ callback / channel ←
|
|
Definition not yet presented.
|
|
|
|
→ click ←
|
|
The action of pressing a button on a mouse, tapping a touchscreen, or
|
|
pressing a stylus to a tablet.
|
|
See also:
|
|
@ drag
|
|
@ release
|
|
|
|
|
|
→ colorspace ←
|
|
Definition not yet presented.
|
|
See also:
|
|
@ RGBA
|
|
@ HSV
|
|
|
|
|
|
→ coordinates ←
|
|
A set of numbers corresponding to a physical position; for example, in
|
|
a two-dimensional (2D) image, "X" and "Y" coordinates specify the
|
|
position across (left-to-right) and down the image, respectively. In
|
|
SDL, the coordinates (0,0) is the top-leftmost pixel of a surface.
|
|
|
|
→ #define ←
|
|
A C statement that defines a substitution that can occur later in the
|
|
code. Generally used for constant values (e.g., "#define RADIUS 16";
|
|
all instances of "RADIUS" will be replaced with "16"), but can also be
|
|
used to create macros. Typically placed within C header files.
|
|
|
|
→ dimensions ←
|
|
The size of an object, in terms of its width (left to right) and height
|
|
(top to bottom).
|
|
|
|
→ .dll ←
|
|
See "Shared Object"
|
|
|
|
→ dot ←
|
|
".". A symbol in C that references an element within a struct.
|
|
See also:
|
|
@ C structure
|
|
@ arrow
|
|
|
|
|
|
→ drag ←
|
|
The action of moving a mouse while the button remains held, or moving a
|
|
finger or stylus across a screen or tablet, without removing it.
|
|
See also:
|
|
@ click
|
|
@ release
|
|
|
|
|
|
→ element ←
|
|
A variable stored within a C structure. (Example: "w" and "h" elements
|
|
of SDL_Surface store the surface's width and height, respectively.)
|
|
See also:
|
|
@ C structure
|
|
@ dot
|
|
@ arrow
|
|
|
|
|
|
→ enum ←
|
|
See "C enumeration"
|
|
|
|
→ float ←
|
|
See "floating point"
|
|
|
|
→ floating point ←
|
|
Definition not yet presented.
|
|
See also: "integer"
|
|
|
|
→ format ←
|
|
An SDL_Surface element (a pointer to an SDL_PixelFormat structure) that
|
|
contains information about a surface; for example, the number of bits
|
|
used to represent each pixel).
|
|
Refer to the "SDL_PixelFormat(3)" man page.
|
|
|
|
→ free() ←
|
|
A C function that frees (deallocates) memory allocated by other C
|
|
functions (such as "strdup()").
|
|
Refer to the "malloc(3)" man page.
|
|
|
|
→ function ←
|
|
See "C function"
|
|
|
|
→ gcc ←
|
|
See "GNU C Compiler"
|
|
|
|
→ GIMP ←
|
|
GNU Image Manipulation Program, an Open Source image manipulation and
|
|
paint program.
|
|
See also: "Krita"
|
|
|
|
→ GNU C Compiler ←
|
|
The GNU C compiler, a portable Open Source package for compiling and
|
|
linking programs written in the C programming language.
|
|
Refer to the "gcc(1)" man page.
|
|
|
|
→ grave ←
|
|
The "`" character; used by the BASH shell to use the output of a
|
|
command as the command-line arguments to another.
|
|
|
|
→ green ←
|
|
See "RGBA"
|
|
|
|
→ .h / header / header file ←
|
|
See "C header file"
|
|
|
|
→ HSV ←
|
|
Hue, Saturation and Value.Definition not yet presented.
|
|
See also:
|
|
@ RGBA
|
|
@ colorspace
|
|
|
|
|
|
→ hue ←
|
|
See "HSV"
|
|
|
|
→ IMG_Load() ←
|
|
An SDL_image function that loads an image file (e.g., a PNG) and
|
|
returns it as an "SDL_Surface *".
|
|
|
|
→ #include ←
|
|
A C statement that asks the compiler to read the contents of another
|
|
file (usually a header file).
|
|
|
|
→ int ←
|
|
See "integer"
|
|
|
|
→ integer ←
|
|
Definition not yet presented.
|
|
See also: "floating point"
|
|
|
|
→ Krita ←
|
|
An Open Source image manipulation and paint program.
|
|
See also: "GIMP"
|
|
|
|
→ libSDL ←
|
|
See "Simple DirectMedia Layer"
|
|
|
|
→ linear ←
|
|
Definition not yet presented.
|
|
|
|
→ macro ←
|
|
A C construct that looks similar to a C function, but is simply a #
|
|
define that is expanded 'inline'. For example, if you declared the
|
|
macro "#define ADD(A,B) ((A)+(B))", and then used it with "c = ADD
|
|
(1,2);", that line of code would literally expand to "c = ((1) + (2));
|
|
", or more simply, "c = 1 + 2;".
|
|
|
|
→ Magic tool ←
|
|
One of a number of effects or drawing tools in Tux Paint, made
|
|
available via the "Magic" tool button.
|
|
|
|
→ magic_api ←
|
|
A C structure that is passed along to a plugin's functions that exposes
|
|
data and functions within the running copy of Tux Paint.
|
|
|
|
→ make ←
|
|
A utility that automatically determines which pieces of a larger
|
|
program need to be recompiled, and issues the commands to recompile
|
|
them.
|
|
See also: "Makefile"
|
|
|
|
→ Makefile ←
|
|
A text file used by the "make" utility; it describes the relationships
|
|
among files in your program, and the commands for updating each file.
|
|
(For example, to compile a human-readable source-code file into a
|
|
computer-readable executable program file.)
|
|
|
|
→ Mix_Chunk * ←
|
|
(A pointer to) a C structure defined by SDL_mixer that contains a
|
|
sound.
|
|
|
|
→ Mix_FreeChunk() ←
|
|
An SDL_mixer function that frees (deallocates) memory allocated for an
|
|
SDL_mixer sound 'chunk' ("Mix_Chunk *").
|
|
|
|
→ Mix_LoadWAV() ←
|
|
An SDL_mixer function that loads a sound file (WAV, Ogg Vorbis, etc.)
|
|
and returns it as a "Mix_Chunk *".
|
|
|
|
→ namespace ←
|
|
Definition not yet presented.
|
|
|
|
→ .ogg ←
|
|
See "Ogg Vorbis"
|
|
|
|
→ Ogg Vorbis / plugin ←
|
|
Definition not yet presented.
|
|
See also: "WAVE"
|
|
|
|
→ .png ←
|
|
See "Portable Network Graphics"
|
|
|
|
→ pointer ←
|
|
See "C pointer"
|
|
|
|
→ Portable Network Graphics ←
|
|
Portable Network Graphics. An extensible file format for the lossless,
|
|
portable, well-compressed storage of raster images. It's the file
|
|
format Tux Paint uses to save images, and for its brushes and stamps.
|
|
It's an easy way to store 32bpp RGBA images (24bpp true color with full
|
|
8bpp alpha transparency), excellent for use in graphics programs like
|
|
Tux Paint.
|
|
Refer to the "png(5)" man page.
|
|
See also: "Scalable Vector Graphic"
|
|
|
|
→ prototype ←
|
|
See "C function prototype"
|
|
|
|
→ red ←
|
|
See "RGBA"
|
|
|
|
→ release ←
|
|
The action of releasing a mouse button, or removing a finger or stylus
|
|
from a screen or tablet.
|
|
See also:
|
|
@ click
|
|
@ drag
|
|
|
|
|
|
→ RGB ←
|
|
See "RGBA"
|
|
|
|
→ RGBA ←
|
|
Red, Green, Blue, and Alpha.Definition not yet presented.
|
|
See also:
|
|
@ HSV
|
|
@ colorspace
|
|
|
|
|
|
→ saturation ←
|
|
See "HSV"
|
|
|
|
→ SDL ←
|
|
See "Simple DirectMedia Layer"
|
|
|
|
→ SDL_FreeSurface() ←
|
|
A libSDL function that frees (deallocates) memory allocated for an SDL
|
|
surface ("SDL_Surface *").
|
|
|
|
→ SDL_GetRGB() ←
|
|
A libSDL function that, given a Uint32 pixel value (e.g., one returned
|
|
from the Tux Paint's Magic tool API helper function "getpixel()"), the
|
|
format of the surface the pixel was taken from, and pointers to three
|
|
Uint8 variables, will place the Red, Green and Blue (RGB) values of the
|
|
pixel into the three Uint8 variables. (Example: "SDL_GetRGB(getpixel
|
|
(surf, x, y), surf->format, &r, &g, &b);".)
|
|
Refer to the "SDL_GetRGB(3)" man page.
|
|
See also:
|
|
@ SDL_MapRGB()
|
|
@ RGBA
|
|
|
|
|
|
→ SDL_image ←
|
|
A library on top of libSDL that can load various kinds of image files
|
|
(e.g., PNG) and return them as an "SDL_Surface *".
|
|
|
|
→ SDL_MapRGB() ←
|
|
A libSDL function that, given the format of a surface and Uint8 values
|
|
representing Red, Green and Blue values for a pixel, returns a Uint32
|
|
pixel value that can be placed in the surface (e.g., using Tux Paint's
|
|
Magic tool API helper function "putpixel()"). (Example: "putpixel(surf,
|
|
x, y, SDL_MapRGB(surf->format, r, g, b));".)
|
|
Refer to the "SDL_MapRGB(3)" man page.
|
|
See also:
|
|
@ SDL_GetRGB()
|
|
@ RGBA
|
|
|
|
|
|
→ SDL_mixer ←
|
|
A library on top of libSDL that can load various kinds of sound files
|
|
(WAV, Ogg Vorbis, etc.) and play back multiple sounds at once (mix
|
|
them).
|
|
|
|
→ SDL_Rect ←
|
|
A C structure defined by libSDL that represents a rectangular area. It
|
|
contains elements representing the coordinates of the top left corner
|
|
of the rectange (x,y) and the dimensions of the rectangle (w,h).
|
|
Refer to the "SDL_Rect(3)" man page.
|
|
|
|
→ SDL_Surface * ←
|
|
(A pointer to) a C structure defined by libSDL that contains a drawing
|
|
surface.
|
|
Refer to the "SDL_Surface(3)" man page.
|
|
|
|
→ shared object ←
|
|
A piece of code that's compiled separately from the main application,
|
|
and loaded dynamically, at runtime.
|
|
|
|
→ shell ←
|
|
See "BASH"
|
|
|
|
→ Simple DirectMedia Layer ←
|
|
The Simple DirectMedia Layer (libSDL) is a programming library that
|
|
provides portable low-level access to a video framebuffer, audio
|
|
output, and mouse and keyboard input. (See: http://www.libsdl.org/)
|
|
|
|
→ snprintf() ←
|
|
A C function, related to "printf()", which takes a 'format' string and
|
|
one or more additional arguments, and puts them together. "snprintf()"
|
|
takes the resulting output and stores it into a string, making sure not
|
|
to go beyond the string's buffer size (which must also be supplied).
|
|
For example, assume a string "char str[20];" has been declared;
|
|
"snprintf(str, 20, "Name: %s, Age: %d", "Bill", 32);" will store "Name:
|
|
Bill, Age: 32" into 'str'.
|
|
Refer to the "sprintf(3)" man page.
|
|
|
|
→ .so ←
|
|
See "shared object"
|
|
|
|
→ sRGB ←
|
|
See "RGBA"
|
|
|
|
→ star ←
|
|
"*". A symbol in C that, when used in the declaration of variables
|
|
(e.g., arguments to a function), denotes that the variable is a
|
|
pointer. (For example, "int * p;" means that "p" is a pointer to an
|
|
integer.) When used next to a pointer, it 'dereferences' the variable.
|
|
(For example, later "*p = 50;" assigns the value of 50 to the memory
|
|
that "p" points to; it does not change the value of "p", which is still
|
|
a pointer to an integer. In essence, it changed the integer that's
|
|
being pointed to.)
|
|
See also: "ampersand"
|
|
|
|
→ strdup() ←
|
|
A C function that allocates enough memory to store a copy of a string,
|
|
copies the string to it, and returns a "char *" pointer to the new
|
|
copy.
|
|
Refer to the "strdup(3)" man page.
|
|
|
|
→ struct ←
|
|
See "C structure"
|
|
|
|
→ tap ←
|
|
See "click"
|
|
|
|
→ tp-magic-config ←
|
|
A command-line program that provides information about the installed
|
|
version of Tux Paint to plugin developers (such as what C compiler
|
|
flags they should compile with, and where plugin shared objects and
|
|
data files should be installed).
|
|
Refer to the "tp-magic-config(3)" man page.
|
|
|
|
→ tp_magic_api.h ←
|
|
A header file that defines Tux Paint's Magic tool API. Plugins must '#
|
|
include' it.
|
|
|
|
→ Uint32 ←
|
|
A 32-bit, unsigned integer (defined by libSDL). In other words, four
|
|
bytes that can represent 0 through 4,294,967,295. (Typically used to
|
|
hold enough information to store three or four bytes representing a
|
|
pixel's color; i.e., RBGA value).
|
|
See also:
|
|
@ Uint8
|
|
@ integer
|
|
@ unsigned
|
|
|
|
|
|
→ Uint8 ←
|
|
An 8-bit, unsigned integer (defined by libSDL). In other words, a byte
|
|
that can represent 0 through 255.
|
|
See also:
|
|
@ Uint32
|
|
@ integer
|
|
@ unsigned
|
|
|
|
|
|
→ unsigned ←
|
|
In C, a variable that can store a numeric value can be declared as
|
|
either "signed" (the default), or "unsigned". In the former case, one
|
|
bit of the value is used to denote the sign of the value (either
|
|
positive or negative). In the latter case, the value can only be
|
|
positive, but benefits from one extra bit of storage for the number. A
|
|
signed byte (8 bits), for example, can represent any number between
|
|
-128 and 127. An unsigned byte can go up to 255, but it cannot go below
|
|
0. For the purposes of graphics in SDL, unsigned values should be used
|
|
for RGB values, since each channel (red, green and blue) may be between
|
|
0 (off) and 255 (brightest).
|
|
See also:
|
|
@ Uint8
|
|
@ Uint32
|
|
@ integer
|
|
|
|
|
|
→ value ←
|
|
See "HSV"
|
|
|
|
→ variable ←
|
|
A construct in computer programming that contains a value which can be
|
|
referenced again later by referring to the variable's name, and
|
|
typically changed later. For example, a variable to hold someone's age
|
|
could be declared as an integer: "int age;". It can be examined later —
|
|
e.g., "if (age >= 18) { /* they are an adult */ } else { /* they are
|
|
not an adult */ }" — as well as modified later — e.g., age = 32; /* set
|
|
age to 32 */
|
|
|
|
→ (w,h) ←
|
|
See "dimensions"
|
|
|
|
→ .wav ←
|
|
See "WAVE"
|
|
|
|
→ WAVE ←
|
|
Waveform Audio File Format (WAVE, or WAV). Definition not yet
|
|
presented.
|
|
See also: "Ogg Vorbis"
|
|
|
|
→ (x,y) ←
|
|
See "coordinates"
|
|
|
|
→ | ←
|
|
See "boolean 'or'"
|
|
|