From c9ed43f6b22277aeee74f696396fed1663e196d9 Mon Sep 17 00:00:00 2001 From: Bill Kendrick Date: Mon, 3 Oct 2022 23:01:46 -0700 Subject: [PATCH] Magic API docs will be managed in tuxpaint-docs --- .../en/README.txt => docs/en/MAGIC-API.txt | 0 .../en/html/MAGIC-API.html | 0 docs/es_ES.UTF-8/MAGIC-API.txt | 1203 +++++++++++++++ docs/es_ES.UTF-8/html/MAGIC-API.html | 1374 +++++++++++++++++ docs/fr_FR.UTF-8/MAGIC-API.txt | 1203 +++++++++++++++ docs/fr_FR.UTF-8/html/MAGIC-API.html | 1374 +++++++++++++++++ docs/gl_ES.UTF-8/MAGIC-API.txt | 1203 +++++++++++++++ docs/gl_ES.UTF-8/html/MAGIC-API.html | 1374 +++++++++++++++++ docs/ja_JP.UTF-8/MAGIC-API.txt | 1203 +++++++++++++++ docs/ja_JP.UTF-8/html/MAGIC-API.html | 1374 +++++++++++++++++ magic/docs/Makefile | 1 - 11 files changed, 10308 insertions(+), 1 deletion(-) rename magic/docs/en/README.txt => docs/en/MAGIC-API.txt (100%) rename magic/docs/en/html/README.html => docs/en/html/MAGIC-API.html (100%) create mode 100644 docs/es_ES.UTF-8/MAGIC-API.txt create mode 100644 docs/es_ES.UTF-8/html/MAGIC-API.html create mode 100644 docs/fr_FR.UTF-8/MAGIC-API.txt create mode 100644 docs/fr_FR.UTF-8/html/MAGIC-API.html create mode 100644 docs/gl_ES.UTF-8/MAGIC-API.txt create mode 100644 docs/gl_ES.UTF-8/html/MAGIC-API.html create mode 100644 docs/ja_JP.UTF-8/MAGIC-API.txt create mode 100644 docs/ja_JP.UTF-8/html/MAGIC-API.html delete mode 100644 magic/docs/Makefile diff --git a/magic/docs/en/README.txt b/docs/en/MAGIC-API.txt similarity index 100% rename from magic/docs/en/README.txt rename to docs/en/MAGIC-API.txt diff --git a/magic/docs/en/html/README.html b/docs/en/html/MAGIC-API.html similarity index 100% rename from magic/docs/en/html/README.html rename to docs/en/html/MAGIC-API.html diff --git a/docs/es_ES.UTF-8/MAGIC-API.txt b/docs/es_ES.UTF-8/MAGIC-API.txt new file mode 100644 index 000000000..5ecd743bb --- /dev/null +++ b/docs/es_ES.UTF-8/MAGIC-API.txt @@ -0,0 +1,1203 @@ + Creating Tux Paint Magic Tool Plugins + + Copyright 2007-2022 by various contributors; see AUTHORS.txt + https://tuxpaint.org/ + + July 5, 2007 - January 20, 2022 + + ---------------------------------------------------------------------- + +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 + + * Prequisites + * Interfaces + * 'Magic' tool plugin functions + * Common arguments to plugin functions + * Required Plugin Functions + * Plugin "housekeeping" functions + * Plugin event functions + * Tux Paint Functions and Data + * Pixel Manipulations + * Helper Functions + * Informational + * Tux Paint System Calls + * Color Conversions + * Helper Macros in "tp_magic_api.h" + * Constant Definitions in "tp_magic_api.h" + * Compiling + * Linux and other Unix-like Platforms + * Windows + * Mac OS X + * Installing + * Linux and other Unix-like Platforms + * Windows + * Mac OS X + * Creating plugins with multiple effects + * Example Code + * Getting Help + * Glossary + + ---------------------------------------------------------------------- + +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. + * magic_api * api + Pointer to a C structure containing pointers to Tux Paint + functions and other data that the plugin can (and sometimes + should) use. The contents of this struct are described below. + + Note: The magic_api struct is defined in the C header file + "tp_magic_api.h", which you should include at the top of your + plugin's C source file: + + #include "tp_magic_api.h" + + * int which + An index the plugin should use to differentiate different 'Magic' + tools, if the plugin provides more than one. (If not, "which" will + always be 0.) See "Creating plugins with multiple effects", below. + + * SDL_Surface * snapshot + A snapshot of the previous Tux Paint canvas, taken when the the + mouse was first clicked to activate the current magic tool. If you + don't continuously affect the image during one hold of the mouse + button, you should base your effects off the contents of this + canvas. (That is, read from "snapshot" and write to "canvas", + below.) + + * SDL_Surface * canvas + The current Tux Paint drawing canvas. Your magical effects should + end up here! + + * SDL_Rect * update_rect + A pointer to an SDL 'rectangle' structure that you use to tell + Tux Paint what part of the canvas has been updated. If your effect + affects a 32x32 area centered around the mouse pointer, you would + fill the SDL_Rect as follows: + + update_rect->x = x - 16; + update_rect->y = y - 16; + update_rect->w = 32; + update_rect->h = 32; + + Or, if your effect changes the entire canvas (e.g., flips it + upside-down), you'd fill it as follows: + + update_rect->x = 0; + update_rect->y = 0; + update_rect->w = canvas->w; + update_rect->h = canvas->h; + + Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than + just an "SDL_Rect") because you need to fill in its contents. + Because it is a pointer, you access its elements via "->" (arrow) + rather than "." (dot). + + Required Plugin Functions: + + Your plugin is required to contain, at the least, all of the + following functions. + + Note: Remember, your plugin's function names must be preceded by + your plugin's filename. That is, if your plugin is called "zoom.so" + (on Linux) or "zoom.dll" (on Windows), then the names of your + functions must begin with "zoom_" (e.g., "zoom_get_name(...)"). + + Plugin "housekeeping" functions: + + * Uint32 api_version(void) + The plugin should return an integer value representing the + version of the Tux Paint 'Magic' tool plugin API the plugin was + built against. The safest thing to do is return the value of + TP_MAGIC_API_VERSION, which is defined in "tp_magic_api.h". If + Tux Paint deems your plugin to be compatible, it will go ahead + and use it. + + Note: Called once by Tux Paint, at startup. It is called first. + + * int init(magic_api * api) + The plugin should do any initialization here. Return '1' if + initialization was successful, or '0' if not (and Tux Paint will + not present any 'Magic' tools from the plugin). + + Note: Called once by Tux Paint, at startup. It is called 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()"). + + * int get_group(magic_api * api, int which) + Use this to group tools together within sections of the 'Magic' + selector. A number of groups are pre-defined within an enum + found in "tp_magic_api.h": + * MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of + the image, like Blur, Emboss, and Ripples + * MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect + the colors of the image without distortion, like Darken, + Negative, and Tint + * MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the + entire picture, like Shift, Flip, and Waves + * MAGIC_TYPE_PAINTING mdash; Tools that generally paint new + content at the cursor position, like Grass, Bricks, and + Rails + * MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in + multiple places at once, like Kaleidoscope and the Symmetry + tools + * MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply + decorations to the entire picture, like Blinds and + Checkboard + * MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, + like Flower, the String tools, and the Rainbow-arc-drawing + tools. + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + Note: Added to Tux Paint 0.9.27; Magic API version '0x00000005' + + * SDL_Surface * get_icon(magic_api * api, int which) + This should return an SDL_Surface containing the icon + representing the tool. (A greyscale image with alpha, no larger + than 40x40.) This will appear on the button in the 'Magic' + selector within Tux Paint. + + Tux Paint will free ("SDL_FreeSurface()") the surface upon exit. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + * char * get_description(magic_api * api, int which, int mode) + This should return a string containing the description of how to + use a particular magic tool. This will appear as a help tip, + explained by Tux the Penguin, within Tux Paint. + + Tux Paint will free() the string upon exit, so you should wrap + it in a C strdup() call. + + Note: For each Magic tool your plugin claims to contain + (reported by your "get_tool_count()" function), this function + will be called for each mode the tool claims to support + (reported by your "modes()" function). + + In other words, if your plugin contains two tools, one which + works in paint mode only, and the other that works in both paint + mode and full-image mode, your plugin's "get_description()" will + be called three times. + + * int requires_colors(magic_api * api, int which) + Return a '1' if the 'Magic' tool accepts colors (the 'Colors' + palette in Tux Paint will be available), or '0' if not. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + * int modes(magic_api * api, int which) + This lets you tell Tux Paint what modes your tool can be used + in; either as a tool the user can paint with, or a tool that + affects the entire drawing at once. + + You must return a value that's some combination of one or more + of available modes: + * MODE_PAINT - freehand paint (click and drag) + * MODE_FULLSCREEN - applies to full image with one click + * MODE_PAINT_WITH_PREVIEW - freehand paint, with preview + (click and drag) + * MODE_ONECLICK - applies to an area around the mouse, with + one click + e.g., if your tool is only one that the user can paint with, + return "MODE_PAINT". If the user can do both, return + "MODE_PAINT | MODE_FULLSCREEN" to tell Tux Paint it can do both. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + Note: Added to Tux Paint 0.9.21; Magic API version '0x00000002' + + * 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.) + + * Uint32 xorpixel(SDL_Surface * surf, int x, int y) + Applies an XOR (exclusive-or) operation to the pixel at + coordinates (x,y) of the SDL_Surface. Applying an XOR again at + the same position will return the pixel to the original value. + Useful for displaying temporary 'rubberband' lines, outlines, + and crosshairs, while utilizing a Magic Tool. + + * SDL_Surface * scale(SDL_Surface * surf, int w, int h, + int keep_aspect) + This accepts an existing SDL surface and creates a new one + scaled to an arbitrary size. (The original surface remains + untouched.) + + The "keep_aspect" flag can be set to '1' to force the new + surface to stay the same shape (aspect ratio) as the original, + meaning it may not be the same width and height you requested. + (Check the "->w" and "->h" elements of the output + "SDL_Surface *" to determine the actual size.) + + Helper Functions + + * int in_circle(int x, int y, int radius) + Returns '1' if the (x,y) location is within a circle of a + particular radius (centered around the origin: (0,0)). Returns + '0' otherwise. Useful to create 'Magic' tools that affect the + canvas with a circular brush shape. + + * void line(void * api, int which, SDL_Surface * canvas, + SDL_Surface * snapshot, int x1, int y1, int x2, int y2, + int step, FUNC callback) + This function calculates all points on a line between the + coordinates (x1,y1) and (x2,y2). Every 'step' iterations, it + calls the 'callback' function. + + It sends the 'callback' function the (x,y) coordinates on the + line, Tux Paint's "magic_api" struct (as a "void *" pointer + which you need to send to it), a 'which' value, represening + which of the plugin's 'Magic' tool is being used, and the + current and snapshot canvases. + + Example prototype of a callback function that may be sent to + Tux Paint's "line()" 'Magic' tool plugin helper function: + + void exampleCallBack(void * ptr_to_api, int which_tool, + SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y); + + Example use of the "line()" helper (e.g., within a plugin's + draw() function): + + api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, + 1, exampleCallBack); + + * Uint8 touched(int x, int y) + This function allows you to avoid re-processing the same pixels + multiple times when the user drags the mouse across an area of + the canvas, thus increasing Tux Paint's response time, + especially with math-heavy effects. + + If your effect's "click()", "drag()" and/or "release()" + functions take the contents of the source surface ("snapshot") + and always create the same results in the desintation surface + ("canvas"), you should wrap the effect in a call to + "api->touched()". + + This function simply returns whether or not it had already been + called for the same (x,y) coordinates, since the user first + clicked the mouse. In other words, the first time you call it + for a particular (x,y) coordinate, it returns '0'. Future calls + will return '1' until the user releases the mouse button. + + Note: Magic effects that continuously affect the destination + surface ("canvas") (ignoring the "snapshot surface) have no + reason to use this function. The "Blur" and "Smudge" tools that + ship with Tux Paint are examples of such effects. + + Informational + + * char * tp_version + A string containing the version of Tux Paint that's running + (e.g., "0.9.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. + + * min(x, y) + The minimum of 'x' and 'y'. (That is, if 'x' is less than or equal + to 'y', then the value of 'x' will be used. If 'y' is less than + 'x', it will be used.) + + * max(x, y) + The maximum of 'x' and 'y'. The opposite of min(). + + * clamp(lo, value, hi) + A value, clamped to be no smaller than 'lo', and no higher than + 'hi'. (That is, if 'value' is less than 'lo', then 'lo' will be + used; if 'value' is greater than 'hi', then 'hi' will be used; + otherwise, 'value' will be used.) + + Example: red = clamp(0, n, 255); + Tries to set 'red' to be the value of 'n', but without allowing it + to become less than 0 or greater than 255. + + Note: This macro is simply a #define of: + "(min(max(value,lo),hi))". + + Constant Defintions in "tp_magic_api.h": + + The following is a summary of constant values that are set + (via "#define") within the 'Magic' tool API header file. + + * TP_MAGIC_API_VERSION + This integer value represents which version of the Tux Paint + 'Magic' tool API the header corresponds to. + + It should be referenced by your magic tool's "api_version()" + function, to inform the running copy of Tux Paint whether or not + your plugin is compatible. + + Note: This version number does not correspond to Tux Paint's own + release number (e.g., "0.9.18"). The API will not change every + time a new version of Tux Paint is released, which means plugins + compiled for earlier versions of Tux Paint will often run under + newer versions. + + * SPECIAL_MIRROR + SPECIAL_FLIP + These are flags for Tux Paint's "special_notify()" helper + function. They are described above. + + ---------------------------------------------------------------------- + +Compiling + + Linux and other Unix-like Platforms + + Use the C compiler's "-shared" command-line option to generate a + shared object file (".so") based on your 'Magic' tool plugin's C + source code. + + Use the "tp-magic-config --cflags" command, supplied as part of + Tux Paint — or in some cases, as part of a "Tux Paint 'Magic' Tool + Plugin Development package" — to provide additional command-line flags + to your C compiler that will help it build your plugin. + + Command-Line Example + + As a stand-alone command, using the GNU C Compiler and BASH shell, + for example: + + $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o + my_plugin.so + + Note: The characters around the "tp-magic-config" command are a + grave/backtick/backquote ("`"), and not an apostrophe/single-quote + ("'"). They tell the shell to execute the command within (in this + case, "tp-magic-config ..."), and use its output as an argument to + the command being executed (in this case, "gcc ..."). + + Makefile Example + + A snippet from a Makefile to compile a Tux Paint "Magic" tool plugin + might look like this: + + +------------------------------------------------------+ + | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) | + | | + | my_plugin.so: my_plugin.c | + | gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c | + +------------------------------------------------------+ + + The first line sets up Makefile variable ("CFLAGS") that contains + flags for the compiler. "-Wall" asks for all compiler warnings to be + shown. "-O2" asks for level 2 optimization. + "($shell tp-magic-config --cflags)" runs "tp-magic-config" to + retrieve additional compiler flags that "Magic" tool plugins + require. (The "$(shell ...)" directive is similar to the ` ("grave") + character in the BASH shell examples, above.) + + The next line defines a Makefile target, "my_plugin.so", and states + that it depends on the C source file "my_plugin.c". (Any time the C + file changes, "make" will know to recompile it and produce an + updated ".so" file. If the C file hadn't changed, it won't bother + recompiling.) + + The last line defines the command "make" should run when it + determines that it needs to (re)compile the ".so" file. Here, we're + using "gcc", with "-shared and "$(CFLAGS)" command-line arguments, + like above. "-o my_plugin.so" tells the C compiler that the output + file should be "my_plugin.so". The last argument is the C file to + compile, in this case "my_plugin.c". + + Note: Commands listed below a Makefile target should be intented + using a single tab character. + + Advanced Makefile + + An even more generalized Makefile might look like this: + + +----------------------------------------------------+ + | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) | + | | + | my_plugin_1.so: my_plugin_1.c | + | $(CC) -shared $(CFLAGS) -o $@ $< | + | | + | my_plugin_2.so: my_plugin_2.c | + | $(CC) -shared $(CFLAGS) -o $@ $< | + +----------------------------------------------------+ + + As before, there are lines that define the command "make" should run + when it determines that it needs to (re)compile the ".so" file(s). + However, more general terms are used... + + "$(CC)" gets expanded to your default C compiler (e.g., "gcc"). + "-shared and "$(CFLAGS)" are command-line arguments to the compiler, + like above. "-o $@" tells the C compiler what the output file should + be; "make" replaces "$@" with the name of the target, in this case + "my_plugin_1.so" or "my_plugin_2.so". And finally, the last argument + is the C file to compile; "make" replaces 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: + + * Use a C "enum" to enumerate the effects, and count them. + + enum { + ONE_TOOL, + ANOTHER_TOOL, + AND_YET_ANOTHER_TOOL, + NUM_TOOLS }; + + * Return the value of "NUM_TOOLS" when "get_tool_count()" is called, + and compare "which" values sent to other functions with the other + enumerated values. + + * Create arrays of "NUM_TOOLS" length to contain effect-specific data. + + char * my_plugin_snd_filenames[NUM_TOOLS] = { + "one.ogg", "another.ogg", "yet_another.ogg" }; + Mix_Chunk * my_plugin_snds[NUM_TOOLS]; + + * Use a C "for"-loop to load or create the effect-specific data (such + as loading sound effects during your "init()"). + + int i; + char fname[1024]; + + for (i = 0; i < NUM_TOOLS; i++) + { + /* Becomes, for example, + "/usr/share/tuxpaint/sounds/magic/one.ogg" */ + + snprintf(fname, sizeof(fname), "%s/sounds/magic/%s", + api->data_prefix, my_plugin_snd_filenames[i]; + + my_plugin_snds[i] = Mix_LoadWAV(fname); + } + + * Similarly, do the same to free them later (such as freeing sound + effects during your "shutdown()"). + + int i; + + for (i = 0; i < NUM_TOOLS; i++) + Mix_FreeChunk(my_plugin_snds[i]); + + * Use "which" values sent to your functions as an index into those + arrays (e.g., for playing the appropriate sound effect for a tool). + + Note: Even if your plugin currently contains only one effect, it may be + useful to follow the steps above so that you can add a new variation of + an effect with little effort. ("NUM_TOOLS" will simply be '1', your + arrays will be of length '1', etc.) + + ---------------------------------------------------------------------- + +Example Code + + The C source file "tp_magic_example.c" contains a complete example of a + plugin with multiple simple effects. + + ---------------------------------------------------------------------- + +Getting Help + + For more information, check the Tux Paint website: + https://tuxpaint.org/, and the Simple DirectMedia Layer library website: + http://www.libsdl.org/. + + Additionally, other Tux Paint developers and users can be found on the + "tuxpaint-devel" and "tuxpaint-users" mailing lists: + https://tuxpaint.org/lists/. + + ---------------------------------------------------------------------- + +Glossary + + * alpha: See "RGBA" + * &: See "ampersand" + * ampersand: "&". A symbol in C that allows you to refer to the memory + address of a variable; that is, a pointer. (For example, consider + "int i;". Later, "&i" refers to the memory where "i" is stored, not + the value of "i" itself; it is a 'pointer to "i"'.) + * API: Application Programming Interface. TBD + * argument: A value sent to a function. + * arrow: "->". A symbol in C that references an element within a pointer + to a struct. + * backquote: See "grave." + * backtick: See "grave." + * bit: "Binary digit." Bits are the basic storage unit in a computer's + memory, disk, networking, etc. They represent either 0 or 1. (Compared + to a decimal digit, which can be anything between 0 and 9.) Just as a + series of decimal digits can represent a larger number (e.g., "1" and + "5" is fifteen (15)), so can bits (e.g., "1" and "0", is two). In + decimal, we go from right to left: ones place, tens place, hundreds + place, thousands place, etc. In binary, it is: ones place, twos place, + fours place, eights place, etc. (See also "byte.") + * blue: See "RGBA" + * boolean 'or': A mathematical operation that results in a true value if + either operand is true. ("1 | 0", "0 | 1" and "1 | 1" all result in + "1". "0 | 0" results in "0".) + * |: See "boolean 'or'" + * .: See "dot" + * `: See "grave." + * *: See "star" + * byte: A unit of memory made up of 8 bits. As a signed value, it can + represent -128 through 127. As an unsigned value, it can represent 0 + through 255. As a series of bits, for example, the byte "00001100" + represents the decimal value 12. + * callback: TBD + * C enumeration: A construct in C that allows you to label numeric + values (usually starting at 0 and incrementing by one). (e.g., "enum { + ONE, TWO, THREE };" + * C function: TBD + * C header file: TBD + * channel: TBD + * click: The action of pressing a button on a mouse. + * coordinates: A set of numbers corresponding to a physical position; + for example, in a two-dimensional (2D) image, "X" and "Y" coordinates + specify the position across (left-to-right) and down the image, + respectively. In SDL, the coordinates (0,0) is the top-leftmost pixel + of a surface. + * C pointer: A variable that contains the location of a piece of memory; + usually used to 'point' to another variable. Since C functions can + only return one value as a result, pointers are often sent to + functions to allow the function to change the values of multiple + variables. (For example, Tux Paint's "rgbtohsv()" and "hsvtorgb()".) + * C structure: A construct in C that allows you to declare a new + variable 'type' which may contain other types within. For example, + SDL's "SDL_Rect" contains four integer values, the coordinates of the + rectangle (X,Y), and its dimensions (width and height). + * #define: A C statement that defines a substitution that can occur + later in the code. Generally used for constant values (e.g., + "#define RADIUS 16"; all instances of "RADIUS" will be replaced with + "16"), but can also be used to create macros. Typically placed within + C header files. + * dimensions: The size of an object, in terms of its width (left to + right) and height (top to bottom). + * .dll: See "Shared Object" + * dot: ".". A symbol in C that references an element within a struct. + * drag: The action of moving a mouse while the button remains held. + * element: A variable stored within a C structure. (Example: "w" and "h" + elements of SDL_Surface store the surface's width and height, + respectively.) + * enum: See "C enumeration" + * float: See "floating point" + * floating point: TBD + * format: An SDL_Surface element (a pointer to an SDL_PixelFormat + structure) that contains information about a surface; for example, the + number of bits used to represent each pixel). (See also the + "SDL_PixelFormat(3) man page) + * free(): A C function that frees (deallocates) memory allocated by + other C functions (such as "strdup()"). + * function: See "C function" + * gcc: The GNU C compiler, a portable Open Source compiler. (See also + the "gcc(1)" man page) + * GNU C Compiler: See "gcc" + * grave: The "`" character; used by the BASH shell to use the output of + a command as the command-line arguments to another. + * green: See "RGBA" + * ->: See "arrow" + * .h: See "C header file" + * header: See "C header file" + * header file: See "C header file" + * HSV: Hue, Saturation and Value. TBD + * hue: See "HSV" + * IMG_Load(): An SDL_image function that loads an image file (e.g., a + PNG) and returns it as an "SDL_Surface *". + * #include: A C statement that asks the compiler to read the contents of + another file (usually a header file). + * int: See "integer" + * integer: TBD + * libSDL: See "Simple DirectMedia Layer" + * linear: TBD + * macro: A C construct that looks similar to a C function, but is simply + a #define that is expanded 'inline'. For example, if you declared the + macro "#define ADD(A,B) ((A)+(B))", and then used it with "c = + ADD(1,2);", that line of code would literally expand to "c = ((1) + + (2));", or more simply, "c = 1 + 2;". + * magic_api: A C structure that is passed along to a plugin's functions + that exposes data and functions within the running copy of Tux Paint. + * make: A utility that automatically determines which pieces of a larger + program need to be recompiled, and issues the commands to recompile + them. (See also "Makefile") + * Makefile: A text file used by the "make" utility; it describes the + relationships among files in your program, and the commands for + updating each file. (For example, to compile a human-readable + source-code file into a computer-readable executable program file.) + * Magic tool: One of a number of effects or drawing tools in Tux Paint, + made available via the "Magic" tool button. + * Mix_Chunk *: (A pointer to) a C structure defined by SDL_mixer that + contains a sound. + * Mix_FreeChunk(): An SDL_mixer function that frees (deallocates) memory + allocated for an SDL_mixer sound 'chunk' ("Mix_Chunk *"). + * Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, + Ogg Vorbis, etc.) and returns it as a "Mix_Chunk *". + * namespace: TBD + * OGG: See "Ogg Vorbis" + * Ogg Vorbis: TBD (See also: "WAV") + * Plugin: TBD + * PNG: Portable Network Graphics. An extensible file format for the + lossless, portable, well-compressed storage of raster images. It's the + file format Tux Paint uses to save images, and for its brushes and + stamps. It's an easy way to store 32bpp RGBA images (24bpp true color + with full 8bpp alpha transparency), excellent for use in graphics + programs like Tux Paint. (See also the "png(5) man page) + * pointer: See "C pointer" + * red: See "RGBA" + * release: The action of releasing a button on a mouse. + * RGBA: "Red, Green, Blue, Alpha." TBD + * RGB: See "RBGA" + * saturation: See "HSV" + * SDL: See "Simple DirectMedia Layer" + * SDL_FreeSurface(): An libSDL function that frees (deallocates) memory + allocated for an SDL surface ("SDL_Surface *"). (See also the + "SDL_FreeSurface(3)" man page) + * SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value + (e.g., one returned from the Tux Paint's Magic tool API helper + function "getpixel()"), the format of the surface the pixel was taken + from, and pointers to three Uint8 variables, will place the Red, Green + and Blue (RGB) values of the pixel into the three Uint8 variables. + (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, + &b);".) (See also the "SDL_GetRGB(3)" man page) + * SDL_MapRGB(): A libSDL function that, given the format of a surface + and Uint8 values representing Red, Green and Blue values for a pixel, + returns a Uint32 pixel value that can be placed in the surface (e.g., + using Tux Paint's Magic tool API helper function "putpixel()"). + (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) + (See also the "SDL_MapRGB(3)" man page) + * SDL_image: A library on top of libSDL that can load various kinds of + image files (e.g., PNG) and return them as an "SDL_Surface *". + * SDL_mixer: A library on top of libSDL that can load various kinds of + sound files (WAV, Ogg Vorbis, etc.) and play back multiple sounds at + once (mix them). + * SDL_Rect: A C structure defined by libSDL that represents a + rectangular area. It contains elements representing the coordinates of + the top left corner of the rectange (x,y) and the dimensions of the + rectangle (w,h). (See also the "SDL_Rect(3)" man page) + * SDL_Surface *: (A pointer to) a C structure defined by libSDL that + contains a drawing surface. (See also the "SDL_Surface(3)" man page) + * Shared Object: A piece of code that's compiled separately from the + main application, and loaded dynamically, at runtime. + * Simple DirectMedia Layer: A programming library that allows programs + portable low level access to a video framebuffer, audio output, mouse, + and keyboard. (See also: http://www.libsdl.org/) + * snprintf(): A C function, related to "printf()", which takes a + 'format' string and one or more additional arguments, and puts them + together. "snprintf()" takes the resulting output and stores it into a + string, making sure not to go beyond the string's buffer size (which + must also be supplied). For example, assume a string "char str[20];" + has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill", + "32");" will store "Name: Bill, Age: 32" into 'str'. (See also the + "snprintf(3)" man page) + * .so: See "Shared Object" + * sRBG: See "RGBA" + * star: "*". A symbol in C that, when used in the declaration of + variables (e.g., arguments to a function), denotes that the variable + is a pointer. (For example, "int * p;" means that "p" is a pointer to + an integer.) When used next to a pointer, it 'dereferences' the + variable. (For example, later "*p = 50;" assigns the value of 50 to + the memory that "p" points to; it does not change the value of "p", + which is still a pointer to an integer. In essence, it changed the + integer that's being pointed to.) + * strdup(): A C function that allocates enough memory to store a copy of + a string, copies the string to it, and returns a "char *" pointer to + the new copy. (See also the "strdup(3)" man page) + * struct: See "C structure" + * The GIMP: An Open Source image manipulation and paint program. + * tp_magic_api.h: A header file that defines Tux Paint's Magic tool API. + Plugins must '#include' it. + * tp-magic-config: A command-line program that provides information + about the installed version of Tux Paint to plugin developers (such as + what C compiler flags they should compile with, and where plugin + shared objects and data files should be installed). (See also the + "tp-magic-config(3)" man page.) + * Uint32: A 32-bit, unsigned integer (defined by libSDL). In other + words, four bytes that can represent 0 through 4294967295. (Typically + used to hold enough information to store three or four bytes + representing a pixel's color; i.e., RBGA value). + * Uint8: An 8-bit, unsigned integer (defined by libSDL). In other words, + a byte that can represent 0 through 255. + * unsigned: In C, a variable that can store a numeric value can be + declared as either "signed" (the default), or "unsigned". In the + former case, one bit of the value is used to denote the sign of the + value (either positive or negative). In the latter case, the value can + only be positive, but benefits from one extra bit of storage for the + number. A signed byte (8 bits), for example, can represent any number + between -128 and 127. An unsigned byte can go up to 255, but it cannot + go below 0. For the purposes of graphics in SDL, unsigned values + should be used for RGB values, since each channel (red, green and + blue) may be between 0 (off) and 255 (brightest). + * value: See "HSV" + * variable: A construct in computer programming that contains a value + which can be referenced again later by referring to the variable's + name, and typically changed later. For example, a variable to hold + someone's age could be declared as an integer: "int a;". It can be + examined later: "if (a >= 18) { /* they are an adult */ } else { /* + they are not an adult */ }". + * WAV: TBD (See also "Ogg Vorbis") + * (w,h): See "Dimensions" + * (x,y): See "Coordinates" diff --git a/docs/es_ES.UTF-8/html/MAGIC-API.html b/docs/es_ES.UTF-8/html/MAGIC-API.html new file mode 100644 index 000000000..6646d45d3 --- /dev/null +++ b/docs/es_ES.UTF-8/html/MAGIC-API.html @@ -0,0 +1,1374 @@ + +Creating Tux Paint Magic Tool Plugins + + + + + + + +
+

Creating Tux Paint Magic Tool Plugins

+ +

Copyright 2007-2022 by various contributors; see AUTHORS.txt
+https://tuxpaint.org/

+ +

July 5, 2007 - January 20, 2022

+
+ +
+ +

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. + +
    +
  • magic_api * api
    + Pointer to a C structure containing pointers to Tux Paint functions and + other data that the plugin can (and sometimes should) use. + The contents of this struct are described below.
    +
    + Note: The magic_api struct is defined in the C header file + "tp_magic_api.h", which you should include at the top of your + plugin's C source file: +
    + #include "tp_magic_api.h" +
    + +
  • int which
    + An index the plugin should use to differentiate different 'Magic' tools, + if the plugin provides more than one. (If not, "which" will always be 0.) + See "Creating plugins with multiple effects", + below.
    +
    + +
  • SDL_Surface * snapshot
    + A snapshot of the previous Tux Paint canvas, taken when the the + mouse was first clicked to activate the current magic tool. If you don't + continuously affect the image during one hold of the mouse button, + you should base your effects off the contents of this canvas. + (That is, read from "snapshot" and write to + "canvas", below.)
    +
    + +
  • SDL_Surface * canvas
    + The current Tux Paint drawing canvas. Your magical effects should end + up here!
    +
    + +
  • SDL_Rect * update_rect
    + A pointer to an SDL 'rectangle' structure that you use to tell Tux Paint + what part of the canvas has been updated. If your effect affects a + 32x32 area centered around the mouse pointer, you would fill the SDL_Rect + as follows: +
    + update_rect->x = x - 16;
    + update_rect->y = y - 16;
    + update_rect->w = 32;
    + update_rect->h = 32; +
    + Or, if your effect changes the entire canvas (e.g., flips it upside-down), + you'd fill it as follows: +
    + update_rect->x = 0;
    + update_rect->y = 0;
    + update_rect->w = canvas->w;
    + update_rect->h = canvas->h; +
    + Note: "update_rect" is a C pointer + (an "SDL_Rect *" rather than just an + "SDL_Rect") because you need to fill in its contents. + Because it is a pointer, you access its elements via + "->" (arrow) rather than "." (dot). +
+ +

Required Plugin Functions:

+ +
+ +

Your plugin is required to contain, at the least, all of the +following functions.

+ +

Note: Remember, your plugin's function names must be +preceded by your plugin's filename. That is, if your plugin is called +"zoom.so" (on Linux) or "zoom.dll" (on Windows), +then the names of your functions must begin with "zoom_" +(e.g., "zoom_get_name(...)").

+ +
Plugin "housekeeping" functions:
+ +
    +
  • Uint32 api_version(void)
    + The plugin should return an integer value representing the version of + the Tux Paint 'Magic' tool plugin API the plugin was built against. + The safest thing to do is return the value of + TP_MAGIC_API_VERSION, which is defined in + "tp_magic_api.h". If Tux Paint deems your plugin to + be compatible, it will go ahead and use it.
    +
    + Note: Called once by Tux Paint, at startup. It is called + first.
    +
    + +
  • int init(magic_api * api)
    + The plugin should do any initialization here. + Return '1' if initialization was successful, + or '0' if not (and Tux Paint will not present any 'Magic' tools + from the plugin).
    +
    + Note: Called once by Tux Paint, at startup. It is called + 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()").
    +
    + +
  • int get_group(magic_api * api, + int which)
    + Use this to group tools together within sections of the + 'Magic' selector. A number of groups are pre-defined within + an enum found in "tp_magic_api.h": +
      +
    • MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of the image, like Blur, Emboss, and Ripples
      • +
    • MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect the colors of the image without distortion, like Darken, Negative, and Tint
      • +
    • MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the entire picture, like Shift, Flip, and Waves
      • +
    • MAGIC_TYPE_PAINTING mdash; Tools that generally paint new content at the cursor position, like Grass, Bricks, and Rails
      • +
    • MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in multiple places at once, like Kaleidoscope and the Symmetry tools
      • +
    • MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply decorations to the entire picture, like Blinds and Checkboard
      • +
    • MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, like Flower, the String tools, and the Rainbow-arc-drawing tools.
      • +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    + Note: Added to Tux Paint 0.9.27; Magic API version + '0x00000005'
    +
    + +
  • SDL_Surface * get_icon(magic_api * api, + int which)
    + This should return an SDL_Surface containing the icon representing + the tool. (A greyscale image with alpha, no larger than 40x40.) + This will appear on the button in the 'Magic' selector within + Tux Paint.
    +
    + Tux Paint will free ("SDL_FreeSurface()") the surface upon + exit.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + +
  • char * get_description(magic_api * api, + int which, int mode)
    + This should return a string containing the description of how to + use a particular magic tool. + This will appear as a help tip, explained by Tux the Penguin, within + Tux Paint.
    +
    + Tux Paint will free() the string upon exit, so you should + wrap it in a C strdup() call.
    +
    + Note: For each Magic tool your plugin claims to + contain (reported by your "get_tool_count()" function), + this function will be called for each mode the tool claims to support + (reported by your "modes()" function).
    +
    + In other words, if your plugin contains two tools, one which works in + paint mode only, and the other that works in both paint mode and + full-image mode, your plugin's "get_description()" will be + called three times.
    +
    + +
  • int requires_colors(magic_api * api, + int which)
    + Return a '1' if the 'Magic' tool accepts colors (the 'Colors' palette in + Tux Paint will be available), or '0' if not.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + +
  • int modes(magic_api * api, + int which)
    + This lets you tell Tux Paint what modes your tool can be used in; + either as a tool the user can paint with, or a tool that affects + the entire drawing at once.
    +
    + You must return a value that's some combination of one or more of + available modes: +
      +
    • MODE_PAINT - freehand paint (click and drag)
      • +
    • MODE_FULLSCREEN - applies to full image with one click
      • +
    • MODE_PAINT_WITH_PREVIEW - freehand paint, with preview (click and drag)
      • +
    • MODE_ONECLICK - applies to an area around the mouse, with one click
      • +
    + e.g., if your tool is only one that the user can paint with, + return "MODE_PAINT". If the user can do both, + return "MODE_PAINT | MODE_FULLSCREEN" + to tell Tux Paint it can do both.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + Note: Added to Tux Paint 0.9.21; Magic API version + '0x00000002'
    +
    + +
  • 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.)
    +
    + +
  • Uint32 xorpixel(SDL_Surface * surf, + int x, int y)
    + Applies an XOR (exclusive-or) operation to the pixel at coordinates + (x,y) of the SDL_Surface. Applying an XOR again at the same position + will return the pixel to the original value. Useful for displaying + temporary 'rubberband' lines, outlines, and crosshairs, while + utilizing a Magic Tool.
    +
    + +
  • SDL_Surface * scale(SDL_Surface * surf, + int w, int h, int keep_aspect)
    + This accepts an existing SDL surface and creates a new one scaled to an + arbitrary size. (The original surface remains untouched.)
    +
    + The "keep_aspect" flag can be set to '1' to force the new + surface to stay the same shape (aspect ratio) as the original, meaning + it may not be the same width and height you requested. (Check the + "->w" and "->h" elements of the output + "SDL_Surface *" to determine the actual size.)
    +
    +
+ +
+ +

Helper Functions

+ +
+ +
    +
  • int in_circle(int x, int y, + int radius)
    + Returns '1' if the (x,y) location is within a circle of a particular + radius (centered around the origin: (0,0)). Returns '0' otherwise. + Useful to create 'Magic' tools that affect the canvas with a circular + brush shape.
    +
    + +
  • void line(void * api, int which, + SDL_Surface * canvas, SDL_Surface * snapshot, + int x1, int y1, + int x2, int y2, int step, FUNC callback)
    + This function calculates all points on a line between the coordinates + (x1,y1) and (x2,y2). Every 'step' iterations, it calls the 'callback' + function.
    +
    + It sends the 'callback' function the (x,y) coordinates on the line, + Tux Paint's "magic_api" struct (as a + "void *" pointer which you need to send to it), + a 'which' value, represening which of the plugin's 'Magic' tool is + being used, and the current and snapshot canvases.
    +
    + Example prototype of a callback function that may be sent to + Tux Paint's "line()" 'Magic' tool plugin helper function: +
    + void exampleCallBack(void * ptr_to_api, int which_tool, + SDL_Surface * canvas, SDL_Surface * snapshot, + int x, int y); +
    +
    + Example use of the "line()" helper (e.g., within a plugin's + draw() function): +
    + api->line((void *) api, which, canvas, snapshot, ox, oy, + x, y, 1, exampleCallBack); +
    +
    + +
  • Uint8 touched(int x, int y)
    + This function allows you to avoid re-processing the same pixels multiple + times when the user drags the mouse across an area of the canvas, thus + increasing Tux Paint's response time, especially with math-heavy + effects.
    +
    + If your effect's "click()", "drag()" and/or + "release()" functions take the contents of the + source surface ("snapshot") and always create the same + results in the desintation surface ("canvas"), you should + wrap the effect in a call to "api->touched()".
    +
    + This function simply returns whether or not it had already been called for + the same (x,y) coordinates, since the user first clicked the mouse. + In other words, the first time you call it for a particular (x,y) coordinate, + it returns '0'. Future calls will return '1' until the user releases + the mouse button.
    +
    + Note: Magic effects that continuously affect the destination + surface ("canvas") (ignoring the "snapshot + surface) have no reason to use this function. The "Blur" and "Smudge" + tools that ship with Tux Paint are examples of such effects.
    +
    +
+ +
+ +

Informational

+ +
+ +
    +
  • char * tp_version
    + A string containing the version of Tux Paint that's running + (e.g., "0.9.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.

+ +
    +
  • min(x, y)
    + The minimum of 'x' and 'y'. (That is, if 'x' is less than or + equal to 'y', then the value of 'x' will be used. If 'y' is less than 'x', + it will be used.)
    +
    + +
  • max(x, y)
    + The maximum of 'x' and 'y'. The opposite of min().
    +
    + +
  • clamp(lo, value, hi)
    + A value, clamped to be no smaller than 'lo', and no higher than 'hi'. + (That is, if 'value' is less than 'lo', then 'lo' will be used; + if 'value' is greater than 'hi', then 'hi' will be used; + otherwise, 'value' will be used.)
    +
    + Example: red = clamp(0, n, 255);
    + Tries to set 'red' to be the value of 'n', but without allowing it to + become less than 0 or greater than 255.
    +
    + Note: This macro is simply a #define of: + "(min(max(value,lo),hi))".
    +
    +
+ +
+ +

Constant Defintions in "tp_magic_api.h":

+ +
+

The following is a summary of constant values that are set +(via "#define") within the 'Magic' tool API header file.

+ +
    +
  • TP_MAGIC_API_VERSION
    + This integer value represents which version of the Tux Paint 'Magic' + tool API the header corresponds to.
    +
    + It should be referenced by your magic tool's "api_version()" + function, to inform the running copy of Tux Paint whether or not your + plugin is compatible.
    +
    + Note: This version number does not correspond to Tux Paint's + own release number (e.g., "0.9.18"). The API will not change every time + a new version of Tux Paint is released, which means plugins compiled + for earlier versions of Tux Paint will often run under newer + versions.
    +
    + +
  • SPECIAL_MIRROR
    + SPECIAL_FLIP
    + These are flags for Tux Paint's "special_notify()" + helper function. They are described above.
    +
    + +
+ +
+ +
+ +
+ +

Compiling

+ +
+ +

Linux and other Unix-like Platforms

+ +
+ +

Use the C compiler's "-shared" command-line option to generate + a shared object file (".so") based on your 'Magic' tool + plugin's C source code.

+ +

Use the "tp-magic-config --cflags" command, + supplied as part of Tux Paint — or in some cases, as part of a + "Tux Paint 'Magic' Tool Plugin Development package" — + to provide additional command-line flags to your C compiler that will help + it build your plugin.

+ +

Command-Line Example

+ +
+ +

As a stand-alone command, using the GNU C Compiler and BASH shell, + for example:

+ +
+

+ $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so +

+
+ +

Note: + The characters around the "tp-magic-config" + command are a grave/backtick/backquote + ("`"), and + not an apostrophe/single-quote ("'"). + They tell the shell to execute the command within (in this case, + "tp-magic-config ..."), and use its output + as an argument to the command being executed (in this case, + "gcc ...").

+ +
+ +

Makefile Example

+ +
+ +

A snippet from a Makefile to compile a Tux Paint "Magic" tool + plugin might look like this:

+ +
+

+ CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
+
+ my_plugin.so: my_plugin.c
+    gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c +

+
+ +

The first line sets up Makefile variable ("CFLAGS") that + contains flags for the compiler. "-Wall" asks for all compiler + warnings to be shown. "-O2" asks for level 2 optimization. + "($shell tp-magic-config --cflags)" runs + "tp-magic-config" to retrieve additional compiler flags that + "Magic" tool plugins require. (The "$(shell ...)" + directive is similar to the ` + ("grave") character in the BASH shell examples, above.)

+ +

The next line defines a Makefile target, "my_plugin.so", + and states that it depends on the C source file + "my_plugin.c". (Any time the C file changes, "make" + will know to recompile it and produce an updated ".so" file. + If the C file hadn't changed, it won't bother recompiling.)

+ +

The last line defines the command "make" should + run when it determines that it needs to (re)compile the ".so" + file. Here, we're using "gcc", with "-shared and + "$(CFLAGS)" command-line arguments, like above. + "-o my_plugin.so" tells the C compiler that the output file + should be "my_plugin.so". The last argument is the C file to + compile, in this case "my_plugin.c".

+ +

Note: Commands listed below a Makefile target should be + intented using a single tab character.

+ +
+ +

Advanced Makefile

+ +
+ +

An even more generalized Makefile might look like this:

+ +
+

+ CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
+
+ my_plugin_1.so: my_plugin_1.c
+    $(CC) -shared $(CFLAGS) -o $@ $<
+
+ my_plugin_2.so: my_plugin_2.c
+    $(CC) -shared $(CFLAGS) -o $@ $< +

+
+ +

As before, there are lines that define the command "make" + should run when it determines that it needs to (re)compile the + ".so" file(s). However, more general terms are used...

+ +

"$(CC)" gets expanded to your default C compiler (e.g., + "gcc"). "-shared and "$(CFLAGS)" + are command-line arguments to the compiler, like above. + "-o $@" tells the C compiler what the output file + should be; "make" replaces "$@" with the name + of the target, in this case "my_plugin_1.so" or + "my_plugin_2.so". And finally, + the last argument is the C file to compile; "make" replaces + 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: +https://tuxpaint.org/, +and the Simple DirectMedia Layer library website: +http://www.libsdl.org/.

+ +

Additionally, other Tux Paint developers and users can be found on the +"tuxpaint-devel" and "tuxpaint-users" +mailing lists: +https://tuxpaint.org/lists/.

+ +
+ +
+ +

Glossary

+ + + + + diff --git a/docs/fr_FR.UTF-8/MAGIC-API.txt b/docs/fr_FR.UTF-8/MAGIC-API.txt new file mode 100644 index 000000000..5ecd743bb --- /dev/null +++ b/docs/fr_FR.UTF-8/MAGIC-API.txt @@ -0,0 +1,1203 @@ + Creating Tux Paint Magic Tool Plugins + + Copyright 2007-2022 by various contributors; see AUTHORS.txt + https://tuxpaint.org/ + + July 5, 2007 - January 20, 2022 + + ---------------------------------------------------------------------- + +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 + + * Prequisites + * Interfaces + * 'Magic' tool plugin functions + * Common arguments to plugin functions + * Required Plugin Functions + * Plugin "housekeeping" functions + * Plugin event functions + * Tux Paint Functions and Data + * Pixel Manipulations + * Helper Functions + * Informational + * Tux Paint System Calls + * Color Conversions + * Helper Macros in "tp_magic_api.h" + * Constant Definitions in "tp_magic_api.h" + * Compiling + * Linux and other Unix-like Platforms + * Windows + * Mac OS X + * Installing + * Linux and other Unix-like Platforms + * Windows + * Mac OS X + * Creating plugins with multiple effects + * Example Code + * Getting Help + * Glossary + + ---------------------------------------------------------------------- + +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. + * magic_api * api + Pointer to a C structure containing pointers to Tux Paint + functions and other data that the plugin can (and sometimes + should) use. The contents of this struct are described below. + + Note: The magic_api struct is defined in the C header file + "tp_magic_api.h", which you should include at the top of your + plugin's C source file: + + #include "tp_magic_api.h" + + * int which + An index the plugin should use to differentiate different 'Magic' + tools, if the plugin provides more than one. (If not, "which" will + always be 0.) See "Creating plugins with multiple effects", below. + + * SDL_Surface * snapshot + A snapshot of the previous Tux Paint canvas, taken when the the + mouse was first clicked to activate the current magic tool. If you + don't continuously affect the image during one hold of the mouse + button, you should base your effects off the contents of this + canvas. (That is, read from "snapshot" and write to "canvas", + below.) + + * SDL_Surface * canvas + The current Tux Paint drawing canvas. Your magical effects should + end up here! + + * SDL_Rect * update_rect + A pointer to an SDL 'rectangle' structure that you use to tell + Tux Paint what part of the canvas has been updated. If your effect + affects a 32x32 area centered around the mouse pointer, you would + fill the SDL_Rect as follows: + + update_rect->x = x - 16; + update_rect->y = y - 16; + update_rect->w = 32; + update_rect->h = 32; + + Or, if your effect changes the entire canvas (e.g., flips it + upside-down), you'd fill it as follows: + + update_rect->x = 0; + update_rect->y = 0; + update_rect->w = canvas->w; + update_rect->h = canvas->h; + + Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than + just an "SDL_Rect") because you need to fill in its contents. + Because it is a pointer, you access its elements via "->" (arrow) + rather than "." (dot). + + Required Plugin Functions: + + Your plugin is required to contain, at the least, all of the + following functions. + + Note: Remember, your plugin's function names must be preceded by + your plugin's filename. That is, if your plugin is called "zoom.so" + (on Linux) or "zoom.dll" (on Windows), then the names of your + functions must begin with "zoom_" (e.g., "zoom_get_name(...)"). + + Plugin "housekeeping" functions: + + * Uint32 api_version(void) + The plugin should return an integer value representing the + version of the Tux Paint 'Magic' tool plugin API the plugin was + built against. The safest thing to do is return the value of + TP_MAGIC_API_VERSION, which is defined in "tp_magic_api.h". If + Tux Paint deems your plugin to be compatible, it will go ahead + and use it. + + Note: Called once by Tux Paint, at startup. It is called first. + + * int init(magic_api * api) + The plugin should do any initialization here. Return '1' if + initialization was successful, or '0' if not (and Tux Paint will + not present any 'Magic' tools from the plugin). + + Note: Called once by Tux Paint, at startup. It is called 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()"). + + * int get_group(magic_api * api, int which) + Use this to group tools together within sections of the 'Magic' + selector. A number of groups are pre-defined within an enum + found in "tp_magic_api.h": + * MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of + the image, like Blur, Emboss, and Ripples + * MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect + the colors of the image without distortion, like Darken, + Negative, and Tint + * MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the + entire picture, like Shift, Flip, and Waves + * MAGIC_TYPE_PAINTING mdash; Tools that generally paint new + content at the cursor position, like Grass, Bricks, and + Rails + * MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in + multiple places at once, like Kaleidoscope and the Symmetry + tools + * MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply + decorations to the entire picture, like Blinds and + Checkboard + * MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, + like Flower, the String tools, and the Rainbow-arc-drawing + tools. + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + Note: Added to Tux Paint 0.9.27; Magic API version '0x00000005' + + * SDL_Surface * get_icon(magic_api * api, int which) + This should return an SDL_Surface containing the icon + representing the tool. (A greyscale image with alpha, no larger + than 40x40.) This will appear on the button in the 'Magic' + selector within Tux Paint. + + Tux Paint will free ("SDL_FreeSurface()") the surface upon exit. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + * char * get_description(magic_api * api, int which, int mode) + This should return a string containing the description of how to + use a particular magic tool. This will appear as a help tip, + explained by Tux the Penguin, within Tux Paint. + + Tux Paint will free() the string upon exit, so you should wrap + it in a C strdup() call. + + Note: For each Magic tool your plugin claims to contain + (reported by your "get_tool_count()" function), this function + will be called for each mode the tool claims to support + (reported by your "modes()" function). + + In other words, if your plugin contains two tools, one which + works in paint mode only, and the other that works in both paint + mode and full-image mode, your plugin's "get_description()" will + be called three times. + + * int requires_colors(magic_api * api, int which) + Return a '1' if the 'Magic' tool accepts colors (the 'Colors' + palette in Tux Paint will be available), or '0' if not. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + * int modes(magic_api * api, int which) + This lets you tell Tux Paint what modes your tool can be used + in; either as a tool the user can paint with, or a tool that + affects the entire drawing at once. + + You must return a value that's some combination of one or more + of available modes: + * MODE_PAINT - freehand paint (click and drag) + * MODE_FULLSCREEN - applies to full image with one click + * MODE_PAINT_WITH_PREVIEW - freehand paint, with preview + (click and drag) + * MODE_ONECLICK - applies to an area around the mouse, with + one click + e.g., if your tool is only one that the user can paint with, + return "MODE_PAINT". If the user can do both, return + "MODE_PAINT | MODE_FULLSCREEN" to tell Tux Paint it can do both. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + Note: Added to Tux Paint 0.9.21; Magic API version '0x00000002' + + * 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.) + + * Uint32 xorpixel(SDL_Surface * surf, int x, int y) + Applies an XOR (exclusive-or) operation to the pixel at + coordinates (x,y) of the SDL_Surface. Applying an XOR again at + the same position will return the pixel to the original value. + Useful for displaying temporary 'rubberband' lines, outlines, + and crosshairs, while utilizing a Magic Tool. + + * SDL_Surface * scale(SDL_Surface * surf, int w, int h, + int keep_aspect) + This accepts an existing SDL surface and creates a new one + scaled to an arbitrary size. (The original surface remains + untouched.) + + The "keep_aspect" flag can be set to '1' to force the new + surface to stay the same shape (aspect ratio) as the original, + meaning it may not be the same width and height you requested. + (Check the "->w" and "->h" elements of the output + "SDL_Surface *" to determine the actual size.) + + Helper Functions + + * int in_circle(int x, int y, int radius) + Returns '1' if the (x,y) location is within a circle of a + particular radius (centered around the origin: (0,0)). Returns + '0' otherwise. Useful to create 'Magic' tools that affect the + canvas with a circular brush shape. + + * void line(void * api, int which, SDL_Surface * canvas, + SDL_Surface * snapshot, int x1, int y1, int x2, int y2, + int step, FUNC callback) + This function calculates all points on a line between the + coordinates (x1,y1) and (x2,y2). Every 'step' iterations, it + calls the 'callback' function. + + It sends the 'callback' function the (x,y) coordinates on the + line, Tux Paint's "magic_api" struct (as a "void *" pointer + which you need to send to it), a 'which' value, represening + which of the plugin's 'Magic' tool is being used, and the + current and snapshot canvases. + + Example prototype of a callback function that may be sent to + Tux Paint's "line()" 'Magic' tool plugin helper function: + + void exampleCallBack(void * ptr_to_api, int which_tool, + SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y); + + Example use of the "line()" helper (e.g., within a plugin's + draw() function): + + api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, + 1, exampleCallBack); + + * Uint8 touched(int x, int y) + This function allows you to avoid re-processing the same pixels + multiple times when the user drags the mouse across an area of + the canvas, thus increasing Tux Paint's response time, + especially with math-heavy effects. + + If your effect's "click()", "drag()" and/or "release()" + functions take the contents of the source surface ("snapshot") + and always create the same results in the desintation surface + ("canvas"), you should wrap the effect in a call to + "api->touched()". + + This function simply returns whether or not it had already been + called for the same (x,y) coordinates, since the user first + clicked the mouse. In other words, the first time you call it + for a particular (x,y) coordinate, it returns '0'. Future calls + will return '1' until the user releases the mouse button. + + Note: Magic effects that continuously affect the destination + surface ("canvas") (ignoring the "snapshot surface) have no + reason to use this function. The "Blur" and "Smudge" tools that + ship with Tux Paint are examples of such effects. + + Informational + + * char * tp_version + A string containing the version of Tux Paint that's running + (e.g., "0.9.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. + + * min(x, y) + The minimum of 'x' and 'y'. (That is, if 'x' is less than or equal + to 'y', then the value of 'x' will be used. If 'y' is less than + 'x', it will be used.) + + * max(x, y) + The maximum of 'x' and 'y'. The opposite of min(). + + * clamp(lo, value, hi) + A value, clamped to be no smaller than 'lo', and no higher than + 'hi'. (That is, if 'value' is less than 'lo', then 'lo' will be + used; if 'value' is greater than 'hi', then 'hi' will be used; + otherwise, 'value' will be used.) + + Example: red = clamp(0, n, 255); + Tries to set 'red' to be the value of 'n', but without allowing it + to become less than 0 or greater than 255. + + Note: This macro is simply a #define of: + "(min(max(value,lo),hi))". + + Constant Defintions in "tp_magic_api.h": + + The following is a summary of constant values that are set + (via "#define") within the 'Magic' tool API header file. + + * TP_MAGIC_API_VERSION + This integer value represents which version of the Tux Paint + 'Magic' tool API the header corresponds to. + + It should be referenced by your magic tool's "api_version()" + function, to inform the running copy of Tux Paint whether or not + your plugin is compatible. + + Note: This version number does not correspond to Tux Paint's own + release number (e.g., "0.9.18"). The API will not change every + time a new version of Tux Paint is released, which means plugins + compiled for earlier versions of Tux Paint will often run under + newer versions. + + * SPECIAL_MIRROR + SPECIAL_FLIP + These are flags for Tux Paint's "special_notify()" helper + function. They are described above. + + ---------------------------------------------------------------------- + +Compiling + + Linux and other Unix-like Platforms + + Use the C compiler's "-shared" command-line option to generate a + shared object file (".so") based on your 'Magic' tool plugin's C + source code. + + Use the "tp-magic-config --cflags" command, supplied as part of + Tux Paint — or in some cases, as part of a "Tux Paint 'Magic' Tool + Plugin Development package" — to provide additional command-line flags + to your C compiler that will help it build your plugin. + + Command-Line Example + + As a stand-alone command, using the GNU C Compiler and BASH shell, + for example: + + $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o + my_plugin.so + + Note: The characters around the "tp-magic-config" command are a + grave/backtick/backquote ("`"), and not an apostrophe/single-quote + ("'"). They tell the shell to execute the command within (in this + case, "tp-magic-config ..."), and use its output as an argument to + the command being executed (in this case, "gcc ..."). + + Makefile Example + + A snippet from a Makefile to compile a Tux Paint "Magic" tool plugin + might look like this: + + +------------------------------------------------------+ + | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) | + | | + | my_plugin.so: my_plugin.c | + | gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c | + +------------------------------------------------------+ + + The first line sets up Makefile variable ("CFLAGS") that contains + flags for the compiler. "-Wall" asks for all compiler warnings to be + shown. "-O2" asks for level 2 optimization. + "($shell tp-magic-config --cflags)" runs "tp-magic-config" to + retrieve additional compiler flags that "Magic" tool plugins + require. (The "$(shell ...)" directive is similar to the ` ("grave") + character in the BASH shell examples, above.) + + The next line defines a Makefile target, "my_plugin.so", and states + that it depends on the C source file "my_plugin.c". (Any time the C + file changes, "make" will know to recompile it and produce an + updated ".so" file. If the C file hadn't changed, it won't bother + recompiling.) + + The last line defines the command "make" should run when it + determines that it needs to (re)compile the ".so" file. Here, we're + using "gcc", with "-shared and "$(CFLAGS)" command-line arguments, + like above. "-o my_plugin.so" tells the C compiler that the output + file should be "my_plugin.so". The last argument is the C file to + compile, in this case "my_plugin.c". + + Note: Commands listed below a Makefile target should be intented + using a single tab character. + + Advanced Makefile + + An even more generalized Makefile might look like this: + + +----------------------------------------------------+ + | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) | + | | + | my_plugin_1.so: my_plugin_1.c | + | $(CC) -shared $(CFLAGS) -o $@ $< | + | | + | my_plugin_2.so: my_plugin_2.c | + | $(CC) -shared $(CFLAGS) -o $@ $< | + +----------------------------------------------------+ + + As before, there are lines that define the command "make" should run + when it determines that it needs to (re)compile the ".so" file(s). + However, more general terms are used... + + "$(CC)" gets expanded to your default C compiler (e.g., "gcc"). + "-shared and "$(CFLAGS)" are command-line arguments to the compiler, + like above. "-o $@" tells the C compiler what the output file should + be; "make" replaces "$@" with the name of the target, in this case + "my_plugin_1.so" or "my_plugin_2.so". And finally, the last argument + is the C file to compile; "make" replaces 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: + + * Use a C "enum" to enumerate the effects, and count them. + + enum { + ONE_TOOL, + ANOTHER_TOOL, + AND_YET_ANOTHER_TOOL, + NUM_TOOLS }; + + * Return the value of "NUM_TOOLS" when "get_tool_count()" is called, + and compare "which" values sent to other functions with the other + enumerated values. + + * Create arrays of "NUM_TOOLS" length to contain effect-specific data. + + char * my_plugin_snd_filenames[NUM_TOOLS] = { + "one.ogg", "another.ogg", "yet_another.ogg" }; + Mix_Chunk * my_plugin_snds[NUM_TOOLS]; + + * Use a C "for"-loop to load or create the effect-specific data (such + as loading sound effects during your "init()"). + + int i; + char fname[1024]; + + for (i = 0; i < NUM_TOOLS; i++) + { + /* Becomes, for example, + "/usr/share/tuxpaint/sounds/magic/one.ogg" */ + + snprintf(fname, sizeof(fname), "%s/sounds/magic/%s", + api->data_prefix, my_plugin_snd_filenames[i]; + + my_plugin_snds[i] = Mix_LoadWAV(fname); + } + + * Similarly, do the same to free them later (such as freeing sound + effects during your "shutdown()"). + + int i; + + for (i = 0; i < NUM_TOOLS; i++) + Mix_FreeChunk(my_plugin_snds[i]); + + * Use "which" values sent to your functions as an index into those + arrays (e.g., for playing the appropriate sound effect for a tool). + + Note: Even if your plugin currently contains only one effect, it may be + useful to follow the steps above so that you can add a new variation of + an effect with little effort. ("NUM_TOOLS" will simply be '1', your + arrays will be of length '1', etc.) + + ---------------------------------------------------------------------- + +Example Code + + The C source file "tp_magic_example.c" contains a complete example of a + plugin with multiple simple effects. + + ---------------------------------------------------------------------- + +Getting Help + + For more information, check the Tux Paint website: + https://tuxpaint.org/, and the Simple DirectMedia Layer library website: + http://www.libsdl.org/. + + Additionally, other Tux Paint developers and users can be found on the + "tuxpaint-devel" and "tuxpaint-users" mailing lists: + https://tuxpaint.org/lists/. + + ---------------------------------------------------------------------- + +Glossary + + * alpha: See "RGBA" + * &: See "ampersand" + * ampersand: "&". A symbol in C that allows you to refer to the memory + address of a variable; that is, a pointer. (For example, consider + "int i;". Later, "&i" refers to the memory where "i" is stored, not + the value of "i" itself; it is a 'pointer to "i"'.) + * API: Application Programming Interface. TBD + * argument: A value sent to a function. + * arrow: "->". A symbol in C that references an element within a pointer + to a struct. + * backquote: See "grave." + * backtick: See "grave." + * bit: "Binary digit." Bits are the basic storage unit in a computer's + memory, disk, networking, etc. They represent either 0 or 1. (Compared + to a decimal digit, which can be anything between 0 and 9.) Just as a + series of decimal digits can represent a larger number (e.g., "1" and + "5" is fifteen (15)), so can bits (e.g., "1" and "0", is two). In + decimal, we go from right to left: ones place, tens place, hundreds + place, thousands place, etc. In binary, it is: ones place, twos place, + fours place, eights place, etc. (See also "byte.") + * blue: See "RGBA" + * boolean 'or': A mathematical operation that results in a true value if + either operand is true. ("1 | 0", "0 | 1" and "1 | 1" all result in + "1". "0 | 0" results in "0".) + * |: See "boolean 'or'" + * .: See "dot" + * `: See "grave." + * *: See "star" + * byte: A unit of memory made up of 8 bits. As a signed value, it can + represent -128 through 127. As an unsigned value, it can represent 0 + through 255. As a series of bits, for example, the byte "00001100" + represents the decimal value 12. + * callback: TBD + * C enumeration: A construct in C that allows you to label numeric + values (usually starting at 0 and incrementing by one). (e.g., "enum { + ONE, TWO, THREE };" + * C function: TBD + * C header file: TBD + * channel: TBD + * click: The action of pressing a button on a mouse. + * coordinates: A set of numbers corresponding to a physical position; + for example, in a two-dimensional (2D) image, "X" and "Y" coordinates + specify the position across (left-to-right) and down the image, + respectively. In SDL, the coordinates (0,0) is the top-leftmost pixel + of a surface. + * C pointer: A variable that contains the location of a piece of memory; + usually used to 'point' to another variable. Since C functions can + only return one value as a result, pointers are often sent to + functions to allow the function to change the values of multiple + variables. (For example, Tux Paint's "rgbtohsv()" and "hsvtorgb()".) + * C structure: A construct in C that allows you to declare a new + variable 'type' which may contain other types within. For example, + SDL's "SDL_Rect" contains four integer values, the coordinates of the + rectangle (X,Y), and its dimensions (width and height). + * #define: A C statement that defines a substitution that can occur + later in the code. Generally used for constant values (e.g., + "#define RADIUS 16"; all instances of "RADIUS" will be replaced with + "16"), but can also be used to create macros. Typically placed within + C header files. + * dimensions: The size of an object, in terms of its width (left to + right) and height (top to bottom). + * .dll: See "Shared Object" + * dot: ".". A symbol in C that references an element within a struct. + * drag: The action of moving a mouse while the button remains held. + * element: A variable stored within a C structure. (Example: "w" and "h" + elements of SDL_Surface store the surface's width and height, + respectively.) + * enum: See "C enumeration" + * float: See "floating point" + * floating point: TBD + * format: An SDL_Surface element (a pointer to an SDL_PixelFormat + structure) that contains information about a surface; for example, the + number of bits used to represent each pixel). (See also the + "SDL_PixelFormat(3) man page) + * free(): A C function that frees (deallocates) memory allocated by + other C functions (such as "strdup()"). + * function: See "C function" + * gcc: The GNU C compiler, a portable Open Source compiler. (See also + the "gcc(1)" man page) + * GNU C Compiler: See "gcc" + * grave: The "`" character; used by the BASH shell to use the output of + a command as the command-line arguments to another. + * green: See "RGBA" + * ->: See "arrow" + * .h: See "C header file" + * header: See "C header file" + * header file: See "C header file" + * HSV: Hue, Saturation and Value. TBD + * hue: See "HSV" + * IMG_Load(): An SDL_image function that loads an image file (e.g., a + PNG) and returns it as an "SDL_Surface *". + * #include: A C statement that asks the compiler to read the contents of + another file (usually a header file). + * int: See "integer" + * integer: TBD + * libSDL: See "Simple DirectMedia Layer" + * linear: TBD + * macro: A C construct that looks similar to a C function, but is simply + a #define that is expanded 'inline'. For example, if you declared the + macro "#define ADD(A,B) ((A)+(B))", and then used it with "c = + ADD(1,2);", that line of code would literally expand to "c = ((1) + + (2));", or more simply, "c = 1 + 2;". + * magic_api: A C structure that is passed along to a plugin's functions + that exposes data and functions within the running copy of Tux Paint. + * make: A utility that automatically determines which pieces of a larger + program need to be recompiled, and issues the commands to recompile + them. (See also "Makefile") + * Makefile: A text file used by the "make" utility; it describes the + relationships among files in your program, and the commands for + updating each file. (For example, to compile a human-readable + source-code file into a computer-readable executable program file.) + * Magic tool: One of a number of effects or drawing tools in Tux Paint, + made available via the "Magic" tool button. + * Mix_Chunk *: (A pointer to) a C structure defined by SDL_mixer that + contains a sound. + * Mix_FreeChunk(): An SDL_mixer function that frees (deallocates) memory + allocated for an SDL_mixer sound 'chunk' ("Mix_Chunk *"). + * Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, + Ogg Vorbis, etc.) and returns it as a "Mix_Chunk *". + * namespace: TBD + * OGG: See "Ogg Vorbis" + * Ogg Vorbis: TBD (See also: "WAV") + * Plugin: TBD + * PNG: Portable Network Graphics. An extensible file format for the + lossless, portable, well-compressed storage of raster images. It's the + file format Tux Paint uses to save images, and for its brushes and + stamps. It's an easy way to store 32bpp RGBA images (24bpp true color + with full 8bpp alpha transparency), excellent for use in graphics + programs like Tux Paint. (See also the "png(5) man page) + * pointer: See "C pointer" + * red: See "RGBA" + * release: The action of releasing a button on a mouse. + * RGBA: "Red, Green, Blue, Alpha." TBD + * RGB: See "RBGA" + * saturation: See "HSV" + * SDL: See "Simple DirectMedia Layer" + * SDL_FreeSurface(): An libSDL function that frees (deallocates) memory + allocated for an SDL surface ("SDL_Surface *"). (See also the + "SDL_FreeSurface(3)" man page) + * SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value + (e.g., one returned from the Tux Paint's Magic tool API helper + function "getpixel()"), the format of the surface the pixel was taken + from, and pointers to three Uint8 variables, will place the Red, Green + and Blue (RGB) values of the pixel into the three Uint8 variables. + (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, + &b);".) (See also the "SDL_GetRGB(3)" man page) + * SDL_MapRGB(): A libSDL function that, given the format of a surface + and Uint8 values representing Red, Green and Blue values for a pixel, + returns a Uint32 pixel value that can be placed in the surface (e.g., + using Tux Paint's Magic tool API helper function "putpixel()"). + (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) + (See also the "SDL_MapRGB(3)" man page) + * SDL_image: A library on top of libSDL that can load various kinds of + image files (e.g., PNG) and return them as an "SDL_Surface *". + * SDL_mixer: A library on top of libSDL that can load various kinds of + sound files (WAV, Ogg Vorbis, etc.) and play back multiple sounds at + once (mix them). + * SDL_Rect: A C structure defined by libSDL that represents a + rectangular area. It contains elements representing the coordinates of + the top left corner of the rectange (x,y) and the dimensions of the + rectangle (w,h). (See also the "SDL_Rect(3)" man page) + * SDL_Surface *: (A pointer to) a C structure defined by libSDL that + contains a drawing surface. (See also the "SDL_Surface(3)" man page) + * Shared Object: A piece of code that's compiled separately from the + main application, and loaded dynamically, at runtime. + * Simple DirectMedia Layer: A programming library that allows programs + portable low level access to a video framebuffer, audio output, mouse, + and keyboard. (See also: http://www.libsdl.org/) + * snprintf(): A C function, related to "printf()", which takes a + 'format' string and one or more additional arguments, and puts them + together. "snprintf()" takes the resulting output and stores it into a + string, making sure not to go beyond the string's buffer size (which + must also be supplied). For example, assume a string "char str[20];" + has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill", + "32");" will store "Name: Bill, Age: 32" into 'str'. (See also the + "snprintf(3)" man page) + * .so: See "Shared Object" + * sRBG: See "RGBA" + * star: "*". A symbol in C that, when used in the declaration of + variables (e.g., arguments to a function), denotes that the variable + is a pointer. (For example, "int * p;" means that "p" is a pointer to + an integer.) When used next to a pointer, it 'dereferences' the + variable. (For example, later "*p = 50;" assigns the value of 50 to + the memory that "p" points to; it does not change the value of "p", + which is still a pointer to an integer. In essence, it changed the + integer that's being pointed to.) + * strdup(): A C function that allocates enough memory to store a copy of + a string, copies the string to it, and returns a "char *" pointer to + the new copy. (See also the "strdup(3)" man page) + * struct: See "C structure" + * The GIMP: An Open Source image manipulation and paint program. + * tp_magic_api.h: A header file that defines Tux Paint's Magic tool API. + Plugins must '#include' it. + * tp-magic-config: A command-line program that provides information + about the installed version of Tux Paint to plugin developers (such as + what C compiler flags they should compile with, and where plugin + shared objects and data files should be installed). (See also the + "tp-magic-config(3)" man page.) + * Uint32: A 32-bit, unsigned integer (defined by libSDL). In other + words, four bytes that can represent 0 through 4294967295. (Typically + used to hold enough information to store three or four bytes + representing a pixel's color; i.e., RBGA value). + * Uint8: An 8-bit, unsigned integer (defined by libSDL). In other words, + a byte that can represent 0 through 255. + * unsigned: In C, a variable that can store a numeric value can be + declared as either "signed" (the default), or "unsigned". In the + former case, one bit of the value is used to denote the sign of the + value (either positive or negative). In the latter case, the value can + only be positive, but benefits from one extra bit of storage for the + number. A signed byte (8 bits), for example, can represent any number + between -128 and 127. An unsigned byte can go up to 255, but it cannot + go below 0. For the purposes of graphics in SDL, unsigned values + should be used for RGB values, since each channel (red, green and + blue) may be between 0 (off) and 255 (brightest). + * value: See "HSV" + * variable: A construct in computer programming that contains a value + which can be referenced again later by referring to the variable's + name, and typically changed later. For example, a variable to hold + someone's age could be declared as an integer: "int a;". It can be + examined later: "if (a >= 18) { /* they are an adult */ } else { /* + they are not an adult */ }". + * WAV: TBD (See also "Ogg Vorbis") + * (w,h): See "Dimensions" + * (x,y): See "Coordinates" diff --git a/docs/fr_FR.UTF-8/html/MAGIC-API.html b/docs/fr_FR.UTF-8/html/MAGIC-API.html new file mode 100644 index 000000000..6646d45d3 --- /dev/null +++ b/docs/fr_FR.UTF-8/html/MAGIC-API.html @@ -0,0 +1,1374 @@ + +Creating Tux Paint Magic Tool Plugins + + + + + + + +
+

Creating Tux Paint Magic Tool Plugins

+ +

Copyright 2007-2022 by various contributors; see AUTHORS.txt
+https://tuxpaint.org/

+ +

July 5, 2007 - January 20, 2022

+
+ +
+ +

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. + +
    +
  • magic_api * api
    + Pointer to a C structure containing pointers to Tux Paint functions and + other data that the plugin can (and sometimes should) use. + The contents of this struct are described below.
    +
    + Note: The magic_api struct is defined in the C header file + "tp_magic_api.h", which you should include at the top of your + plugin's C source file: +
    + #include "tp_magic_api.h" +
    + +
  • int which
    + An index the plugin should use to differentiate different 'Magic' tools, + if the plugin provides more than one. (If not, "which" will always be 0.) + See "Creating plugins with multiple effects", + below.
    +
    + +
  • SDL_Surface * snapshot
    + A snapshot of the previous Tux Paint canvas, taken when the the + mouse was first clicked to activate the current magic tool. If you don't + continuously affect the image during one hold of the mouse button, + you should base your effects off the contents of this canvas. + (That is, read from "snapshot" and write to + "canvas", below.)
    +
    + +
  • SDL_Surface * canvas
    + The current Tux Paint drawing canvas. Your magical effects should end + up here!
    +
    + +
  • SDL_Rect * update_rect
    + A pointer to an SDL 'rectangle' structure that you use to tell Tux Paint + what part of the canvas has been updated. If your effect affects a + 32x32 area centered around the mouse pointer, you would fill the SDL_Rect + as follows: +
    + update_rect->x = x - 16;
    + update_rect->y = y - 16;
    + update_rect->w = 32;
    + update_rect->h = 32; +
    + Or, if your effect changes the entire canvas (e.g., flips it upside-down), + you'd fill it as follows: +
    + update_rect->x = 0;
    + update_rect->y = 0;
    + update_rect->w = canvas->w;
    + update_rect->h = canvas->h; +
    + Note: "update_rect" is a C pointer + (an "SDL_Rect *" rather than just an + "SDL_Rect") because you need to fill in its contents. + Because it is a pointer, you access its elements via + "->" (arrow) rather than "." (dot). +
+ +

Required Plugin Functions:

+ +
+ +

Your plugin is required to contain, at the least, all of the +following functions.

+ +

Note: Remember, your plugin's function names must be +preceded by your plugin's filename. That is, if your plugin is called +"zoom.so" (on Linux) or "zoom.dll" (on Windows), +then the names of your functions must begin with "zoom_" +(e.g., "zoom_get_name(...)").

+ +
Plugin "housekeeping" functions:
+ +
    +
  • Uint32 api_version(void)
    + The plugin should return an integer value representing the version of + the Tux Paint 'Magic' tool plugin API the plugin was built against. + The safest thing to do is return the value of + TP_MAGIC_API_VERSION, which is defined in + "tp_magic_api.h". If Tux Paint deems your plugin to + be compatible, it will go ahead and use it.
    +
    + Note: Called once by Tux Paint, at startup. It is called + first.
    +
    + +
  • int init(magic_api * api)
    + The plugin should do any initialization here. + Return '1' if initialization was successful, + or '0' if not (and Tux Paint will not present any 'Magic' tools + from the plugin).
    +
    + Note: Called once by Tux Paint, at startup. It is called + 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()").
    +
    + +
  • int get_group(magic_api * api, + int which)
    + Use this to group tools together within sections of the + 'Magic' selector. A number of groups are pre-defined within + an enum found in "tp_magic_api.h": +
      +
    • MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of the image, like Blur, Emboss, and Ripples
      • +
    • MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect the colors of the image without distortion, like Darken, Negative, and Tint
      • +
    • MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the entire picture, like Shift, Flip, and Waves
      • +
    • MAGIC_TYPE_PAINTING mdash; Tools that generally paint new content at the cursor position, like Grass, Bricks, and Rails
      • +
    • MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in multiple places at once, like Kaleidoscope and the Symmetry tools
      • +
    • MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply decorations to the entire picture, like Blinds and Checkboard
      • +
    • MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, like Flower, the String tools, and the Rainbow-arc-drawing tools.
      • +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    + Note: Added to Tux Paint 0.9.27; Magic API version + '0x00000005'
    +
    + +
  • SDL_Surface * get_icon(magic_api * api, + int which)
    + This should return an SDL_Surface containing the icon representing + the tool. (A greyscale image with alpha, no larger than 40x40.) + This will appear on the button in the 'Magic' selector within + Tux Paint.
    +
    + Tux Paint will free ("SDL_FreeSurface()") the surface upon + exit.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + +
  • char * get_description(magic_api * api, + int which, int mode)
    + This should return a string containing the description of how to + use a particular magic tool. + This will appear as a help tip, explained by Tux the Penguin, within + Tux Paint.
    +
    + Tux Paint will free() the string upon exit, so you should + wrap it in a C strdup() call.
    +
    + Note: For each Magic tool your plugin claims to + contain (reported by your "get_tool_count()" function), + this function will be called for each mode the tool claims to support + (reported by your "modes()" function).
    +
    + In other words, if your plugin contains two tools, one which works in + paint mode only, and the other that works in both paint mode and + full-image mode, your plugin's "get_description()" will be + called three times.
    +
    + +
  • int requires_colors(magic_api * api, + int which)
    + Return a '1' if the 'Magic' tool accepts colors (the 'Colors' palette in + Tux Paint will be available), or '0' if not.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + +
  • int modes(magic_api * api, + int which)
    + This lets you tell Tux Paint what modes your tool can be used in; + either as a tool the user can paint with, or a tool that affects + the entire drawing at once.
    +
    + You must return a value that's some combination of one or more of + available modes: +
      +
    • MODE_PAINT - freehand paint (click and drag)
      • +
    • MODE_FULLSCREEN - applies to full image with one click
      • +
    • MODE_PAINT_WITH_PREVIEW - freehand paint, with preview (click and drag)
      • +
    • MODE_ONECLICK - applies to an area around the mouse, with one click
      • +
    + e.g., if your tool is only one that the user can paint with, + return "MODE_PAINT". If the user can do both, + return "MODE_PAINT | MODE_FULLSCREEN" + to tell Tux Paint it can do both.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + Note: Added to Tux Paint 0.9.21; Magic API version + '0x00000002'
    +
    + +
  • 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.)
    +
    + +
  • Uint32 xorpixel(SDL_Surface * surf, + int x, int y)
    + Applies an XOR (exclusive-or) operation to the pixel at coordinates + (x,y) of the SDL_Surface. Applying an XOR again at the same position + will return the pixel to the original value. Useful for displaying + temporary 'rubberband' lines, outlines, and crosshairs, while + utilizing a Magic Tool.
    +
    + +
  • SDL_Surface * scale(SDL_Surface * surf, + int w, int h, int keep_aspect)
    + This accepts an existing SDL surface and creates a new one scaled to an + arbitrary size. (The original surface remains untouched.)
    +
    + The "keep_aspect" flag can be set to '1' to force the new + surface to stay the same shape (aspect ratio) as the original, meaning + it may not be the same width and height you requested. (Check the + "->w" and "->h" elements of the output + "SDL_Surface *" to determine the actual size.)
    +
    +
+ +
+ +

Helper Functions

+ +
+ +
    +
  • int in_circle(int x, int y, + int radius)
    + Returns '1' if the (x,y) location is within a circle of a particular + radius (centered around the origin: (0,0)). Returns '0' otherwise. + Useful to create 'Magic' tools that affect the canvas with a circular + brush shape.
    +
    + +
  • void line(void * api, int which, + SDL_Surface * canvas, SDL_Surface * snapshot, + int x1, int y1, + int x2, int y2, int step, FUNC callback)
    + This function calculates all points on a line between the coordinates + (x1,y1) and (x2,y2). Every 'step' iterations, it calls the 'callback' + function.
    +
    + It sends the 'callback' function the (x,y) coordinates on the line, + Tux Paint's "magic_api" struct (as a + "void *" pointer which you need to send to it), + a 'which' value, represening which of the plugin's 'Magic' tool is + being used, and the current and snapshot canvases.
    +
    + Example prototype of a callback function that may be sent to + Tux Paint's "line()" 'Magic' tool plugin helper function: +
    + void exampleCallBack(void * ptr_to_api, int which_tool, + SDL_Surface * canvas, SDL_Surface * snapshot, + int x, int y); +
    +
    + Example use of the "line()" helper (e.g., within a plugin's + draw() function): +
    + api->line((void *) api, which, canvas, snapshot, ox, oy, + x, y, 1, exampleCallBack); +
    +
    + +
  • Uint8 touched(int x, int y)
    + This function allows you to avoid re-processing the same pixels multiple + times when the user drags the mouse across an area of the canvas, thus + increasing Tux Paint's response time, especially with math-heavy + effects.
    +
    + If your effect's "click()", "drag()" and/or + "release()" functions take the contents of the + source surface ("snapshot") and always create the same + results in the desintation surface ("canvas"), you should + wrap the effect in a call to "api->touched()".
    +
    + This function simply returns whether or not it had already been called for + the same (x,y) coordinates, since the user first clicked the mouse. + In other words, the first time you call it for a particular (x,y) coordinate, + it returns '0'. Future calls will return '1' until the user releases + the mouse button.
    +
    + Note: Magic effects that continuously affect the destination + surface ("canvas") (ignoring the "snapshot + surface) have no reason to use this function. The "Blur" and "Smudge" + tools that ship with Tux Paint are examples of such effects.
    +
    +
+ +
+ +

Informational

+ +
+ +
    +
  • char * tp_version
    + A string containing the version of Tux Paint that's running + (e.g., "0.9.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.

+ +
    +
  • min(x, y)
    + The minimum of 'x' and 'y'. (That is, if 'x' is less than or + equal to 'y', then the value of 'x' will be used. If 'y' is less than 'x', + it will be used.)
    +
    + +
  • max(x, y)
    + The maximum of 'x' and 'y'. The opposite of min().
    +
    + +
  • clamp(lo, value, hi)
    + A value, clamped to be no smaller than 'lo', and no higher than 'hi'. + (That is, if 'value' is less than 'lo', then 'lo' will be used; + if 'value' is greater than 'hi', then 'hi' will be used; + otherwise, 'value' will be used.)
    +
    + Example: red = clamp(0, n, 255);
    + Tries to set 'red' to be the value of 'n', but without allowing it to + become less than 0 or greater than 255.
    +
    + Note: This macro is simply a #define of: + "(min(max(value,lo),hi))".
    +
    +
+ +
+ +

Constant Defintions in "tp_magic_api.h":

+ +
+

The following is a summary of constant values that are set +(via "#define") within the 'Magic' tool API header file.

+ +
    +
  • TP_MAGIC_API_VERSION
    + This integer value represents which version of the Tux Paint 'Magic' + tool API the header corresponds to.
    +
    + It should be referenced by your magic tool's "api_version()" + function, to inform the running copy of Tux Paint whether or not your + plugin is compatible.
    +
    + Note: This version number does not correspond to Tux Paint's + own release number (e.g., "0.9.18"). The API will not change every time + a new version of Tux Paint is released, which means plugins compiled + for earlier versions of Tux Paint will often run under newer + versions.
    +
    + +
  • SPECIAL_MIRROR
    + SPECIAL_FLIP
    + These are flags for Tux Paint's "special_notify()" + helper function. They are described above.
    +
    + +
+ +
+ +
+ +
+ +

Compiling

+ +
+ +

Linux and other Unix-like Platforms

+ +
+ +

Use the C compiler's "-shared" command-line option to generate + a shared object file (".so") based on your 'Magic' tool + plugin's C source code.

+ +

Use the "tp-magic-config --cflags" command, + supplied as part of Tux Paint — or in some cases, as part of a + "Tux Paint 'Magic' Tool Plugin Development package" — + to provide additional command-line flags to your C compiler that will help + it build your plugin.

+ +

Command-Line Example

+ +
+ +

As a stand-alone command, using the GNU C Compiler and BASH shell, + for example:

+ +
+

+ $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so +

+
+ +

Note: + The characters around the "tp-magic-config" + command are a grave/backtick/backquote + ("`"), and + not an apostrophe/single-quote ("'"). + They tell the shell to execute the command within (in this case, + "tp-magic-config ..."), and use its output + as an argument to the command being executed (in this case, + "gcc ...").

+ +
+ +

Makefile Example

+ +
+ +

A snippet from a Makefile to compile a Tux Paint "Magic" tool + plugin might look like this:

+ +
+

+ CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
+
+ my_plugin.so: my_plugin.c
+    gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c +

+
+ +

The first line sets up Makefile variable ("CFLAGS") that + contains flags for the compiler. "-Wall" asks for all compiler + warnings to be shown. "-O2" asks for level 2 optimization. + "($shell tp-magic-config --cflags)" runs + "tp-magic-config" to retrieve additional compiler flags that + "Magic" tool plugins require. (The "$(shell ...)" + directive is similar to the ` + ("grave") character in the BASH shell examples, above.)

+ +

The next line defines a Makefile target, "my_plugin.so", + and states that it depends on the C source file + "my_plugin.c". (Any time the C file changes, "make" + will know to recompile it and produce an updated ".so" file. + If the C file hadn't changed, it won't bother recompiling.)

+ +

The last line defines the command "make" should + run when it determines that it needs to (re)compile the ".so" + file. Here, we're using "gcc", with "-shared and + "$(CFLAGS)" command-line arguments, like above. + "-o my_plugin.so" tells the C compiler that the output file + should be "my_plugin.so". The last argument is the C file to + compile, in this case "my_plugin.c".

+ +

Note: Commands listed below a Makefile target should be + intented using a single tab character.

+ +
+ +

Advanced Makefile

+ +
+ +

An even more generalized Makefile might look like this:

+ +
+

+ CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
+
+ my_plugin_1.so: my_plugin_1.c
+    $(CC) -shared $(CFLAGS) -o $@ $<
+
+ my_plugin_2.so: my_plugin_2.c
+    $(CC) -shared $(CFLAGS) -o $@ $< +

+
+ +

As before, there are lines that define the command "make" + should run when it determines that it needs to (re)compile the + ".so" file(s). However, more general terms are used...

+ +

"$(CC)" gets expanded to your default C compiler (e.g., + "gcc"). "-shared and "$(CFLAGS)" + are command-line arguments to the compiler, like above. + "-o $@" tells the C compiler what the output file + should be; "make" replaces "$@" with the name + of the target, in this case "my_plugin_1.so" or + "my_plugin_2.so". And finally, + the last argument is the C file to compile; "make" replaces + 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: +https://tuxpaint.org/, +and the Simple DirectMedia Layer library website: +http://www.libsdl.org/.

+ +

Additionally, other Tux Paint developers and users can be found on the +"tuxpaint-devel" and "tuxpaint-users" +mailing lists: +https://tuxpaint.org/lists/.

+ +
+ +
+ +

Glossary

+ + + + + diff --git a/docs/gl_ES.UTF-8/MAGIC-API.txt b/docs/gl_ES.UTF-8/MAGIC-API.txt new file mode 100644 index 000000000..5ecd743bb --- /dev/null +++ b/docs/gl_ES.UTF-8/MAGIC-API.txt @@ -0,0 +1,1203 @@ + Creating Tux Paint Magic Tool Plugins + + Copyright 2007-2022 by various contributors; see AUTHORS.txt + https://tuxpaint.org/ + + July 5, 2007 - January 20, 2022 + + ---------------------------------------------------------------------- + +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 + + * Prequisites + * Interfaces + * 'Magic' tool plugin functions + * Common arguments to plugin functions + * Required Plugin Functions + * Plugin "housekeeping" functions + * Plugin event functions + * Tux Paint Functions and Data + * Pixel Manipulations + * Helper Functions + * Informational + * Tux Paint System Calls + * Color Conversions + * Helper Macros in "tp_magic_api.h" + * Constant Definitions in "tp_magic_api.h" + * Compiling + * Linux and other Unix-like Platforms + * Windows + * Mac OS X + * Installing + * Linux and other Unix-like Platforms + * Windows + * Mac OS X + * Creating plugins with multiple effects + * Example Code + * Getting Help + * Glossary + + ---------------------------------------------------------------------- + +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. + * magic_api * api + Pointer to a C structure containing pointers to Tux Paint + functions and other data that the plugin can (and sometimes + should) use. The contents of this struct are described below. + + Note: The magic_api struct is defined in the C header file + "tp_magic_api.h", which you should include at the top of your + plugin's C source file: + + #include "tp_magic_api.h" + + * int which + An index the plugin should use to differentiate different 'Magic' + tools, if the plugin provides more than one. (If not, "which" will + always be 0.) See "Creating plugins with multiple effects", below. + + * SDL_Surface * snapshot + A snapshot of the previous Tux Paint canvas, taken when the the + mouse was first clicked to activate the current magic tool. If you + don't continuously affect the image during one hold of the mouse + button, you should base your effects off the contents of this + canvas. (That is, read from "snapshot" and write to "canvas", + below.) + + * SDL_Surface * canvas + The current Tux Paint drawing canvas. Your magical effects should + end up here! + + * SDL_Rect * update_rect + A pointer to an SDL 'rectangle' structure that you use to tell + Tux Paint what part of the canvas has been updated. If your effect + affects a 32x32 area centered around the mouse pointer, you would + fill the SDL_Rect as follows: + + update_rect->x = x - 16; + update_rect->y = y - 16; + update_rect->w = 32; + update_rect->h = 32; + + Or, if your effect changes the entire canvas (e.g., flips it + upside-down), you'd fill it as follows: + + update_rect->x = 0; + update_rect->y = 0; + update_rect->w = canvas->w; + update_rect->h = canvas->h; + + Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than + just an "SDL_Rect") because you need to fill in its contents. + Because it is a pointer, you access its elements via "->" (arrow) + rather than "." (dot). + + Required Plugin Functions: + + Your plugin is required to contain, at the least, all of the + following functions. + + Note: Remember, your plugin's function names must be preceded by + your plugin's filename. That is, if your plugin is called "zoom.so" + (on Linux) or "zoom.dll" (on Windows), then the names of your + functions must begin with "zoom_" (e.g., "zoom_get_name(...)"). + + Plugin "housekeeping" functions: + + * Uint32 api_version(void) + The plugin should return an integer value representing the + version of the Tux Paint 'Magic' tool plugin API the plugin was + built against. The safest thing to do is return the value of + TP_MAGIC_API_VERSION, which is defined in "tp_magic_api.h". If + Tux Paint deems your plugin to be compatible, it will go ahead + and use it. + + Note: Called once by Tux Paint, at startup. It is called first. + + * int init(magic_api * api) + The plugin should do any initialization here. Return '1' if + initialization was successful, or '0' if not (and Tux Paint will + not present any 'Magic' tools from the plugin). + + Note: Called once by Tux Paint, at startup. It is called 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()"). + + * int get_group(magic_api * api, int which) + Use this to group tools together within sections of the 'Magic' + selector. A number of groups are pre-defined within an enum + found in "tp_magic_api.h": + * MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of + the image, like Blur, Emboss, and Ripples + * MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect + the colors of the image without distortion, like Darken, + Negative, and Tint + * MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the + entire picture, like Shift, Flip, and Waves + * MAGIC_TYPE_PAINTING mdash; Tools that generally paint new + content at the cursor position, like Grass, Bricks, and + Rails + * MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in + multiple places at once, like Kaleidoscope and the Symmetry + tools + * MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply + decorations to the entire picture, like Blinds and + Checkboard + * MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, + like Flower, the String tools, and the Rainbow-arc-drawing + tools. + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + Note: Added to Tux Paint 0.9.27; Magic API version '0x00000005' + + * SDL_Surface * get_icon(magic_api * api, int which) + This should return an SDL_Surface containing the icon + representing the tool. (A greyscale image with alpha, no larger + than 40x40.) This will appear on the button in the 'Magic' + selector within Tux Paint. + + Tux Paint will free ("SDL_FreeSurface()") the surface upon exit. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + * char * get_description(magic_api * api, int which, int mode) + This should return a string containing the description of how to + use a particular magic tool. This will appear as a help tip, + explained by Tux the Penguin, within Tux Paint. + + Tux Paint will free() the string upon exit, so you should wrap + it in a C strdup() call. + + Note: For each Magic tool your plugin claims to contain + (reported by your "get_tool_count()" function), this function + will be called for each mode the tool claims to support + (reported by your "modes()" function). + + In other words, if your plugin contains two tools, one which + works in paint mode only, and the other that works in both paint + mode and full-image mode, your plugin's "get_description()" will + be called three times. + + * int requires_colors(magic_api * api, int which) + Return a '1' if the 'Magic' tool accepts colors (the 'Colors' + palette in Tux Paint will be available), or '0' if not. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + * int modes(magic_api * api, int which) + This lets you tell Tux Paint what modes your tool can be used + in; either as a tool the user can paint with, or a tool that + affects the entire drawing at once. + + You must return a value that's some combination of one or more + of available modes: + * MODE_PAINT - freehand paint (click and drag) + * MODE_FULLSCREEN - applies to full image with one click + * MODE_PAINT_WITH_PREVIEW - freehand paint, with preview + (click and drag) + * MODE_ONECLICK - applies to an area around the mouse, with + one click + e.g., if your tool is only one that the user can paint with, + return "MODE_PAINT". If the user can do both, return + "MODE_PAINT | MODE_FULLSCREEN" to tell Tux Paint it can do both. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + Note: Added to Tux Paint 0.9.21; Magic API version '0x00000002' + + * 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.) + + * Uint32 xorpixel(SDL_Surface * surf, int x, int y) + Applies an XOR (exclusive-or) operation to the pixel at + coordinates (x,y) of the SDL_Surface. Applying an XOR again at + the same position will return the pixel to the original value. + Useful for displaying temporary 'rubberband' lines, outlines, + and crosshairs, while utilizing a Magic Tool. + + * SDL_Surface * scale(SDL_Surface * surf, int w, int h, + int keep_aspect) + This accepts an existing SDL surface and creates a new one + scaled to an arbitrary size. (The original surface remains + untouched.) + + The "keep_aspect" flag can be set to '1' to force the new + surface to stay the same shape (aspect ratio) as the original, + meaning it may not be the same width and height you requested. + (Check the "->w" and "->h" elements of the output + "SDL_Surface *" to determine the actual size.) + + Helper Functions + + * int in_circle(int x, int y, int radius) + Returns '1' if the (x,y) location is within a circle of a + particular radius (centered around the origin: (0,0)). Returns + '0' otherwise. Useful to create 'Magic' tools that affect the + canvas with a circular brush shape. + + * void line(void * api, int which, SDL_Surface * canvas, + SDL_Surface * snapshot, int x1, int y1, int x2, int y2, + int step, FUNC callback) + This function calculates all points on a line between the + coordinates (x1,y1) and (x2,y2). Every 'step' iterations, it + calls the 'callback' function. + + It sends the 'callback' function the (x,y) coordinates on the + line, Tux Paint's "magic_api" struct (as a "void *" pointer + which you need to send to it), a 'which' value, represening + which of the plugin's 'Magic' tool is being used, and the + current and snapshot canvases. + + Example prototype of a callback function that may be sent to + Tux Paint's "line()" 'Magic' tool plugin helper function: + + void exampleCallBack(void * ptr_to_api, int which_tool, + SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y); + + Example use of the "line()" helper (e.g., within a plugin's + draw() function): + + api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, + 1, exampleCallBack); + + * Uint8 touched(int x, int y) + This function allows you to avoid re-processing the same pixels + multiple times when the user drags the mouse across an area of + the canvas, thus increasing Tux Paint's response time, + especially with math-heavy effects. + + If your effect's "click()", "drag()" and/or "release()" + functions take the contents of the source surface ("snapshot") + and always create the same results in the desintation surface + ("canvas"), you should wrap the effect in a call to + "api->touched()". + + This function simply returns whether or not it had already been + called for the same (x,y) coordinates, since the user first + clicked the mouse. In other words, the first time you call it + for a particular (x,y) coordinate, it returns '0'. Future calls + will return '1' until the user releases the mouse button. + + Note: Magic effects that continuously affect the destination + surface ("canvas") (ignoring the "snapshot surface) have no + reason to use this function. The "Blur" and "Smudge" tools that + ship with Tux Paint are examples of such effects. + + Informational + + * char * tp_version + A string containing the version of Tux Paint that's running + (e.g., "0.9.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. + + * min(x, y) + The minimum of 'x' and 'y'. (That is, if 'x' is less than or equal + to 'y', then the value of 'x' will be used. If 'y' is less than + 'x', it will be used.) + + * max(x, y) + The maximum of 'x' and 'y'. The opposite of min(). + + * clamp(lo, value, hi) + A value, clamped to be no smaller than 'lo', and no higher than + 'hi'. (That is, if 'value' is less than 'lo', then 'lo' will be + used; if 'value' is greater than 'hi', then 'hi' will be used; + otherwise, 'value' will be used.) + + Example: red = clamp(0, n, 255); + Tries to set 'red' to be the value of 'n', but without allowing it + to become less than 0 or greater than 255. + + Note: This macro is simply a #define of: + "(min(max(value,lo),hi))". + + Constant Defintions in "tp_magic_api.h": + + The following is a summary of constant values that are set + (via "#define") within the 'Magic' tool API header file. + + * TP_MAGIC_API_VERSION + This integer value represents which version of the Tux Paint + 'Magic' tool API the header corresponds to. + + It should be referenced by your magic tool's "api_version()" + function, to inform the running copy of Tux Paint whether or not + your plugin is compatible. + + Note: This version number does not correspond to Tux Paint's own + release number (e.g., "0.9.18"). The API will not change every + time a new version of Tux Paint is released, which means plugins + compiled for earlier versions of Tux Paint will often run under + newer versions. + + * SPECIAL_MIRROR + SPECIAL_FLIP + These are flags for Tux Paint's "special_notify()" helper + function. They are described above. + + ---------------------------------------------------------------------- + +Compiling + + Linux and other Unix-like Platforms + + Use the C compiler's "-shared" command-line option to generate a + shared object file (".so") based on your 'Magic' tool plugin's C + source code. + + Use the "tp-magic-config --cflags" command, supplied as part of + Tux Paint — or in some cases, as part of a "Tux Paint 'Magic' Tool + Plugin Development package" — to provide additional command-line flags + to your C compiler that will help it build your plugin. + + Command-Line Example + + As a stand-alone command, using the GNU C Compiler and BASH shell, + for example: + + $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o + my_plugin.so + + Note: The characters around the "tp-magic-config" command are a + grave/backtick/backquote ("`"), and not an apostrophe/single-quote + ("'"). They tell the shell to execute the command within (in this + case, "tp-magic-config ..."), and use its output as an argument to + the command being executed (in this case, "gcc ..."). + + Makefile Example + + A snippet from a Makefile to compile a Tux Paint "Magic" tool plugin + might look like this: + + +------------------------------------------------------+ + | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) | + | | + | my_plugin.so: my_plugin.c | + | gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c | + +------------------------------------------------------+ + + The first line sets up Makefile variable ("CFLAGS") that contains + flags for the compiler. "-Wall" asks for all compiler warnings to be + shown. "-O2" asks for level 2 optimization. + "($shell tp-magic-config --cflags)" runs "tp-magic-config" to + retrieve additional compiler flags that "Magic" tool plugins + require. (The "$(shell ...)" directive is similar to the ` ("grave") + character in the BASH shell examples, above.) + + The next line defines a Makefile target, "my_plugin.so", and states + that it depends on the C source file "my_plugin.c". (Any time the C + file changes, "make" will know to recompile it and produce an + updated ".so" file. If the C file hadn't changed, it won't bother + recompiling.) + + The last line defines the command "make" should run when it + determines that it needs to (re)compile the ".so" file. Here, we're + using "gcc", with "-shared and "$(CFLAGS)" command-line arguments, + like above. "-o my_plugin.so" tells the C compiler that the output + file should be "my_plugin.so". The last argument is the C file to + compile, in this case "my_plugin.c". + + Note: Commands listed below a Makefile target should be intented + using a single tab character. + + Advanced Makefile + + An even more generalized Makefile might look like this: + + +----------------------------------------------------+ + | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) | + | | + | my_plugin_1.so: my_plugin_1.c | + | $(CC) -shared $(CFLAGS) -o $@ $< | + | | + | my_plugin_2.so: my_plugin_2.c | + | $(CC) -shared $(CFLAGS) -o $@ $< | + +----------------------------------------------------+ + + As before, there are lines that define the command "make" should run + when it determines that it needs to (re)compile the ".so" file(s). + However, more general terms are used... + + "$(CC)" gets expanded to your default C compiler (e.g., "gcc"). + "-shared and "$(CFLAGS)" are command-line arguments to the compiler, + like above. "-o $@" tells the C compiler what the output file should + be; "make" replaces "$@" with the name of the target, in this case + "my_plugin_1.so" or "my_plugin_2.so". And finally, the last argument + is the C file to compile; "make" replaces 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: + + * Use a C "enum" to enumerate the effects, and count them. + + enum { + ONE_TOOL, + ANOTHER_TOOL, + AND_YET_ANOTHER_TOOL, + NUM_TOOLS }; + + * Return the value of "NUM_TOOLS" when "get_tool_count()" is called, + and compare "which" values sent to other functions with the other + enumerated values. + + * Create arrays of "NUM_TOOLS" length to contain effect-specific data. + + char * my_plugin_snd_filenames[NUM_TOOLS] = { + "one.ogg", "another.ogg", "yet_another.ogg" }; + Mix_Chunk * my_plugin_snds[NUM_TOOLS]; + + * Use a C "for"-loop to load or create the effect-specific data (such + as loading sound effects during your "init()"). + + int i; + char fname[1024]; + + for (i = 0; i < NUM_TOOLS; i++) + { + /* Becomes, for example, + "/usr/share/tuxpaint/sounds/magic/one.ogg" */ + + snprintf(fname, sizeof(fname), "%s/sounds/magic/%s", + api->data_prefix, my_plugin_snd_filenames[i]; + + my_plugin_snds[i] = Mix_LoadWAV(fname); + } + + * Similarly, do the same to free them later (such as freeing sound + effects during your "shutdown()"). + + int i; + + for (i = 0; i < NUM_TOOLS; i++) + Mix_FreeChunk(my_plugin_snds[i]); + + * Use "which" values sent to your functions as an index into those + arrays (e.g., for playing the appropriate sound effect for a tool). + + Note: Even if your plugin currently contains only one effect, it may be + useful to follow the steps above so that you can add a new variation of + an effect with little effort. ("NUM_TOOLS" will simply be '1', your + arrays will be of length '1', etc.) + + ---------------------------------------------------------------------- + +Example Code + + The C source file "tp_magic_example.c" contains a complete example of a + plugin with multiple simple effects. + + ---------------------------------------------------------------------- + +Getting Help + + For more information, check the Tux Paint website: + https://tuxpaint.org/, and the Simple DirectMedia Layer library website: + http://www.libsdl.org/. + + Additionally, other Tux Paint developers and users can be found on the + "tuxpaint-devel" and "tuxpaint-users" mailing lists: + https://tuxpaint.org/lists/. + + ---------------------------------------------------------------------- + +Glossary + + * alpha: See "RGBA" + * &: See "ampersand" + * ampersand: "&". A symbol in C that allows you to refer to the memory + address of a variable; that is, a pointer. (For example, consider + "int i;". Later, "&i" refers to the memory where "i" is stored, not + the value of "i" itself; it is a 'pointer to "i"'.) + * API: Application Programming Interface. TBD + * argument: A value sent to a function. + * arrow: "->". A symbol in C that references an element within a pointer + to a struct. + * backquote: See "grave." + * backtick: See "grave." + * bit: "Binary digit." Bits are the basic storage unit in a computer's + memory, disk, networking, etc. They represent either 0 or 1. (Compared + to a decimal digit, which can be anything between 0 and 9.) Just as a + series of decimal digits can represent a larger number (e.g., "1" and + "5" is fifteen (15)), so can bits (e.g., "1" and "0", is two). In + decimal, we go from right to left: ones place, tens place, hundreds + place, thousands place, etc. In binary, it is: ones place, twos place, + fours place, eights place, etc. (See also "byte.") + * blue: See "RGBA" + * boolean 'or': A mathematical operation that results in a true value if + either operand is true. ("1 | 0", "0 | 1" and "1 | 1" all result in + "1". "0 | 0" results in "0".) + * |: See "boolean 'or'" + * .: See "dot" + * `: See "grave." + * *: See "star" + * byte: A unit of memory made up of 8 bits. As a signed value, it can + represent -128 through 127. As an unsigned value, it can represent 0 + through 255. As a series of bits, for example, the byte "00001100" + represents the decimal value 12. + * callback: TBD + * C enumeration: A construct in C that allows you to label numeric + values (usually starting at 0 and incrementing by one). (e.g., "enum { + ONE, TWO, THREE };" + * C function: TBD + * C header file: TBD + * channel: TBD + * click: The action of pressing a button on a mouse. + * coordinates: A set of numbers corresponding to a physical position; + for example, in a two-dimensional (2D) image, "X" and "Y" coordinates + specify the position across (left-to-right) and down the image, + respectively. In SDL, the coordinates (0,0) is the top-leftmost pixel + of a surface. + * C pointer: A variable that contains the location of a piece of memory; + usually used to 'point' to another variable. Since C functions can + only return one value as a result, pointers are often sent to + functions to allow the function to change the values of multiple + variables. (For example, Tux Paint's "rgbtohsv()" and "hsvtorgb()".) + * C structure: A construct in C that allows you to declare a new + variable 'type' which may contain other types within. For example, + SDL's "SDL_Rect" contains four integer values, the coordinates of the + rectangle (X,Y), and its dimensions (width and height). + * #define: A C statement that defines a substitution that can occur + later in the code. Generally used for constant values (e.g., + "#define RADIUS 16"; all instances of "RADIUS" will be replaced with + "16"), but can also be used to create macros. Typically placed within + C header files. + * dimensions: The size of an object, in terms of its width (left to + right) and height (top to bottom). + * .dll: See "Shared Object" + * dot: ".". A symbol in C that references an element within a struct. + * drag: The action of moving a mouse while the button remains held. + * element: A variable stored within a C structure. (Example: "w" and "h" + elements of SDL_Surface store the surface's width and height, + respectively.) + * enum: See "C enumeration" + * float: See "floating point" + * floating point: TBD + * format: An SDL_Surface element (a pointer to an SDL_PixelFormat + structure) that contains information about a surface; for example, the + number of bits used to represent each pixel). (See also the + "SDL_PixelFormat(3) man page) + * free(): A C function that frees (deallocates) memory allocated by + other C functions (such as "strdup()"). + * function: See "C function" + * gcc: The GNU C compiler, a portable Open Source compiler. (See also + the "gcc(1)" man page) + * GNU C Compiler: See "gcc" + * grave: The "`" character; used by the BASH shell to use the output of + a command as the command-line arguments to another. + * green: See "RGBA" + * ->: See "arrow" + * .h: See "C header file" + * header: See "C header file" + * header file: See "C header file" + * HSV: Hue, Saturation and Value. TBD + * hue: See "HSV" + * IMG_Load(): An SDL_image function that loads an image file (e.g., a + PNG) and returns it as an "SDL_Surface *". + * #include: A C statement that asks the compiler to read the contents of + another file (usually a header file). + * int: See "integer" + * integer: TBD + * libSDL: See "Simple DirectMedia Layer" + * linear: TBD + * macro: A C construct that looks similar to a C function, but is simply + a #define that is expanded 'inline'. For example, if you declared the + macro "#define ADD(A,B) ((A)+(B))", and then used it with "c = + ADD(1,2);", that line of code would literally expand to "c = ((1) + + (2));", or more simply, "c = 1 + 2;". + * magic_api: A C structure that is passed along to a plugin's functions + that exposes data and functions within the running copy of Tux Paint. + * make: A utility that automatically determines which pieces of a larger + program need to be recompiled, and issues the commands to recompile + them. (See also "Makefile") + * Makefile: A text file used by the "make" utility; it describes the + relationships among files in your program, and the commands for + updating each file. (For example, to compile a human-readable + source-code file into a computer-readable executable program file.) + * Magic tool: One of a number of effects or drawing tools in Tux Paint, + made available via the "Magic" tool button. + * Mix_Chunk *: (A pointer to) a C structure defined by SDL_mixer that + contains a sound. + * Mix_FreeChunk(): An SDL_mixer function that frees (deallocates) memory + allocated for an SDL_mixer sound 'chunk' ("Mix_Chunk *"). + * Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, + Ogg Vorbis, etc.) and returns it as a "Mix_Chunk *". + * namespace: TBD + * OGG: See "Ogg Vorbis" + * Ogg Vorbis: TBD (See also: "WAV") + * Plugin: TBD + * PNG: Portable Network Graphics. An extensible file format for the + lossless, portable, well-compressed storage of raster images. It's the + file format Tux Paint uses to save images, and for its brushes and + stamps. It's an easy way to store 32bpp RGBA images (24bpp true color + with full 8bpp alpha transparency), excellent for use in graphics + programs like Tux Paint. (See also the "png(5) man page) + * pointer: See "C pointer" + * red: See "RGBA" + * release: The action of releasing a button on a mouse. + * RGBA: "Red, Green, Blue, Alpha." TBD + * RGB: See "RBGA" + * saturation: See "HSV" + * SDL: See "Simple DirectMedia Layer" + * SDL_FreeSurface(): An libSDL function that frees (deallocates) memory + allocated for an SDL surface ("SDL_Surface *"). (See also the + "SDL_FreeSurface(3)" man page) + * SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value + (e.g., one returned from the Tux Paint's Magic tool API helper + function "getpixel()"), the format of the surface the pixel was taken + from, and pointers to three Uint8 variables, will place the Red, Green + and Blue (RGB) values of the pixel into the three Uint8 variables. + (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, + &b);".) (See also the "SDL_GetRGB(3)" man page) + * SDL_MapRGB(): A libSDL function that, given the format of a surface + and Uint8 values representing Red, Green and Blue values for a pixel, + returns a Uint32 pixel value that can be placed in the surface (e.g., + using Tux Paint's Magic tool API helper function "putpixel()"). + (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) + (See also the "SDL_MapRGB(3)" man page) + * SDL_image: A library on top of libSDL that can load various kinds of + image files (e.g., PNG) and return them as an "SDL_Surface *". + * SDL_mixer: A library on top of libSDL that can load various kinds of + sound files (WAV, Ogg Vorbis, etc.) and play back multiple sounds at + once (mix them). + * SDL_Rect: A C structure defined by libSDL that represents a + rectangular area. It contains elements representing the coordinates of + the top left corner of the rectange (x,y) and the dimensions of the + rectangle (w,h). (See also the "SDL_Rect(3)" man page) + * SDL_Surface *: (A pointer to) a C structure defined by libSDL that + contains a drawing surface. (See also the "SDL_Surface(3)" man page) + * Shared Object: A piece of code that's compiled separately from the + main application, and loaded dynamically, at runtime. + * Simple DirectMedia Layer: A programming library that allows programs + portable low level access to a video framebuffer, audio output, mouse, + and keyboard. (See also: http://www.libsdl.org/) + * snprintf(): A C function, related to "printf()", which takes a + 'format' string and one or more additional arguments, and puts them + together. "snprintf()" takes the resulting output and stores it into a + string, making sure not to go beyond the string's buffer size (which + must also be supplied). For example, assume a string "char str[20];" + has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill", + "32");" will store "Name: Bill, Age: 32" into 'str'. (See also the + "snprintf(3)" man page) + * .so: See "Shared Object" + * sRBG: See "RGBA" + * star: "*". A symbol in C that, when used in the declaration of + variables (e.g., arguments to a function), denotes that the variable + is a pointer. (For example, "int * p;" means that "p" is a pointer to + an integer.) When used next to a pointer, it 'dereferences' the + variable. (For example, later "*p = 50;" assigns the value of 50 to + the memory that "p" points to; it does not change the value of "p", + which is still a pointer to an integer. In essence, it changed the + integer that's being pointed to.) + * strdup(): A C function that allocates enough memory to store a copy of + a string, copies the string to it, and returns a "char *" pointer to + the new copy. (See also the "strdup(3)" man page) + * struct: See "C structure" + * The GIMP: An Open Source image manipulation and paint program. + * tp_magic_api.h: A header file that defines Tux Paint's Magic tool API. + Plugins must '#include' it. + * tp-magic-config: A command-line program that provides information + about the installed version of Tux Paint to plugin developers (such as + what C compiler flags they should compile with, and where plugin + shared objects and data files should be installed). (See also the + "tp-magic-config(3)" man page.) + * Uint32: A 32-bit, unsigned integer (defined by libSDL). In other + words, four bytes that can represent 0 through 4294967295. (Typically + used to hold enough information to store three or four bytes + representing a pixel's color; i.e., RBGA value). + * Uint8: An 8-bit, unsigned integer (defined by libSDL). In other words, + a byte that can represent 0 through 255. + * unsigned: In C, a variable that can store a numeric value can be + declared as either "signed" (the default), or "unsigned". In the + former case, one bit of the value is used to denote the sign of the + value (either positive or negative). In the latter case, the value can + only be positive, but benefits from one extra bit of storage for the + number. A signed byte (8 bits), for example, can represent any number + between -128 and 127. An unsigned byte can go up to 255, but it cannot + go below 0. For the purposes of graphics in SDL, unsigned values + should be used for RGB values, since each channel (red, green and + blue) may be between 0 (off) and 255 (brightest). + * value: See "HSV" + * variable: A construct in computer programming that contains a value + which can be referenced again later by referring to the variable's + name, and typically changed later. For example, a variable to hold + someone's age could be declared as an integer: "int a;". It can be + examined later: "if (a >= 18) { /* they are an adult */ } else { /* + they are not an adult */ }". + * WAV: TBD (See also "Ogg Vorbis") + * (w,h): See "Dimensions" + * (x,y): See "Coordinates" diff --git a/docs/gl_ES.UTF-8/html/MAGIC-API.html b/docs/gl_ES.UTF-8/html/MAGIC-API.html new file mode 100644 index 000000000..6646d45d3 --- /dev/null +++ b/docs/gl_ES.UTF-8/html/MAGIC-API.html @@ -0,0 +1,1374 @@ + +Creating Tux Paint Magic Tool Plugins + + + + + + + +
+

Creating Tux Paint Magic Tool Plugins

+ +

Copyright 2007-2022 by various contributors; see AUTHORS.txt
+https://tuxpaint.org/

+ +

July 5, 2007 - January 20, 2022

+
+ +
+ +

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. + +
    +
  • magic_api * api
    + Pointer to a C structure containing pointers to Tux Paint functions and + other data that the plugin can (and sometimes should) use. + The contents of this struct are described below.
    +
    + Note: The magic_api struct is defined in the C header file + "tp_magic_api.h", which you should include at the top of your + plugin's C source file: +
    + #include "tp_magic_api.h" +
    + +
  • int which
    + An index the plugin should use to differentiate different 'Magic' tools, + if the plugin provides more than one. (If not, "which" will always be 0.) + See "Creating plugins with multiple effects", + below.
    +
    + +
  • SDL_Surface * snapshot
    + A snapshot of the previous Tux Paint canvas, taken when the the + mouse was first clicked to activate the current magic tool. If you don't + continuously affect the image during one hold of the mouse button, + you should base your effects off the contents of this canvas. + (That is, read from "snapshot" and write to + "canvas", below.)
    +
    + +
  • SDL_Surface * canvas
    + The current Tux Paint drawing canvas. Your magical effects should end + up here!
    +
    + +
  • SDL_Rect * update_rect
    + A pointer to an SDL 'rectangle' structure that you use to tell Tux Paint + what part of the canvas has been updated. If your effect affects a + 32x32 area centered around the mouse pointer, you would fill the SDL_Rect + as follows: +
    + update_rect->x = x - 16;
    + update_rect->y = y - 16;
    + update_rect->w = 32;
    + update_rect->h = 32; +
    + Or, if your effect changes the entire canvas (e.g., flips it upside-down), + you'd fill it as follows: +
    + update_rect->x = 0;
    + update_rect->y = 0;
    + update_rect->w = canvas->w;
    + update_rect->h = canvas->h; +
    + Note: "update_rect" is a C pointer + (an "SDL_Rect *" rather than just an + "SDL_Rect") because you need to fill in its contents. + Because it is a pointer, you access its elements via + "->" (arrow) rather than "." (dot). +
+ +

Required Plugin Functions:

+ +
+ +

Your plugin is required to contain, at the least, all of the +following functions.

+ +

Note: Remember, your plugin's function names must be +preceded by your plugin's filename. That is, if your plugin is called +"zoom.so" (on Linux) or "zoom.dll" (on Windows), +then the names of your functions must begin with "zoom_" +(e.g., "zoom_get_name(...)").

+ +
Plugin "housekeeping" functions:
+ +
    +
  • Uint32 api_version(void)
    + The plugin should return an integer value representing the version of + the Tux Paint 'Magic' tool plugin API the plugin was built against. + The safest thing to do is return the value of + TP_MAGIC_API_VERSION, which is defined in + "tp_magic_api.h". If Tux Paint deems your plugin to + be compatible, it will go ahead and use it.
    +
    + Note: Called once by Tux Paint, at startup. It is called + first.
    +
    + +
  • int init(magic_api * api)
    + The plugin should do any initialization here. + Return '1' if initialization was successful, + or '0' if not (and Tux Paint will not present any 'Magic' tools + from the plugin).
    +
    + Note: Called once by Tux Paint, at startup. It is called + 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()").
    +
    + +
  • int get_group(magic_api * api, + int which)
    + Use this to group tools together within sections of the + 'Magic' selector. A number of groups are pre-defined within + an enum found in "tp_magic_api.h": +
      +
    • MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of the image, like Blur, Emboss, and Ripples
      • +
    • MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect the colors of the image without distortion, like Darken, Negative, and Tint
      • +
    • MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the entire picture, like Shift, Flip, and Waves
      • +
    • MAGIC_TYPE_PAINTING mdash; Tools that generally paint new content at the cursor position, like Grass, Bricks, and Rails
      • +
    • MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in multiple places at once, like Kaleidoscope and the Symmetry tools
      • +
    • MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply decorations to the entire picture, like Blinds and Checkboard
      • +
    • MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, like Flower, the String tools, and the Rainbow-arc-drawing tools.
      • +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    + Note: Added to Tux Paint 0.9.27; Magic API version + '0x00000005'
    +
    + +
  • SDL_Surface * get_icon(magic_api * api, + int which)
    + This should return an SDL_Surface containing the icon representing + the tool. (A greyscale image with alpha, no larger than 40x40.) + This will appear on the button in the 'Magic' selector within + Tux Paint.
    +
    + Tux Paint will free ("SDL_FreeSurface()") the surface upon + exit.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + +
  • char * get_description(magic_api * api, + int which, int mode)
    + This should return a string containing the description of how to + use a particular magic tool. + This will appear as a help tip, explained by Tux the Penguin, within + Tux Paint.
    +
    + Tux Paint will free() the string upon exit, so you should + wrap it in a C strdup() call.
    +
    + Note: For each Magic tool your plugin claims to + contain (reported by your "get_tool_count()" function), + this function will be called for each mode the tool claims to support + (reported by your "modes()" function).
    +
    + In other words, if your plugin contains two tools, one which works in + paint mode only, and the other that works in both paint mode and + full-image mode, your plugin's "get_description()" will be + called three times.
    +
    + +
  • int requires_colors(magic_api * api, + int which)
    + Return a '1' if the 'Magic' tool accepts colors (the 'Colors' palette in + Tux Paint will be available), or '0' if not.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + +
  • int modes(magic_api * api, + int which)
    + This lets you tell Tux Paint what modes your tool can be used in; + either as a tool the user can paint with, or a tool that affects + the entire drawing at once.
    +
    + You must return a value that's some combination of one or more of + available modes: +
      +
    • MODE_PAINT - freehand paint (click and drag)
      • +
    • MODE_FULLSCREEN - applies to full image with one click
      • +
    • MODE_PAINT_WITH_PREVIEW - freehand paint, with preview (click and drag)
      • +
    • MODE_ONECLICK - applies to an area around the mouse, with one click
      • +
    + e.g., if your tool is only one that the user can paint with, + return "MODE_PAINT". If the user can do both, + return "MODE_PAINT | MODE_FULLSCREEN" + to tell Tux Paint it can do both.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + Note: Added to Tux Paint 0.9.21; Magic API version + '0x00000002'
    +
    + +
  • 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.)
    +
    + +
  • Uint32 xorpixel(SDL_Surface * surf, + int x, int y)
    + Applies an XOR (exclusive-or) operation to the pixel at coordinates + (x,y) of the SDL_Surface. Applying an XOR again at the same position + will return the pixel to the original value. Useful for displaying + temporary 'rubberband' lines, outlines, and crosshairs, while + utilizing a Magic Tool.
    +
    + +
  • SDL_Surface * scale(SDL_Surface * surf, + int w, int h, int keep_aspect)
    + This accepts an existing SDL surface and creates a new one scaled to an + arbitrary size. (The original surface remains untouched.)
    +
    + The "keep_aspect" flag can be set to '1' to force the new + surface to stay the same shape (aspect ratio) as the original, meaning + it may not be the same width and height you requested. (Check the + "->w" and "->h" elements of the output + "SDL_Surface *" to determine the actual size.)
    +
    +
+ +
+ +

Helper Functions

+ +
+ +
    +
  • int in_circle(int x, int y, + int radius)
    + Returns '1' if the (x,y) location is within a circle of a particular + radius (centered around the origin: (0,0)). Returns '0' otherwise. + Useful to create 'Magic' tools that affect the canvas with a circular + brush shape.
    +
    + +
  • void line(void * api, int which, + SDL_Surface * canvas, SDL_Surface * snapshot, + int x1, int y1, + int x2, int y2, int step, FUNC callback)
    + This function calculates all points on a line between the coordinates + (x1,y1) and (x2,y2). Every 'step' iterations, it calls the 'callback' + function.
    +
    + It sends the 'callback' function the (x,y) coordinates on the line, + Tux Paint's "magic_api" struct (as a + "void *" pointer which you need to send to it), + a 'which' value, represening which of the plugin's 'Magic' tool is + being used, and the current and snapshot canvases.
    +
    + Example prototype of a callback function that may be sent to + Tux Paint's "line()" 'Magic' tool plugin helper function: +
    + void exampleCallBack(void * ptr_to_api, int which_tool, + SDL_Surface * canvas, SDL_Surface * snapshot, + int x, int y); +
    +
    + Example use of the "line()" helper (e.g., within a plugin's + draw() function): +
    + api->line((void *) api, which, canvas, snapshot, ox, oy, + x, y, 1, exampleCallBack); +
    +
    + +
  • Uint8 touched(int x, int y)
    + This function allows you to avoid re-processing the same pixels multiple + times when the user drags the mouse across an area of the canvas, thus + increasing Tux Paint's response time, especially with math-heavy + effects.
    +
    + If your effect's "click()", "drag()" and/or + "release()" functions take the contents of the + source surface ("snapshot") and always create the same + results in the desintation surface ("canvas"), you should + wrap the effect in a call to "api->touched()".
    +
    + This function simply returns whether or not it had already been called for + the same (x,y) coordinates, since the user first clicked the mouse. + In other words, the first time you call it for a particular (x,y) coordinate, + it returns '0'. Future calls will return '1' until the user releases + the mouse button.
    +
    + Note: Magic effects that continuously affect the destination + surface ("canvas") (ignoring the "snapshot + surface) have no reason to use this function. The "Blur" and "Smudge" + tools that ship with Tux Paint are examples of such effects.
    +
    +
+ +
+ +

Informational

+ +
+ +
    +
  • char * tp_version
    + A string containing the version of Tux Paint that's running + (e.g., "0.9.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.

+ +
    +
  • min(x, y)
    + The minimum of 'x' and 'y'. (That is, if 'x' is less than or + equal to 'y', then the value of 'x' will be used. If 'y' is less than 'x', + it will be used.)
    +
    + +
  • max(x, y)
    + The maximum of 'x' and 'y'. The opposite of min().
    +
    + +
  • clamp(lo, value, hi)
    + A value, clamped to be no smaller than 'lo', and no higher than 'hi'. + (That is, if 'value' is less than 'lo', then 'lo' will be used; + if 'value' is greater than 'hi', then 'hi' will be used; + otherwise, 'value' will be used.)
    +
    + Example: red = clamp(0, n, 255);
    + Tries to set 'red' to be the value of 'n', but without allowing it to + become less than 0 or greater than 255.
    +
    + Note: This macro is simply a #define of: + "(min(max(value,lo),hi))".
    +
    +
+ +
+ +

Constant Defintions in "tp_magic_api.h":

+ +
+

The following is a summary of constant values that are set +(via "#define") within the 'Magic' tool API header file.

+ +
    +
  • TP_MAGIC_API_VERSION
    + This integer value represents which version of the Tux Paint 'Magic' + tool API the header corresponds to.
    +
    + It should be referenced by your magic tool's "api_version()" + function, to inform the running copy of Tux Paint whether or not your + plugin is compatible.
    +
    + Note: This version number does not correspond to Tux Paint's + own release number (e.g., "0.9.18"). The API will not change every time + a new version of Tux Paint is released, which means plugins compiled + for earlier versions of Tux Paint will often run under newer + versions.
    +
    + +
  • SPECIAL_MIRROR
    + SPECIAL_FLIP
    + These are flags for Tux Paint's "special_notify()" + helper function. They are described above.
    +
    + +
+ +
+ +
+ +
+ +

Compiling

+ +
+ +

Linux and other Unix-like Platforms

+ +
+ +

Use the C compiler's "-shared" command-line option to generate + a shared object file (".so") based on your 'Magic' tool + plugin's C source code.

+ +

Use the "tp-magic-config --cflags" command, + supplied as part of Tux Paint — or in some cases, as part of a + "Tux Paint 'Magic' Tool Plugin Development package" — + to provide additional command-line flags to your C compiler that will help + it build your plugin.

+ +

Command-Line Example

+ +
+ +

As a stand-alone command, using the GNU C Compiler and BASH shell, + for example:

+ +
+

+ $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so +

+
+ +

Note: + The characters around the "tp-magic-config" + command are a grave/backtick/backquote + ("`"), and + not an apostrophe/single-quote ("'"). + They tell the shell to execute the command within (in this case, + "tp-magic-config ..."), and use its output + as an argument to the command being executed (in this case, + "gcc ...").

+ +
+ +

Makefile Example

+ +
+ +

A snippet from a Makefile to compile a Tux Paint "Magic" tool + plugin might look like this:

+ +
+

+ CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
+
+ my_plugin.so: my_plugin.c
+    gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c +

+
+ +

The first line sets up Makefile variable ("CFLAGS") that + contains flags for the compiler. "-Wall" asks for all compiler + warnings to be shown. "-O2" asks for level 2 optimization. + "($shell tp-magic-config --cflags)" runs + "tp-magic-config" to retrieve additional compiler flags that + "Magic" tool plugins require. (The "$(shell ...)" + directive is similar to the ` + ("grave") character in the BASH shell examples, above.)

+ +

The next line defines a Makefile target, "my_plugin.so", + and states that it depends on the C source file + "my_plugin.c". (Any time the C file changes, "make" + will know to recompile it and produce an updated ".so" file. + If the C file hadn't changed, it won't bother recompiling.)

+ +

The last line defines the command "make" should + run when it determines that it needs to (re)compile the ".so" + file. Here, we're using "gcc", with "-shared and + "$(CFLAGS)" command-line arguments, like above. + "-o my_plugin.so" tells the C compiler that the output file + should be "my_plugin.so". The last argument is the C file to + compile, in this case "my_plugin.c".

+ +

Note: Commands listed below a Makefile target should be + intented using a single tab character.

+ +
+ +

Advanced Makefile

+ +
+ +

An even more generalized Makefile might look like this:

+ +
+

+ CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
+
+ my_plugin_1.so: my_plugin_1.c
+    $(CC) -shared $(CFLAGS) -o $@ $<
+
+ my_plugin_2.so: my_plugin_2.c
+    $(CC) -shared $(CFLAGS) -o $@ $< +

+
+ +

As before, there are lines that define the command "make" + should run when it determines that it needs to (re)compile the + ".so" file(s). However, more general terms are used...

+ +

"$(CC)" gets expanded to your default C compiler (e.g., + "gcc"). "-shared and "$(CFLAGS)" + are command-line arguments to the compiler, like above. + "-o $@" tells the C compiler what the output file + should be; "make" replaces "$@" with the name + of the target, in this case "my_plugin_1.so" or + "my_plugin_2.so". And finally, + the last argument is the C file to compile; "make" replaces + 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: +https://tuxpaint.org/, +and the Simple DirectMedia Layer library website: +http://www.libsdl.org/.

+ +

Additionally, other Tux Paint developers and users can be found on the +"tuxpaint-devel" and "tuxpaint-users" +mailing lists: +https://tuxpaint.org/lists/.

+ +
+ +
+ +

Glossary

+ + + + + diff --git a/docs/ja_JP.UTF-8/MAGIC-API.txt b/docs/ja_JP.UTF-8/MAGIC-API.txt new file mode 100644 index 000000000..5ecd743bb --- /dev/null +++ b/docs/ja_JP.UTF-8/MAGIC-API.txt @@ -0,0 +1,1203 @@ + Creating Tux Paint Magic Tool Plugins + + Copyright 2007-2022 by various contributors; see AUTHORS.txt + https://tuxpaint.org/ + + July 5, 2007 - January 20, 2022 + + ---------------------------------------------------------------------- + +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 + + * Prequisites + * Interfaces + * 'Magic' tool plugin functions + * Common arguments to plugin functions + * Required Plugin Functions + * Plugin "housekeeping" functions + * Plugin event functions + * Tux Paint Functions and Data + * Pixel Manipulations + * Helper Functions + * Informational + * Tux Paint System Calls + * Color Conversions + * Helper Macros in "tp_magic_api.h" + * Constant Definitions in "tp_magic_api.h" + * Compiling + * Linux and other Unix-like Platforms + * Windows + * Mac OS X + * Installing + * Linux and other Unix-like Platforms + * Windows + * Mac OS X + * Creating plugins with multiple effects + * Example Code + * Getting Help + * Glossary + + ---------------------------------------------------------------------- + +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. + * magic_api * api + Pointer to a C structure containing pointers to Tux Paint + functions and other data that the plugin can (and sometimes + should) use. The contents of this struct are described below. + + Note: The magic_api struct is defined in the C header file + "tp_magic_api.h", which you should include at the top of your + plugin's C source file: + + #include "tp_magic_api.h" + + * int which + An index the plugin should use to differentiate different 'Magic' + tools, if the plugin provides more than one. (If not, "which" will + always be 0.) See "Creating plugins with multiple effects", below. + + * SDL_Surface * snapshot + A snapshot of the previous Tux Paint canvas, taken when the the + mouse was first clicked to activate the current magic tool. If you + don't continuously affect the image during one hold of the mouse + button, you should base your effects off the contents of this + canvas. (That is, read from "snapshot" and write to "canvas", + below.) + + * SDL_Surface * canvas + The current Tux Paint drawing canvas. Your magical effects should + end up here! + + * SDL_Rect * update_rect + A pointer to an SDL 'rectangle' structure that you use to tell + Tux Paint what part of the canvas has been updated. If your effect + affects a 32x32 area centered around the mouse pointer, you would + fill the SDL_Rect as follows: + + update_rect->x = x - 16; + update_rect->y = y - 16; + update_rect->w = 32; + update_rect->h = 32; + + Or, if your effect changes the entire canvas (e.g., flips it + upside-down), you'd fill it as follows: + + update_rect->x = 0; + update_rect->y = 0; + update_rect->w = canvas->w; + update_rect->h = canvas->h; + + Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than + just an "SDL_Rect") because you need to fill in its contents. + Because it is a pointer, you access its elements via "->" (arrow) + rather than "." (dot). + + Required Plugin Functions: + + Your plugin is required to contain, at the least, all of the + following functions. + + Note: Remember, your plugin's function names must be preceded by + your plugin's filename. That is, if your plugin is called "zoom.so" + (on Linux) or "zoom.dll" (on Windows), then the names of your + functions must begin with "zoom_" (e.g., "zoom_get_name(...)"). + + Plugin "housekeeping" functions: + + * Uint32 api_version(void) + The plugin should return an integer value representing the + version of the Tux Paint 'Magic' tool plugin API the plugin was + built against. The safest thing to do is return the value of + TP_MAGIC_API_VERSION, which is defined in "tp_magic_api.h". If + Tux Paint deems your plugin to be compatible, it will go ahead + and use it. + + Note: Called once by Tux Paint, at startup. It is called first. + + * int init(magic_api * api) + The plugin should do any initialization here. Return '1' if + initialization was successful, or '0' if not (and Tux Paint will + not present any 'Magic' tools from the plugin). + + Note: Called once by Tux Paint, at startup. It is called 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()"). + + * int get_group(magic_api * api, int which) + Use this to group tools together within sections of the 'Magic' + selector. A number of groups are pre-defined within an enum + found in "tp_magic_api.h": + * MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of + the image, like Blur, Emboss, and Ripples + * MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect + the colors of the image without distortion, like Darken, + Negative, and Tint + * MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the + entire picture, like Shift, Flip, and Waves + * MAGIC_TYPE_PAINTING mdash; Tools that generally paint new + content at the cursor position, like Grass, Bricks, and + Rails + * MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in + multiple places at once, like Kaleidoscope and the Symmetry + tools + * MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply + decorations to the entire picture, like Blinds and + Checkboard + * MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, + like Flower, the String tools, and the Rainbow-arc-drawing + tools. + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + Note: Added to Tux Paint 0.9.27; Magic API version '0x00000005' + + * SDL_Surface * get_icon(magic_api * api, int which) + This should return an SDL_Surface containing the icon + representing the tool. (A greyscale image with alpha, no larger + than 40x40.) This will appear on the button in the 'Magic' + selector within Tux Paint. + + Tux Paint will free ("SDL_FreeSurface()") the surface upon exit. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + * char * get_description(magic_api * api, int which, int mode) + This should return a string containing the description of how to + use a particular magic tool. This will appear as a help tip, + explained by Tux the Penguin, within Tux Paint. + + Tux Paint will free() the string upon exit, so you should wrap + it in a C strdup() call. + + Note: For each Magic tool your plugin claims to contain + (reported by your "get_tool_count()" function), this function + will be called for each mode the tool claims to support + (reported by your "modes()" function). + + In other words, if your plugin contains two tools, one which + works in paint mode only, and the other that works in both paint + mode and full-image mode, your plugin's "get_description()" will + be called three times. + + * int requires_colors(magic_api * api, int which) + Return a '1' if the 'Magic' tool accepts colors (the 'Colors' + palette in Tux Paint will be available), or '0' if not. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + * int modes(magic_api * api, int which) + This lets you tell Tux Paint what modes your tool can be used + in; either as a tool the user can paint with, or a tool that + affects the entire drawing at once. + + You must return a value that's some combination of one or more + of available modes: + * MODE_PAINT - freehand paint (click and drag) + * MODE_FULLSCREEN - applies to full image with one click + * MODE_PAINT_WITH_PREVIEW - freehand paint, with preview + (click and drag) + * MODE_ONECLICK - applies to an area around the mouse, with + one click + e.g., if your tool is only one that the user can paint with, + return "MODE_PAINT". If the user can do both, return + "MODE_PAINT | MODE_FULLSCREEN" to tell Tux Paint it can do both. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + Note: Added to Tux Paint 0.9.21; Magic API version '0x00000002' + + * 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.) + + * Uint32 xorpixel(SDL_Surface * surf, int x, int y) + Applies an XOR (exclusive-or) operation to the pixel at + coordinates (x,y) of the SDL_Surface. Applying an XOR again at + the same position will return the pixel to the original value. + Useful for displaying temporary 'rubberband' lines, outlines, + and crosshairs, while utilizing a Magic Tool. + + * SDL_Surface * scale(SDL_Surface * surf, int w, int h, + int keep_aspect) + This accepts an existing SDL surface and creates a new one + scaled to an arbitrary size. (The original surface remains + untouched.) + + The "keep_aspect" flag can be set to '1' to force the new + surface to stay the same shape (aspect ratio) as the original, + meaning it may not be the same width and height you requested. + (Check the "->w" and "->h" elements of the output + "SDL_Surface *" to determine the actual size.) + + Helper Functions + + * int in_circle(int x, int y, int radius) + Returns '1' if the (x,y) location is within a circle of a + particular radius (centered around the origin: (0,0)). Returns + '0' otherwise. Useful to create 'Magic' tools that affect the + canvas with a circular brush shape. + + * void line(void * api, int which, SDL_Surface * canvas, + SDL_Surface * snapshot, int x1, int y1, int x2, int y2, + int step, FUNC callback) + This function calculates all points on a line between the + coordinates (x1,y1) and (x2,y2). Every 'step' iterations, it + calls the 'callback' function. + + It sends the 'callback' function the (x,y) coordinates on the + line, Tux Paint's "magic_api" struct (as a "void *" pointer + which you need to send to it), a 'which' value, represening + which of the plugin's 'Magic' tool is being used, and the + current and snapshot canvases. + + Example prototype of a callback function that may be sent to + Tux Paint's "line()" 'Magic' tool plugin helper function: + + void exampleCallBack(void * ptr_to_api, int which_tool, + SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y); + + Example use of the "line()" helper (e.g., within a plugin's + draw() function): + + api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, + 1, exampleCallBack); + + * Uint8 touched(int x, int y) + This function allows you to avoid re-processing the same pixels + multiple times when the user drags the mouse across an area of + the canvas, thus increasing Tux Paint's response time, + especially with math-heavy effects. + + If your effect's "click()", "drag()" and/or "release()" + functions take the contents of the source surface ("snapshot") + and always create the same results in the desintation surface + ("canvas"), you should wrap the effect in a call to + "api->touched()". + + This function simply returns whether or not it had already been + called for the same (x,y) coordinates, since the user first + clicked the mouse. In other words, the first time you call it + for a particular (x,y) coordinate, it returns '0'. Future calls + will return '1' until the user releases the mouse button. + + Note: Magic effects that continuously affect the destination + surface ("canvas") (ignoring the "snapshot surface) have no + reason to use this function. The "Blur" and "Smudge" tools that + ship with Tux Paint are examples of such effects. + + Informational + + * char * tp_version + A string containing the version of Tux Paint that's running + (e.g., "0.9.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. + + * min(x, y) + The minimum of 'x' and 'y'. (That is, if 'x' is less than or equal + to 'y', then the value of 'x' will be used. If 'y' is less than + 'x', it will be used.) + + * max(x, y) + The maximum of 'x' and 'y'. The opposite of min(). + + * clamp(lo, value, hi) + A value, clamped to be no smaller than 'lo', and no higher than + 'hi'. (That is, if 'value' is less than 'lo', then 'lo' will be + used; if 'value' is greater than 'hi', then 'hi' will be used; + otherwise, 'value' will be used.) + + Example: red = clamp(0, n, 255); + Tries to set 'red' to be the value of 'n', but without allowing it + to become less than 0 or greater than 255. + + Note: This macro is simply a #define of: + "(min(max(value,lo),hi))". + + Constant Defintions in "tp_magic_api.h": + + The following is a summary of constant values that are set + (via "#define") within the 'Magic' tool API header file. + + * TP_MAGIC_API_VERSION + This integer value represents which version of the Tux Paint + 'Magic' tool API the header corresponds to. + + It should be referenced by your magic tool's "api_version()" + function, to inform the running copy of Tux Paint whether or not + your plugin is compatible. + + Note: This version number does not correspond to Tux Paint's own + release number (e.g., "0.9.18"). The API will not change every + time a new version of Tux Paint is released, which means plugins + compiled for earlier versions of Tux Paint will often run under + newer versions. + + * SPECIAL_MIRROR + SPECIAL_FLIP + These are flags for Tux Paint's "special_notify()" helper + function. They are described above. + + ---------------------------------------------------------------------- + +Compiling + + Linux and other Unix-like Platforms + + Use the C compiler's "-shared" command-line option to generate a + shared object file (".so") based on your 'Magic' tool plugin's C + source code. + + Use the "tp-magic-config --cflags" command, supplied as part of + Tux Paint — or in some cases, as part of a "Tux Paint 'Magic' Tool + Plugin Development package" — to provide additional command-line flags + to your C compiler that will help it build your plugin. + + Command-Line Example + + As a stand-alone command, using the GNU C Compiler and BASH shell, + for example: + + $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o + my_plugin.so + + Note: The characters around the "tp-magic-config" command are a + grave/backtick/backquote ("`"), and not an apostrophe/single-quote + ("'"). They tell the shell to execute the command within (in this + case, "tp-magic-config ..."), and use its output as an argument to + the command being executed (in this case, "gcc ..."). + + Makefile Example + + A snippet from a Makefile to compile a Tux Paint "Magic" tool plugin + might look like this: + + +------------------------------------------------------+ + | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) | + | | + | my_plugin.so: my_plugin.c | + | gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c | + +------------------------------------------------------+ + + The first line sets up Makefile variable ("CFLAGS") that contains + flags for the compiler. "-Wall" asks for all compiler warnings to be + shown. "-O2" asks for level 2 optimization. + "($shell tp-magic-config --cflags)" runs "tp-magic-config" to + retrieve additional compiler flags that "Magic" tool plugins + require. (The "$(shell ...)" directive is similar to the ` ("grave") + character in the BASH shell examples, above.) + + The next line defines a Makefile target, "my_plugin.so", and states + that it depends on the C source file "my_plugin.c". (Any time the C + file changes, "make" will know to recompile it and produce an + updated ".so" file. If the C file hadn't changed, it won't bother + recompiling.) + + The last line defines the command "make" should run when it + determines that it needs to (re)compile the ".so" file. Here, we're + using "gcc", with "-shared and "$(CFLAGS)" command-line arguments, + like above. "-o my_plugin.so" tells the C compiler that the output + file should be "my_plugin.so". The last argument is the C file to + compile, in this case "my_plugin.c". + + Note: Commands listed below a Makefile target should be intented + using a single tab character. + + Advanced Makefile + + An even more generalized Makefile might look like this: + + +----------------------------------------------------+ + | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) | + | | + | my_plugin_1.so: my_plugin_1.c | + | $(CC) -shared $(CFLAGS) -o $@ $< | + | | + | my_plugin_2.so: my_plugin_2.c | + | $(CC) -shared $(CFLAGS) -o $@ $< | + +----------------------------------------------------+ + + As before, there are lines that define the command "make" should run + when it determines that it needs to (re)compile the ".so" file(s). + However, more general terms are used... + + "$(CC)" gets expanded to your default C compiler (e.g., "gcc"). + "-shared and "$(CFLAGS)" are command-line arguments to the compiler, + like above. "-o $@" tells the C compiler what the output file should + be; "make" replaces "$@" with the name of the target, in this case + "my_plugin_1.so" or "my_plugin_2.so". And finally, the last argument + is the C file to compile; "make" replaces 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: + + * Use a C "enum" to enumerate the effects, and count them. + + enum { + ONE_TOOL, + ANOTHER_TOOL, + AND_YET_ANOTHER_TOOL, + NUM_TOOLS }; + + * Return the value of "NUM_TOOLS" when "get_tool_count()" is called, + and compare "which" values sent to other functions with the other + enumerated values. + + * Create arrays of "NUM_TOOLS" length to contain effect-specific data. + + char * my_plugin_snd_filenames[NUM_TOOLS] = { + "one.ogg", "another.ogg", "yet_another.ogg" }; + Mix_Chunk * my_plugin_snds[NUM_TOOLS]; + + * Use a C "for"-loop to load or create the effect-specific data (such + as loading sound effects during your "init()"). + + int i; + char fname[1024]; + + for (i = 0; i < NUM_TOOLS; i++) + { + /* Becomes, for example, + "/usr/share/tuxpaint/sounds/magic/one.ogg" */ + + snprintf(fname, sizeof(fname), "%s/sounds/magic/%s", + api->data_prefix, my_plugin_snd_filenames[i]; + + my_plugin_snds[i] = Mix_LoadWAV(fname); + } + + * Similarly, do the same to free them later (such as freeing sound + effects during your "shutdown()"). + + int i; + + for (i = 0; i < NUM_TOOLS; i++) + Mix_FreeChunk(my_plugin_snds[i]); + + * Use "which" values sent to your functions as an index into those + arrays (e.g., for playing the appropriate sound effect for a tool). + + Note: Even if your plugin currently contains only one effect, it may be + useful to follow the steps above so that you can add a new variation of + an effect with little effort. ("NUM_TOOLS" will simply be '1', your + arrays will be of length '1', etc.) + + ---------------------------------------------------------------------- + +Example Code + + The C source file "tp_magic_example.c" contains a complete example of a + plugin with multiple simple effects. + + ---------------------------------------------------------------------- + +Getting Help + + For more information, check the Tux Paint website: + https://tuxpaint.org/, and the Simple DirectMedia Layer library website: + http://www.libsdl.org/. + + Additionally, other Tux Paint developers and users can be found on the + "tuxpaint-devel" and "tuxpaint-users" mailing lists: + https://tuxpaint.org/lists/. + + ---------------------------------------------------------------------- + +Glossary + + * alpha: See "RGBA" + * &: See "ampersand" + * ampersand: "&". A symbol in C that allows you to refer to the memory + address of a variable; that is, a pointer. (For example, consider + "int i;". Later, "&i" refers to the memory where "i" is stored, not + the value of "i" itself; it is a 'pointer to "i"'.) + * API: Application Programming Interface. TBD + * argument: A value sent to a function. + * arrow: "->". A symbol in C that references an element within a pointer + to a struct. + * backquote: See "grave." + * backtick: See "grave." + * bit: "Binary digit." Bits are the basic storage unit in a computer's + memory, disk, networking, etc. They represent either 0 or 1. (Compared + to a decimal digit, which can be anything between 0 and 9.) Just as a + series of decimal digits can represent a larger number (e.g., "1" and + "5" is fifteen (15)), so can bits (e.g., "1" and "0", is two). In + decimal, we go from right to left: ones place, tens place, hundreds + place, thousands place, etc. In binary, it is: ones place, twos place, + fours place, eights place, etc. (See also "byte.") + * blue: See "RGBA" + * boolean 'or': A mathematical operation that results in a true value if + either operand is true. ("1 | 0", "0 | 1" and "1 | 1" all result in + "1". "0 | 0" results in "0".) + * |: See "boolean 'or'" + * .: See "dot" + * `: See "grave." + * *: See "star" + * byte: A unit of memory made up of 8 bits. As a signed value, it can + represent -128 through 127. As an unsigned value, it can represent 0 + through 255. As a series of bits, for example, the byte "00001100" + represents the decimal value 12. + * callback: TBD + * C enumeration: A construct in C that allows you to label numeric + values (usually starting at 0 and incrementing by one). (e.g., "enum { + ONE, TWO, THREE };" + * C function: TBD + * C header file: TBD + * channel: TBD + * click: The action of pressing a button on a mouse. + * coordinates: A set of numbers corresponding to a physical position; + for example, in a two-dimensional (2D) image, "X" and "Y" coordinates + specify the position across (left-to-right) and down the image, + respectively. In SDL, the coordinates (0,0) is the top-leftmost pixel + of a surface. + * C pointer: A variable that contains the location of a piece of memory; + usually used to 'point' to another variable. Since C functions can + only return one value as a result, pointers are often sent to + functions to allow the function to change the values of multiple + variables. (For example, Tux Paint's "rgbtohsv()" and "hsvtorgb()".) + * C structure: A construct in C that allows you to declare a new + variable 'type' which may contain other types within. For example, + SDL's "SDL_Rect" contains four integer values, the coordinates of the + rectangle (X,Y), and its dimensions (width and height). + * #define: A C statement that defines a substitution that can occur + later in the code. Generally used for constant values (e.g., + "#define RADIUS 16"; all instances of "RADIUS" will be replaced with + "16"), but can also be used to create macros. Typically placed within + C header files. + * dimensions: The size of an object, in terms of its width (left to + right) and height (top to bottom). + * .dll: See "Shared Object" + * dot: ".". A symbol in C that references an element within a struct. + * drag: The action of moving a mouse while the button remains held. + * element: A variable stored within a C structure. (Example: "w" and "h" + elements of SDL_Surface store the surface's width and height, + respectively.) + * enum: See "C enumeration" + * float: See "floating point" + * floating point: TBD + * format: An SDL_Surface element (a pointer to an SDL_PixelFormat + structure) that contains information about a surface; for example, the + number of bits used to represent each pixel). (See also the + "SDL_PixelFormat(3) man page) + * free(): A C function that frees (deallocates) memory allocated by + other C functions (such as "strdup()"). + * function: See "C function" + * gcc: The GNU C compiler, a portable Open Source compiler. (See also + the "gcc(1)" man page) + * GNU C Compiler: See "gcc" + * grave: The "`" character; used by the BASH shell to use the output of + a command as the command-line arguments to another. + * green: See "RGBA" + * ->: See "arrow" + * .h: See "C header file" + * header: See "C header file" + * header file: See "C header file" + * HSV: Hue, Saturation and Value. TBD + * hue: See "HSV" + * IMG_Load(): An SDL_image function that loads an image file (e.g., a + PNG) and returns it as an "SDL_Surface *". + * #include: A C statement that asks the compiler to read the contents of + another file (usually a header file). + * int: See "integer" + * integer: TBD + * libSDL: See "Simple DirectMedia Layer" + * linear: TBD + * macro: A C construct that looks similar to a C function, but is simply + a #define that is expanded 'inline'. For example, if you declared the + macro "#define ADD(A,B) ((A)+(B))", and then used it with "c = + ADD(1,2);", that line of code would literally expand to "c = ((1) + + (2));", or more simply, "c = 1 + 2;". + * magic_api: A C structure that is passed along to a plugin's functions + that exposes data and functions within the running copy of Tux Paint. + * make: A utility that automatically determines which pieces of a larger + program need to be recompiled, and issues the commands to recompile + them. (See also "Makefile") + * Makefile: A text file used by the "make" utility; it describes the + relationships among files in your program, and the commands for + updating each file. (For example, to compile a human-readable + source-code file into a computer-readable executable program file.) + * Magic tool: One of a number of effects or drawing tools in Tux Paint, + made available via the "Magic" tool button. + * Mix_Chunk *: (A pointer to) a C structure defined by SDL_mixer that + contains a sound. + * Mix_FreeChunk(): An SDL_mixer function that frees (deallocates) memory + allocated for an SDL_mixer sound 'chunk' ("Mix_Chunk *"). + * Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, + Ogg Vorbis, etc.) and returns it as a "Mix_Chunk *". + * namespace: TBD + * OGG: See "Ogg Vorbis" + * Ogg Vorbis: TBD (See also: "WAV") + * Plugin: TBD + * PNG: Portable Network Graphics. An extensible file format for the + lossless, portable, well-compressed storage of raster images. It's the + file format Tux Paint uses to save images, and for its brushes and + stamps. It's an easy way to store 32bpp RGBA images (24bpp true color + with full 8bpp alpha transparency), excellent for use in graphics + programs like Tux Paint. (See also the "png(5) man page) + * pointer: See "C pointer" + * red: See "RGBA" + * release: The action of releasing a button on a mouse. + * RGBA: "Red, Green, Blue, Alpha." TBD + * RGB: See "RBGA" + * saturation: See "HSV" + * SDL: See "Simple DirectMedia Layer" + * SDL_FreeSurface(): An libSDL function that frees (deallocates) memory + allocated for an SDL surface ("SDL_Surface *"). (See also the + "SDL_FreeSurface(3)" man page) + * SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value + (e.g., one returned from the Tux Paint's Magic tool API helper + function "getpixel()"), the format of the surface the pixel was taken + from, and pointers to three Uint8 variables, will place the Red, Green + and Blue (RGB) values of the pixel into the three Uint8 variables. + (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, + &b);".) (See also the "SDL_GetRGB(3)" man page) + * SDL_MapRGB(): A libSDL function that, given the format of a surface + and Uint8 values representing Red, Green and Blue values for a pixel, + returns a Uint32 pixel value that can be placed in the surface (e.g., + using Tux Paint's Magic tool API helper function "putpixel()"). + (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) + (See also the "SDL_MapRGB(3)" man page) + * SDL_image: A library on top of libSDL that can load various kinds of + image files (e.g., PNG) and return them as an "SDL_Surface *". + * SDL_mixer: A library on top of libSDL that can load various kinds of + sound files (WAV, Ogg Vorbis, etc.) and play back multiple sounds at + once (mix them). + * SDL_Rect: A C structure defined by libSDL that represents a + rectangular area. It contains elements representing the coordinates of + the top left corner of the rectange (x,y) and the dimensions of the + rectangle (w,h). (See also the "SDL_Rect(3)" man page) + * SDL_Surface *: (A pointer to) a C structure defined by libSDL that + contains a drawing surface. (See also the "SDL_Surface(3)" man page) + * Shared Object: A piece of code that's compiled separately from the + main application, and loaded dynamically, at runtime. + * Simple DirectMedia Layer: A programming library that allows programs + portable low level access to a video framebuffer, audio output, mouse, + and keyboard. (See also: http://www.libsdl.org/) + * snprintf(): A C function, related to "printf()", which takes a + 'format' string and one or more additional arguments, and puts them + together. "snprintf()" takes the resulting output and stores it into a + string, making sure not to go beyond the string's buffer size (which + must also be supplied). For example, assume a string "char str[20];" + has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill", + "32");" will store "Name: Bill, Age: 32" into 'str'. (See also the + "snprintf(3)" man page) + * .so: See "Shared Object" + * sRBG: See "RGBA" + * star: "*". A symbol in C that, when used in the declaration of + variables (e.g., arguments to a function), denotes that the variable + is a pointer. (For example, "int * p;" means that "p" is a pointer to + an integer.) When used next to a pointer, it 'dereferences' the + variable. (For example, later "*p = 50;" assigns the value of 50 to + the memory that "p" points to; it does not change the value of "p", + which is still a pointer to an integer. In essence, it changed the + integer that's being pointed to.) + * strdup(): A C function that allocates enough memory to store a copy of + a string, copies the string to it, and returns a "char *" pointer to + the new copy. (See also the "strdup(3)" man page) + * struct: See "C structure" + * The GIMP: An Open Source image manipulation and paint program. + * tp_magic_api.h: A header file that defines Tux Paint's Magic tool API. + Plugins must '#include' it. + * tp-magic-config: A command-line program that provides information + about the installed version of Tux Paint to plugin developers (such as + what C compiler flags they should compile with, and where plugin + shared objects and data files should be installed). (See also the + "tp-magic-config(3)" man page.) + * Uint32: A 32-bit, unsigned integer (defined by libSDL). In other + words, four bytes that can represent 0 through 4294967295. (Typically + used to hold enough information to store three or four bytes + representing a pixel's color; i.e., RBGA value). + * Uint8: An 8-bit, unsigned integer (defined by libSDL). In other words, + a byte that can represent 0 through 255. + * unsigned: In C, a variable that can store a numeric value can be + declared as either "signed" (the default), or "unsigned". In the + former case, one bit of the value is used to denote the sign of the + value (either positive or negative). In the latter case, the value can + only be positive, but benefits from one extra bit of storage for the + number. A signed byte (8 bits), for example, can represent any number + between -128 and 127. An unsigned byte can go up to 255, but it cannot + go below 0. For the purposes of graphics in SDL, unsigned values + should be used for RGB values, since each channel (red, green and + blue) may be between 0 (off) and 255 (brightest). + * value: See "HSV" + * variable: A construct in computer programming that contains a value + which can be referenced again later by referring to the variable's + name, and typically changed later. For example, a variable to hold + someone's age could be declared as an integer: "int a;". It can be + examined later: "if (a >= 18) { /* they are an adult */ } else { /* + they are not an adult */ }". + * WAV: TBD (See also "Ogg Vorbis") + * (w,h): See "Dimensions" + * (x,y): See "Coordinates" diff --git a/docs/ja_JP.UTF-8/html/MAGIC-API.html b/docs/ja_JP.UTF-8/html/MAGIC-API.html new file mode 100644 index 000000000..6646d45d3 --- /dev/null +++ b/docs/ja_JP.UTF-8/html/MAGIC-API.html @@ -0,0 +1,1374 @@ + +Creating Tux Paint Magic Tool Plugins + + + + + + + +
+

Creating Tux Paint Magic Tool Plugins

+ +

Copyright 2007-2022 by various contributors; see AUTHORS.txt
+https://tuxpaint.org/

+ +

July 5, 2007 - January 20, 2022

+
+ +
+ +

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. + +
    +
  • magic_api * api
    + Pointer to a C structure containing pointers to Tux Paint functions and + other data that the plugin can (and sometimes should) use. + The contents of this struct are described below.
    +
    + Note: The magic_api struct is defined in the C header file + "tp_magic_api.h", which you should include at the top of your + plugin's C source file: +
    + #include "tp_magic_api.h" +
    + +
  • int which
    + An index the plugin should use to differentiate different 'Magic' tools, + if the plugin provides more than one. (If not, "which" will always be 0.) + See "Creating plugins with multiple effects", + below.
    +
    + +
  • SDL_Surface * snapshot
    + A snapshot of the previous Tux Paint canvas, taken when the the + mouse was first clicked to activate the current magic tool. If you don't + continuously affect the image during one hold of the mouse button, + you should base your effects off the contents of this canvas. + (That is, read from "snapshot" and write to + "canvas", below.)
    +
    + +
  • SDL_Surface * canvas
    + The current Tux Paint drawing canvas. Your magical effects should end + up here!
    +
    + +
  • SDL_Rect * update_rect
    + A pointer to an SDL 'rectangle' structure that you use to tell Tux Paint + what part of the canvas has been updated. If your effect affects a + 32x32 area centered around the mouse pointer, you would fill the SDL_Rect + as follows: +
    + update_rect->x = x - 16;
    + update_rect->y = y - 16;
    + update_rect->w = 32;
    + update_rect->h = 32; +
    + Or, if your effect changes the entire canvas (e.g., flips it upside-down), + you'd fill it as follows: +
    + update_rect->x = 0;
    + update_rect->y = 0;
    + update_rect->w = canvas->w;
    + update_rect->h = canvas->h; +
    + Note: "update_rect" is a C pointer + (an "SDL_Rect *" rather than just an + "SDL_Rect") because you need to fill in its contents. + Because it is a pointer, you access its elements via + "->" (arrow) rather than "." (dot). +
+ +

Required Plugin Functions:

+ +
+ +

Your plugin is required to contain, at the least, all of the +following functions.

+ +

Note: Remember, your plugin's function names must be +preceded by your plugin's filename. That is, if your plugin is called +"zoom.so" (on Linux) or "zoom.dll" (on Windows), +then the names of your functions must begin with "zoom_" +(e.g., "zoom_get_name(...)").

+ +
Plugin "housekeeping" functions:
+ +
    +
  • Uint32 api_version(void)
    + The plugin should return an integer value representing the version of + the Tux Paint 'Magic' tool plugin API the plugin was built against. + The safest thing to do is return the value of + TP_MAGIC_API_VERSION, which is defined in + "tp_magic_api.h". If Tux Paint deems your plugin to + be compatible, it will go ahead and use it.
    +
    + Note: Called once by Tux Paint, at startup. It is called + first.
    +
    + +
  • int init(magic_api * api)
    + The plugin should do any initialization here. + Return '1' if initialization was successful, + or '0' if not (and Tux Paint will not present any 'Magic' tools + from the plugin).
    +
    + Note: Called once by Tux Paint, at startup. It is called + 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()").
    +
    + +
  • int get_group(magic_api * api, + int which)
    + Use this to group tools together within sections of the + 'Magic' selector. A number of groups are pre-defined within + an enum found in "tp_magic_api.h": +
      +
    • MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of the image, like Blur, Emboss, and Ripples
      • +
    • MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect the colors of the image without distortion, like Darken, Negative, and Tint
      • +
    • MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the entire picture, like Shift, Flip, and Waves
      • +
    • MAGIC_TYPE_PAINTING mdash; Tools that generally paint new content at the cursor position, like Grass, Bricks, and Rails
      • +
    • MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in multiple places at once, like Kaleidoscope and the Symmetry tools
      • +
    • MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply decorations to the entire picture, like Blinds and Checkboard
      • +
    • MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, like Flower, the String tools, and the Rainbow-arc-drawing tools.
      • +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    + Note: Added to Tux Paint 0.9.27; Magic API version + '0x00000005'
    +
    + +
  • SDL_Surface * get_icon(magic_api * api, + int which)
    + This should return an SDL_Surface containing the icon representing + the tool. (A greyscale image with alpha, no larger than 40x40.) + This will appear on the button in the 'Magic' selector within + Tux Paint.
    +
    + Tux Paint will free ("SDL_FreeSurface()") the surface upon + exit.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + +
  • char * get_description(magic_api * api, + int which, int mode)
    + This should return a string containing the description of how to + use a particular magic tool. + This will appear as a help tip, explained by Tux the Penguin, within + Tux Paint.
    +
    + Tux Paint will free() the string upon exit, so you should + wrap it in a C strdup() call.
    +
    + Note: For each Magic tool your plugin claims to + contain (reported by your "get_tool_count()" function), + this function will be called for each mode the tool claims to support + (reported by your "modes()" function).
    +
    + In other words, if your plugin contains two tools, one which works in + paint mode only, and the other that works in both paint mode and + full-image mode, your plugin's "get_description()" will be + called three times.
    +
    + +
  • int requires_colors(magic_api * api, + int which)
    + Return a '1' if the 'Magic' tool accepts colors (the 'Colors' palette in + Tux Paint will be available), or '0' if not.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + +
  • int modes(magic_api * api, + int which)
    + This lets you tell Tux Paint what modes your tool can be used in; + either as a tool the user can paint with, or a tool that affects + the entire drawing at once.
    +
    + You must return a value that's some combination of one or more of + available modes: +
      +
    • MODE_PAINT - freehand paint (click and drag)
      • +
    • MODE_FULLSCREEN - applies to full image with one click
      • +
    • MODE_PAINT_WITH_PREVIEW - freehand paint, with preview (click and drag)
      • +
    • MODE_ONECLICK - applies to an area around the mouse, with one click
      • +
    + e.g., if your tool is only one that the user can paint with, + return "MODE_PAINT". If the user can do both, + return "MODE_PAINT | MODE_FULLSCREEN" + to tell Tux Paint it can do both.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    + Note: Added to Tux Paint 0.9.21; Magic API version + '0x00000002'
    +
    + +
  • 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.)
    +
    + +
  • Uint32 xorpixel(SDL_Surface * surf, + int x, int y)
    + Applies an XOR (exclusive-or) operation to the pixel at coordinates + (x,y) of the SDL_Surface. Applying an XOR again at the same position + will return the pixel to the original value. Useful for displaying + temporary 'rubberband' lines, outlines, and crosshairs, while + utilizing a Magic Tool.
    +
    + +
  • SDL_Surface * scale(SDL_Surface * surf, + int w, int h, int keep_aspect)
    + This accepts an existing SDL surface and creates a new one scaled to an + arbitrary size. (The original surface remains untouched.)
    +
    + The "keep_aspect" flag can be set to '1' to force the new + surface to stay the same shape (aspect ratio) as the original, meaning + it may not be the same width and height you requested. (Check the + "->w" and "->h" elements of the output + "SDL_Surface *" to determine the actual size.)
    +
    +
+ +
+ +

Helper Functions

+ +
+ +
    +
  • int in_circle(int x, int y, + int radius)
    + Returns '1' if the (x,y) location is within a circle of a particular + radius (centered around the origin: (0,0)). Returns '0' otherwise. + Useful to create 'Magic' tools that affect the canvas with a circular + brush shape.
    +
    + +
  • void line(void * api, int which, + SDL_Surface * canvas, SDL_Surface * snapshot, + int x1, int y1, + int x2, int y2, int step, FUNC callback)
    + This function calculates all points on a line between the coordinates + (x1,y1) and (x2,y2). Every 'step' iterations, it calls the 'callback' + function.
    +
    + It sends the 'callback' function the (x,y) coordinates on the line, + Tux Paint's "magic_api" struct (as a + "void *" pointer which you need to send to it), + a 'which' value, represening which of the plugin's 'Magic' tool is + being used, and the current and snapshot canvases.
    +
    + Example prototype of a callback function that may be sent to + Tux Paint's "line()" 'Magic' tool plugin helper function: +
    + void exampleCallBack(void * ptr_to_api, int which_tool, + SDL_Surface * canvas, SDL_Surface * snapshot, + int x, int y); +
    +
    + Example use of the "line()" helper (e.g., within a plugin's + draw() function): +
    + api->line((void *) api, which, canvas, snapshot, ox, oy, + x, y, 1, exampleCallBack); +
    +
    + +
  • Uint8 touched(int x, int y)
    + This function allows you to avoid re-processing the same pixels multiple + times when the user drags the mouse across an area of the canvas, thus + increasing Tux Paint's response time, especially with math-heavy + effects.
    +
    + If your effect's "click()", "drag()" and/or + "release()" functions take the contents of the + source surface ("snapshot") and always create the same + results in the desintation surface ("canvas"), you should + wrap the effect in a call to "api->touched()".
    +
    + This function simply returns whether or not it had already been called for + the same (x,y) coordinates, since the user first clicked the mouse. + In other words, the first time you call it for a particular (x,y) coordinate, + it returns '0'. Future calls will return '1' until the user releases + the mouse button.
    +
    + Note: Magic effects that continuously affect the destination + surface ("canvas") (ignoring the "snapshot + surface) have no reason to use this function. The "Blur" and "Smudge" + tools that ship with Tux Paint are examples of such effects.
    +
    +
+ +
+ +

Informational

+ +
+ +
    +
  • char * tp_version
    + A string containing the version of Tux Paint that's running + (e.g., "0.9.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.

+ +
    +
  • min(x, y)
    + The minimum of 'x' and 'y'. (That is, if 'x' is less than or + equal to 'y', then the value of 'x' will be used. If 'y' is less than 'x', + it will be used.)
    +
    + +
  • max(x, y)
    + The maximum of 'x' and 'y'. The opposite of min().
    +
    + +
  • clamp(lo, value, hi)
    + A value, clamped to be no smaller than 'lo', and no higher than 'hi'. + (That is, if 'value' is less than 'lo', then 'lo' will be used; + if 'value' is greater than 'hi', then 'hi' will be used; + otherwise, 'value' will be used.)
    +
    + Example: red = clamp(0, n, 255);
    + Tries to set 'red' to be the value of 'n', but without allowing it to + become less than 0 or greater than 255.
    +
    + Note: This macro is simply a #define of: + "(min(max(value,lo),hi))".
    +
    +
+ +
+ +

Constant Defintions in "tp_magic_api.h":

+ +
+

The following is a summary of constant values that are set +(via "#define") within the 'Magic' tool API header file.

+ +
    +
  • TP_MAGIC_API_VERSION
    + This integer value represents which version of the Tux Paint 'Magic' + tool API the header corresponds to.
    +
    + It should be referenced by your magic tool's "api_version()" + function, to inform the running copy of Tux Paint whether or not your + plugin is compatible.
    +
    + Note: This version number does not correspond to Tux Paint's + own release number (e.g., "0.9.18"). The API will not change every time + a new version of Tux Paint is released, which means plugins compiled + for earlier versions of Tux Paint will often run under newer + versions.
    +
    + +
  • SPECIAL_MIRROR
    + SPECIAL_FLIP
    + These are flags for Tux Paint's "special_notify()" + helper function. They are described above.
    +
    + +
+ +
+ +
+ +
+ +

Compiling

+ +
+ +

Linux and other Unix-like Platforms

+ +
+ +

Use the C compiler's "-shared" command-line option to generate + a shared object file (".so") based on your 'Magic' tool + plugin's C source code.

+ +

Use the "tp-magic-config --cflags" command, + supplied as part of Tux Paint — or in some cases, as part of a + "Tux Paint 'Magic' Tool Plugin Development package" — + to provide additional command-line flags to your C compiler that will help + it build your plugin.

+ +

Command-Line Example

+ +
+ +

As a stand-alone command, using the GNU C Compiler and BASH shell, + for example:

+ +
+

+ $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so +

+
+ +

Note: + The characters around the "tp-magic-config" + command are a grave/backtick/backquote + ("`"), and + not an apostrophe/single-quote ("'"). + They tell the shell to execute the command within (in this case, + "tp-magic-config ..."), and use its output + as an argument to the command being executed (in this case, + "gcc ...").

+ +
+ +

Makefile Example

+ +
+ +

A snippet from a Makefile to compile a Tux Paint "Magic" tool + plugin might look like this:

+ +
+

+ CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
+
+ my_plugin.so: my_plugin.c
+    gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c +

+
+ +

The first line sets up Makefile variable ("CFLAGS") that + contains flags for the compiler. "-Wall" asks for all compiler + warnings to be shown. "-O2" asks for level 2 optimization. + "($shell tp-magic-config --cflags)" runs + "tp-magic-config" to retrieve additional compiler flags that + "Magic" tool plugins require. (The "$(shell ...)" + directive is similar to the ` + ("grave") character in the BASH shell examples, above.)

+ +

The next line defines a Makefile target, "my_plugin.so", + and states that it depends on the C source file + "my_plugin.c". (Any time the C file changes, "make" + will know to recompile it and produce an updated ".so" file. + If the C file hadn't changed, it won't bother recompiling.)

+ +

The last line defines the command "make" should + run when it determines that it needs to (re)compile the ".so" + file. Here, we're using "gcc", with "-shared and + "$(CFLAGS)" command-line arguments, like above. + "-o my_plugin.so" tells the C compiler that the output file + should be "my_plugin.so". The last argument is the C file to + compile, in this case "my_plugin.c".

+ +

Note: Commands listed below a Makefile target should be + intented using a single tab character.

+ +
+ +

Advanced Makefile

+ +
+ +

An even more generalized Makefile might look like this:

+ +
+

+ CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
+
+ my_plugin_1.so: my_plugin_1.c
+    $(CC) -shared $(CFLAGS) -o $@ $<
+
+ my_plugin_2.so: my_plugin_2.c
+    $(CC) -shared $(CFLAGS) -o $@ $< +

+
+ +

As before, there are lines that define the command "make" + should run when it determines that it needs to (re)compile the + ".so" file(s). However, more general terms are used...

+ +

"$(CC)" gets expanded to your default C compiler (e.g., + "gcc"). "-shared and "$(CFLAGS)" + are command-line arguments to the compiler, like above. + "-o $@" tells the C compiler what the output file + should be; "make" replaces "$@" with the name + of the target, in this case "my_plugin_1.so" or + "my_plugin_2.so". And finally, + the last argument is the C file to compile; "make" replaces + 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: +https://tuxpaint.org/, +and the Simple DirectMedia Layer library website: +http://www.libsdl.org/.

+ +

Additionally, other Tux Paint developers and users can be found on the +"tuxpaint-devel" and "tuxpaint-users" +mailing lists: +https://tuxpaint.org/lists/.

+ +
+ +
+ +

Glossary

+ + + + + diff --git a/magic/docs/Makefile b/magic/docs/Makefile deleted file mode 100644 index 5977c3ee8..000000000 --- a/magic/docs/Makefile +++ /dev/null @@ -1 +0,0 @@ -include ../../docs/Makefile