Creating Tux Paint Magic Tool Plugins

Copyright 2007-2008 by Bill Kendrick and others
New Breed Software

bill@newbreedsoftware.com
http://www.tuxpaint.org/

July 5, 2007 - July 19, 2008

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 The GIMP, should be familiar with this plugin concept.)

Table of Contents

Prerequisites

Tux Paint is written in the C programming language, and uses the Simple DirectMedia Layer library ('libSDL', or simply 'SDL'; available from http://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.

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 first. 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.

  • 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()").

  • 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 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
    • MODE_FULLSCREEN
    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'

  • 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, 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 plugin's Magic tools that accept colors becomes active, and whenever the user picks a new color while such a tool is currently active.)

  • 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.)

  • 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.18").

  • int canvas_w Returns the width of the drawing canvas.

  • int canvas_h Returns the height of the drawing canvas.

  • 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).

    See also: sRGB article at Wikipedia.

  • 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).

    See also: HSV Color Space article at Wikipedia.

  • 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).

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.

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.

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 it with the target's dependency, in this case "my_plugin_1.c" or "my_plugin_2.c".

Windows

TBD

Mac OS X

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

Mac OS X

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:

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: http://www.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: http://www.tuxpaint.org/lists/.

Glossary