From 1211034182adf305b493856175d3699cfc18dfc5 Mon Sep 17 00:00:00 2001 From: William Kendrick Date: Fri, 27 Jul 2007 22:25:48 +0000 Subject: [PATCH] Update and formatting enhancements to Plugin API docs. --- magic/docs/README.txt | 520 ++++++++++++++++++++++-------------- magic/docs/html/README.html | 348 +++++++++++++++++------- 2 files changed, 565 insertions(+), 303 deletions(-) diff --git a/magic/docs/README.txt b/magic/docs/README.txt index 63c1b18c0..3e6ba0d4a 100644 --- a/magic/docs/README.txt +++ b/magic/docs/README.txt @@ -6,7 +6,7 @@ bill@newbreedsoftware.com http://www.tuxpaint.org/ - July 5, 2007 - July 8, 2007 + July 5, 2007 - July 27, 2007 -------------------------------------------------------------------------- @@ -28,7 +28,7 @@ Prerequisites Tux Paint is written in the C programming language, and uses the Simple DirectMedia Layer library ('libSDL', or simply 'SDL'). Therefore, - for the moment at least, one must understand the C language, how to + for the moment at least, one must understand the C language and how to compile C-based programs. Familiarity with the SDL API is highly recommended, but some basic SDL concepts will be covered in this document. @@ -45,215 +45,318 @@ Interfaces 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 should) use. This is exposed as a C structure - (containing pointers to functions inside Tux Paint and other data) that - gets passed along to the plugin's functions as an argument. + 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 file "tp_magic_api.h", and compiler flags - which should be used when building plugins (to find the aforementioned - header file, as well as SDL's header files) can be acquired by invoking - the tool "tp-magic-config". + 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. - (These are included with Tux Paint -- or in some cases, as part of a - "Tux Paint 'Magic' Tool Plugin Development package".) + 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 provide the functions listed below. Note: To - avoid namespace collisions, each function's name must start with the + '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, unless you declare those as 'static'. + functions (ones not used by Tux Paint directly), unless you declare + those as 'static'. Common arguments to plugin functions: + Here is a description of arguments that many of your plugin's + functions will need to accept. + * magic_api * api - Pointer to the struct containing pointers to Tux Paint functions - and other data (see below) + 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.) - * SDL_Surface * canvas - The active Tux Paint drawing canvas. Your magical effects should - end up here! - * SDL_Surface * last + 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 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. + 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: - * int get_tool_count(magic_api * api) - This should return the number of Magic tools this plugin provides - to Tux Paint. - * char * get_name(magic_api * api, int which) - This should return a string containing the name of a magic tool. - This will appear on the button in the 'Magic' selector within - Tux Paint. Tux Paint will free() the string upon exit, so you - should wrap it in a C strdup() call. - * SDL_Surface * get_icon(magic_api * api, int which) - This should return an SDL_Surface containing the icon representing - the tool. (A greyscale image with alpha, no larger than 40x40.) - This will appear on the button in the 'Magic' selector within - Tux Paint. - Tux Paint will SDL_FreeSurface() the surface upon exit. - * char * get_description(magic_api * api, int which) - This should return a string containing the description of a magic - tool. This will appear as a help tip, explained by Tux the - Penguin, within Tux Paint. - Tux Paint will free() the string upon exit, so you should wrap it - in a C strdup() call. - * int requires_colors(magic_api * api, int which) - Return a '1' if the 'Magic' tool accepts colors (the 'Colors' - palette in Tux Paint will be available), or '0' if not. - * void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g) - Tux Paint will call this function to inform the plugin of the RGB - values of the currently-selected color in Tux Paint's 'Colors' - palette. (It will be called whenever one of the plguin's Magic - tools that accept colors becomes active, or the user picks a new - color while such a tool is currently active.) - * Uint32 api_version(void) - The plugin should return an integer value representing the version - of the Tux Paint 'Magic' tool plugin API it was built against. - Simply return TP_MAGIC_API_VERSION, which is defined in - "tp_magic_api.h", to satisfy this requirement. - * int init(magic_api * api) - The plugin should do any initialization here. This function is - called once, at Tux Paint startup. Return '1' if initialization - was successful, or '0' if not (and Tux Paint will not present any - 'Magic' tools from the plugin). - * void shutdown(magic_api * api) - The plugin should do any cleanup here. This function is called - once, at Tux Paint exit. - * void click(magic_api * api, int which, SDL_Surface * snapshot, - SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect) - The plugin should apply the appropriate 'Magic' tool on the - 'canvas' surface. The (x,y) coordinates are where the mouse was - (within the canvas) when the mouse button was clicked. - The plugin should report back what part of the canvas was - affected, by filling in the (x,y) and (w,h) values in - 'update_rect'. - The contents of the drawing canvas immediately prior to the mouse - button click is stored within the 'snapshot' canvas. - * void drag(magic_api * api, int which, SDL_Surface * snapshot, - SDL_Surface * canvas, int ox, int oy, int x, int y, SDL_Rect * - update_rect) - The plugin should apply the appropriate 'Magic' tool on the - 'canvas' surface. The (ox,oy) and (x,y) coordinates are the - location of the mouse at the beginning and end of the stroke. - Typically, plugins that let the user "draw" effects onto the - canvas call the Tux Paint 'Magic' tool plugin "line()" helper - function. (See below). - The plugin should report back what part of the canvas was - affected, by filling in the (x,y) and (w,h) values in - 'update_rect'. - Note: The contents of the drawing canvas immediately prior to the - mouse button click remains as it was (when the plugin's "click()" - function was called), and is still available in the 'snapshot' - canvas. - * void release(magic_api * api, int which, SDL_Surface * snapshot, - SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect) - The plugin should apply the appropriate 'Magic' tool on the - 'canvas' surface. The (x,y) coordinates are where the mouse was - (within the canvas) when the mouse button was released. - The plugin should report back what part of the canvas was - affected, by filling in the (x,y) and (w,h) values in - 'update_rect'. - Note: The contents of the drawing canvas immediately prior to the - mouse button click remains as it was (when the plugin's "click()" - function was called), and is still available in the 'snapshot' - canvas. + Your plugin is required to contain, at the least, all of the + following functions. + + Note: Remember, your plugin's function names must be preceded by + your plugin's filename. That is, if your plugin is called "zoom.so" + (on Linux) or "zoom.dll" (on Windows), then the names of your + functions must begin with "zoom_" (e.g., "zoom_get_name(...)"). + + Plugin "housekeeping" functions: + + * Uint32 api_version(void) + The plugin should return an integer value representing the + version of the Tux Paint 'Magic' tool plugin API the plugin was + built against. The safest thing to do is return the value of + TP_MAGIC_API_VERSION, which is defined in "tp_magic_api.h". If + Tux Paint deems your plugin to be compatible, it will go ahead + and use it. + + Note: Called once by Tux Paint, at startup. It is called first. + * int init(magic_api * api) + The plugin should do any initialization here. Return '1' if + initialization was successful, or '0' if not (and Tux Paint will + not present any 'Magic' tools from the plugin). + + Note: Called once by Tux Paint, at startup. It is called first. + It is called after "api_version()", if Tux Paint believes your + plugin to be compatible. + * int get_tool_count(magic_api * api) + This should return the number of Magic tools this plugin + provides to Tux Paint. + + Note: Called once by Tux Paint, at startup. It is called after + your "init()", if it succeeded. + + * char * get_name(magic_api * api, int which) + This should return a string containing the name of a magic tool. + This will appear on the button in the 'Magic' selector within + Tux Paint. + + Tux Paint will free() the string upon exit, so you should wrap + it in a C strdup() call. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + * SDL_Surface * get_icon(magic_api * api, int which) + This should return an SDL_Surface containing the icon + representing the tool. (A greyscale image with alpha, no larger + than 40x40.) This will appear on the button in the 'Magic' + selector within Tux Paint. + + Tux Paint will free ("SDL_FreeSurface()") the surface upon exit. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + * char * get_description(magic_api * api, int which) + This should return a string containing the description of a + magic tool. This will appear as a help tip, explained by Tux the + Penguin, within Tux Paint. + + Tux Paint will free() the string upon exit, so you should wrap + it in a C strdup() call. + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + + * 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()"). + + * 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 set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g) + Tux Paint will call this function to inform the plugin of the + RGB values of the currently-selected color in Tux Paint's + 'Colors' palette. (It will be called whenever one of the + plguin's Magic tools that accept colors becomes active, or the + user picks a new color while such a tool is currently active.) + + * void click(magic_api * api, int which, SDL_Surface * snapshot, + SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect) + The plugin should apply the appropriate 'Magic' tool on the + 'canvas' surface. The (x,y) coordinates are where the mouse was + (within the canvas) when the mouse button was clicked. + + The plugin should report back what part of the canvas was + affected, by filling in the (x,y) and (w,h) values in + 'update_rect'. + + The contents of the drawing canvas immediately prior to the + mouse button click is stored within the 'snapshot' canvas. + + * void drag(magic_api * api, int which, SDL_Surface * snapshot, + SDL_Surface * canvas, int ox, int oy, int x, int y, SDL_Rect * + update_rect) + The plugin should apply the appropriate 'Magic' tool on the + 'canvas' surface. The (ox,oy) and (x,y) coordinates are the + location of the mouse at the beginning and end of the stroke. + Typically, plugins that let the user "draw" effects onto the + canvas call the Tux Paint 'Magic' tool plugin "line()" helper + function. (See below). + + The plugin should report back what part of the canvas was + affected, by filling in the (x,y) and (w,h) values in + 'update_rect'. + + Note: The contents of the drawing canvas immediately prior to + the mouse button click remains as it was (when the plugin's + "click()" function was called), and is still available in the + 'snapshot' canvas. + + * void release(magic_api * api, int which, SDL_Surface * snapshot, + SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect) + The plugin should apply the appropriate 'Magic' tool on the + 'canvas' surface. The (x,y) coordinates are where the mouse was + (within the canvas) when the mouse button was released. + + The plugin should report back what part of the canvas was + affected, by filling in the (x,y) and (w,h) values in + 'update_rect'. + + Note: The contents of the drawing canvas immediately prior to + the mouse button click remains as it was (when the plugin's + "click()" function was called), and is still available in the + 'snapshot' canvas. Tux Paint Functions - Tux Paint provides a number of helper functions that plugins may - access via the "magic_api" structure, sent to all of the - plugin's functions (see above). + Tux Paint provides a number of helper functions that plugins may + access via the "magic_api" structure, sent to all of the plugin's + functions (see above). - * Uint32 getpixel(SDL_Surface * surf, int x, int y) Retreives - the pixel value from the (x,y) coordinates of an - SDL_Surface. (You can use SDL's "SDL_GetRGB()" function to - convert the Uint32 'pixel' to a set of Uint8 RGB values.) - * void putpixel(SDL_Surface * surf, int x, int y, Uint32 - pixel) - Sets the pixel value at position (x,y) of an SDL_Surface. - (You can use SDL's "SDL_MapRGB()" function to convert a set - of Uint8 RGB values to a Uint32 'pixel' value appropriate - to the destination surface.) - * int in_circle(int x, int y, int radius) - Returns '1' if the (x,y) location is within a circle of a - particular radius (centered around the origin: (0,0)). - Returns '0' otherwise. Useful to create 'Magic' tools that - affect the canvas with a circular brush shape. - * void show_progress_bar(void) - Asks Tux Paint to animate and draw one frame of its - progress bar (at the bottom of the screen). Useful for - routines that may take a long time, to provide feedback to - the user that Tux Paint has not crashed or frozen. - * void tuxpaint_version(int * major, int * minor, int * - revision) - Returns the version of Tux Paint being used (e.g., - "0.9.18"), separated into three integers. - * void line(int which, SDL_Surface * canvas, SDL_Surface * - snapshot, int x1, int y1, int x2, int y2, int step, FUNC - callback) - This function calculates all points on a line between the - coordinates (x1,y1) and (x2,y2). Every 'step' iterations, - it calls the 'callback' function. - It sends the 'callback' function the (x,y) coordinates on - the line, Tux Paint's "magic_api" struct (as a "void *" - pointer), a 'which' value, represening which of the - plugin's 'Magic' tool is being used, and the current and - snapshot canvases. + * 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.) - Example prototype of a callback function that may be sent - to Tux Paint's "line()" 'Magic' tool plugin helper - function: + * 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.) - void exampleCallBack(void * ptr_to_api, int which_tool, - SDL_Surface * canvas, SDL_Surface * snapshot, int x, int - y); + * 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 playsound(Mix_Chunk * snd, int pan, int dist) - This function plays a sound (one loaded by the SDL helper - library "SDL_mixer"). It uses SDL_mixer's - "Mix_SetPanning()" to set the volume of the sound on the - left and right speakers, based on the 'pan' and 'dist' - values sent to it. - A 'pan' of 128 causes the sound to be played at equal - volume on the left and right speakers. A 'pan' of 0 causes - it to be played completely on the left, and 255 completely - on the right. - The 'dist' value affects overall volume. 255 is loudest, - and 0 is silent. - The 'pan' and 'dist' values can be used to simulate - location and distance of the 'Magic' tool effect. - * void special_notify(int flag) - This function notifies Tux Paint of special events. Various - values defined in "tp_magic_api.h" can be logically 'or'ed - together and sent to this function. + * void show_progress_bar(void) + Asks Tux Paint to animate and draw one frame of its progress bar + (at the bottom of the screen). Useful for routines that may take a + long time, to provide feedback to the user that Tux Paint has not + crashed or frozen. - * SPECIAL_FLIP -- The contents of the canvas has been - flipped. If a 'Starter' image was used as the basis of - this image, it should be flipped too, and a record of - the flip should be stored as part of Tux Paint's undo - buffer stack. Additionally, the fact that the starter - has been flipped (or unflipped) should be recorded on - disk when the current drawing is saved. - * SPECIAL_MIRROR -- Similar to SPECIAL_FLIP, but for - magic tools that mirror the contents of the canvas. + * void tuxpaint_version(int * major, int * minor, int * revision) + Returns the version of Tux Paint being used (e.g., "0.9.18"), + separated into three integers. - * int button_down(void) - A '1' is returned if the mouse button is down; '0' - otherwise. - * float sRGB_to_linear(Uint8 srbg) - Converts an 8-bit sRGB value (one between 0 and 255) to a - linear floating point value (between 0.0 and 1.0). - * uint8 linear_to_sRGB(float linear) - Converts a linear floating point value (one between 0.0 and - 1.0) to an 8-bit sRGB value (between 0 and 255). + * void line(int which, SDL_Surface * canvas, SDL_Surface * snapshot, + int x1, int y1, int x2, int y2, int step, FUNC callback) + This function calculates all points on a line between the + coordinates (x1,y1) and (x2,y2). Every 'step' iterations, it calls + the 'callback' function. + + It sends the 'callback' function the (x,y) coordinates on the + line, Tux Paint's "magic_api" struct (as a "void *" pointer), a + 'which' value, represening which of the plugin's 'Magic' tool is + being used, and the current and snapshot canvases. + + Example prototype of a callback function that may be sent to + Tux Paint's "line()" 'Magic' tool plugin helper function: + + void exampleCallBack(void * ptr_to_api, int which_tool, + SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y); + + * void playsound(Mix_Chunk * snd, int pan, int dist) + This function plays a sound (one loaded by the SDL helper library + "SDL_mixer"). It uses SDL_mixer's "Mix_SetPanning()" to set the + volume of the sound on the left and right speakers, based on the + 'pan' and 'dist' values sent to it. + + A 'pan' of 128 causes the sound to be played at equal volume on + the left and right speakers. A 'pan' of 0 causes it to be played + completely on the left, and 255 completely on the right. + + The 'dist' value affects overall volume. 255 is loudest, and 0 is + silent. + The 'pan' and 'dist' values can be used to simulate location and + distance of the 'Magic' tool effect. + + * void special_notify(int flag) + This function notifies Tux Paint of special events. Various values + defined in "tp_magic_api.h" can be logically 'or'ed together and + sent to this function. + + * SPECIAL_FLIP -- The contents of the canvas has been flipped. + If a 'Starter' image was used as the basis of this image, it + should be flipped too, and a record of the flip should be + stored as part of Tux Paint's undo buffer stack. + Additionally, the fact that the starter has been flipped (or + unflipped) should be recorded on disk when the current + drawing is saved. + * SPECIAL_MIRROR -- Similar to SPECIAL_FLIP, but for magic + tools that mirror the contents of the canvas. + + * int button_down(void) + A '1' is returned if the mouse button is down; '0' otherwise. + + * float sRGB_to_linear(Uint8 srbg) + Converts an 8-bit sRGB value (one between 0 and 255) to a linear + floating point value (between 0.0 and 1.0). + + * uint8 linear_to_sRGB(float linear) + Converts a linear floating point value (one between 0.0 and 1.0) + to an 8-bit sRGB value (between 0 and 255). -------------------------------------------------------------------------- @@ -261,39 +364,46 @@ Compiling Linux and other Unix-like Platforms - 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 C compiler's "-shared" command-line option to generate a + shared object file (".so") based on your 'Magic' tool plugin's C + source code. - Additionally, use the "tp-magic-config --cflags" command, - supplied as part of Tux Paint, to provide additional - command-line flags to your C compiler that will help it build - your plugin. + Additionally, use the "tp-magic-config --cflags" command, supplied as + part of Tux Paint, to provide additional command-line flags to your C + compiler that will help it build your plugin. - As a stand-alone command, using the GNU C Compiler and BASH - shell, for example: + 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 + gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so - A snippet from a more generalized Makefile might look like - this: + 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 ..."). - CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) + A snippet from a more generalized Makefile might look like this: - my_plugin.so: my_plugin.c $(CC) -shared $(CFLAGS) -o $@ - $< + CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) - Then install globally into: /usr/[local/]lib/tuxpaint/. Or - locally into: ~/.tuxpaint/magic/ + my_plugin.so: my_plugin.c $(CC) -shared $(CFLAGS) -o $@ $< + + You may then install it globally into: /usr/lib/tuxpaint/plugins/ or + /usr/local/lib/tuxpaint/plugins/ (depending on how Tux Paint was + installed). + + Or install it locally (for the current user only) into: + ~/.tuxpaint/magic/ + (FIXME: As of 2007-07-27, Tux Paint does not look here yet!) Windows - TBD + TBD Mac OS X - TBD + TBD -------------------------------------------------------------------------- @@ -301,4 +411,4 @@ Example Code -------------------------------------------------------------------------- - Summary and contact info TBD. + Summary and contact info TBD. diff --git a/magic/docs/html/README.html b/magic/docs/html/README.html index 674929261..668b7f9da 100644 --- a/magic/docs/html/README.html +++ b/magic/docs/html/README.html @@ -15,7 +15,7 @@ New Breed Software

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

