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

Update and formatting enhancements to Plugin API docs.

Browse source
This commit is contained in:
William Kendrick 2007-07-27 22:25:48 +00:00
parent 10881623cf
commit 1211034182
2 changed files with 565 additions and 303 deletions
Download patch file Download diff file Expand all files Collapse all files

520
magic/docs/README.txt
View file

@ -6,7 +6,7 @@
bill@newbreedsoftware.com bill@newbreedsoftware.com
http://www.tuxpaint.org/ http://www.tuxpaint.org/
July 5, 2007 - July 8, 2007 July 5, 2007 - July 27, 2007
-------------------------------------------------------------------------- --------------------------------------------------------------------------
@ -28,7 +28,7 @@ Prerequisites
Tux Paint is written in the C programming language, and uses the Tux Paint is written in the C programming language, and uses the
Simple DirectMedia Layer library ('libSDL', or simply 'SDL'). Therefore, Simple DirectMedia Layer library ('libSDL', or simply 'SDL'). Therefore,
for the moment at least, one must understand the C language, how to 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 compile C-based programs. Familiarity with the SDL API is highly
recommended, but some basic SDL concepts will be covered in this recommended, but some basic SDL concepts will be covered in this
document. document.
@ -45,215 +45,318 @@ Interfaces
Linux or ".dll" files on Windows) and find the functions within. Linux or ".dll" files on Windows) and find the functions within.
In turn, Tux Paint provides a number of helper functions that the plugin 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 may (or sometimes is required to) use. This is exposed as a C structure
(containing pointers to functions inside Tux Paint and other data) that (or "struct") which contains pointers to functions and other data inside
gets passed along to the plugin's functions as an argument. 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 file "tp_magic_api.h", and compiler flags Plugins should #include the C header file "tp_magic_api.h", which
which should be used when building plugins (to find the aforementioned exposes the 'Magic' tool plugin API. Also, when you run the C compiler
header file, as well as SDL's header files) can be acquired by invoking to build a plugin, you should use the command-line tool
the tool "tp-magic-config". "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.
(These are included with Tux Paint -- or in some cases, as part of a The C header file and command-line tool mentioned above are included
"Tux Paint 'Magic' Tool Plugin Development package".) with Tux Paint -- or in some cases, as part of a "Tux Paint 'Magic' Tool
Plugin Development package".
'Magic' tool plugin functions 'Magic' tool plugin functions
'Magic' tool plugins must provide the functions listed below. Note: To 'Magic' tool plugins must contain the functions listed below. Note: To
avoid namespace collisions, each function's name must start with the avoid 'namespace' collisions, each function's name must start with the
shared object's filename (e.g., "blur.so" or "blur.dll" would have shared object's filename (e.g., "blur.so" or "blur.dll" would have
functions whose names begin with "blur_"). This includes private functions whose names begin with "blur_"). This includes private
functions, unless you declare those as 'static'. functions (ones not used by Tux Paint directly), unless you declare
those as 'static'.
Common arguments to plugin functions: 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 * magic_api * api
Pointer to the struct containing pointers to Tux Paint functions Pointer to a C structure containing pointers to Tux Paint
and other data (see below) 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 * int which
An index the plugin should use to differentiate different 'Magic' An index the plugin should use to differentiate different 'Magic'
tools, if the plugin provides more than one. (If not, "which" will tools, if the plugin provides more than one. (If not, "which" will
always be 0.) always be 0.) See "Creating plugins with multiple effects", below.
* SDL_Surface * canvas
The active Tux Paint drawing canvas. Your magical effects should * SDL_Surface * snapshot
end up here!
* SDL_Surface * last
A snapshot of the previous Tux Paint canvas, taken when the the 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 mouse was first clicked to activate the current magic tool. If you
continuously affect the image during one hold of the mouse button, don't continuously affect the image during one hold of the mouse
you should base your effects off the contents of this canvas. 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.
Because it is a pointer, you access its elements via "->" (arrow)
rather than "." (dot).
Required plugin functions: Required plugin functions:
* int get_tool_count(magic_api * api) Your plugin is required to contain, at the least, all of the
This should return the number of Magic tools this plugin provides following functions.
to Tux Paint.
* char * get_name(magic_api * api, int which) Note: Remember, your plugin's function names must be preceded by
This should return a string containing the name of a magic tool. your plugin's filename. That is, if your plugin is called "zoom.so"
This will appear on the button in the 'Magic' selector within (on Linux) or "zoom.dll" (on Windows), then the names of your
Tux Paint. Tux Paint will free() the string upon exit, so you functions must begin with "zoom_" (e.g., "zoom_get_name(...)").
should wrap it in a C strdup() call.
* SDL_Surface * get_icon(magic_api * api, int which) Plugin "housekeeping" functions:
This should return an SDL_Surface containing the icon representing
the tool. (A greyscale image with alpha, no larger than 40x40.) * Uint32 api_version(void)
This will appear on the button in the 'Magic' selector within The plugin should return an integer value representing the
Tux Paint. version of the Tux Paint 'Magic' tool plugin API the plugin was
Tux Paint will SDL_FreeSurface() the surface upon exit. built against. The safest thing to do is return the value of
* char * get_description(magic_api * api, int which) TP_MAGIC_API_VERSION, which is defined in "tp_magic_api.h". If
This should return a string containing the description of a magic Tux Paint deems your plugin to be compatible, it will go ahead
tool. This will appear as a help tip, explained by Tux the and use it.
Penguin, within Tux Paint.
Tux Paint will free() the string upon exit, so you should wrap it Note: Called once by Tux Paint, at startup. It is called first.
in a C strdup() call. * int init(magic_api * api)
* int requires_colors(magic_api * api, int which) The plugin should do any initialization here. Return '1' if
Return a '1' if the 'Magic' tool accepts colors (the 'Colors' initialization was successful, or '0' if not (and Tux Paint will
palette in Tux Paint will be available), or '0' if not. not present any 'Magic' tools from the plugin).
* 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 Note: Called once by Tux Paint, at startup. It is called first.
values of the currently-selected color in Tux Paint's 'Colors' It is called after "api_version()", if Tux Paint believes your
palette. (It will be called whenever one of the plguin's Magic plugin to be compatible.
tools that accept colors becomes active, or the user picks a new * int get_tool_count(magic_api * api)
color while such a tool is currently active.) This should return the number of Magic tools this plugin
* Uint32 api_version(void) provides to Tux Paint.
The plugin should return an integer value representing the version
of the Tux Paint 'Magic' tool plugin API it was built against. Note: Called once by Tux Paint, at startup. It is called after
Simply return TP_MAGIC_API_VERSION, which is defined in your "init()", if it succeeded.
"tp_magic_api.h", to satisfy this requirement.
* int init(magic_api * api) * char * get_name(magic_api * api, int which)
The plugin should do any initialization here. This function is This should return a string containing the name of a magic tool.
called once, at Tux Paint startup. Return '1' if initialization This will appear on the button in the 'Magic' selector within
was successful, or '0' if not (and Tux Paint will not present any Tux Paint.
'Magic' tools from the plugin).
* void shutdown(magic_api * api) Tux Paint will free() the string upon exit, so you should wrap
The plugin should do any cleanup here. This function is called it in a C strdup() call.
once, at Tux Paint exit.
* void click(magic_api * api, int which, SDL_Surface * snapshot, Note: Called once for each Magic tool your plugin claims to
SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect) contain (by your "get_tool_count()").
The plugin should apply the appropriate 'Magic' tool on the
'canvas' surface. The (x,y) coordinates are where the mouse was * SDL_Surface * get_icon(magic_api * api, int which)
(within the canvas) when the mouse button was clicked. This should return an SDL_Surface containing the icon
The plugin should report back what part of the canvas was representing the tool. (A greyscale image with alpha, no larger
affected, by filling in the (x,y) and (w,h) values in than 40x40.) This will appear on the button in the 'Magic'
'update_rect'. selector within Tux Paint.
The contents of the drawing canvas immediately prior to the mouse
button click is stored within the 'snapshot' canvas. Tux Paint will free ("SDL_FreeSurface()") the surface upon exit.
* void drag(magic_api * api, int which, SDL_Surface * snapshot,
SDL_Surface * canvas, int ox, int oy, int x, int y, SDL_Rect * Note: Called once for each Magic tool your plugin claims to
update_rect) contain (by your "get_tool_count()").
The plugin should apply the appropriate 'Magic' tool on the
'canvas' surface. The (ox,oy) and (x,y) coordinates are the * char * get_description(magic_api * api, int which)
location of the mouse at the beginning and end of the stroke. This should return a string containing the description of a
Typically, plugins that let the user "draw" effects onto the magic tool. This will appear as a help tip, explained by Tux the
canvas call the Tux Paint 'Magic' tool plugin "line()" helper Penguin, within Tux Paint.
function. (See below).
The plugin should report back what part of the canvas was Tux Paint will free() the string upon exit, so you should wrap
affected, by filling in the (x,y) and (w,h) values in it in a C strdup() call.
'update_rect'.
Note: The contents of the drawing canvas immediately prior to the Note: Called once for each Magic tool your plugin claims to
mouse button click remains as it was (when the plugin's "click()" contain (by your "get_tool_count()").
function was called), and is still available in the 'snapshot'
canvas. * int requires_colors(magic_api * api, int which)
* void release(magic_api * api, int which, SDL_Surface * snapshot, Return a '1' if the 'Magic' tool accepts colors (the 'Colors'
SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect) palette in Tux Paint will be available), or '0' if not.
The plugin should apply the appropriate 'Magic' tool on the
'canvas' surface. The (x,y) coordinates are where the mouse was Note: Called once for each Magic tool your plugin claims to
(within the canvas) when the mouse button was released. contain (by your "get_tool_count()").
The plugin should report back what part of the canvas was
affected, by filling in the (x,y) and (w,h) values in * void shutdown(magic_api * api)
'update_rect'. The plugin should do any cleanup here. If you allocated any
Note: The contents of the drawing canvas immediately prior to the memory or used SDL_Mixer to load any sounds during init(), for
mouse button click remains as it was (when the plugin's "click()" example, you should free() the allocated memory and
function was called), and is still available in the 'snapshot' Mix_FreeChunk() the sounds here.
canvas.
Note: This function is called once, when Tux Paint exits.
Plugin event functions:
* 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.)
* void click(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 clicked.
The plugin should report back what part of the canvas was
affected, by filling in the (x,y) and (w,h) values in
'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 call the Tux Paint 'Magic' tool plugin "line()" helper
function. (See below).
The plugin should report back what part of the canvas was
affected, by filling in the (x,y) and (w,h) values in
'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) values in
'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 Tux Paint Functions
Tux Paint provides a number of helper functions that plugins may Tux Paint provides a number of helper functions that plugins may
access via the "magic_api" structure, sent to all of the access via the "magic_api" structure, sent to all of the plugin's
plugin's functions (see above). functions (see above).
* Uint32 getpixel(SDL_Surface * surf, int x, int y) Retreives * Uint32 getpixel(SDL_Surface * surf, int x, int y) Retreives the
the pixel value from the (x,y) coordinates of an pixel value from the (x,y) coordinates of an SDL_Surface. (You can
SDL_Surface. (You can use SDL's "SDL_GetRGB()" function to use SDL's "SDL_GetRGB()" function to convert the Uint32 'pixel' to
convert the Uint32 'pixel' to a set of Uint8 RGB values.) 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.
Example prototype of a callback function that may be sent * void putpixel(SDL_Surface * surf, int x, int y, Uint32 pixel)
to Tux Paint's "line()" 'Magic' tool plugin helper Sets the pixel value at position (x,y) of an SDL_Surface. (You can
function: use SDL's "SDL_MapRGB()" function to convert a set of Uint8 RGB
values to a Uint32 'pixel' value appropriate to the destination
surface.)
void exampleCallBack(void * ptr_to_api, int which_tool, * int in_circle(int x, int y, int radius)
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int Returns '1' if the (x,y) location is within a circle of a
y); 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 playsound(Mix_Chunk * snd, int pan, int dist) * void show_progress_bar(void)
This function plays a sound (one loaded by the SDL helper Asks Tux Paint to animate and draw one frame of its progress bar
library "SDL_mixer"). It uses SDL_mixer's (at the bottom of the screen). Useful for routines that may take a
"Mix_SetPanning()" to set the volume of the sound on the long time, to provide feedback to the user that Tux Paint has not
left and right speakers, based on the 'pan' and 'dist' crashed or frozen.
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.
* SPECIAL_FLIP -- The contents of the canvas has been * void tuxpaint_version(int * major, int * minor, int * revision)
flipped. If a 'Starter' image was used as the basis of Returns the version of Tux Paint being used (e.g., "0.9.18"),
this image, it should be flipped too, and a record of separated into three integers.
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.
* int button_down(void) * void line(int which, SDL_Surface * canvas, SDL_Surface * snapshot,
A '1' is returned if the mouse button is down; '0' int x1, int y1, int x2, int y2, int step, FUNC callback)
otherwise. This function calculates all points on a line between the
* float sRGB_to_linear(Uint8 srbg) coordinates (x1,y1) and (x2,y2). Every 'step' iterations, it calls
Converts an 8-bit sRGB value (one between 0 and 255) to a the 'callback' function.
linear floating point value (between 0.0 and 1.0).
* uint8 linear_to_sRGB(float linear) It sends the 'callback' function the (x,y) coordinates on the
Converts a linear floating point value (one between 0.0 and line, Tux Paint's "magic_api" struct (as a "void *" pointer), a
1.0) to an 8-bit sRGB value (between 0 and 255). '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);
* 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.
* 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.
* 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).
-------------------------------------------------------------------------- --------------------------------------------------------------------------
@ -261,39 +364,46 @@ Compiling
Linux and other Unix-like Platforms Linux and other Unix-like Platforms
Use the C compiler's "-shared" command-line option to generate Use the C compiler's "-shared" command-line option to generate a
a shared object file (".so") based on your 'Magic' tool shared object file (".so") based on your 'Magic' tool plugin's C
plugin's C source code. source code.
Additionally, use the "tp-magic-config --cflags" command, Additionally, use the "tp-magic-config --cflags" command, supplied as
supplied as part of Tux Paint, to provide additional part of Tux Paint, to provide additional command-line flags to your C
command-line flags to your C compiler that will help it build compiler that will help it build your plugin.
your plugin.
As a stand-alone command, using the GNU C Compiler and BASH As a stand-alone command, using the GNU C Compiler and BASH shell, for
shell, for example: example:
gcc -shared `tp-magic-config --cflags` my_plugin.c -o gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so
my_plugin.so
A snippet from a more generalized Makefile might look like Note: The characters around the "tp-magic-config" command are a
this: 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 ...").
CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) A snippet from a more generalized Makefile might look like this:
my_plugin.so: my_plugin.c $(CC) -shared $(CFLAGS) -o $@ CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
$<
Then install globally into: /usr/[local/]lib/tuxpaint/. Or my_plugin.so: my_plugin.c $(CC) -shared $(CFLAGS) -o $@ $<
locally into: ~/.tuxpaint/magic/
You may then install it globally into: /usr/lib/tuxpaint/plugins/ or
/usr/local/lib/tuxpaint/plugins/ (depending on how Tux Paint was
installed).
Or install it locally (for the current user only) into:
~/.tuxpaint/magic/
(FIXME: As of 2007-07-27, Tux Paint does not look here yet!)
Windows Windows
TBD TBD
Mac OS X Mac OS X
TBD TBD
-------------------------------------------------------------------------- --------------------------------------------------------------------------
@ -301,4 +411,4 @@ Example Code
-------------------------------------------------------------------------- --------------------------------------------------------------------------
Summary and contact info TBD. Summary and contact info TBD.

