Added Makefile to convert HTML docs to plain text.
Recreated plain text docs based on HTML.
This commit is contained in:
William Kendrick
parent
674b28c7e4
commit
fbbfb2fafd
2 changed files with 268 additions and 99 deletions
21
magic/docs/Makefile
Normal file
21
magic/docs/Makefile
Normal file
|
|
@ -0,0 +1,21 @@
|
||||||
|
# Makefile for Tux Paint Magic Tool Plugin API docs
|
||||||
|
#
|
||||||
|
# Uses "links" to convert docs from HTML to plain text.
|
||||||
|
# (Normally only ran by the developers after updating the HTML, prior to
|
||||||
|
# release.)
|
||||||
|
#
|
||||||
|
# Bill Kendrick
|
||||||
|
# bill@newbreedsoftware.com
|
||||||
|
#
|
||||||
|
# July 6, 2007 - July 6, 2007
|
||||||
|
# $Id$
|
||||||
|
|
||||||
|
LINKS=links -dump -no-numbering -no-references
|
||||||
|
|
||||||
|
all: README.txt
|
||||||
|
|
||||||
|
clean:
|
||||||
|
-rm README.txt
|
||||||
|
|
||||||
|
README.txt: html/README.html
|
||||||
|
$(LINKS) $< > $@
|
||||||
|
|
@ -1,131 +1,279 @@
|
||||||
Stub docs for Tux Paint Magic Plugin Development
|
Creating Tux Paint Magic Tool Plugins
|
||||||
|
|
||||||
#include "tp_magic_api.h"
|
Copyright 2007-2007 by Bill Kendrick and others
|
||||||
|
New Breed Software
|
||||||
|
|
||||||
|
bill@newbreedsoftware.com
|
||||||
|
http://www.tuxpaint.org/
|
||||||
|
|
||||||
build plugins with:
|
July 5, 2007 - July 6, 2007
|
||||||
-------------------
|
|
||||||
Linux/Unix:
|
|
||||||
-----------
|
|
||||||
$(CC) -shared `tp-magic-config --cflags` plugin.c -o plugin.so
|
|
||||||
|
|
||||||
Then install globally into: /usr/[local/]lib/tuxpaint/.
|
--------------------------------------------------------------------------
|
||||||
Or locally into: ~/.tuxpaint/magic/ [[FIXME]]
|
|
||||||
|
|
||||||
Windows:
|
Overview
|
||||||
--------
|
|
||||||
??? [[FIXME]]
|
|
||||||
|
|
||||||
Mac OS X:
|
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
|
||||||
??? [[FIXME]]
|
'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 The GIMP, should be familiar with this plugin
|
||||||
|
concept.)
|
||||||
|
|
||||||
magic plugins must provide:
|
--------------------------------------------------------------------------
|
||||||
---------------------------
|
|
||||||
NOTE: Each function name should be preceded with the name of the
|
|
||||||
shared object file, e.g. "negative.so" or "negative.dll" would have
|
|
||||||
a function called "negative_init()".
|
|
||||||
|
|
||||||
int get_tool_count(magic_api * api)
|
Prerequisites
|
||||||
return the number of Magic tools this plugin provides
|
|
||||||
(used below as the 'which' values sent to each function)
|
|
||||||
|
|
||||||
char * get_name(magic_api * api, int which)
|
Tux Paint is written in the C programming language, and uses the
|
||||||
return the name of a/the magic tool (for 'Magic' tool buttons in UI)
|
Simple DirectMedia Layer library ('libSDL', or simply 'SDL'). Therefore,
|
||||||
Tux Paint will free() the string;
|
for the moment at least, one must understand the C language, how to
|
||||||
example:
|
compile C-based programs. Familiarity with the SDL API is highly
|
||||||
return (strdup(gettext("Fun")));
|
recommended, but some basic SDL concepts will be covered in this
|
||||||
|
document.
|
||||||
|
|
||||||
SDL_Surface * get_icon(magic_api * api, int which)
|
--------------------------------------------------------------------------
|
||||||
return the icon of a/the magic tool (for 'Magic' tool buttons in UI)
|
|
||||||
Tux Paint will SDL_FreeSurface() the surface:
|
|
||||||
example:
|
|
||||||
sprintf(fname, "%s/images/magic/funtool.png", api->data_directory);
|
|
||||||
return(IMG_Load(fname));
|
|
||||||
|
|
||||||
char * get_description(magic_api * api, int which)
|
Interfaces
|
||||||
return the description of a/the magic tool (for Tux help text in UI);
|
|
||||||
Tux Paint will free() the string;
|
|
||||||
example:
|
|
||||||
return (strdup(gettext("A fun tool")));
|
|
||||||
|
|
||||||
int requires_colors(magic_api * api, int which)
|
Those who create 'Magic' tool plugins for Tux Paint must provide some
|
||||||
return whether a/the magic tool accepts colors
|
interfaces (C functions) that Tux Paint may invoke.
|
||||||
('1' for true; activates color palette in UI;
|
|
||||||
'0' for false; disables color palette in UI)
|
|
||||||
|
|
||||||
void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g)
|
Tux Paint utilizes SDL's "SDL_LoadObject()" and "SDL_LoadFunction()"
|
||||||
accept the color palette choice from Tux Paint
|
routines to load plugins (shared objects files; e.g., ".so" files on
|
||||||
(only called if requires_colors() for the current tool returned true)
|
Linux or ".dll" files on Windows) and find the functions within.
|
||||||
|
|
||||||
int init(magic_api * api)
|
In turn, Tux Paint provides a number of helper functions that the plugin
|
||||||
initialization function; called once, during Tux Paint startup
|
may (or sometimes should) use. This is exposed as a C structure
|
||||||
return 1 if success;
|
(containing pointers to functions inside Tux Paint and other data) that
|
||||||
return 0 if failure (tool(s) will be disabled in Magic tool);
|
gets passed along to the plugin's functions as an argument.
|
||||||
|
|
||||||
void shutdown(magic_api * api)
|
Plugins should #include the file "tp_magic_api.h", and compiler flags
|
||||||
cleanup function; should free any alloc'd memory, etc.;
|
which should be used when building plugins (to find the aforementioned
|
||||||
happens once, at Tux Paint shutdown
|
header file, as well as SDL's header files) can be acquired by invoking
|
||||||
|
the tool "tp-magic-config".
|
||||||
|
|
||||||
void click(magic_api * api, int which,
|
(These are included with Tux Paint -- or in some cases, as part of a
|
||||||
SDL_Surface * snapshot, SDL_Surface * canvas,
|
"Tux Paint 'Magic' Tool Plugin Development package".)
|
||||||
int x, int y)
|
|
||||||
should affect 'canvas' at (x,y) location; may use 'snapshot' to fetch
|
|
||||||
pixels from most recent undo buffer;
|
|
||||||
Tux Paint's undo buffer is updated prior to this call
|
|
||||||
|
|
||||||
void drag(magic_api * api, int which,
|
'Magic' tool plugin functions
|
||||||
SDL_Surface * snapshot, SDL_Surface * canvas,
|
|
||||||
int ox, int oy, int x, int y)
|
|
||||||
should affect 'canvas' between (ox,oy) and (x,y) locations;
|
|
||||||
may use 'snapshot' to fetch pixels from most recent undo buffer;
|
|
||||||
Tux Paint's undo buffer is NOT updated prior to this call; the
|
|
||||||
'snapshot' buffer will contain the same contents as when click() was
|
|
||||||
last called
|
|
||||||
|
|
||||||
|
'Magic' tool plugins must provide 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_").
|
||||||
|
|
||||||
tp provides, via magic_api structure ("api" arg to magic tool functions):
|
Common arguments to plugin functions:
|
||||||
-------------------------------------------------------------------------
|
|
||||||
void putpixel(SDL_Surface * surf, int x, int y, Uint32 pixel)
|
|
||||||
function that puts a pixel at an (x,y) position in a surface
|
|
||||||
|
|
||||||
Uint32 getpixel(SDL_Surface * surf, int x, int y)
|
* magic_api * api
|
||||||
function that returns a pixel value from an (x,y) position on a surface
|
Pointer to the struct containing pointers to Tux Paint functions
|
||||||
|
and other data (see below)
|
||||||
|
* 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.)
|
||||||
|
* SDL_Surface * canvas
|
||||||
|
The active Tux Paint drawing canvas. Your magical effects should
|
||||||
|
end up here!
|
||||||
|
* SDL_Surface * last
|
||||||
|
A snapshot of the previous Tux Paint canvas, taken when the the
|
||||||
|
mouse was first clicked to activate the 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.
|
||||||
|
|
||||||
int in_circle(int x, int y, int radius)
|
Required plugin functions:
|
||||||
function that returns whether an x/y position (centered at (0,0)) is
|
|
||||||
within a circle of 'radius'
|
|
||||||
|
|
||||||
void show_progress_bar(void)
|
* int get_tool_count(magic_api * api)
|
||||||
draws the Tux Paint progress bar animation; use while you're busy
|
This should return the number of Magic tools this plugin provides
|
||||||
|
to Tux Paint.
|
||||||
|
* 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.
|
||||||
|
* 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 SDL_FreeSurface() the surface upon exit.
|
||||||
|
* char * get_description(magic_api * api, int which)
|
||||||
|
This should return a string containing the description of a magic
|
||||||
|
tool. This will appear as a help tip, explained by Tux the
|
||||||
|
Penguin, within Tux Paint.
|
||||||
|
Tux Paint will free() the string upon exit, so you should wrap it
|
||||||
|
in a C strdup() call.
|
||||||
|
* 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.
|
||||||
|
* void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g)
|
||||||
|
Tux Paint will call this function to inform the plugin of the RGB
|
||||||
|
values of the currently-selected color in Tux Paint's 'Colors'
|
||||||
|
palette. (It will be called whenever one of the plguin's Magic
|
||||||
|
tools that accept colors becomes active, or the user picks a new
|
||||||
|
color while such a tool is currently active.)
|
||||||
|
* int init(magic_api * api)
|
||||||
|
The plugin should do any initialization here. This function is
|
||||||
|
called once, at Tux Paint startup. Return '1' if initialization
|
||||||
|
was successful, or '0' if not (and Tux Paint will not present any
|
||||||
|
'Magic' tools from the plugin).
|
||||||
|
* void shutdown(magic_api * api)
|
||||||
|
The plugin should do any cleanup here. This function is called
|
||||||
|
once, at Tux Paint exit.
|
||||||
|
* void click(magic_api * api, int which, SDL_Surface * snapshot,
|
||||||
|
SDL_Surface * canvas, int x, int y)
|
||||||
|
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.
|
||||||
|
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)
|
||||||
|
The plugin should apply the appropriate 'Magic' tool on the
|
||||||
|
'canvas' surface. The (ox,oy) and (x,y) coordinates are the
|
||||||
|
location of the mouse at the beginning and end of the stroke.
|
||||||
|
Typically, plugins that let the user "draw" effects onto the
|
||||||
|
canvas call the Tux Paint 'Magic' tool plugin "line()" helper
|
||||||
|
function. (See below).
|
||||||
|
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 tuxpaint_version(int * major, int * minor, int * revision)
|
Tux Paint Functions
|
||||||
returns the version of Tux Paint being used
|
|
||||||
|
|
||||||
void line(int which, SDL_Surface * canvas, SDL_Surface * snapshot,
|
Tux Paint provides a number of helper functions that plugins may
|
||||||
int x1, int y1, int x2, int y2, int step, FUNC callback)
|
access via the "magic_api" structure, sent to all of the
|
||||||
function that calls calculates a line between (x1,y1) and (x2,y2)
|
plugin's functions (see above).
|
||||||
and calls 'callback' every 'step' iterations;
|
|
||||||
sends to the callback: Tux Paint's 'magic_api' structure, along with the
|
|
||||||
'which', 'canvas' and 'snapshot' values sent to line(), and the (x,y)
|
|
||||||
coordinates
|
|
||||||
|
|
||||||
|
* 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.)
|
||||||
|
* 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 show_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 tuxpaint_version(int * major, int * minor, int *
|
||||||
|
revision)
|
||||||
|
Returns the version of Tux Paint being used (e.g.,
|
||||||
|
"0.9.18"), separated into three integers.
|
||||||
|
* void line(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), a 'which' value, represening which of the
|
||||||
|
plugin's 'Magic' tool is being used, and the current and
|
||||||
|
snapshot canvases.
|
||||||
|
|
||||||
FIXME: Implement these:
|
Example prototype of a callback function that may be sent
|
||||||
|
to Tux Paint's "line()" 'Magic' tool plugin helper
|
||||||
|
function:
|
||||||
|
|
||||||
void playsound(Mix_Chunk * snd, int pan, int dist)
|
void exampleCallBack(void * ptr_to_api, int which_tool,
|
||||||
function that plays a sound, panned left/right 'pan'
|
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int
|
||||||
and at distance 'dist'. pan may be SNDPOS_LEFT, SNDPOS_CENTER or
|
y);
|
||||||
SNDPOS_RIGHT, and dist may be SNDDIST_NEAR.
|
|
||||||
|
|
||||||
void special_notify(int flag)
|
* void playsound(Mix_Chunk * snd, int pan, int dist)
|
||||||
notifies tux paint of special events; SPECIAL_FLIP and SPECIAL_MIRROR
|
This function plays a sound (one loaded by the SDL helper
|
||||||
flags may be sent
|
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 special_notify(int flag)
|
||||||
|
This function notifies Tux Paint of special events. Various
|
||||||
|
values defined in "tp_magic_api.h" can be logically 'or'ed
|
||||||
|
together and sent to this function.
|
||||||
|
|
||||||
float sRGB_to_linear_table[256]
|
* SPECIAL_FLIP -- The contents of the canvas has been
|
||||||
sRGB-to-linear look-up table
|
flipped. 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.
|
||||||
|
|
||||||
unsigned char linear_to_sRGB(float linear)
|
* int button_down(void)
|
||||||
linear-to-sRGB look-up helper function
|
A '1' is returned if the mouse button is down; '0'
|
||||||
|
otherwise.
|
||||||
|
* 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).
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Additionally, use the "tp-magic-config --cflags" command,
|
||||||
|
supplied as part of Tux Paint, to provide additional
|
||||||
|
command-line flags to your C compiler that will help it build
|
||||||
|
your plugin.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
A snippet from a more generalized Makefile might look like
|
||||||
|
this:
|
||||||
|
|
||||||
|
CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
|
||||||
|
|
||||||
|
my_plugin.so: my_plugin.c $(CC) -shared $(CFLAGS) -o $@
|
||||||
|
$<
|
||||||
|
|
||||||
|
Then install globally into: /usr/[local/]lib/tuxpaint/. Or
|
||||||
|
locally into: ~/.tuxpaint/magic/
|
||||||
|
|
||||||
|
Windows
|
||||||
|
|
||||||
|
TBD
|
||||||
|
|
||||||
|
Mac OS X
|
||||||
|
|
||||||
|
TBD
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Example Code
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Summary and contact info TBD.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue