notgne2/tuxpaint-pencil-sharpener
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Added Makefile to convert HTML docs to plain text.

Browse source 
Recreated plain text docs based on HTML.
This commit is contained in:
William Kendrick 2007-07-06 19:38:11 +00:00
parent 674b28c7e4
commit fbbfb2fafd
2 changed files with 268 additions and 99 deletions
Download patch file Download diff file Expand all files Collapse all files

21
magic/docs/Makefile Normal file
View 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) $< > $@

346
magic/docs/README.txt
View file

@ -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:
-------------------
Linux/Unix:
-----------
$(CC) -shared `tp-magic-config --cflags` plugin.c -o plugin.so
July 5, 2007 - July 6, 2007
Then install globally into: /usr/[local/]lib/tuxpaint/.
Or locally into: ~/.tuxpaint/magic/ [[FIXME]]
--------------------------------------------------------------------------
Windows:
--------
??? [[FIXME]]
Overview
Mac OS X:
---------
??? [[FIXME]]
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 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)
return the number of Magic tools this plugin provides
(used below as the 'which' values sent to each function)
Prerequisites
char * get_name(magic_api * api, int which)
return the name of a/the magic tool (for 'Magic' tool buttons in UI)
Tux Paint will free() the string;
example:
return (strdup(gettext("Fun")));
Tux Paint is written in the C programming language, and uses the
Simple DirectMedia Layer library ('libSDL', or simply 'SDL'). Therefore,
for the moment at least, one must understand the C language, 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.
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)
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")));
Interfaces
int requires_colors(magic_api * api, int which)
return whether a/the magic tool accepts colors
('1' for true; activates color palette in UI;
'0' for false; disables color palette in UI)
Those who create 'Magic' tool plugins for Tux Paint must provide some
interfaces (C functions) that Tux Paint may invoke.
void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g)
accept the color palette choice from Tux Paint
(only called if requires_colors() for the current tool returned true)
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.
int init(magic_api * api)
initialization function; called once, during Tux Paint startup
return 1 if success;
return 0 if failure (tool(s) will be disabled in Magic tool);
In turn, Tux Paint provides a number of helper functions that the plugin
may (or sometimes should) use. This is exposed as a C structure
(containing pointers to functions inside Tux Paint and other data) that
gets passed along to the plugin's functions as an argument.
void shutdown(magic_api * api)
cleanup function; should free any alloc'd memory, etc.;
happens once, at Tux Paint shutdown
Plugins should #include the file "tp_magic_api.h", and compiler flags
which should be used when building plugins (to find the aforementioned
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,
SDL_Surface * snapshot, SDL_Surface * canvas,
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
(These are included with Tux Paint -- or in some cases, as part of a
"Tux Paint 'Magic' Tool Plugin Development package".)
void drag(magic_api * api, int which,
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 plugin functions
'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):
-------------------------------------------------------------------------
void putpixel(SDL_Surface * surf, int x, int y, Uint32 pixel)
function that puts a pixel at an (x,y) position in a surface
Common arguments to plugin functions:
Uint32 getpixel(SDL_Surface * surf, int x, int y)
function that returns a pixel value from an (x,y) position on a surface
* magic_api * api
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)
function that returns whether an x/y position (centered at (0,0)) is
within a circle of 'radius'
Required plugin functions:
void show_progress_bar(void)
draws the Tux Paint progress bar animation; use while you're busy
* int get_tool_count(magic_api * api)
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)
returns the version of Tux Paint being used
Tux Paint Functions
void line(int which, SDL_Surface * canvas, SDL_Surface * snapshot,
int x1, int y1, int x2, int y2, int step, FUNC callback)
function that calls calculates a line between (x1,y1) and (x2,y2)
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
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 above).
* 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)
function that plays a sound, panned left/right 'pan'
and at distance 'dist'. pan may be SNDPOS_LEFT, SNDPOS_CENTER or
SNDPOS_RIGHT, and dist may be SNDDIST_NEAR.
void exampleCallBack(void * ptr_to_api, int which_tool,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int
y);
void special_notify(int flag)
notifies tux paint of special events; SPECIAL_FLIP and SPECIAL_MIRROR
flags may be sent
* 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 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]
sRGB-to-linear look-up table
* SPECIAL_FLIP -- The contents of the canvas has been
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)
linear-to-sRGB look-up helper function
* int button_down(void)
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.