348
magic/docs/html/README.html
View file

@ -15,7 +15,7 @@ New Breed Software</p>
<p><a href="mailto:bill@newbreedsoftware.com">bill@newbreedsoftware.com</a><br> <p><a href="mailto:bill@newbreedsoftware.com">bill@newbreedsoftware.com</a><br>
<a href="http://www.tuxpaint.org/">http://www.tuxpaint.org/</a></p> <a href="http://www.tuxpaint.org/">http://www.tuxpaint.org/</a></p>
<p>July 5, 2007 - July 8, 2007</p> <p>July 5, 2007 - July 27, 2007</p>
</center> </center>
<hr size=2 noshade> <hr size=2 noshade>
@ -44,7 +44,7 @@ concept.)</p>
<p>Tux Paint is written in the C programming language, and uses the <p>Tux Paint is written in the C programming language, and uses the
Simple&nbsp;DirectMedia&nbsp;Layer library ('libSDL', or simply 'SDL'). Simple&nbsp;DirectMedia&nbsp;Layer library ('libSDL', or simply 'SDL').
Therefore, for the moment at least, one must understand the C language, 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 how to compile C-based programs. Familiarity with the SDL API is highly
recommended, but some basic SDL concepts will be covered in this document.</p> recommended, but some basic SDL concepts will be covered in this document.</p>
@ -65,141 +65,264 @@ files on Linux or "<code>.dll</code>" files on Windows) and find the
functions within.</p> functions within.</p>
<p>In turn, Tux Paint provides a number of helper functions that the <p>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 plugin may (or sometimes is required to) use. This is exposed as a C
(containing pointers to functions inside Tux&nbsp;Paint and other data) structure (or "<code>struct</code>") which contains pointers to functions
that gets passed along to the plugin's functions as an argument.</p> and other data inside Tux&nbsp;Paint. A pointer to this structure gets
passed along to the plugin's functions as an argument when Tux&nbsp;Paint
invokes them.</p>
<p>Plugins should <code>#include</code> the file "<code>tp_magic_api.h</code>", <p>Plugins should <code>#include</code> the C header file
and compiler flags which should be used when building plugins (to find the "<code>tp_magic_api.h</code>", which exposes the 'Magic' tool plugin API.
aforementioned header file, as well as SDL's header files) can be acquired Also, when you run the C compiler to build a plugin, you should use the
by invoking the tool "<code>tp-magic-config</code>".</p> command-line tool "<code>tp-magic-config</code>" to get the appropriate
compiler flags (such as where the compiler can find the Tux&nbsp;Paint
plugin header file, as well as SDL's header files) for building a plugin.</p>
<p>(These are included with Tux&nbsp;Paint &mdash; or in some cases, as part <p>The C header file and command-line tool mentioned above are included
of a "Tux&nbsp;Paint 'Magic' Tool Plugin Development package".)</p> with Tux&nbsp;Paint &mdash; or in some cases, as part of a "Tux&nbsp;Paint
'Magic' Tool Plugin Development package".</p>
<h3>'Magic' tool plugin functions</h3> <h3>'Magic' tool plugin functions</h3>
<blockquote> <blockquote>
<p>'Magic' tool plugins must provide the functions listed below. <p>'Magic' tool plugins <i>must</i> contain the functions listed below.
<b>Note:</b> To avoid namespace collisions, each function's name must <b>Note:</b> To avoid 'namespace' collisions, each function's name must
start with the shared object's filename (e.g., "blur.so" or "blur.dll" start with the shared object's filename (e.g., "blur.so" or "blur.dll"
would have functions whose names begin with "blur_"). <i>This would have functions whose names begin with "<code>blur_</code>"). <i>This
includes private functions</i>, unless you declare those as includes private functions</i> (ones not used by Tux&nbsp;Paint directly),
'static'.</p> unless you declare those as '<code>static</code>'.</p>
<h4>Common arguments to plugin functions:</h4> <h4>Common arguments to plugin functions:</h4>
Here is a description of arguments that many of your plugin's functions
will need to accept.
<ul> <ul>
<li>magic_api * api<br> <li><code><b>magic_api * api</b></code><br>
Pointer to the struct containing pointers to Tux&nbsp;Paint functions and Pointer to a C structure containing pointers to Tux&nbsp;Paint functions and
other data (see below) other data that the plugin can (and sometimes should) use.
<li>int which<br> The contents of this struct are <a href="#tpfuncs">described below</a>.<br>
<br>
Note: The <code>magic_api</code> struct is defined in the C header file
"<code>tp_magic_api.h</code>", which you should include at the top of your
plugin's C source file:
<blockquote><code>
#include "tp_magic_api.h"
</code></blockquote>
<li><code><b>int which</b></code><br>
An index the plugin should use to differentiate different 'Magic' tools, 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.) if the plugin provides more than one. (If not, "which" will always be 0.)
<li>SDL_Surface * canvas<br> See <a href="#multiple">"Creating plugins with multiple effects"</a>,
The active Tux&nbsp;Paint drawing canvas. Your magical effects should end below.<br>
up here! <br>
<li>SDL_Surface * last<br>
<li><code><b>SDL_Surface * snapshot</b></code><br>
A snapshot of the previous Tux&nbsp;Paint canvas, taken when the the A snapshot of the previous Tux&nbsp;Paint canvas, taken when the the
mouse was first clicked to activate the magic tool. If you don't 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, continuously affect the image during one hold of the mouse button,
you should base your effects off the contents of this canvas. you should base your effects off the contents of this canvas.
(That is, read from "<code>snapshot</code>" and write to
"<code>canvas</code>", below.)<br>
<br>
<li><code><b>SDL_Surface * canvas</b></code><br>
The current Tux&nbsp;Paint drawing canvas. Your magical effects should end
up here!<br>
<br>
<li><code><b>SDL_Rect * update_rect</b></code><br>
A pointer to an SDL 'rectangle' structure that you use to tell Tux&nbsp;Paint
what part of the canvas has been updated. If your effect affects a
32x32 area centered around the mouse pointer, you would fill the SDL_Rect
as follows:
<blockquote><code>
update_rect-&gt;x = x - 16;<br>
update_rect-&gt;y = y - 16;<br>
update_rect-&gt;w = 32;<br>
update_rect-&gt;h = 32;
</code></blockquote>
Or, if your effect changes the entire canvas (e.g., flips it upside-down),
you'd fill it as follows:
<blockquote><code>
update_rect-&gt;x = 0;<br>
update_rect-&gt;y = 0;<br>
update_rect-&gt;w = canvas-&gt;w;<br>
update_rect-&gt;h = canvas-&gt;h;
</code></blockquote>
Note: "<code>update_rect</code>" is a C pointer
(an "<code>SDL_Rect&nbsp;*</code>" rather than just an
"<code>SDL_Rect</code>") because you need to fill in its contents.
Because it is a pointer, you access its elements via
"<code>-&gt;</code>" (arrow) rather than "<code>.</code>" (dot).
</ul> </ul>
<h4>Required plugin functions:</h4> <h4>Required plugin functions:</h4>
<blockquote>
<p>Your plugin is required to contain, at the least, all of the
following functions.</p>
<p><b>Note:</b> Remember, your plugin's function names must be
preceded by your plugin's filename. That is, if your plugin is called
"<code>zoom.so</code>" (on Linux) or "<code>zoom.dll</code>" (on Windows),
then the names of your functions must begin with "<code><b>zoom_</b></code>"
(e.g., "<code>zoom_get_name(...)</code>").</p>
<h5>Plugin "housekeeping" functions:</h5>
<ul> <ul>
<li>int get_tool_count(magic_api * api)<br> <li><code><b>Uint32 api_version(void)</b></code><br>
The plugin should return an integer value representing the version of
the Tux&nbsp;Paint 'Magic' tool plugin API the plugin was built against.
The safest thing to do is return the value of
<code>TP_MAGIC_API_VERSION</code>, which is defined in
"<code>tp_magic_api.h</code>". If Tux&nbsp;Paint deems your plugin to
be compatible, it will go ahead and use it.<br>
<br>
<b>Note:</b> Called once by Tux&nbsp;Paint, at startup. It is called
first.<br>
<li><code><b>int init(magic_api * api)</b></code><br>
The plugin should do any initialization here.
Return '1' if initialization was successful,
or '0' if not (and Tux&nbsp;Paint will not present any 'Magic' tools
from the plugin).<br>
<br>
<b>Note:</b> Called once by Tux&nbsp;Paint, at startup. It is called
first. It is called after "<code>api_version()</code>", if
Tux&nbsp;Paint believes your plugin to be compatible.<br>
<li><code><b>int get_tool_count(magic_api * api)</b></code><br>
This should return the number of Magic tools this plugin provides to This should return the number of Magic tools this plugin provides to
Tux Paint. Tux Paint.<br>
<br>
<b>Note:</b> Called once by Tux&nbsp;Paint, at startup. It is called
after your "<code>init()</code>", if it succeeded.<br>
<br>
<li>char * get_name(magic_api * api, int which)<br> <li><code><b>char * get_name(magic_api * api, int which)</b></code><br>
This should return a string containing the name of a magic tool. This should return a string containing the name of a magic tool.
This will appear on the button in the 'Magic' selector within Tux&nbsp;Paint. This will appear on the button in the 'Magic' selector within
Tux&nbsp;Paint.<br>
<br>
Tux Paint will <code>free()</code> the string upon exit, so you should Tux Paint will <code>free()</code> the string upon exit, so you should
wrap it in a C <code>strdup()</code> call. wrap it in a C <code>strdup()</code> call.<br>
<br>
<b>Note:</b> Called once for each Magic tool your plugin claims to
contain (by your "<code>get_tool_count()</code>").<br>
<br>
<li>SDL_Surface * get_icon(magic_api * api, int which)<br> <li><code><b>SDL_Surface * get_icon(magic_api * api, int which)</b></code><br>
This should return an SDL_Surface containing the icon representing This should return an SDL_Surface containing the icon representing
the tool. (A greyscale image with alpha, no larger than 40x40.) the tool. (A greyscale image with alpha, no larger than 40x40.)
This will appear on the button in the 'Magic' selector within This will appear on the button in the 'Magic' selector within
Tux&nbsp;Paint.<br> Tux&nbsp;Paint.<br>
Tux Paint will SDL_FreeSurface() the surface upon exit. <br>
Tux Paint will free ("<code>SDL_FreeSurface()</code>") the surface upon
exit.<br>
<br>
<b>Note:</b> Called once for each Magic tool your plugin claims to
contain (by your "<code>get_tool_count()</code>").<br>
<br>
<li>char * get_description(magic_api * api, int which)<br> <li><code><b>char * get_description(magic_api * api, int which)</b></code><br>
This should return a string containing the description of a magic tool. This should return a string containing the description of a magic tool.
This will appear as a help tip, explained by Tux the Penguin, within This will appear as a help tip, explained by Tux the Penguin, within
Tux&nbsp;Paint.<br> Tux&nbsp;Paint.<br>
<br>
Tux Paint will <code>free()</code> the string upon exit, so you should Tux Paint will <code>free()</code> the string upon exit, so you should
wrap it in a C <code>strdup()</code> call. wrap it in a C <code>strdup()</code> call.<br>
<br>
<b>Note:</b> Called once for each Magic tool your plugin claims to
contain (by your "<code>get_tool_count()</code>").<br>
<br>
<li>int requires_colors(magic_api * api, int which)<br> <li><code><b>int requires_colors(magic_api * api, int which)</b></code><br>
Return a '1' if the 'Magic' tool accepts colors (the 'Colors' palette in Return a '1' if the 'Magic' tool accepts colors (the 'Colors' palette in
Tux&nbsp;Paint will be available), or '0' if not. Tux&nbsp;Paint will be available), or '0' if not.<br>
<br>
<b>Note:</b> Called once for each Magic tool your plugin claims to
contain (by your "<code>get_tool_count()</code>").<br>
<br>
<li>void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g)<br> <li><code><b>void shutdown(magic_api * api)</b></code><br>
The plugin should do any cleanup here. If you allocated any memory
or used SDL_Mixer to load any sounds during <code>init()</code>,
for example, you should <code>free()</code> the allocated memory
and <code>Mix_FreeChunk()</code> the sounds here.<br>
<br>
<b>Note:</b> This function is called once, when Tux&nbsp;Paint exits.<br>
<br>
</ul>
<h5>Plugin event functions:</h5>
<ul>
<li><code><b>void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g)
</b></code><br>
Tux&nbsp;Paint will call this function to inform the plugin of the Tux&nbsp;Paint will call this function to inform the plugin of the
RGB values of the currently-selected color in Tux&nbsp;Paint's RGB values of the currently-selected color in Tux&nbsp;Paint's
'Colors' palette. (It will be called whenever one of the plguin'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 Magic tools that accept colors becomes active, or the user picks a new
color while such a tool is currently active.) color while such a tool is currently active.)<br>
<br>
<li>Uint32 api_version(void)<br> <li><code><b>void click(magic_api * api, int which, SDL_Surface * snapshot,
The plugin should return an integer value representing the version of SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect)
the Tux&nbsp;Paint 'Magic' tool plugin API it was built against. </b></code><br>
Simply return TP_MAGIC_API_VERSION, which is defined in
"tp_magic_api.h", to satisfy this requirement.
<li>int init(magic_api * api)<br>
The plugin should do any initialization here. This function is called once,
at Tux&nbsp;Paint startup. Return '1' if initialization was successful,
or '0' if not (and Tux&nbsp;Paint will not present any 'Magic' tools
from the plugin).
<li>void shutdown(magic_api * api)<br>
The plugin should do any cleanup here. This function is called once,
at Tux&nbsp;Paint exit.
<li>void click(magic_api * api, int which, SDL_Surface * snapshot,
SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect)<br>
The plugin should apply the appropriate 'Magic' tool on the 'canvas' The plugin should apply the appropriate 'Magic' tool on the 'canvas'
surface. The (x,y) coordinates are where the mouse was (within the canvas) surface. The (x,y) coordinates are where the mouse was (within the canvas)
when the mouse button was clicked.<br> when the mouse button was clicked.<br>
<br>
The plugin should report back what part of the canvas was affected, by The plugin should report back what part of the canvas was affected, by
filling in the (x,y) and (w,h) values in 'update_rect'.<br> filling in the (x,y) and (w,h) values in 'update_rect'.<br>
<br>
The contents of the drawing canvas immediately prior to the mouse button The contents of the drawing canvas immediately prior to the mouse button
click is stored within the 'snapshot' canvas. click is stored within the 'snapshot' canvas.<br>
<br>
<li>void drag(magic_api * api, int which, SDL_Surface * snapshot, <li><code><b>void drag(magic_api * api, int which, SDL_Surface * snapshot,
SDL_Surface * canvas, int ox, int oy, int x, int y, SDL_Surface * canvas, int ox, int oy, int x, int y,
SDL_Rect * update_rect)<br> SDL_Rect * update_rect)</b></code><br>
The plugin should apply the appropriate 'Magic' tool on the 'canvas' 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 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 at the beginning and end of the stroke. Typically, plugins that let the
user "draw" effects onto the canvas call the Tux&nbsp;Paint 'Magic' tool user "draw" effects onto the canvas call the Tux&nbsp;Paint 'Magic' tool
plugin "line()" helper function. (See below).<br> plugin "line()" helper function. (See below).<br>
<br>
The plugin should report back what part of the canvas was affected, by The plugin should report back what part of the canvas was affected, by
filling in the (x,y) and (w,h) values in 'update_rect'.<br> filling in the (x,y) and (w,h) values in 'update_rect'.<br>
<br>
Note: The contents of the drawing canvas immediately prior to the mouse 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 button click remains as it was (when the plugin's "click()" function was
called), and is still available in the 'snapshot' canvas. called), and is still available in the 'snapshot' canvas.<br>
<br>
<li>void release(magic_api * api, int which, SDL_Surface * snapshot, <li><code><b>void release(magic_api * api, int which, SDL_Surface * snapshot,
SDL_Surface * canvas, int x, int y, SDL_Surface * canvas, int x, int y,
SDL_Rect * update_rect)<br> SDL_Rect * update_rect)</b></code><br>
The plugin should apply the appropriate 'Magic' tool on the 'canvas' The plugin should apply the appropriate 'Magic' tool on the 'canvas'
surface. The (x,y) coordinates are where the mouse was (within the canvas) surface. The (x,y) coordinates are where the mouse was (within the canvas)
when the mouse button was released.<br> when the mouse button was released.<br>
<br>
The plugin should report back what part of the canvas was affected, by The plugin should report back what part of the canvas was affected, by
filling in the (x,y) and (w,h) values in 'update_rect'.<br> filling in the (x,y) and (w,h) values in 'update_rect'.<br>
Note: The contents of the drawing canvas immediately prior to the mouse <br>
<b>Note:</b> The contents of the drawing canvas immediately prior to the mouse
button click remains as it was (when the plugin's "click()" function was button click remains as it was (when the plugin's "click()" function was
called), and is still available in the 'snapshot' canvas. called), and is still available in the 'snapshot' canvas.<br>
<br>
</ul>
</blockquote> </blockquote>
<h3>Tux Paint Functions</h3> </blockquote>
<h3><a name="tpfuncs">Tux Paint Functions</a></h3>
<blockquote> <blockquote>
@ -208,64 +331,74 @@ access via the "magic_api" structure, sent to all of the plugin's functions
(see above).</p> (see above).</p>
<ul> <ul>
<li>Uint32 getpixel(SDL_Surface * surf, int x, int y) <li><code><b>Uint32 getpixel(SDL_Surface * surf, int x, int y)</b></code>
Retreives the pixel value from the (x,y) coordinates of an SDL_Surface. 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' (You can use SDL's "SDL_GetRGB()" function to convert the Uint32 'pixel'
to a set of Uint8 RGB values.) to a set of Uint8 RGB values.)<br>
<br>
<li>void putpixel(SDL_Surface * surf, int x, int y, Uint32 pixel)<br> <li><code><b>void putpixel(SDL_Surface * surf, int x, int y, Uint32 pixel)
</b></code><br>
Sets the pixel value at position (x,y) of an SDL_Surface. 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 (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 RGB values to a Uint32 'pixel' value appropriate to the destination
surface.) surface.)<br>
<br>
<li>int in_circle(int x, int y, int radius)<br> <li><code><b>int in_circle(int x, int y, int radius)</b></code><br>
Returns '1' if the (x,y) location is within a circle of a particular Returns '1' if the (x,y) location is within a circle of a particular
radius (centered around the origin: (0,0)). Returns '0' otherwise. radius (centered around the origin: (0,0)). Returns '0' otherwise.
Useful to create 'Magic' tools that affect the canvas with a circular Useful to create 'Magic' tools that affect the canvas with a circular
brush shape. brush shape.<br>
<br>
<li>void show_progress_bar(void)<br> <li><code><b>void show_progress_bar(void)</b></code><br>
Asks Tux&nbsp;Paint to animate and draw one frame of its progress bar Asks Tux&nbsp;Paint to animate and draw one frame of its progress bar
(at the bottom of the screen). Useful for routines that may take a (at the bottom of the screen). Useful for routines that may take a
long time, to provide feedback to the user that Tux&nbsp;Paint has not long time, to provide feedback to the user that Tux&nbsp;Paint has not
crashed or frozen. crashed or frozen.<br>
<br>
<li>void tuxpaint_version(int * major, int * minor, int * revision)<br> <li><code><b>void tuxpaint_version(int * major, int * minor, int * revision)
</b></code><br>
Returns the version of Tux Paint being used (e.g., "0.9.18"), Returns the version of Tux Paint being used (e.g., "0.9.18"),
separated into three integers. separated into three integers.<br>
<br>
<li>void line(int which, SDL_Surface * canvas, SDL_Surface * snapshot, <li><code><b>void line(int which, SDL_Surface * canvas, SDL_Surface * snapshot,
int x1, int y1, int x2, int y2, int step, FUNC callback)<br> int x1, int y1, int x2, int y2, int step, FUNC callback)</b></code><br>
This function calculates all points on a line between the coordinates This function calculates all points on a line between the coordinates
(x1,y1) and (x2,y2). Every 'step' iterations, it calls the 'callback' (x1,y1) and (x2,y2). Every 'step' iterations, it calls the 'callback'
function.<br> function.<br>
<br>
It sends the 'callback' function the (x,y) coordinates on the line, It sends the 'callback' function the (x,y) coordinates on the line,
Tux&nbsp;Paint's "magic_api" struct (as a "void&nbsp;*" pointer), Tux&nbsp;Paint's "magic_api" struct (as a "void&nbsp;*" pointer),
a 'which' value, represening which of the plugin's 'Magic' tool is a 'which' value, represening which of the plugin's 'Magic' tool is
being used, and the current and snapshot canvases.<br> being used, and the current and snapshot canvases.<br>
<br>
Example prototype of a callback function that may be sent to
Tux&nbsp;Paint's "line()" 'Magic' tool plugin helper function:
<blockquote><code>
void exampleCallBack(void * ptr_to_api, int which_tool,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y);
</code></blockquote>
<p>Example prototype of a callback function that may be sent to <li><code><b>void playsound(Mix_Chunk * snd, int pan, int dist)</b></code><br>
Tux&nbsp;Paint's "line()" 'Magic' tool plugin helper function:</p>
<blockquote>
<p><code>void exampleCallBack(void * ptr_to_api, int which_tool,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y);</code></p>
</blockquote>
<li>void playsound(Mix_Chunk * snd, int pan, int dist)<br>
This function plays a sound (one loaded by the SDL helper library 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 "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' of the sound on the left and right speakers, based on the 'pan' and 'dist'
values sent to it.<br> values sent to it.<br>
<br>
A 'pan' of 128 causes the sound to be played at equal volume on the left 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 and right speakers. A 'pan' of 0 causes it to be played completely on the
left, and 255 completely on the right.<br> left, and 255 completely on the right.<br>
<br>
The 'dist' value affects overall volume. 255 is loudest, and 0 is silent.<br> The 'dist' value affects overall volume. 255 is loudest, and 0 is silent.<br>
The 'pan' and 'dist' values can be used to simulate location and distance of The 'pan' and 'dist' values can be used to simulate location and distance of
the 'Magic' tool effect. the 'Magic' tool effect.<br>
<br>
<li>void special_notify(int flag)<br> <li><code><b>void special_notify(int flag)</b></code><br>
This function notifies Tux&nbsp;Paint of special events. Various values This function notifies Tux&nbsp;Paint of special events. Various values
defined in "tp_magic_api.h" can be logically 'or'ed together and sent to defined in "tp_magic_api.h" can be logically 'or'ed together and sent to
this function. this function.
@ -279,17 +412,21 @@ access via the "magic_api" structure, sent to all of the plugin's functions
<li>SPECIAL_MIRROR &mdash; Similar to SPECIAL_FLIP, but for magic tools <li>SPECIAL_MIRROR &mdash; Similar to SPECIAL_FLIP, but for magic tools
that mirror the contents of the canvas. that mirror the contents of the canvas.
</ul> </ul>
<br>
<li>int button_down(void)<br> <li><code><b>int button_down(void)</b></code><br>
A '1' is returned if the mouse button is down; '0' otherwise. A '1' is returned if the mouse button is down; '0' otherwise.<br>
<br>
<li>float sRGB_to_linear(Uint8 srbg)<br> <li><code><b>float sRGB_to_linear(Uint8 srbg)</b></code><br>
Converts an 8-bit sRGB value (one between 0 and 255) to a linear Converts an 8-bit sRGB value (one between 0 and 255) to a linear
floating point value (between 0.0 and 1.0). floating point value (between 0.0 and 1.0).<br>
<br>
<li>uint8 linear_to_sRGB(float linear)<br> <li><code><b>uint8 linear_to_sRGB(float linear)</b></code><br>
Converts a linear floating point value (one between 0.0 and 1.0) to Converts a linear floating point value (one between 0.0 and 1.0) to
an 8-bit sRGB value (between 0 and 255). an 8-bit sRGB value (between 0 and 255).<br>
<br>
</ul> </ul>
</blockquote> </blockquote>
@ -306,11 +443,11 @@ access via the "magic_api" structure, sent to all of the plugin's functions
<blockquote> <blockquote>
<p>Use the C compiler's "-shared" command-line option to generate <p>Use the C compiler's "<code>-shared</code>" command-line option to generate
a shared object file ("<code>.so</code>") based on your 'Magic' tool a shared object file ("<code>.so</code>") based on your 'Magic' tool
plugin's C source code.</p> plugin's C source code.</p>
<p>Additionally, use the "tp-magic-config&nbsp;--cflags" command, <p>Additionally, use the "<code>tp-magic-config&nbsp;--cflags</code>" command,
supplied as part of Tux&nbsp;Paint, to provide additional command-line supplied as part of Tux&nbsp;Paint, to provide additional command-line
flags to your C compiler that will help it build your plugin.</p> flags to your C compiler that will help it build your plugin.</p>
@ -323,6 +460,15 @@ access via the "magic_api" structure, sent to all of the plugin's functions
</code></p> </code></p>
</blockquote> </blockquote>
<p><b>Note:</b> The characters around the "<code>tp-magic-config</code>"
command are a grave/backtick/backquote
("<code><b><font size=+1>`</font></b></code>"), and
not an apostrophe/single-quote ("<code><b><font size=+1>'</font></b></code>").
They tell the shell to execute the command within (in this case,
"<code>tp-magic-config&nbsp;...</code>"), and use its output
as an argument to the command being executed (in this case,
"<code>gcc&nbsp;...</code>").</p>
<p>A snippet from a more generalized Makefile might look like this:</p> <p>A snippet from a more generalized Makefile might look like this:</p>
<blockquote> <blockquote>
@ -334,8 +480,14 @@ access via the "magic_api" structure, sent to all of the plugin's functions
</code></p> </code></p>
</blockquote> </blockquote>
<p>Then install globally into: /usr/[local/]lib/tuxpaint/. <p>You may then install it globally into:
Or locally into: ~/.tuxpaint/magic/</p> <code>/usr/lib/tuxpaint/plugins/</code> or
<code>/usr/local/lib/tuxpaint/plugins/</code> (depending on how
Tux&nbsp;Paint was installed).</p>
<p>Or install it locally (for the current user only) into:
<code>~/.tuxpaint/magic/</code><br>
(<b>FIXME:</b> As of 2007-07-27, Tux&nbsp;Paint does not look here yet!)</p>
</blockquote> </blockquote>