1224 lines
56 KiB
Text
1224 lines
56 KiB
Text
Tux Paint
|
|
version 0.9.30
|
|
|
|
Magic Tool Plugin API Documentation
|
|
|
|
Copyright © 2007-2023 by various contributors; see AUTHORS.txt.
|
|
https://tuxpaint.org/
|
|
|
|
Abril 9, 2023
|
|
|
|
+----------------------------------------------------+
|
|
|Table of Contents |
|
|
|----------------------------------------------------|
|
|
| * Prequisites |
|
|
| * Interfaces |
|
|
| * 'Magic' tool plugin functions |
|
|
| * Common arguments to plugin functions |
|
|
| * Required Plugin Functions |
|
|
| * Plugin "housekeeping" functions |
|
|
| * Plugin event functions |
|
|
| * Tux Paint Functions and Data |
|
|
| * Pixel Manipulations |
|
|
| * Helper Functions |
|
|
| * Informational |
|
|
| * Tux Paint System Calls |
|
|
| * Color Conversions |
|
|
| * Helper Macros in "tp_magic_api.h" |
|
|
| * Constant Definitions in "tp_magic_api.h" |
|
|
| * Compiling |
|
|
| * Linux and other Unix-like Platforms |
|
|
| * Windows |
|
|
| * macOS |
|
|
| * Installing |
|
|
| * Linux and other Unix-like Platforms |
|
|
| * Windows |
|
|
| * macOS |
|
|
| * Creating plugins with multiple effects |
|
|
| * Example Code |
|
|
| * Getting Help |
|
|
| * Glossary |
|
|
+----------------------------------------------------+
|
|
|
|
Overview
|
|
|
|
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.
|
|
|
|
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)
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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:
|
|
* MODE_PAINT - freehand paint (click and drag)
|
|
* MODE_FULLSCREEN - applies to full image with one click
|
|
* MODE_PAINT_WITH_PREVIEW - freehand paint, with preview (click
|
|
and drag)
|
|
* 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":
|
|
* MAGIC_TYPE_DISTORTS — Tools that distort the shape of the
|
|
image, like Blur, Emboss, and Ripples
|
|
* MAGIC_TYPE_COLOR_FILTERS — Tools that mostly affect the
|
|
colors of the image without distortion, like Darken,
|
|
Negative, and Tint
|
|
* MAGIC_TYPE_PICTURE_WARPS — Tools that warp or move the entire
|
|
picture, like Shift, Flip, and Waves
|
|
* MAGIC_TYPE_PAINTING — Tools that generally paint new content
|
|
at the cursor position, like Grass, Bricks, and Rails
|
|
* MAGIC_TYPE_PATTERN_PAINTING — Tools that paint in multiple
|
|
places at once, like Kaleidoscope and the Symmetry tools
|
|
* MAGIC_TYPE_PICTURE_DECORATIONS — Tools that apply decorations
|
|
to the entire picture, like Blinds and Checkboard
|
|
* 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()").
|
|
|
|
int accepted_sizes(magic_api * api, int which)
|
|
|
|
Return how many size variations the 'Magic' tool accepts. Return a
|
|
'0' if the 'Magic' tool should not offer sizing options. Returning
|
|
'1' is the same as returning '0'.
|
|
|
|
Note: Called once for each Magic tool your plugin claims to
|
|
contain (by your "get_tool_count()").
|
|
|
|
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, 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.30").
|
|
|
|
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/").
|
|
|
|
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 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).
|
|
|
|
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.
|
|
|
|
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 Defintions in "tp_magic_api.h"
|
|
|
|
The following is a summary of constant values that are set (via "#define")
|
|
within the 'Magic' tool API header file.
|
|
|
|
TP_MAGIC_API_VERSION
|
|
|
|
This integer value represents which version of the Tux Paint
|
|
'Magic' tool API the header corresponds to.
|
|
|
|
It should be referenced by your magic tool's "api_version()"
|
|
function, to inform the running copy of Tux Paint whether or not
|
|
your plugin is compatible.
|
|
|
|
Note: This version number does not correspond to Tux Paint's own
|
|
release number (e.g., "0.9.30"). 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 `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:
|
|
* Use a C "enum" to enumerate the effects, and count them.
|
|
|
|
enum {
|
|
ONE_TOOL,
|
|
ANOTHER_TOOL,
|
|
AND_YET_ANOTHER_TOOL,
|
|
NUM_TOOLS };
|
|
|
|
* Return the value of "NUM_TOOLS" when "get_tool_count()" is called, and
|
|
compare "which" values sent to other functions with the other
|
|
enumerated values.
|
|
* Create arrays of "NUM_TOOLS" length to contain effect-specific data.
|
|
|
|
char * my_plugin_snd_filenames[NUM_TOOLS] = {
|
|
"one.ogg", "another.ogg", "yet_another.ogg" };
|
|
Mix_Chunk * my_plugin_snds[NUM_TOOLS]") ?>;
|
|
|
|
* Use a C "for"-loop to load or create the effect-specific data (such as
|
|
loading sound effects during your "init()").
|
|
|
|
int i;
|
|
char fname[1024];
|
|
|
|
for (i = 0; i < NUM_TOOLS; i++)
|
|
{
|
|
/* 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);
|
|
}
|
|
|
|
* 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]);
|
|
|
|
* 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
|
|
|
|
* alpha: See "RGBA"
|
|
* &: See "ampersand"
|
|
* ampersand: "&". A symbol in C that allows you to refer to the memory
|
|
address of a variable; that is, a pointer. (For example, consider "int
|
|
i;". Later, "&i" refers to the memory where "i" is stored, not the
|
|
value of "i" itself; it is a 'pointer to "i"'.) See also: "star"
|
|
* API: Application Programming Interface. TBD
|
|
* argument: A value sent to a function.
|
|
* arrow: "->". A symbol in C that references an element within a pointer
|
|
to a struct.
|
|
* backquote: See "grave"
|
|
* backtick: See "grave"
|
|
* 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 "boolean 'or'"
|
|
* .: See "dot"
|
|
* `: See "grave"
|
|
* *: See "star"
|
|
* 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.
|
|
* callback: TBD
|
|
* 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: TBD
|
|
* C function prototype: TBD
|
|
* C header file: TBD
|
|
* channel: TBD
|
|
* click: The action of pressing a button on a mouse.
|
|
* 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.
|
|
* 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).
|
|
* #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.
|
|
* drag: The action of moving a mouse while the button remains held.
|
|
* element: A variable stored within a C structure. (Example: "w" and "h"
|
|
elements of SDL_Surface store the surface's width and height,
|
|
respectively.)
|
|
* enum: See "C enumeration"
|
|
* float: See "floating point"
|
|
* floating point: TBD
|
|
* format: 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). See also the
|
|
"SDL_PixelFormat(3)" man page)
|
|
* free(): A C function that frees (deallocates) memory allocated by
|
|
other C functions (such as "strdup()").
|
|
* function: See "C function"
|
|
* gcc: The GNU C compiler, a portable Open Source compiler. See also the
|
|
"gcc(1)" man page)
|
|
* GIMP: An Open Source image manipulation and paint program.
|
|
* GNU C Compiler: See "gcc"
|
|
* grave: The "`" character; used by the BASH shell to use the output of
|
|
a command as the command-line arguments to another.
|
|
* green: See "RGBA"
|
|
* ->: See "arrow"
|
|
* .h: See "C header file"
|
|
* header: See "C header file"
|
|
* header file: See "C header file"
|
|
* HSV: Hue, Saturation and Value. TBD
|
|
* hue: See "HSV"
|
|
* IMG_Load(): An SDL_image function that loads an image file (e.g., a
|
|
PNG) and returns it as an "SDL_Surface *".
|
|
* #include: A C statement that asks the compiler to read the contents of
|
|
another file (usually a header file).
|
|
* int: See "integer"
|
|
* integer: TBD
|
|
* libSDL: See "Simple DirectMedia Layer"
|
|
* linear: TBD
|
|
* macro: 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_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.)
|
|
* Magic tool: One of a number of effects or drawing tools in Tux Paint,
|
|
made available via the "Magic" tool button.
|
|
* Mix_Chunk *: (A pointer to) a C structure defined by SDL_mixer that
|
|
contains a sound.
|
|
* Mix_FreeChunk(): An SDL_mixer function that frees (deallocates) memory
|
|
allocated for an SDL_mixer sound 'chunk' ("Mix_Chunk *").
|
|
* Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg
|
|
Vorbis, etc.) and returns it as a "Mix_Chunk *".
|
|
* namespace: TBD
|
|
* .ogg: See "Ogg Vorbis"
|
|
* Ogg Vorbis: See also: "WAV"
|
|
* Plugin: TBD
|
|
* .png: 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. See also the "png(5)" man page)
|
|
* pointer: See "C pointer"
|
|
* prototype: See "C function prototype"
|
|
* red: See "RGBA"
|
|
* release: The action of releasing a button on a mouse.
|
|
* RGBA: "Red, Green, Blue, Alpha." TBD
|
|
* RGB: See "RGBA"
|
|
* saturation: See "HSV"
|
|
* SDL: See "Simple DirectMedia Layer"
|
|
* SDL_FreeSurface(): An libSDL function that frees (deallocates) memory
|
|
allocated for an SDL surface ("SDL_Surface *"). See also the
|
|
"SDL_FreeSurface(3)" man page)
|
|
* 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);".) See also the "SDL_GetRGB(3)" man page)
|
|
* 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));".)
|
|
See also the "SDL_MapRGB(3)" man page)
|
|
* SDL_image: A library on top of libSDL that can load various kinds of
|
|
image files (e.g., PNG) and return them as an "SDL_Surface *".
|
|
* SDL_mixer: A library on top of libSDL that can load various kinds of
|
|
sound files (WAV, Ogg Vorbis, etc.) and play back multiple sounds at
|
|
once (mix them).
|
|
* SDL_Rect: A C structure defined by libSDL that represents a
|
|
rectangular area. It contains elements representing the coordinates of
|
|
the top left corner of the rectange (x,y) and the dimensions of the
|
|
rectangle (w,h). See also the "SDL_Rect(3)" man page)
|
|
* SDL_Surface *: (A pointer to) a C structure defined by libSDL that
|
|
contains a drawing surface. See also 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.
|
|
* Simple DirectMedia Layer: A programming library that allows programs
|
|
portable low level access to a video framebuffer, audio output, mouse,
|
|
and keyboard. (See also: 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'. See also the
|
|
"snprintf(3)" man page)
|
|
* .so: See "Shared Object"
|
|
* sRBG: See "RGBA"
|
|
* star: "*". A symbol in C that, when used in the declaration of
|
|
variables (e.g., arguments to a function), denotes that the variable
|
|
is a pointer. (For example, "int * p;" means that "p" is a pointer to
|
|
an integer.) When used next to a pointer, it 'dereferences' the
|
|
variable. (For example, later "*p = 50;" assigns the value of 50 to
|
|
the memory that "p" points to; it does not change the value of "p",
|
|
which is still a pointer to an integer. In essence, it changed the
|
|
integer that's being pointed to.) 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. See also the "strdup(3)" man page)
|
|
* struct: See "C structure"
|
|
* tp_magic_api.h: A header file that defines Tux Paint's Magic tool API.
|
|
Plugins must '#include' it.
|
|
* tp-magic-config: A command-line program that provides information
|
|
about the installed version of Tux Paint to plugin developers (such as
|
|
what C compiler flags they should compile with, and where plugin
|
|
shared objects and data files should be installed). See also the
|
|
"tp-magic-config(3)" man page)
|
|
* Uint32: A 32-bit, unsigned integer (defined by libSDL). In other
|
|
words, four bytes that can represent 0 through 4294967295. (Typically
|
|
used to hold enough information to store three or four bytes
|
|
representing a pixel's color; i.e., RBGA value).
|
|
* Uint8: An 8-bit, unsigned integer (defined by libSDL). In other words,
|
|
a byte that can represent 0 through 255.
|
|
* unsigned: 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).
|
|
* 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 a;". It can be
|
|
examined later: "if (a >= 18) { /* they are an adult */ } else { /*
|
|
they are not an adult */ }".
|
|
* .wav: See also: "Ogg Vorbis"
|
|
* (w,h): See "Dimensions"
|
|
* (x,y): See "Coordinates"
|