-

July 5, 2007 - July 8, 2007

+

July 5, 2007 - July 27, 2007

@@ -44,7 +44,7 @@ concept.)

Tux Paint is written in the C programming language, and uses the Simple DirectMedia Layer library ('libSDL', or simply 'SDL'). -Therefore, for the moment at least, one must understand the C language, +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.

@@ -65,141 +65,264 @@ 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 should) use. This is exposed as a C structure -(containing pointers to functions inside Tux Paint and other data) -that gets passed along to the plugin's functions as an argument.

+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 file "tp_magic_api.h", -and compiler flags which should be used when building plugins (to find the -aforementioned header file, as well as SDL's header files) can be acquired -by invoking the tool "tp-magic-config".

+

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.

-

(These are included with Tux Paint — or in some cases, as part -of a "Tux Paint 'Magic' Tool Plugin Development package".)

+

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 provide the functions listed below. -Note: To avoid namespace collisions, each function's name must +

'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, unless you declare those as -'static'.

+would have functions whose names begin with "blur_"). This +includes private functions (ones not used by Tux Paint directly), +unless you declare those as 'static'.

Common arguments to plugin functions:

+Here is a description of arguments that many of your plugin's functions +will need to accept. +

Required plugin functions:

+
+ +

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

+ +

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

+ +
Plugin "housekeeping" functions:
+
    -
  • int get_tool_count(magic_api * api)
    +
  • 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. + 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)
    +
  • 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. + 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. + wrap it in a C strdup() call.
    +
    + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()").
    +
    -
  • SDL_Surface * get_icon(magic_api * api, int which)
    +
  • SDL_Surface * get_icon(magic_api * api, int which)
    This should return an SDL_Surface containing the icon representing the tool. (A greyscale image with alpha, no larger than 40x40.) This will appear on the button in the 'Magic' selector within Tux Paint.
    - Tux Paint will SDL_FreeSurface() the surface upon exit. +
    + 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)
    +
  • char * get_description(magic_api * api, int which)
    This should return a string containing the description of a magic tool. This will appear as a help tip, explained by Tux the Penguin, within Tux Paint.
    +
    Tux Paint will free() the string upon exit, so you should - wrap it in a C strdup() call. + 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 requires_colors(magic_api * api, int which)
    +
  • 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. + 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()").
    +
    -
  • void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g)
    +
  • 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 set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g) +
    Tux Paint will call this function to inform the plugin of the RGB values of the currently-selected color in Tux Paint's 'Colors' palette. (It will be called whenever one of the plguin's Magic tools that accept colors becomes active, or the user picks a new - color while such a tool is currently active.) + color while such a tool is currently active.)
    +
    -
  • Uint32 api_version(void)
    - The plugin should return an integer value representing the version of - the Tux Paint 'Magic' tool plugin API it was built against. - Simply return TP_MAGIC_API_VERSION, which is defined in - "tp_magic_api.h", to satisfy this requirement. - -
  • int init(magic_api * api)
    - The plugin should do any initialization here. This function is called once, - at Tux Paint startup. Return '1' if initialization was successful, - or '0' if not (and Tux Paint will not present any 'Magic' tools - from the plugin). - -
  • void shutdown(magic_api * api)
    - The plugin should do any cleanup here. This function is called once, - at Tux Paint exit. - -
  • void click(magic_api * api, int which, SDL_Surface * snapshot, - SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect)
    +
  • void click(magic_api * api, int which, SDL_Surface * snapshot, + SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect) +
    The plugin should apply the appropriate 'Magic' tool on the 'canvas' surface. The (x,y) coordinates are where the mouse was (within the canvas) when the mouse button was clicked.
    +
    The plugin should report back what part of the canvas was affected, by filling in the (x,y) and (w,h) values in 'update_rect'.
    +
    The contents of the drawing canvas immediately prior to the mouse button - click is stored within the 'snapshot' canvas. + click is stored within the 'snapshot' canvas.
    +
    -
  • void drag(magic_api * api, int which, SDL_Surface * snapshot, +
  • 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)
    + SDL_Rect * update_rect)
    The plugin should apply the appropriate 'Magic' tool on the 'canvas' surface. The (ox,oy) and (x,y) coordinates are the location of the mouse at the beginning and end of the stroke. Typically, plugins that let the user "draw" effects onto the canvas call the Tux Paint 'Magic' tool plugin "line()" helper function. (See below).
    +
    The plugin should report back what part of the canvas was affected, by filling in the (x,y) and (w,h) values in 'update_rect'.
    +
    Note: The contents of the drawing canvas immediately prior to the mouse button click remains as it was (when the plugin's "click()" function was - called), and is still available in the 'snapshot' canvas. + called), and is still available in the 'snapshot' canvas.
    +
    -
  • void release(magic_api * api, int which, SDL_Surface * snapshot, +
  • void release(magic_api * api, int which, SDL_Surface * snapshot, SDL_Surface * canvas, int x, int y, - SDL_Rect * update_rect)
    + SDL_Rect * update_rect)
    The plugin should apply the appropriate 'Magic' tool on the 'canvas' surface. The (x,y) coordinates are where the mouse was (within the canvas) when the mouse button was released.
    +
    The plugin should report back what part of the canvas was affected, by filling in the (x,y) and (w,h) values in 'update_rect'.
    - Note: The contents of the drawing canvas immediately prior to the mouse +
    + 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. + called), and is still available in the 'snapshot' canvas.
    +
    +
