From fbbfb2fafd67446cba035aaaf8561b38ed9cf1c2 Mon Sep 17 00:00:00 2001 From: William Kendrick Date: Fri, 6 Jul 2007 19:38:11 +0000 Subject: [PATCH] Added Makefile to convert HTML docs to plain text. Recreated plain text docs based on HTML. --- magic/docs/Makefile | 21 +++ magic/docs/README.txt | 346 ++++++++++++++++++++++++++++++------------ 2 files changed, 268 insertions(+), 99 deletions(-) create mode 100644 magic/docs/Makefile diff --git a/magic/docs/Makefile b/magic/docs/Makefile new file mode 100644 index 000000000..05e41b7ac --- /dev/null +++ b/magic/docs/Makefile @@ -0,0 +1,21 @@ +# Makefile for Tux Paint Magic Tool Plugin API docs +# +# Uses "links" to convert docs from HTML to plain text. +# (Normally only ran by the developers after updating the HTML, prior to +# release.) +# +# Bill Kendrick +# bill@newbreedsoftware.com +# +# July 6, 2007 - July 6, 2007 +# $Id$ + +LINKS=links -dump -no-numbering -no-references + +all: README.txt + +clean: + -rm README.txt + +README.txt: html/README.html + $(LINKS) $< > $@ diff --git a/magic/docs/README.txt b/magic/docs/README.txt index dd632f7f6..6fd4b1677 100644 --- a/magic/docs/README.txt +++ b/magic/docs/README.txt @@ -1,131 +1,279 @@ -Stub docs for Tux Paint Magic Plugin Development + Creating Tux Paint Magic Tool Plugins -#include "tp_magic_api.h" + Copyright 2007-2007 by Bill Kendrick and others + New Breed Software + bill@newbreedsoftware.com + http://www.tuxpaint.org/ -build plugins with: -------------------- - Linux/Unix: - ----------- - $(CC) -shared `tp-magic-config --cflags` plugin.c -o plugin.so + July 5, 2007 - July 6, 2007 - Then install globally into: /usr/[local/]lib/tuxpaint/. - Or locally into: ~/.tuxpaint/magic/ [[FIXME]] + -------------------------------------------------------------------------- - Windows: - -------- - ??? [[FIXME]] +Overview - Mac OS X: - --------- - ??? [[FIXME]] + Beginning with version 0.9.18, Tux Paint's 'Magic' tools were converted + from routines that lived within the application itself, to a set of + 'plugins' that are loaded when Tux Paint starts up. + This division allows more rapid development of 'Magic' tools, and allows + programmers to create and test new tools without needing to integrate + them within the main Tux Paint source code. (Users of more professional + graphics tools, such as The GIMP, should be familiar with this plugin + concept.) -magic plugins must provide: ---------------------------- - NOTE: Each function name should be preceded with the name of the - shared object file, e.g. "negative.so" or "negative.dll" would have - a function called "negative_init()". + -------------------------------------------------------------------------- - int get_tool_count(magic_api * api) - return the number of Magic tools this plugin provides - (used below as the 'which' values sent to each function) +Prerequisites - char * get_name(magic_api * api, int which) - return the name of a/the magic tool (for 'Magic' tool buttons in UI) - Tux Paint will free() the string; - example: - return (strdup(gettext("Fun"))); + Tux Paint is written in the C programming language, and uses the + Simple DirectMedia Layer library ('libSDL', or simply 'SDL'). Therefore, + for the moment at least, one must understand the C language, how to + compile C-based programs. Familiarity with the SDL API is highly + recommended, but some basic SDL concepts will be covered in this + document. - SDL_Surface * get_icon(magic_api * api, int which) - return the icon of a/the magic tool (for 'Magic' tool buttons in UI) - Tux Paint will SDL_FreeSurface() the surface: - example: - sprintf(fname, "%s/images/magic/funtool.png", api->data_directory); - return(IMG_Load(fname)); + -------------------------------------------------------------------------- - char * get_description(magic_api * api, int which) - return the description of a/the magic tool (for Tux help text in UI); - Tux Paint will free() the string; - example: - return (strdup(gettext("A fun tool"))); +Interfaces - int requires_colors(magic_api * api, int which) - return whether a/the magic tool accepts colors - ('1' for true; activates color palette in UI; - '0' for false; disables color palette in UI) + Those who create 'Magic' tool plugins for Tux Paint must provide some + interfaces (C functions) that Tux Paint may invoke. - void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g) - accept the color palette choice from Tux Paint - (only called if requires_colors() for the current tool returned true) + Tux Paint utilizes SDL's "SDL_LoadObject()" and "SDL_LoadFunction()" + routines to load plugins (shared objects files; e.g., ".so" files on + Linux or ".dll" files on Windows) and find the functions within. - int init(magic_api * api) - initialization function; called once, during Tux Paint startup - return 1 if success; - return 0 if failure (tool(s) will be disabled in Magic tool); + In turn, Tux Paint provides a number of helper functions that the plugin + may (or sometimes should) use. This is exposed as a C structure + (containing pointers to functions inside Tux Paint and other data) that + gets passed along to the plugin's functions as an argument. - void shutdown(magic_api * api) - cleanup function; should free any alloc'd memory, etc.; - happens once, at Tux Paint shutdown + Plugins should #include the file "tp_magic_api.h", and compiler flags + which should be used when building plugins (to find the aforementioned + header file, as well as SDL's header files) can be acquired by invoking + the tool "tp-magic-config". - void click(magic_api * api, int which, - SDL_Surface * snapshot, SDL_Surface * canvas, - int x, int y) - should affect 'canvas' at (x,y) location; may use 'snapshot' to fetch - pixels from most recent undo buffer; - Tux Paint's undo buffer is updated prior to this call + (These are included with Tux Paint -- or in some cases, as part of a + "Tux Paint 'Magic' Tool Plugin Development package".) - void drag(magic_api * api, int which, - SDL_Surface * snapshot, SDL_Surface * canvas, - int ox, int oy, int x, int y) - should affect 'canvas' between (ox,oy) and (x,y) locations; - may use 'snapshot' to fetch pixels from most recent undo buffer; - Tux Paint's undo buffer is NOT updated prior to this call; the - 'snapshot' buffer will contain the same contents as when click() was - last called + 'Magic' tool plugin functions + 'Magic' tool plugins must provide the functions listed below. Note: To + avoid namespace collisions, each function's name must start with the + shared object's filename (e.g., "blur.so" or "blur.dll" would have + functions whose names begin with "blur_"). -tp provides, via magic_api structure ("api" arg to magic tool functions): -------------------------------------------------------------------------- - void putpixel(SDL_Surface * surf, int x, int y, Uint32 pixel) - function that puts a pixel at an (x,y) position in a surface + Common arguments to plugin functions: - Uint32 getpixel(SDL_Surface * surf, int x, int y) - function that returns a pixel value from an (x,y) position on a surface + * magic_api * api + Pointer to the struct containing pointers to Tux Paint functions + and other data (see below) + * int which + An index the plugin should use to differentiate different 'Magic' + tools, if the plugin provides more than one. (If not, "which" will + always be 0.) + * SDL_Surface * canvas + The active Tux Paint drawing canvas. Your magical effects should + end up here! + * SDL_Surface * last + A snapshot of the previous Tux Paint canvas, taken when the the + mouse was first clicked to activate the magic tool. If you don't + continuously affect the image during one hold of the mouse button, + you should base your effects off the contents of this canvas. - int in_circle(int x, int y, int radius) - function that returns whether an x/y position (centered at (0,0)) is - within a circle of 'radius' + Required plugin functions: - void show_progress_bar(void) - draws the Tux Paint progress bar animation; use while you're busy + * int get_tool_count(magic_api * api) + This should return the number of Magic tools this plugin provides + to Tux Paint. + * char * get_name(magic_api * api, int which) + This should return a string containing the name of a magic tool. + This will appear on the button in the 'Magic' selector within + Tux Paint. Tux Paint will free() the string upon exit, so you + should wrap it in a C strdup() call. + * SDL_Surface * get_icon(magic_api * api, int which) + This should return an SDL_Surface containing the icon representing + the tool. (A greyscale image with alpha, no larger than 40x40.) + This will appear on the button in the 'Magic' selector within + Tux Paint. + Tux Paint will SDL_FreeSurface() the surface upon exit. + * char * get_description(magic_api * api, int which) + This should return a string containing the description of a magic + tool. This will appear as a help tip, explained by Tux the + Penguin, within Tux Paint. + Tux Paint will free() the string upon exit, so you should wrap it + in a C strdup() call. + * int requires_colors(magic_api * api, int which) + Return a '1' if the 'Magic' tool accepts colors (the 'Colors' + palette in Tux Paint will be available), or '0' if not. + * void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g) + Tux Paint will call this function to inform the plugin of the RGB + values of the currently-selected color in Tux Paint's 'Colors' + palette. (It will be called whenever one of the plguin's Magic + tools that accept colors becomes active, or the user picks a new + color while such a tool is currently active.) + * int init(magic_api * api) + The plugin should do any initialization here. This function is + called once, at Tux Paint startup. Return '1' if initialization + was successful, or '0' if not (and Tux Paint will not present any + 'Magic' tools from the plugin). + * void shutdown(magic_api * api) + The plugin should do any cleanup here. This function is called + once, at Tux Paint exit. + * void click(magic_api * api, int which, SDL_Surface * snapshot, + SDL_Surface * canvas, int x, int y) + The plugin should apply the appropriate 'Magic' tool on the + 'canvas' surface. The (x,y) coordinates are where the mouse was + (within the canvas) when the mouse button was clicked. + The contents of the drawing canvas immediately prior to the mouse + button click is stored within the 'snapshot' canvas. + * void drag(magic_api * api, int which, SDL_Surface * snapshot, + SDL_Surface * canvas, int ox, int oy, int x, int y) + The plugin should apply the appropriate 'Magic' tool on the + 'canvas' surface. The (ox,oy) and (x,y) coordinates are the + location of the mouse at the beginning and end of the stroke. + Typically, plugins that let the user "draw" effects onto the + canvas call the Tux Paint 'Magic' tool plugin "line()" helper + function. (See below). + Note: The contents of the drawing canvas immediately prior to the + mouse button click remains as it was (when the plugin's "click()" + function was called), and is still available in the 'snapshot' + canvas. - void tuxpaint_version(int * major, int * minor, int * revision) - returns the version of Tux Paint being used + Tux Paint Functions - void line(int which, SDL_Surface * canvas, SDL_Surface * snapshot, - int x1, int y1, int x2, int y2, int step, FUNC callback) - function that calls calculates a line between (x1,y1) and (x2,y2) - and calls 'callback' every 'step' iterations; - sends to the callback: Tux Paint's 'magic_api' structure, along with the - 'which', 'canvas' and 'snapshot' values sent to line(), and the (x,y) - coordinates + Tux Paint provides a number of helper functions that plugins may + access via the "magic_api" structure, sent to all of the + plugin's functions (see above). + * Uint32 getpixel(SDL_Surface * surf, int x, int y) Retreives + the pixel value from the (x,y) coordinates of an + SDL_Surface. (You can use SDL's "SDL_GetRGB()" function to + convert the Uint32 'pixel' to a set of Uint8 RGB values.) + * void putpixel(SDL_Surface * surf, int x, int y, Uint32 + pixel) + Sets the pixel value at position (x,y) of an SDL_Surface. + (You can use SDL's "SDL_MapRGB()" function to convert a set + of Uint8 RGB values to a Uint32 'pixel' value appropriate + to the destination surface.) + * int in_circle(int x, int y, int radius) + Returns '1' if the (x,y) location is within a circle of a + particular radius (centered around the origin: (0,0)). + Returns '0' otherwise. Useful to create 'Magic' tools that + affect the canvas with a circular brush shape. + * void show_progress_bar(void) + Asks Tux Paint to animate and draw one frame of its + progress bar (at the bottom of the screen). Useful for + routines that may take a long time, to provide feedback to + the user that Tux Paint has not crashed or frozen. + * void tuxpaint_version(int * major, int * minor, int * + revision) + Returns the version of Tux Paint being used (e.g., + "0.9.18"), separated into three integers. + * void line(int which, SDL_Surface * canvas, SDL_Surface * + snapshot, int x1, int y1, int x2, int y2, int step, FUNC + callback) + This function calculates all points on a line between the + coordinates (x1,y1) and (x2,y2). Every 'step' iterations, + it calls the 'callback' function. + It sends the 'callback' function the (x,y) coordinates on + the line, Tux Paint's "magic_api" struct (as a "void *" + pointer), a 'which' value, represening which of the + plugin's 'Magic' tool is being used, and the current and + snapshot canvases. -FIXME: Implement these: + Example prototype of a callback function that may be sent + to Tux Paint's "line()" 'Magic' tool plugin helper + function: - void playsound(Mix_Chunk * snd, int pan, int dist) - function that plays a sound, panned left/right 'pan' - and at distance 'dist'. pan may be SNDPOS_LEFT, SNDPOS_CENTER or - SNDPOS_RIGHT, and dist may be SNDDIST_NEAR. + void exampleCallBack(void * ptr_to_api, int which_tool, + SDL_Surface * canvas, SDL_Surface * snapshot, int x, int + y); - void special_notify(int flag) - notifies tux paint of special events; SPECIAL_FLIP and SPECIAL_MIRROR - flags may be sent + * void playsound(Mix_Chunk * snd, int pan, int dist) + This function plays a sound (one loaded by the SDL helper + library "SDL_mixer"). It uses SDL_mixer's + "Mix_SetPanning()" to set the volume of the sound on the + left and right speakers, based on the 'pan' and 'dist' + values sent to it. + A 'pan' of 128 causes the sound to be played at equal + volume on the left and right speakers. A 'pan' of 0 causes + it to be played completely on the left, and 255 completely + on the right. + The 'dist' value affects overall volume. 255 is loudest, + and 0 is silent. + The 'pan' and 'dist' values can be used to simulate + location and distance of the 'Magic' tool effect. + * void special_notify(int flag) + This function notifies Tux Paint of special events. Various + values defined in "tp_magic_api.h" can be logically 'or'ed + together and sent to this function. - float sRGB_to_linear_table[256] - sRGB-to-linear look-up table + * SPECIAL_FLIP -- The contents of the canvas has been + flipped. If a 'Starter' image was used as the basis of + this image, it should be flipped too, and a record of + the flip should be stored as part of Tux Paint's undo + buffer stack. Additionally, the fact that the starter + has been flipped (or unflipped) should be recorded on + disk when the current drawing is saved. + * SPECIAL_MIRROR -- Similar to SPECIAL_FLIP, but for + magic tools that mirror the contents of the canvas. - unsigned char linear_to_sRGB(float linear) - linear-to-sRGB look-up helper function + * int button_down(void) + A '1' is returned if the mouse button is down; '0' + otherwise. + * float sRGB_to_linear(Uint8 srbg) + Converts an 8-bit sRGB value (one between 0 and 255) to a + linear floating point value (between 0.0 and 1.0). + * uint8 linear_to_sRGB(float linear) + Converts a linear floating point value (one between 0.0 and + 1.0) to an 8-bit sRGB value (between 0 and 255). + -------------------------------------------------------------------------- + +Compiling + + Linux and other Unix-like Platforms + + Use the C compiler's "-shared" command-line option to generate + a shared object file (".so") based on your 'Magic' tool + plugin's C source code. + + Additionally, use the "tp-magic-config --cflags" command, + supplied as part of Tux Paint, to provide additional + command-line flags to your C compiler that will help it build + your plugin. + + As a stand-alone command, using the GNU C Compiler and BASH + shell, for example: + + gcc -shared `tp-magic-config --cflags` my_plugin.c -o + my_plugin.so + + A snippet from a more generalized Makefile might look like + this: + + CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) + + my_plugin.so: my_plugin.c $(CC) -shared $(CFLAGS) -o $@ + $< + + Then install globally into: /usr/[local/]lib/tuxpaint/. Or + locally into: ~/.tuxpaint/magic/ + + Windows + + TBD + + Mac OS X + + TBD + + -------------------------------------------------------------------------- + +Example Code + + -------------------------------------------------------------------------- + + Summary and contact info TBD.