-

Tux Paint Functions

+
+ +

Tux Paint Functions

@@ -208,64 +331,74 @@ access via the "magic_api" structure, sent to all of the plugin's functions (see above).

+
-
  • int button_down(void)
    - A '1' is returned if the mouse button is down; '0' otherwise. +
  • int button_down(void)
    + A '1' is returned if the mouse button is down; '0' otherwise.
    +
    -
  • float sRGB_to_linear(Uint8 srbg)
    +
  • 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). + floating point value (between 0.0 and 1.0).
    +
    -
  • uint8 linear_to_sRGB(float linear)
    +
  • 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). + an 8-bit sRGB value (between 0 and 255).
    +
    • @@ -306,11 +443,11 @@ access via the "magic_api" structure, sent to all of the plugin's functions
    -

    Use the C compiler's "-shared" command-line option to generate +

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

    -

    Additionally, use the "tp-magic-config --cflags" command, +

    Additionally, use the "tp-magic-config --cflags" command, supplied as part of Tux Paint, to provide additional command-line flags to your C compiler that will help it build your plugin.

    @@ -323,6 +460,15 @@ access via the "magic_api" structure, sent to all of the plugin's functions

    +

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

    +

    A snippet from a more generalized Makefile might look like this:

    @@ -334,8 +480,14 @@ access via the "magic_api" structure, sent to all of the plugin's functions

    -

    Then install globally into: /usr/[local/]lib/tuxpaint/. - Or locally into: ~/.tuxpaint/magic/

    +

    You may then install it globally into: + /usr/lib/tuxpaint/plugins/ or + /usr/local/lib/tuxpaint/plugins/ (depending on how + Tux Paint was installed).

    + +

    Or install it locally (for the current user only) into: + ~/.tuxpaint/magic/
    + (FIXME: As of 2007-07-27, Tux Paint does not look here yet!)