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

Sync docs after finishing initial rework of Magic API docs

Browse source
This commit is contained in:
Bill Kendrick 2022-10-04 02:08:59 -07:00
parent c3141ad2d1
commit f9ecc42725
11 changed files with 3077 additions and 2733 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/CHANGES.txt
View file

@ -161,6 +161,10 @@ http://www.tuxpaint.org/
* Update macOS build instructions for SDL2.0. * Update macOS build instructions for SDL2.0.
Mark Kim <markuskimius@gmail.com> Mark Kim <markuskimius@gmail.com>
* Magic tool API documentation updated to match other docs,
and allow for localization.
Bill Kendrick <bill@newbreedsoftware.com>
* "--verbose-version" now shows whether SDL2_Pango is being used. * "--verbose-version" now shows whether SDL2_Pango is being used.
Bill Kendrick <bill@newbreedsoftware.com> Bill Kendrick <bill@newbreedsoftware.com>

154
docs/en/MAGIC-API.txt
View file

@ -151,7 +151,7 @@ Magic Tool Plugin API Documentation
Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than
just an "SDL_Rect") because you need to fill in its contents. just an "SDL_Rect") because you need to fill in its contents.
Because it is a pointer, you access its elements via "->" (arrow) Since it is a pointer, you access its elements via "->" (arrow)
rather than "." (dot). rather than "." (dot).
Required Plugin Functions Required Plugin Functions
@ -183,9 +183,9 @@ Magic Tool Plugin API Documentation
initialization was successful, or '0' if not (and Tux Paint will initialization was successful, or '0' if not (and Tux Paint will
not present any 'Magic' tools from the plugin). not present any 'Magic' tools from the plugin).
Note: Called once by Tux Paint, at startup. It is called first. It Note: Called once by Tux Paint, at startup. It is called after
is called after "api_version()", if Tux Paint believes your plugin "api_version()", if Tux Paint believes your plugin to be
to be compatible. compatible.
int get_tool_count(magic_api * api) int get_tool_count(magic_api * api)
@ -195,6 +195,29 @@ Magic Tool Plugin API Documentation
Note: Called once by Tux Paint, at startup. It is called after Note: Called once by Tux Paint, at startup. It is called after
your "init()", if it succeeded. your "init()", if it succeeded.
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.
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 should return a string containing the name of a magic tool.
@ -212,28 +235,26 @@ Magic Tool Plugin API Documentation
Use this to group tools together within sections of the 'Magic' Use this to group tools together within sections of the 'Magic'
selector. A number of groups are pre-defined within an enum found selector. A number of groups are pre-defined within an enum found
in "tp_magic_api.h": in "tp_magic_api.h":
* MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of * MAGIC_TYPE_DISTORTS — Tools that distort the shape of the
the image, like Blur, Emboss, and Ripples image, like Blur, Emboss, and Ripples
* MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect the * MAGIC_TYPE_COLOR_FILTERS — Tools that mostly affect the
colors of the image without distortion, like Darken, colors of the image without distortion, like Darken,
Negative, and Tint Negative, and Tint
* MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the * MAGIC_TYPE_PICTURE_WARPS — Tools that warp or move the entire
entire picture, like Shift, Flip, and Waves picture, like Shift, Flip, and Waves
* MAGIC_TYPE_PAINTING mdash; Tools that generally paint new * MAGIC_TYPE_PAINTING — Tools that generally paint new content
content at the cursor position, like Grass, Bricks, and Rails at the cursor position, like Grass, Bricks, and Rails
* MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in * MAGIC_TYPE_PATTERN_PAINTING — Tools that paint in multiple
multiple places at once, like Kaleidoscope and the Symmetry places at once, like Kaleidoscope and the Symmetry tools
tools * MAGIC_TYPE_PICTURE_DECORATIONS — Tools that apply decorations
* MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply to the entire picture, like Blinds and Checkboard
decorations to the entire picture, like Blinds and Checkboard * MAGIC_TYPE_ARTISTIC — Special-purpose artistic tools, like
* MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, Flower, the String tools, and the Rainbow-arc-drawing tools.
like Flower, the String tools, and the Rainbow-arc-drawing
tools.
Note: Called once for each Magic tool your plugin claims to Note: Called once for each Magic tool your plugin claims to
contain (by your "get_tool_count()"). contain (by your "get_tool_count()").
Note: Added to Tux Paint 0.9.27; Magic API version '0x00000005' Note: Added to Tux Paint 0.9.27; Magic API version 0x00000005.
SDL_Surface * get_icon(magic_api * api, int which) SDL_Surface * get_icon(magic_api * api, int which)
@ -274,29 +295,6 @@ Magic Tool Plugin API Documentation
Note: Called once for each Magic tool your plugin claims to Note: Called once for each Magic tool your plugin claims to
contain (by your "get_tool_count()"). 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) void shutdown(magic_api * api)
The plugin should do any cleanup here. If you allocated any memory The plugin should do any cleanup here. If you allocated any memory
@ -347,7 +345,7 @@ Magic Tool Plugin API Documentation
pieces of that copy could be drawn on the canvas when they draw pieces of that copy could be drawn on the canvas when they draw
with the Magic tool. with the Magic tool.
Note: Added to Tux Paint 0.9.21; Magic API version '0x00000002' Note: Added to Tux Paint 0.9.21; Magic API version 0x00000002.
void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g) 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 Tux Paint will call this function to inform the plugin of the RGB
@ -507,7 +505,7 @@ Tux Paint Functions and Data
char * tp_version char * tp_version
A string containing the version of Tux Paint that's running (e.g., A string containing the version of Tux Paint that's running (e.g.,
"0.9.18"). "0.9.29").
int canvas_w int canvas_w
int canvas_h int canvas_h
@ -652,7 +650,7 @@ Constant Defintions in "tp_magic_api.h"
your plugin is compatible. your plugin is compatible.
Note: This version number does not correspond to Tux Paint's own 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 release number (e.g., "0.9.29"). The API will not change every
time a new version of Tux Paint is released, which means plugins time a new version of Tux Paint is released, which means plugins
compiled for earlier versions of Tux Paint will often run under compiled for earlier versions of Tux Paint will often run under
newer versions. newer versions.
@ -699,9 +697,9 @@ Linux and other Unix-like Platforms
The first line sets up Makefile variable ("CFLAGS") that contains flags The first line sets up Makefile variable ("CFLAGS") that contains flags
for the compiler. "-Wall" asks for all compiler warnings to be shown. for the compiler. "-Wall" asks for all compiler warnings to be shown.
"-O2" asks for level 2 optimization. "($shell tp-magic-config --cflags)" "-O2" asks for level 2 optimization. "( tp-magic-config --cflags)" runs
runs "tp-magic-config" to retrieve additional compiler flags that "Magic" "tp-magic-config" to retrieve additional compiler flags that "Magic" tool
tool plugins require. (The "$(shell ...)" directive is similar to the ` plugins require. (The "$(shell ...)" directive is similar to the `
("grave") character in the BASH shell examples, above.) ("grave") character in the BASH shell examples, above.)
The next line defines a Makefile target, "my_plugin.so", and states that The next line defines a Makefile target, "my_plugin.so", and states that
@ -911,7 +909,7 @@ macOS
char * my_plugin_snd_filenames[NUM_TOOLS] = { char * my_plugin_snd_filenames[NUM_TOOLS] = {
"one.ogg", "another.ogg", "yet_another.ogg" }; "one.ogg", "another.ogg", "yet_another.ogg" };
Mix_Chunk * my_plugin_snds[NUM_TOOLS]; Mix_Chunk * my_plugin_snds[NUM_TOOLS]") ?>;
* Use a C "for"-loop to load or create the effect-specific data (such as * Use a C "for"-loop to load or create the effect-specific data (such as
loading sound effects during your "init()"). loading sound effects during your "init()").
@ -925,7 +923,7 @@ macOS
"/usr/share/tuxpaint/sounds/magic/one.ogg" */ "/usr/share/tuxpaint/sounds/magic/one.ogg" */
snprintf(fname, sizeof(fname), "%s/sounds/magic/%s", snprintf(fname, sizeof(fname), "%s/sounds/magic/%s",
api->data_prefix, my_plugin_snd_filenames[i]; api->data_prefix, my_plugin_snd_filenames[i]);
my_plugin_snds[i] = Mix_LoadWAV(fname); my_plugin_snds[i] = Mix_LoadWAV(fname);
} }
@ -967,13 +965,13 @@ macOS
* ampersand: "&". A symbol in C that allows you to refer to the memory * 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 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 i;". Later, "&i" refers to the memory where "i" is stored, not the
value of "i" itself; it is a 'pointer to "i"'.) (See also "star") value of "i" itself; it is a 'pointer to "i"'.) See also: "star"
* API: Application Programming Interface. TBD * API: Application Programming Interface. TBD
* argument: A value sent to a function. * argument: A value sent to a function.
* arrow: "->". A symbol in C that references an element within a pointer * arrow: "->". A symbol in C that references an element within a pointer
to a struct. to a struct.
* backquote: See "grave." * backquote: See "grave"
* backtick: See "grave." * backtick: See "grave"
* bit: "Binary digit." Bits are the basic storage unit in a computer's * bit: "Binary digit." Bits are the basic storage unit in a computer's
memory, disk, networking, etc. They represent either 0 or 1. (Compared 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 to a decimal digit, which can be anything between 0 and 9.) Just as a
@ -981,14 +979,14 @@ macOS
"5" is fifteen (15)), so can bits (e.g., "1" and "0", is two). In "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 decimal, we go from right to left: ones place, tens place, hundreds
place, thousands place, etc. In binary, it is: ones place, twos place, place, thousands place, etc. In binary, it is: ones place, twos place,
fours place, eights place, etc. (See also "byte.") fours place, eights place, etc. See also: "byte"
* blue: See "RGBA" * blue: See "RGBA"
* boolean 'or': A mathematical operation that results in a true value if * 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 either operand is true. ("1 | 0", "0 | 1" and "1 | 1" all result in
"1". "0 | 0" results in "0".) "1". "0 | 0" results in "0".)
* |: See "boolean 'or'" * |: See "boolean 'or'"
* .: See "dot" * .: See "dot"
* `: See "grave." * `: See "grave"
* *: See "star" * *: See "star"
* byte: A unit of memory made up of 8 bits. As a signed value, it can * 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 represent -128 through 127. As an unsigned value, it can represent 0
@ -1035,13 +1033,14 @@ macOS
* floating point: TBD * floating point: TBD
* format: An SDL_Surface element (a pointer to an SDL_PixelFormat * format: An SDL_Surface element (a pointer to an SDL_PixelFormat
structure) that contains information about a surface; for example, the structure) that contains information about a surface; for example, the
number of bits used to represent each pixel). (See also the number of bits used to represent each pixel). See also the
"SDL_PixelFormat(3) man page) "SDL_PixelFormat(3)" man page)
* free(): A C function that frees (deallocates) memory allocated by * free(): A C function that frees (deallocates) memory allocated by
other C functions (such as "strdup()"). other C functions (such as "strdup()").
* function: See "C function" * function: See "C function"
* gcc: The GNU C compiler, a portable Open Source compiler. (See also * gcc: The GNU C compiler, a portable Open Source compiler. See also the
the "gcc(1)" man page) "gcc(1)" man page)
* GIMP: An Open Source image manipulation and paint program.
* GNU C Compiler: See "gcc" * GNU C Compiler: See "gcc"
* grave: The "`" character; used by the BASH shell to use the output of * grave: The "`" character; used by the BASH shell to use the output of
a command as the command-line arguments to another. a command as the command-line arguments to another.
@ -1069,7 +1068,7 @@ macOS
that exposes data and functions within the running copy of Tux Paint. that exposes data and functions within the running copy of Tux Paint.
* make: A utility that automatically determines which pieces of a larger * make: A utility that automatically determines which pieces of a larger
program need to be recompiled, and issues the commands to recompile program need to be recompiled, and issues the commands to recompile
them. (See also "Makefile") them. See also: "Makefile"
* Makefile: A text file used by the "make" utility; it describes the * Makefile: A text file used by the "make" utility; it describes the
relationships among files in your program, and the commands for relationships among files in your program, and the commands for
updating each file. (For example, to compile a human-readable updating each file. (For example, to compile a human-readable
@ -1083,25 +1082,25 @@ macOS
* Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg * Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg
Vorbis, etc.) and returns it as a "Mix_Chunk *". Vorbis, etc.) and returns it as a "Mix_Chunk *".
* namespace: TBD * namespace: TBD
* OGG: See "Ogg Vorbis" * .ogg: See "Ogg Vorbis"
* Ogg Vorbis: TBD (See also: "WAV") * Ogg Vorbis: See also: "WAV"
* Plugin: TBD * Plugin: TBD
* PNG: Portable Network Graphics. An extensible file format for the * .png: Portable Network Graphics. An extensible file format for the
lossless, portable, well-compressed storage of raster images. It's 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 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 stamps. It's an easy way to store 32bpp RGBA images (24bpp true color
with full 8bpp alpha transparency), excellent for use in graphics with full 8bpp alpha transparency), excellent for use in graphics
programs like Tux Paint. (See also the "png(5) man page) programs like Tux Paint. See also the "png(5)" man page)
* pointer: See "C pointer" * pointer: See "C pointer"
* prototype: See "C function prototype" * prototype: See "C function prototype"
* red: See "RGBA" * red: See "RGBA"
* release: The action of releasing a button on a mouse. * release: The action of releasing a button on a mouse.
* RGBA: "Red, Green, Blue, Alpha." TBD * RGBA: "Red, Green, Blue, Alpha." TBD
* RGB: See "RBGA" * RGB: See "RGBA"
* saturation: See "HSV" * saturation: See "HSV"
* SDL: See "Simple DirectMedia Layer" * SDL: See "Simple DirectMedia Layer"
* SDL_FreeSurface(): An libSDL function that frees (deallocates) memory * SDL_FreeSurface(): An libSDL function that frees (deallocates) memory
allocated for an SDL surface ("SDL_Surface *"). (See also the allocated for an SDL surface ("SDL_Surface *"). See also the
"SDL_FreeSurface(3)" man page) "SDL_FreeSurface(3)" man page)
* SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value * SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value
(e.g., one returned from the Tux Paint's Magic tool API helper (e.g., one returned from the Tux Paint's Magic tool API helper
@ -1109,13 +1108,13 @@ macOS
from, and pointers to three Uint8 variables, will place the Red, Green from, and pointers to three Uint8 variables, will place the Red, Green
and Blue (RGB) values of the pixel into the three Uint8 variables. and Blue (RGB) values of the pixel into the three Uint8 variables.
(Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g,
&b);".) (See also the "SDL_GetRGB(3)" man page) &b);".) See also the "SDL_GetRGB(3)" man page)
* SDL_MapRGB(): A libSDL function that, given the format of a surface * SDL_MapRGB(): A libSDL function that, given the format of a surface
and Uint8 values representing Red, Green and Blue values for a pixel, 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., returns a Uint32 pixel value that can be placed in the surface (e.g.,
using Tux Paint's Magic tool API helper function "putpixel()"). using Tux Paint's Magic tool API helper function "putpixel()").
(Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".)
(See also the "SDL_MapRGB(3)" man page) See also the "SDL_MapRGB(3)" man page)
* SDL_image: A library on top of libSDL that can load various kinds of * 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 *". 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 * SDL_mixer: A library on top of libSDL that can load various kinds of
@ -1124,9 +1123,9 @@ macOS
* SDL_Rect: A C structure defined by libSDL that represents a * SDL_Rect: A C structure defined by libSDL that represents a
rectangular area. It contains elements representing the coordinates of rectangular area. It contains elements representing the coordinates of
the top left corner of the rectange (x,y) and the dimensions of the 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) rectangle (w,h). See also the "SDL_Rect(3)" man page)
* SDL_Surface *: (A pointer to) a C structure defined by libSDL that * SDL_Surface *: (A pointer to) a C structure defined by libSDL that
contains a drawing surface. (See also the "SDL_Surface(3)" man page) contains a drawing surface. See also the "SDL_Surface(3)" man page)
* Shared Object: A piece of code that's compiled separately from the * Shared Object: A piece of code that's compiled separately from the
main application, and loaded dynamically, at runtime. main application, and loaded dynamically, at runtime.
* Simple DirectMedia Layer: A programming library that allows programs * Simple DirectMedia Layer: A programming library that allows programs
@ -1138,7 +1137,7 @@ macOS
string, making sure not to go beyond the string's buffer size (which 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];" must also be supplied). For example, assume a string "char str[20];"
has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill", has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill",
"32");" will store "Name: Bill, Age: 32" into 'str'. (See also the "32");" will store "Name: Bill, Age: 32" into 'str'. See also the
"snprintf(3)" man page) "snprintf(3)" man page)
* .so: See "Shared Object" * .so: See "Shared Object"
* sRBG: See "RGBA" * sRBG: See "RGBA"
@ -1149,19 +1148,18 @@ macOS
variable. (For example, later "*p = 50;" assigns the value of 50 to 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", 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 which is still a pointer to an integer. In essence, it changed the
integer that's being pointed to.) (See also "ampersand") integer that's being pointed to.) See also: "ampersand"
* strdup(): A C function that allocates enough memory to store a copy of * 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 a string, copies the string to it, and returns a "char *" pointer to
the new copy. (See also the "strdup(3)" man page) the new copy. See also the "strdup(3)" man page)
* struct: See "C structure" * 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. * tp_magic_api.h: A header file that defines Tux Paint's Magic tool API.
Plugins must '#include' it. Plugins must '#include' it.
* tp-magic-config: A command-line program that provides information * tp-magic-config: A command-line program that provides information
about the installed version of Tux Paint to plugin developers (such as about the installed version of Tux Paint to plugin developers (such as
what C compiler flags they should compile with, and where plugin what C compiler flags they should compile with, and where plugin
shared objects and data files should be installed). (See also the shared objects and data files should be installed). See also the
"tp-magic-config(3)" man page.) "tp-magic-config(3)" man page)
* Uint32: A 32-bit, unsigned integer (defined by libSDL). In other * Uint32: A 32-bit, unsigned integer (defined by libSDL). In other
words, four bytes that can represent 0 through 4294967295. (Typically words, four bytes that can represent 0 through 4294967295. (Typically
used to hold enough information to store three or four bytes used to hold enough information to store three or four bytes
@ -1185,6 +1183,6 @@ macOS
someone's age could be declared as an integer: "int a;". It can be someone's age could be declared as an integer: "int a;". It can be
examined later: "if (a >= 18) { /* they are an adult */ } else { /* examined later: "if (a >= 18) { /* they are an adult */ } else { /*
they are not an adult */ }". they are not an adult */ }".
* WAV: TBD (See also "Ogg Vorbis") * .wav: See also: "Ogg Vorbis"
* (w,h): See "Dimensions" * (w,h): See "Dimensions"
* (x,y): See "Coordinates" * (x,y): See "Coordinates"

1006
docs/en/html/MAGIC-API.html
View file

File diff suppressed because it is too large Load diff

154
docs/es_ES.UTF-8/MAGIC-API.txt
View file

@ -151,7 +151,7 @@ Magic Tool Plugin API Documentation
Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than
just an "SDL_Rect") because you need to fill in its contents. just an "SDL_Rect") because you need to fill in its contents.
Because it is a pointer, you access its elements via "->" (arrow) Since it is a pointer, you access its elements via "->" (arrow)
rather than "." (dot). rather than "." (dot).
Required Plugin Functions Required Plugin Functions
@ -183,9 +183,9 @@ Magic Tool Plugin API Documentation
initialization was successful, or '0' if not (and Tux Paint will initialization was successful, or '0' if not (and Tux Paint will
not present any 'Magic' tools from the plugin). not present any 'Magic' tools from the plugin).
Note: Called once by Tux Paint, at startup. It is called first. It Note: Called once by Tux Paint, at startup. It is called after
is called after "api_version()", if Tux Paint believes your plugin "api_version()", if Tux Paint believes your plugin to be
to be compatible. compatible.
int get_tool_count(magic_api * api) int get_tool_count(magic_api * api)
@ -195,6 +195,29 @@ Magic Tool Plugin API Documentation
Note: Called once by Tux Paint, at startup. It is called after Note: Called once by Tux Paint, at startup. It is called after
your "init()", if it succeeded. your "init()", if it succeeded.
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.
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 should return a string containing the name of a magic tool.
@ -212,28 +235,26 @@ Magic Tool Plugin API Documentation
Use this to group tools together within sections of the 'Magic' Use this to group tools together within sections of the 'Magic'
selector. A number of groups are pre-defined within an enum found selector. A number of groups are pre-defined within an enum found
in "tp_magic_api.h": in "tp_magic_api.h":
* MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of * MAGIC_TYPE_DISTORTS — Tools that distort the shape of the
the image, like Blur, Emboss, and Ripples image, like Blur, Emboss, and Ripples
* MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect the * MAGIC_TYPE_COLOR_FILTERS — Tools that mostly affect the
colors of the image without distortion, like Darken, colors of the image without distortion, like Darken,
Negative, and Tint Negative, and Tint
* MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the * MAGIC_TYPE_PICTURE_WARPS — Tools that warp or move the entire
entire picture, like Shift, Flip, and Waves picture, like Shift, Flip, and Waves
* MAGIC_TYPE_PAINTING mdash; Tools that generally paint new * MAGIC_TYPE_PAINTING — Tools that generally paint new content
content at the cursor position, like Grass, Bricks, and Rails at the cursor position, like Grass, Bricks, and Rails
* MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in * MAGIC_TYPE_PATTERN_PAINTING — Tools that paint in multiple
multiple places at once, like Kaleidoscope and the Symmetry places at once, like Kaleidoscope and the Symmetry tools
tools * MAGIC_TYPE_PICTURE_DECORATIONS — Tools that apply decorations
* MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply to the entire picture, like Blinds and Checkboard
decorations to the entire picture, like Blinds and Checkboard * MAGIC_TYPE_ARTISTIC — Special-purpose artistic tools, like
* MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, Flower, the String tools, and the Rainbow-arc-drawing tools.
like Flower, the String tools, and the Rainbow-arc-drawing
tools.
Note: Called once for each Magic tool your plugin claims to Note: Called once for each Magic tool your plugin claims to
contain (by your "get_tool_count()"). contain (by your "get_tool_count()").
Note: Added to Tux Paint 0.9.27; Magic API version '0x00000005' Note: Added to Tux Paint 0.9.27; Magic API version 0x00000005.
SDL_Surface * get_icon(magic_api * api, int which) SDL_Surface * get_icon(magic_api * api, int which)
@ -274,29 +295,6 @@ Magic Tool Plugin API Documentation
Note: Called once for each Magic tool your plugin claims to Note: Called once for each Magic tool your plugin claims to
contain (by your "get_tool_count()"). 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) void shutdown(magic_api * api)
The plugin should do any cleanup here. If you allocated any memory The plugin should do any cleanup here. If you allocated any memory
@ -347,7 +345,7 @@ Magic Tool Plugin API Documentation
pieces of that copy could be drawn on the canvas when they draw pieces of that copy could be drawn on the canvas when they draw
with the Magic tool. with the Magic tool.
Note: Added to Tux Paint 0.9.21; Magic API version '0x00000002' Note: Added to Tux Paint 0.9.21; Magic API version 0x00000002.
void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g) 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 Tux Paint will call this function to inform the plugin of the RGB
@ -507,7 +505,7 @@ Tux Paint Functions and Data
char * tp_version char * tp_version
A string containing the version of Tux Paint that's running (e.g., A string containing the version of Tux Paint that's running (e.g.,
"0.9.18"). "0.9.29").
int canvas_w int canvas_w
int canvas_h int canvas_h
@ -652,7 +650,7 @@ Constant Defintions in "tp_magic_api.h"
your plugin is compatible. your plugin is compatible.
Note: This version number does not correspond to Tux Paint's own 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 release number (e.g., "0.9.29"). The API will not change every
time a new version of Tux Paint is released, which means plugins time a new version of Tux Paint is released, which means plugins
compiled for earlier versions of Tux Paint will often run under compiled for earlier versions of Tux Paint will often run under
newer versions. newer versions.
@ -699,9 +697,9 @@ Linux and other Unix-like Platforms
The first line sets up Makefile variable ("CFLAGS") that contains flags The first line sets up Makefile variable ("CFLAGS") that contains flags
for the compiler. "-Wall" asks for all compiler warnings to be shown. for the compiler. "-Wall" asks for all compiler warnings to be shown.
"-O2" asks for level 2 optimization. "($shell tp-magic-config --cflags)" "-O2" asks for level 2 optimization. "( tp-magic-config --cflags)" runs
runs "tp-magic-config" to retrieve additional compiler flags that "Magic" "tp-magic-config" to retrieve additional compiler flags that "Magic" tool
tool plugins require. (The "$(shell ...)" directive is similar to the ` plugins require. (The "$(shell ...)" directive is similar to the `
("grave") character in the BASH shell examples, above.) ("grave") character in the BASH shell examples, above.)
The next line defines a Makefile target, "my_plugin.so", and states that The next line defines a Makefile target, "my_plugin.so", and states that
@ -911,7 +909,7 @@ macOS
char * my_plugin_snd_filenames[NUM_TOOLS] = { char * my_plugin_snd_filenames[NUM_TOOLS] = {
"one.ogg", "another.ogg", "yet_another.ogg" }; "one.ogg", "another.ogg", "yet_another.ogg" };
Mix_Chunk * my_plugin_snds[NUM_TOOLS]; Mix_Chunk * my_plugin_snds[NUM_TOOLS]") ?>;
* Use a C "for"-loop to load or create the effect-specific data (such as * Use a C "for"-loop to load or create the effect-specific data (such as
loading sound effects during your "init()"). loading sound effects during your "init()").
@ -925,7 +923,7 @@ macOS
"/usr/share/tuxpaint/sounds/magic/one.ogg" */ "/usr/share/tuxpaint/sounds/magic/one.ogg" */
snprintf(fname, sizeof(fname), "%s/sounds/magic/%s", snprintf(fname, sizeof(fname), "%s/sounds/magic/%s",
api->data_prefix, my_plugin_snd_filenames[i]; api->data_prefix, my_plugin_snd_filenames[i]);
my_plugin_snds[i] = Mix_LoadWAV(fname); my_plugin_snds[i] = Mix_LoadWAV(fname);
} }
@ -967,13 +965,13 @@ macOS
* ampersand: "&". A symbol in C that allows you to refer to the memory * 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 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 i;". Later, "&i" refers to the memory where "i" is stored, not the
value of "i" itself; it is a 'pointer to "i"'.) (See also "star") value of "i" itself; it is a 'pointer to "i"'.) See also: "star"
* API: Application Programming Interface. TBD * API: Application Programming Interface. TBD
* argument: A value sent to a function. * argument: A value sent to a function.
* arrow: "->". A symbol in C that references an element within a pointer * arrow: "->". A symbol in C that references an element within a pointer
to a struct. to a struct.
* backquote: See "grave." * backquote: See "grave"
* backtick: See "grave." * backtick: See "grave"
* bit: "Binary digit." Bits are the basic storage unit in a computer's * bit: "Binary digit." Bits are the basic storage unit in a computer's
memory, disk, networking, etc. They represent either 0 or 1. (Compared 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 to a decimal digit, which can be anything between 0 and 9.) Just as a
@ -981,14 +979,14 @@ macOS
"5" is fifteen (15)), so can bits (e.g., "1" and "0", is two). In "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 decimal, we go from right to left: ones place, tens place, hundreds
place, thousands place, etc. In binary, it is: ones place, twos place, place, thousands place, etc. In binary, it is: ones place, twos place,
fours place, eights place, etc. (See also "byte.") fours place, eights place, etc. See also: "byte"
* blue: See "RGBA" * blue: See "RGBA"
* boolean 'or': A mathematical operation that results in a true value if * 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 either operand is true. ("1 | 0", "0 | 1" and "1 | 1" all result in
"1". "0 | 0" results in "0".) "1". "0 | 0" results in "0".)
* |: See "boolean 'or'" * |: See "boolean 'or'"
* .: See "dot" * .: See "dot"
* `: See "grave." * `: See "grave"
* *: See "star" * *: See "star"
* byte: A unit of memory made up of 8 bits. As a signed value, it can * 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 represent -128 through 127. As an unsigned value, it can represent 0
@ -1035,13 +1033,14 @@ macOS
* floating point: TBD * floating point: TBD
* format: An SDL_Surface element (a pointer to an SDL_PixelFormat * format: An SDL_Surface element (a pointer to an SDL_PixelFormat
structure) that contains information about a surface; for example, the structure) that contains information about a surface; for example, the
number of bits used to represent each pixel). (See also the number of bits used to represent each pixel). See also the
"SDL_PixelFormat(3) man page) "SDL_PixelFormat(3)" man page)
* free(): A C function that frees (deallocates) memory allocated by * free(): A C function that frees (deallocates) memory allocated by
other C functions (such as "strdup()"). other C functions (such as "strdup()").
* function: See "C function" * function: See "C function"
* gcc: The GNU C compiler, a portable Open Source compiler. (See also * gcc: The GNU C compiler, a portable Open Source compiler. See also the
the "gcc(1)" man page) "gcc(1)" man page)
* GIMP: An Open Source image manipulation and paint program.
* GNU C Compiler: See "gcc" * GNU C Compiler: See "gcc"
* grave: The "`" character; used by the BASH shell to use the output of * grave: The "`" character; used by the BASH shell to use the output of
a command as the command-line arguments to another. a command as the command-line arguments to another.
@ -1069,7 +1068,7 @@ macOS
that exposes data and functions within the running copy of Tux Paint. that exposes data and functions within the running copy of Tux Paint.
* make: A utility that automatically determines which pieces of a larger * make: A utility that automatically determines which pieces of a larger
program need to be recompiled, and issues the commands to recompile program need to be recompiled, and issues the commands to recompile
them. (See also "Makefile") them. See also: "Makefile"
* Makefile: A text file used by the "make" utility; it describes the * Makefile: A text file used by the "make" utility; it describes the
relationships among files in your program, and the commands for relationships among files in your program, and the commands for
updating each file. (For example, to compile a human-readable updating each file. (For example, to compile a human-readable
@ -1083,25 +1082,25 @@ macOS
* Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg * Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg
Vorbis, etc.) and returns it as a "Mix_Chunk *". Vorbis, etc.) and returns it as a "Mix_Chunk *".
* namespace: TBD * namespace: TBD
* OGG: See "Ogg Vorbis" * .ogg: See "Ogg Vorbis"
* Ogg Vorbis: TBD (See also: "WAV") * Ogg Vorbis: See also: "WAV"
* Plugin: TBD * Plugin: TBD
* PNG: Portable Network Graphics. An extensible file format for the * .png: Portable Network Graphics. An extensible file format for the
lossless, portable, well-compressed storage of raster images. It's 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 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 stamps. It's an easy way to store 32bpp RGBA images (24bpp true color
with full 8bpp alpha transparency), excellent for use in graphics with full 8bpp alpha transparency), excellent for use in graphics
programs like Tux Paint. (See also the "png(5) man page) programs like Tux Paint. See also the "png(5)" man page)
* pointer: See "C pointer" * pointer: See "C pointer"
* prototype: See "C function prototype" * prototype: See "C function prototype"
* red: See "RGBA" * red: See "RGBA"
* release: The action of releasing a button on a mouse. * release: The action of releasing a button on a mouse.
* RGBA: "Red, Green, Blue, Alpha." TBD * RGBA: "Red, Green, Blue, Alpha." TBD
* RGB: See "RBGA" * RGB: See "RGBA"
* saturation: See "HSV" * saturation: See "HSV"
* SDL: See "Simple DirectMedia Layer" * SDL: See "Simple DirectMedia Layer"
* SDL_FreeSurface(): An libSDL function that frees (deallocates) memory * SDL_FreeSurface(): An libSDL function that frees (deallocates) memory
allocated for an SDL surface ("SDL_Surface *"). (See also the allocated for an SDL surface ("SDL_Surface *"). See also the
"SDL_FreeSurface(3)" man page) "SDL_FreeSurface(3)" man page)
* SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value * SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value
(e.g., one returned from the Tux Paint's Magic tool API helper (e.g., one returned from the Tux Paint's Magic tool API helper
@ -1109,13 +1108,13 @@ macOS
from, and pointers to three Uint8 variables, will place the Red, Green from, and pointers to three Uint8 variables, will place the Red, Green
and Blue (RGB) values of the pixel into the three Uint8 variables. and Blue (RGB) values of the pixel into the three Uint8 variables.
(Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g,
&b);".) (See also the "SDL_GetRGB(3)" man page) &b);".) See also the "SDL_GetRGB(3)" man page)
* SDL_MapRGB(): A libSDL function that, given the format of a surface * SDL_MapRGB(): A libSDL function that, given the format of a surface
and Uint8 values representing Red, Green and Blue values for a pixel, 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., returns a Uint32 pixel value that can be placed in the surface (e.g.,
using Tux Paint's Magic tool API helper function "putpixel()"). using Tux Paint's Magic tool API helper function "putpixel()").
(Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".)
(See also the "SDL_MapRGB(3)" man page) See also the "SDL_MapRGB(3)" man page)
* SDL_image: A library on top of libSDL that can load various kinds of * 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 *". 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 * SDL_mixer: A library on top of libSDL that can load various kinds of
@ -1124,9 +1123,9 @@ macOS
* SDL_Rect: A C structure defined by libSDL that represents a * SDL_Rect: A C structure defined by libSDL that represents a
rectangular area. It contains elements representing the coordinates of rectangular area. It contains elements representing the coordinates of
the top left corner of the rectange (x,y) and the dimensions of the 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) rectangle (w,h). See also the "SDL_Rect(3)" man page)
* SDL_Surface *: (A pointer to) a C structure defined by libSDL that * SDL_Surface *: (A pointer to) a C structure defined by libSDL that
contains a drawing surface. (See also the "SDL_Surface(3)" man page) contains a drawing surface. See also the "SDL_Surface(3)" man page)
* Shared Object: A piece of code that's compiled separately from the * Shared Object: A piece of code that's compiled separately from the
main application, and loaded dynamically, at runtime. main application, and loaded dynamically, at runtime.
* Simple DirectMedia Layer: A programming library that allows programs * Simple DirectMedia Layer: A programming library that allows programs
@ -1138,7 +1137,7 @@ macOS
string, making sure not to go beyond the string's buffer size (which 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];" must also be supplied). For example, assume a string "char str[20];"
has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill", has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill",
"32");" will store "Name: Bill, Age: 32" into 'str'. (See also the "32");" will store "Name: Bill, Age: 32" into 'str'. See also the
"snprintf(3)" man page) "snprintf(3)" man page)
* .so: See "Shared Object" * .so: See "Shared Object"
* sRBG: See "RGBA" * sRBG: See "RGBA"
@ -1149,19 +1148,18 @@ macOS
variable. (For example, later "*p = 50;" assigns the value of 50 to 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", 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 which is still a pointer to an integer. In essence, it changed the
integer that's being pointed to.) (See also "ampersand") integer that's being pointed to.) See also: "ampersand"
* strdup(): A C function that allocates enough memory to store a copy of * 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 a string, copies the string to it, and returns a "char *" pointer to
the new copy. (See also the "strdup(3)" man page) the new copy. See also the "strdup(3)" man page)
* struct: See "C structure" * 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. * tp_magic_api.h: A header file that defines Tux Paint's Magic tool API.
Plugins must '#include' it. Plugins must '#include' it.
* tp-magic-config: A command-line program that provides information * tp-magic-config: A command-line program that provides information
about the installed version of Tux Paint to plugin developers (such as about the installed version of Tux Paint to plugin developers (such as
what C compiler flags they should compile with, and where plugin what C compiler flags they should compile with, and where plugin
shared objects and data files should be installed). (See also the shared objects and data files should be installed). See also the
"tp-magic-config(3)" man page.) "tp-magic-config(3)" man page)
* Uint32: A 32-bit, unsigned integer (defined by libSDL). In other * Uint32: A 32-bit, unsigned integer (defined by libSDL). In other
words, four bytes that can represent 0 through 4294967295. (Typically words, four bytes that can represent 0 through 4294967295. (Typically
used to hold enough information to store three or four bytes used to hold enough information to store three or four bytes
@ -1185,6 +1183,6 @@ macOS
someone's age could be declared as an integer: "int a;". It can be someone's age could be declared as an integer: "int a;". It can be
examined later: "if (a >= 18) { /* they are an adult */ } else { /* examined later: "if (a >= 18) { /* they are an adult */ } else { /*
they are not an adult */ }". they are not an adult */ }".
* WAV: TBD (See also "Ogg Vorbis") * .wav: See also: "Ogg Vorbis"
* (w,h): See "Dimensions" * (w,h): See "Dimensions"
* (x,y): See "Coordinates" * (x,y): See "Coordinates"

1006
docs/es_ES.UTF-8/html/MAGIC-API.html
View file

File diff suppressed because it is too large Load diff

156
docs/fr_FR.UTF-8/MAGIC-API.txt
View file

@ -151,7 +151,7 @@ Magic Tool Plugin API Documentation
Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than
just an "SDL_Rect") because you need to fill in its contents. just an "SDL_Rect") because you need to fill in its contents.
Because it is a pointer, you access its elements via "->" (arrow) Since it is a pointer, you access its elements via "->" (arrow)
rather than "." (dot). rather than "." (dot).
Required Plugin Functions Required Plugin Functions
@ -183,9 +183,9 @@ Magic Tool Plugin API Documentation
initialization was successful, or '0' if not (and Tux Paint will initialization was successful, or '0' if not (and Tux Paint will
not present any 'Magic' tools from the plugin). not present any 'Magic' tools from the plugin).
Note: Called once by Tux Paint, at startup. It is called first. It Note: Called once by Tux Paint, at startup. It is called after
is called after "api_version()", if Tux Paint believes your plugin "api_version()", if Tux Paint believes your plugin to be
to be compatible. compatible.
int get_tool_count(magic_api * api) int get_tool_count(magic_api * api)
@ -195,6 +195,29 @@ Magic Tool Plugin API Documentation
Note: Called once by Tux Paint, at startup. It is called after Note: Called once by Tux Paint, at startup. It is called after
your "init()", if it succeeded. your "init()", if it succeeded.
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.
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 should return a string containing the name of a magic tool.
@ -212,28 +235,26 @@ Magic Tool Plugin API Documentation
Use this to group tools together within sections of the 'Magic' Use this to group tools together within sections of the 'Magic'
selector. A number of groups are pre-defined within an enum found selector. A number of groups are pre-defined within an enum found
in "tp_magic_api.h": in "tp_magic_api.h":
* MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of * MAGIC_TYPE_DISTORTS — Tools that distort the shape of the
the image, like Blur, Emboss, and Ripples image, like Blur, Emboss, and Ripples
* MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect the * MAGIC_TYPE_COLOR_FILTERS — Tools that mostly affect the
colors of the image without distortion, like Darken, colors of the image without distortion, like Darken,
Negative, and Tint Negative, and Tint
* MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the * MAGIC_TYPE_PICTURE_WARPS — Tools that warp or move the entire
entire picture, like Shift, Flip, and Waves picture, like Shift, Flip, and Waves
* MAGIC_TYPE_PAINTING mdash; Tools that generally paint new * MAGIC_TYPE_PAINTING — Tools that generally paint new content
content at the cursor position, like Grass, Bricks, and Rails at the cursor position, like Grass, Bricks, and Rails
* MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in * MAGIC_TYPE_PATTERN_PAINTING — Tools that paint in multiple
multiple places at once, like Kaleidoscope and the Symmetry places at once, like Kaleidoscope and the Symmetry tools
tools * MAGIC_TYPE_PICTURE_DECORATIONS — Tools that apply decorations
* MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply to the entire picture, like Blinds and Checkboard
decorations to the entire picture, like Blinds and Checkboard * MAGIC_TYPE_ARTISTIC — Special-purpose artistic tools, like
* MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, Flower, the String tools, and the Rainbow-arc-drawing tools.
like Flower, the String tools, and the Rainbow-arc-drawing
tools.
Note: Called once for each Magic tool your plugin claims to Note: Called once for each Magic tool your plugin claims to
contain (by your "get_tool_count()"). contain (by your "get_tool_count()").
Note: Added to Tux Paint 0.9.27; Magic API version '0x00000005' Note: Added to Tux Paint 0.9.27; Magic API version 0x00000005.
SDL_Surface * get_icon(magic_api * api, int which) SDL_Surface * get_icon(magic_api * api, int which)
@ -274,29 +295,6 @@ Magic Tool Plugin API Documentation
Note: Called once for each Magic tool your plugin claims to Note: Called once for each Magic tool your plugin claims to
contain (by your "get_tool_count()"). 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) void shutdown(magic_api * api)
The plugin should do any cleanup here. If you allocated any memory The plugin should do any cleanup here. If you allocated any memory
@ -347,7 +345,7 @@ Magic Tool Plugin API Documentation
pieces of that copy could be drawn on the canvas when they draw pieces of that copy could be drawn on the canvas when they draw
with the Magic tool. with the Magic tool.
Note: Added to Tux Paint 0.9.21; Magic API version '0x00000002' Note: Added to Tux Paint 0.9.21; Magic API version 0x00000002.
void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g) 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 Tux Paint will call this function to inform the plugin of the RGB
@ -507,7 +505,7 @@ Tux Paint Functions and Data
char * tp_version char * tp_version
A string containing the version of Tux Paint that's running (e.g., A string containing the version of Tux Paint that's running (e.g.,
"0.9.18"). "0.9.29").
int canvas_w int canvas_w
int canvas_h int canvas_h
@ -652,7 +650,7 @@ Constant Defintions in "tp_magic_api.h"
your plugin is compatible. your plugin is compatible.
Note: This version number does not correspond to Tux Paint's own 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 release number (e.g., "0.9.29"). The API will not change every
time a new version of Tux Paint is released, which means plugins time a new version of Tux Paint is released, which means plugins
compiled for earlier versions of Tux Paint will often run under compiled for earlier versions of Tux Paint will often run under
newer versions. newer versions.
@ -699,9 +697,9 @@ Linux and other Unix-like Platforms
The first line sets up Makefile variable ("CFLAGS") that contains flags The first line sets up Makefile variable ("CFLAGS") that contains flags
for the compiler. "-Wall" asks for all compiler warnings to be shown. for the compiler. "-Wall" asks for all compiler warnings to be shown.
"-O2" asks for level 2 optimization. "($shell tp-magic-config --cflags)" "-O2" asks for level 2 optimization. "( tp-magic-config --cflags)" runs
runs "tp-magic-config" to retrieve additional compiler flags that "Magic" "tp-magic-config" to retrieve additional compiler flags that "Magic" tool
tool plugins require. (The "$(shell ...)" directive is similar to the ` plugins require. (The "$(shell ...)" directive is similar to the `
("grave") character in the BASH shell examples, above.) ("grave") character in the BASH shell examples, above.)
The next line defines a Makefile target, "my_plugin.so", and states that The next line defines a Makefile target, "my_plugin.so", and states that
@ -911,7 +909,7 @@ macOS
char * my_plugin_snd_filenames[NUM_TOOLS] = { char * my_plugin_snd_filenames[NUM_TOOLS] = {
"one.ogg", "another.ogg", "yet_another.ogg" }; "one.ogg", "another.ogg", "yet_another.ogg" };
Mix_Chunk * my_plugin_snds[NUM_TOOLS]; Mix_Chunk * my_plugin_snds[NUM_TOOLS]") ?>;
* Use a C "for"-loop to load or create the effect-specific data (such as * Use a C "for"-loop to load or create the effect-specific data (such as
loading sound effects during your "init()"). loading sound effects during your "init()").
@ -925,7 +923,7 @@ macOS
"/usr/share/tuxpaint/sounds/magic/one.ogg" */ "/usr/share/tuxpaint/sounds/magic/one.ogg" */
snprintf(fname, sizeof(fname), "%s/sounds/magic/%s", snprintf(fname, sizeof(fname), "%s/sounds/magic/%s",
api->data_prefix, my_plugin_snd_filenames[i]; api->data_prefix, my_plugin_snd_filenames[i]);
my_plugin_snds[i] = Mix_LoadWAV(fname); my_plugin_snds[i] = Mix_LoadWAV(fname);
} }
@ -967,13 +965,13 @@ macOS
* ampersand: "&". A symbol in C that allows you to refer to the memory * 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 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 i;". Later, "&i" refers to the memory where "i" is stored, not the
value of "i" itself; it is a 'pointer to "i"'.) (See also "star") value of "i" itself; it is a 'pointer to "i"'.) See also: "star"
* API: Application Programming Interface. TBD * API: Application Programming Interface. TBD
* argument: A value sent to a function. * argument: A value sent to a function.
* arrow: "->". A symbol in C that references an element within a pointer * arrow: "->". A symbol in C that references an element within a pointer
to a struct. to a struct.
* backquote: See "grave." * backquote: See "grave"
* backtick: See "grave." * backtick: See "grave"
* bit: "Binary digit." Bits are the basic storage unit in a computer's * bit: "Binary digit." Bits are the basic storage unit in a computer's
memory, disk, networking, etc. They represent either 0 or 1. (Compared 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 to a decimal digit, which can be anything between 0 and 9.) Just as a
@ -981,14 +979,14 @@ macOS
"5" is fifteen (15)), so can bits (e.g., "1" and "0", is two). In "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 decimal, we go from right to left: ones place, tens place, hundreds
place, thousands place, etc. In binary, it is: ones place, twos place, place, thousands place, etc. In binary, it is: ones place, twos place,
fours place, eights place, etc. (See also "byte.") fours place, eights place, etc. See also: "byte"
* blue: See "RGBA" * blue: See "RGBA"
* boolean 'or': A mathematical operation that results in a true value if * 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 either operand is true. ("1 | 0", "0 | 1" and "1 | 1" all result in
"1". "0 | 0" results in "0".) "1". "0 | 0" results in "0".)
* |: See "boolean 'or'" * |: See "boolean 'or'"
* .: See "dot" * .: See "dot"
* `: See "grave." * `: See "grave"
* *: See "star" * *: See "star"
* byte: A unit of memory made up of 8 bits. As a signed value, it can * 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 represent -128 through 127. As an unsigned value, it can represent 0
@ -1035,17 +1033,18 @@ macOS
* floating point: TBD * floating point: TBD
* format: An SDL_Surface element (a pointer to an SDL_PixelFormat * format: An SDL_Surface element (a pointer to an SDL_PixelFormat
structure) that contains information about a surface; for example, the structure) that contains information about a surface; for example, the
number of bits used to represent each pixel). (See also the number of bits used to represent each pixel). See also the
"SDL_PixelFormat(3) man page) "SDL_PixelFormat(3)" man page)
* free(): A C function that frees (deallocates) memory allocated by * free(): A C function that frees (deallocates) memory allocated by
other C functions (such as "strdup()"). other C functions (such as "strdup()").
* function: See "C function" * function: See "C function"
* gcc: The GNU C compiler, a portable Open Source compiler. (See also * gcc: The GNU C compiler, a portable Open Source compiler. See also the
the "gcc(1)" man page) "gcc(1)" man page)
* GIMP: An Open Source image manipulation and paint program.
* GNU C Compiler: See "gcc" * GNU C Compiler: See "gcc"
* grave: The "`" character; used by the BASH shell to use the output of * grave: The "`" character; used by the BASH shell to use the output of
a command as the command-line arguments to another. a command as the command-line arguments to another.
* green: See "RGBA" * vert: See "RGBA"
* ->: See "arrow" * ->: See "arrow"
* .h: See "C header file" * .h: See "C header file"
* header: See "C header file" * header: See "C header file"
@ -1069,7 +1068,7 @@ macOS
that exposes data and functions within the running copy of Tux Paint. that exposes data and functions within the running copy of Tux Paint.
* make: A utility that automatically determines which pieces of a larger * make: A utility that automatically determines which pieces of a larger
program need to be recompiled, and issues the commands to recompile program need to be recompiled, and issues the commands to recompile
them. (See also "Makefile") them. See also: "Makefile"
* Makefile: A text file used by the "make" utility; it describes the * Makefile: A text file used by the "make" utility; it describes the
relationships among files in your program, and the commands for relationships among files in your program, and the commands for
updating each file. (For example, to compile a human-readable updating each file. (For example, to compile a human-readable
@ -1083,25 +1082,25 @@ macOS
* Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg * Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg
Vorbis, etc.) and returns it as a "Mix_Chunk *". Vorbis, etc.) and returns it as a "Mix_Chunk *".
* namespace: TBD * namespace: TBD
* OGG: See "Ogg Vorbis" * .ogg: See "Ogg Vorbis"
* Ogg Vorbis: TBD (See also: "WAV") * Ogg Vorbis: See also: "WAV"
* Plugin: TBD * Plugin: TBD
* PNG: Portable Network Graphics. An extensible file format for the * .png: Portable Network Graphics. An extensible file format for the
lossless, portable, well-compressed storage of raster images. It's 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 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 stamps. It's an easy way to store 32bpp RGBA images (24bpp true color
with full 8bpp alpha transparency), excellent for use in graphics with full 8bpp alpha transparency), excellent for use in graphics
programs like Tux Paint. (See also the "png(5) man page) programs like Tux Paint. See also the "png(5)" man page)
* pointer: See "C pointer" * pointer: See "C pointer"
* prototype: See "C function prototype" * prototype: See "C function prototype"
* red: See "RGBA" * red: See "RGBA"
* release: The action of releasing a button on a mouse. * release: The action of releasing a button on a mouse.
* RGBA: "Red, Green, Blue, Alpha." TBD * RGBA: "Red, Green, Blue, Alpha." TBD
* RGB: See "RBGA" * RGB: See "RGBA"
* saturation: See "HSV" * saturation: See "HSV"
* SDL: See "Simple DirectMedia Layer" * SDL: See "Simple DirectMedia Layer"
* SDL_FreeSurface(): An libSDL function that frees (deallocates) memory * SDL_FreeSurface(): An libSDL function that frees (deallocates) memory
allocated for an SDL surface ("SDL_Surface *"). (See also the allocated for an SDL surface ("SDL_Surface *"). See also the
"SDL_FreeSurface(3)" man page) "SDL_FreeSurface(3)" man page)
* SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value * SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value
(e.g., one returned from the Tux Paint's Magic tool API helper (e.g., one returned from the Tux Paint's Magic tool API helper
@ -1109,13 +1108,13 @@ macOS
from, and pointers to three Uint8 variables, will place the Red, Green from, and pointers to three Uint8 variables, will place the Red, Green
and Blue (RGB) values of the pixel into the three Uint8 variables. and Blue (RGB) values of the pixel into the three Uint8 variables.
(Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g,
&b);".) (See also the "SDL_GetRGB(3)" man page) &b);".) See also the "SDL_GetRGB(3)" man page)
* SDL_MapRGB(): A libSDL function that, given the format of a surface * SDL_MapRGB(): A libSDL function that, given the format of a surface
and Uint8 values representing Red, Green and Blue values for a pixel, 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., returns a Uint32 pixel value that can be placed in the surface (e.g.,
using Tux Paint's Magic tool API helper function "putpixel()"). using Tux Paint's Magic tool API helper function "putpixel()").
(Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".)
(See also the "SDL_MapRGB(3)" man page) See also the "SDL_MapRGB(3)" man page)
* SDL_image: A library on top of libSDL that can load various kinds of * 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 *". 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 * SDL_mixer: A library on top of libSDL that can load various kinds of
@ -1124,9 +1123,9 @@ macOS
* SDL_Rect: A C structure defined by libSDL that represents a * SDL_Rect: A C structure defined by libSDL that represents a
rectangular area. It contains elements representing the coordinates of rectangular area. It contains elements representing the coordinates of
the top left corner of the rectange (x,y) and the dimensions of the 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) rectangle (w,h). See also the "SDL_Rect(3)" man page)
* SDL_Surface *: (A pointer to) a C structure defined by libSDL that * SDL_Surface *: (A pointer to) a C structure defined by libSDL that
contains a drawing surface. (See also the "SDL_Surface(3)" man page) contains a drawing surface. See also the "SDL_Surface(3)" man page)
* Shared Object: A piece of code that's compiled separately from the * Shared Object: A piece of code that's compiled separately from the
main application, and loaded dynamically, at runtime. main application, and loaded dynamically, at runtime.
* Simple DirectMedia Layer: A programming library that allows programs * Simple DirectMedia Layer: A programming library that allows programs
@ -1138,7 +1137,7 @@ macOS
string, making sure not to go beyond the string's buffer size (which 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];" must also be supplied). For example, assume a string "char str[20];"
has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill", has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill",
"32");" will store "Name: Bill, Age: 32" into 'str'. (See also the "32");" will store "Name: Bill, Age: 32" into 'str'. See also the
"snprintf(3)" man page) "snprintf(3)" man page)
* .so: See "Shared Object" * .so: See "Shared Object"
* sRBG: See "RGBA" * sRBG: See "RGBA"
@ -1149,19 +1148,18 @@ macOS
variable. (For example, later "*p = 50;" assigns the value of 50 to 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", 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 which is still a pointer to an integer. In essence, it changed the
integer that's being pointed to.) (See also "ampersand") integer that's being pointed to.) See also: "ampersand"
* strdup(): A C function that allocates enough memory to store a copy of * 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 a string, copies the string to it, and returns a "char *" pointer to
the new copy. (See also the "strdup(3)" man page) the new copy. See also the "strdup(3)" man page)
* struct: See "C structure" * 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. * tp_magic_api.h: A header file that defines Tux Paint's Magic tool API.
Plugins must '#include' it. Plugins must '#include' it.
* tp-magic-config: A command-line program that provides information * tp-magic-config: A command-line program that provides information
about the installed version of Tux Paint to plugin developers (such as about the installed version of Tux Paint to plugin developers (such as
what C compiler flags they should compile with, and where plugin what C compiler flags they should compile with, and where plugin
shared objects and data files should be installed). (See also the shared objects and data files should be installed). See also the
"tp-magic-config(3)" man page.) "tp-magic-config(3)" man page)
* Uint32: A 32-bit, unsigned integer (defined by libSDL). In other * Uint32: A 32-bit, unsigned integer (defined by libSDL). In other
words, four bytes that can represent 0 through 4294967295. (Typically words, four bytes that can represent 0 through 4294967295. (Typically
used to hold enough information to store three or four bytes used to hold enough information to store three or four bytes
@ -1185,6 +1183,6 @@ macOS
someone's age could be declared as an integer: "int a;". It can be someone's age could be declared as an integer: "int a;". It can be
examined later: "if (a >= 18) { /* they are an adult */ } else { /* examined later: "if (a >= 18) { /* they are an adult */ } else { /*
they are not an adult */ }". they are not an adult */ }".
* WAV: TBD (See also "Ogg Vorbis") * .wav: See also: "Ogg Vorbis"
* (w,h): See "Dimensions" * (w,h): See "Dimensions"
* (x,y): See "Coordinates" * (x,y): See "Coordinates"

1006
docs/fr_FR.UTF-8/html/MAGIC-API.html
View file

File diff suppressed because it is too large Load diff

156
docs/gl_ES.UTF-8/MAGIC-API.txt
View file

@ -151,7 +151,7 @@ Magic Tool Plugin API Documentation
Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than
just an "SDL_Rect") because you need to fill in its contents. just an "SDL_Rect") because you need to fill in its contents.
Because it is a pointer, you access its elements via "->" (arrow) Since it is a pointer, you access its elements via "->" (arrow)
rather than "." (dot). rather than "." (dot).
Required Plugin Functions Required Plugin Functions
@ -183,9 +183,9 @@ Magic Tool Plugin API Documentation
initialization was successful, or '0' if not (and Tux Paint will initialization was successful, or '0' if not (and Tux Paint will
not present any 'Magic' tools from the plugin). not present any 'Magic' tools from the plugin).
Note: Called once by Tux Paint, at startup. It is called first. It Note: Called once by Tux Paint, at startup. It is called after
is called after "api_version()", if Tux Paint believes your plugin "api_version()", if Tux Paint believes your plugin to be
to be compatible. compatible.
int get_tool_count(magic_api * api) int get_tool_count(magic_api * api)
@ -195,6 +195,29 @@ Magic Tool Plugin API Documentation
Note: Called once by Tux Paint, at startup. It is called after Note: Called once by Tux Paint, at startup. It is called after
your "init()", if it succeeded. your "init()", if it succeeded.
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.
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 should return a string containing the name of a magic tool.
@ -212,28 +235,26 @@ Magic Tool Plugin API Documentation
Use this to group tools together within sections of the 'Magic' Use this to group tools together within sections of the 'Magic'
selector. A number of groups are pre-defined within an enum found selector. A number of groups are pre-defined within an enum found
in "tp_magic_api.h": in "tp_magic_api.h":
* MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of * MAGIC_TYPE_DISTORTS — Tools that distort the shape of the
the image, like Blur, Emboss, and Ripples image, like Blur, Emboss, and Ripples
* MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect the * MAGIC_TYPE_COLOR_FILTERS — Tools that mostly affect the
colors of the image without distortion, like Darken, colors of the image without distortion, like Darken,
Negative, and Tint Negative, and Tint
* MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the * MAGIC_TYPE_PICTURE_WARPS — Tools that warp or move the entire
entire picture, like Shift, Flip, and Waves picture, like Shift, Flip, and Waves
* MAGIC_TYPE_PAINTING mdash; Tools that generally paint new * MAGIC_TYPE_PAINTING — Tools that generally paint new content
content at the cursor position, like Grass, Bricks, and Rails at the cursor position, like Grass, Bricks, and Rails
* MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in * MAGIC_TYPE_PATTERN_PAINTING — Tools that paint in multiple
multiple places at once, like Kaleidoscope and the Symmetry places at once, like Kaleidoscope and the Symmetry tools
tools * MAGIC_TYPE_PICTURE_DECORATIONS — Tools that apply decorations
* MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply to the entire picture, like Blinds and Checkboard
decorations to the entire picture, like Blinds and Checkboard * MAGIC_TYPE_ARTISTIC — Special-purpose artistic tools, like
* MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, Flower, the String tools, and the Rainbow-arc-drawing tools.
like Flower, the String tools, and the Rainbow-arc-drawing
tools.
Note: Called once for each Magic tool your plugin claims to Note: Called once for each Magic tool your plugin claims to
contain (by your "get_tool_count()"). contain (by your "get_tool_count()").
Note: Added to Tux Paint 0.9.27; Magic API version '0x00000005' Note: Added to Tux Paint 0.9.27; Magic API version 0x00000005.
SDL_Surface * get_icon(magic_api * api, int which) SDL_Surface * get_icon(magic_api * api, int which)
@ -274,29 +295,6 @@ Magic Tool Plugin API Documentation
Note: Called once for each Magic tool your plugin claims to Note: Called once for each Magic tool your plugin claims to
contain (by your "get_tool_count()"). 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) void shutdown(magic_api * api)
The plugin should do any cleanup here. If you allocated any memory The plugin should do any cleanup here. If you allocated any memory
@ -347,7 +345,7 @@ Magic Tool Plugin API Documentation
pieces of that copy could be drawn on the canvas when they draw pieces of that copy could be drawn on the canvas when they draw
with the Magic tool. with the Magic tool.
Note: Added to Tux Paint 0.9.21; Magic API version '0x00000002' Note: Added to Tux Paint 0.9.21; Magic API version 0x00000002.
void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g) 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 Tux Paint will call this function to inform the plugin of the RGB
@ -507,7 +505,7 @@ Tux Paint Functions and Data
char * tp_version char * tp_version
A string containing the version of Tux Paint that's running (e.g., A string containing the version of Tux Paint that's running (e.g.,
"0.9.18"). "0.9.29").
int canvas_w int canvas_w
int canvas_h int canvas_h
@ -652,7 +650,7 @@ Constant Defintions in "tp_magic_api.h"
your plugin is compatible. your plugin is compatible.
Note: This version number does not correspond to Tux Paint's own 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 release number (e.g., "0.9.29"). The API will not change every
time a new version of Tux Paint is released, which means plugins time a new version of Tux Paint is released, which means plugins
compiled for earlier versions of Tux Paint will often run under compiled for earlier versions of Tux Paint will often run under
newer versions. newer versions.
@ -699,9 +697,9 @@ Linux and other Unix-like Platforms
The first line sets up Makefile variable ("CFLAGS") that contains flags The first line sets up Makefile variable ("CFLAGS") that contains flags
for the compiler. "-Wall" asks for all compiler warnings to be shown. for the compiler. "-Wall" asks for all compiler warnings to be shown.
"-O2" asks for level 2 optimization. "($shell tp-magic-config --cflags)" "-O2" asks for level 2 optimization. "( tp-magic-config --cflags)" runs
runs "tp-magic-config" to retrieve additional compiler flags that "Magic" "tp-magic-config" to retrieve additional compiler flags that "Magic" tool
tool plugins require. (The "$(shell ...)" directive is similar to the ` plugins require. (The "$(shell ...)" directive is similar to the `
("grave") character in the BASH shell examples, above.) ("grave") character in the BASH shell examples, above.)
The next line defines a Makefile target, "my_plugin.so", and states that The next line defines a Makefile target, "my_plugin.so", and states that
@ -911,7 +909,7 @@ macOS
char * my_plugin_snd_filenames[NUM_TOOLS] = { char * my_plugin_snd_filenames[NUM_TOOLS] = {
"one.ogg", "another.ogg", "yet_another.ogg" }; "one.ogg", "another.ogg", "yet_another.ogg" };
Mix_Chunk * my_plugin_snds[NUM_TOOLS]; Mix_Chunk * my_plugin_snds[NUM_TOOLS]") ?>;
* Use a C "for"-loop to load or create the effect-specific data (such as * Use a C "for"-loop to load or create the effect-specific data (such as
loading sound effects during your "init()"). loading sound effects during your "init()").
@ -925,7 +923,7 @@ macOS
"/usr/share/tuxpaint/sounds/magic/one.ogg" */ "/usr/share/tuxpaint/sounds/magic/one.ogg" */
snprintf(fname, sizeof(fname), "%s/sounds/magic/%s", snprintf(fname, sizeof(fname), "%s/sounds/magic/%s",
api->data_prefix, my_plugin_snd_filenames[i]; api->data_prefix, my_plugin_snd_filenames[i]);
my_plugin_snds[i] = Mix_LoadWAV(fname); my_plugin_snds[i] = Mix_LoadWAV(fname);
} }
@ -967,13 +965,13 @@ macOS
* ampersand: "&". A symbol in C that allows you to refer to the memory * 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 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 i;". Later, "&i" refers to the memory where "i" is stored, not the
value of "i" itself; it is a 'pointer to "i"'.) (See also "star") value of "i" itself; it is a 'pointer to "i"'.) See also: "star"
* API: Application Programming Interface. TBD * API: Application Programming Interface. TBD
* argument: A value sent to a function. * argument: A value sent to a function.
* arrow: "->". A symbol in C that references an element within a pointer * arrow: "->". A symbol in C that references an element within a pointer
to a struct. to a struct.
* backquote: See "grave." * backquote: See "grave"
* backtick: See "grave." * backtick: See "grave"
* bit: "Binary digit." Bits are the basic storage unit in a computer's * bit: "Binary digit." Bits are the basic storage unit in a computer's
memory, disk, networking, etc. They represent either 0 or 1. (Compared 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 to a decimal digit, which can be anything between 0 and 9.) Just as a
@ -981,14 +979,14 @@ macOS
"5" is fifteen (15)), so can bits (e.g., "1" and "0", is two). In "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 decimal, we go from right to left: ones place, tens place, hundreds
place, thousands place, etc. In binary, it is: ones place, twos place, place, thousands place, etc. In binary, it is: ones place, twos place,
fours place, eights place, etc. (See also "byte.") fours place, eights place, etc. See also: "byte"
* blue: See "RGBA" * blue: See "RGBA"
* boolean 'or': A mathematical operation that results in a true value if * 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 either operand is true. ("1 | 0", "0 | 1" and "1 | 1" all result in
"1". "0 | 0" results in "0".) "1". "0 | 0" results in "0".)
* |: See "boolean 'or'" * |: See "boolean 'or'"
* .: See "dot" * .: See "dot"
* `: See "grave." * `: See "grave"
* *: See "star" * *: See "star"
* byte: A unit of memory made up of 8 bits. As a signed value, it can * 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 represent -128 through 127. As an unsigned value, it can represent 0
@ -1035,17 +1033,18 @@ macOS
* floating point: TBD * floating point: TBD
* format: An SDL_Surface element (a pointer to an SDL_PixelFormat * format: An SDL_Surface element (a pointer to an SDL_PixelFormat
structure) that contains information about a surface; for example, the structure) that contains information about a surface; for example, the
number of bits used to represent each pixel). (See also the number of bits used to represent each pixel). See also the
"SDL_PixelFormat(3) man page) "SDL_PixelFormat(3)" man page)
* free(): A C function that frees (deallocates) memory allocated by * free(): A C function that frees (deallocates) memory allocated by
other C functions (such as "strdup()"). other C functions (such as "strdup()").
* function: See "C function" * function: See "C function"
* gcc: The GNU C compiler, a portable Open Source compiler. (See also * gcc: The GNU C compiler, a portable Open Source compiler. See also the
the "gcc(1)" man page) "gcc(1)" man page)
* GIMP: An Open Source image manipulation and paint program.
* GNU C Compiler: See "gcc" * GNU C Compiler: See "gcc"
* grave: The "`" character; used by the BASH shell to use the output of * grave: The "`" character; used by the BASH shell to use the output of
a command as the command-line arguments to another. a command as the command-line arguments to another.
* green: See "RGBA" * verde: See "RGBA"
* ->: See "arrow" * ->: See "arrow"
* .h: See "C header file" * .h: See "C header file"
* header: See "C header file" * header: See "C header file"
@ -1069,7 +1068,7 @@ macOS
that exposes data and functions within the running copy of Tux Paint. that exposes data and functions within the running copy of Tux Paint.
* make: A utility that automatically determines which pieces of a larger * make: A utility that automatically determines which pieces of a larger
program need to be recompiled, and issues the commands to recompile program need to be recompiled, and issues the commands to recompile
them. (See also "Makefile") them. See also: "Makefile"
* Makefile: A text file used by the "make" utility; it describes the * Makefile: A text file used by the "make" utility; it describes the
relationships among files in your program, and the commands for relationships among files in your program, and the commands for
updating each file. (For example, to compile a human-readable updating each file. (For example, to compile a human-readable
@ -1083,25 +1082,25 @@ macOS
* Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg * Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg
Vorbis, etc.) and returns it as a "Mix_Chunk *". Vorbis, etc.) and returns it as a "Mix_Chunk *".
* namespace: TBD * namespace: TBD
* OGG: See "Ogg Vorbis" * .ogg: See "Ogg Vorbis"
* Ogg Vorbis: TBD (See also: "WAV") * Ogg Vorbis: See also: "WAV"
* Plugin: TBD * Plugin: TBD
* PNG: Portable Network Graphics. An extensible file format for the * .png: Portable Network Graphics. An extensible file format for the
lossless, portable, well-compressed storage of raster images. It's 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 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 stamps. It's an easy way to store 32bpp RGBA images (24bpp true color
with full 8bpp alpha transparency), excellent for use in graphics with full 8bpp alpha transparency), excellent for use in graphics
programs like Tux Paint. (See also the "png(5) man page) programs like Tux Paint. See also the "png(5)" man page)
* pointer: See "C pointer" * pointer: See "C pointer"
* prototype: See "C function prototype" * prototype: See "C function prototype"
* red: See "RGBA" * red: See "RGBA"
* release: The action of releasing a button on a mouse. * release: The action of releasing a button on a mouse.
* RGBA: "Red, Green, Blue, Alpha." TBD * RGBA: "Red, Green, Blue, Alpha." TBD
* RGB: See "RBGA" * RGB: See "RGBA"
* saturation: See "HSV" * saturation: See "HSV"
* SDL: See "Simple DirectMedia Layer" * SDL: See "Simple DirectMedia Layer"
* SDL_FreeSurface(): An libSDL function that frees (deallocates) memory * SDL_FreeSurface(): An libSDL function that frees (deallocates) memory
allocated for an SDL surface ("SDL_Surface *"). (See also the allocated for an SDL surface ("SDL_Surface *"). See also the
"SDL_FreeSurface(3)" man page) "SDL_FreeSurface(3)" man page)
* SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value * SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value
(e.g., one returned from the Tux Paint's Magic tool API helper (e.g., one returned from the Tux Paint's Magic tool API helper
@ -1109,13 +1108,13 @@ macOS
from, and pointers to three Uint8 variables, will place the Red, Green from, and pointers to three Uint8 variables, will place the Red, Green
and Blue (RGB) values of the pixel into the three Uint8 variables. and Blue (RGB) values of the pixel into the three Uint8 variables.
(Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g,
&b);".) (See also the "SDL_GetRGB(3)" man page) &b);".) See also the "SDL_GetRGB(3)" man page)
* SDL_MapRGB(): A libSDL function that, given the format of a surface * SDL_MapRGB(): A libSDL function that, given the format of a surface
and Uint8 values representing Red, Green and Blue values for a pixel, 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., returns a Uint32 pixel value that can be placed in the surface (e.g.,
using Tux Paint's Magic tool API helper function "putpixel()"). using Tux Paint's Magic tool API helper function "putpixel()").
(Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".)
(See also the "SDL_MapRGB(3)" man page) See also the "SDL_MapRGB(3)" man page)
* SDL_image: A library on top of libSDL that can load various kinds of * 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 *". 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 * SDL_mixer: A library on top of libSDL that can load various kinds of
@ -1124,9 +1123,9 @@ macOS
* SDL_Rect: A C structure defined by libSDL that represents a * SDL_Rect: A C structure defined by libSDL that represents a
rectangular area. It contains elements representing the coordinates of rectangular area. It contains elements representing the coordinates of
the top left corner of the rectange (x,y) and the dimensions of the 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) rectangle (w,h). See also the "SDL_Rect(3)" man page)
* SDL_Surface *: (A pointer to) a C structure defined by libSDL that * SDL_Surface *: (A pointer to) a C structure defined by libSDL that
contains a drawing surface. (See also the "SDL_Surface(3)" man page) contains a drawing surface. See also the "SDL_Surface(3)" man page)
* Shared Object: A piece of code that's compiled separately from the * Shared Object: A piece of code that's compiled separately from the
main application, and loaded dynamically, at runtime. main application, and loaded dynamically, at runtime.
* Simple DirectMedia Layer: A programming library that allows programs * Simple DirectMedia Layer: A programming library that allows programs
@ -1138,7 +1137,7 @@ macOS
string, making sure not to go beyond the string's buffer size (which 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];" must also be supplied). For example, assume a string "char str[20];"
has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill", has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill",
"32");" will store "Name: Bill, Age: 32" into 'str'. (See also the "32");" will store "Name: Bill, Age: 32" into 'str'. See also the
"snprintf(3)" man page) "snprintf(3)" man page)
* .so: See "Shared Object" * .so: See "Shared Object"
* sRBG: See "RGBA" * sRBG: See "RGBA"
@ -1149,19 +1148,18 @@ macOS
variable. (For example, later "*p = 50;" assigns the value of 50 to 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", 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 which is still a pointer to an integer. In essence, it changed the
integer that's being pointed to.) (See also "ampersand") integer that's being pointed to.) See also: "ampersand"
* strdup(): A C function that allocates enough memory to store a copy of * 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 a string, copies the string to it, and returns a "char *" pointer to
the new copy. (See also the "strdup(3)" man page) the new copy. See also the "strdup(3)" man page)
* struct: See "C structure" * 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. * tp_magic_api.h: A header file that defines Tux Paint's Magic tool API.
Plugins must '#include' it. Plugins must '#include' it.
* tp-magic-config: A command-line program that provides information * tp-magic-config: A command-line program that provides information
about the installed version of Tux Paint to plugin developers (such as about the installed version of Tux Paint to plugin developers (such as
what C compiler flags they should compile with, and where plugin what C compiler flags they should compile with, and where plugin
shared objects and data files should be installed). (See also the shared objects and data files should be installed). See also the
"tp-magic-config(3)" man page.) "tp-magic-config(3)" man page)
* Uint32: A 32-bit, unsigned integer (defined by libSDL). In other * Uint32: A 32-bit, unsigned integer (defined by libSDL). In other
words, four bytes that can represent 0 through 4294967295. (Typically words, four bytes that can represent 0 through 4294967295. (Typically
used to hold enough information to store three or four bytes used to hold enough information to store three or four bytes
@ -1185,6 +1183,6 @@ macOS
someone's age could be declared as an integer: "int a;". It can be someone's age could be declared as an integer: "int a;". It can be
examined later: "if (a >= 18) { /* they are an adult */ } else { /* examined later: "if (a >= 18) { /* they are an adult */ } else { /*
they are not an adult */ }". they are not an adult */ }".
* WAV: TBD (See also "Ogg Vorbis") * .wav: See also: "Ogg Vorbis"
* (w,h): See "Dimensions" * (w,h): See "Dimensions"
* (x,y): See "Coordinates" * (x,y): See "Coordinates"

1006
docs/gl_ES.UTF-8/html/MAGIC-API.html
View file

File diff suppressed because it is too large Load diff

156
docs/ja_JP.UTF-8/MAGIC-API.txt
View file

@ -151,7 +151,7 @@ Magic Tool Plugin API Documentation
Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than
just an "SDL_Rect") because you need to fill in its contents. just an "SDL_Rect") because you need to fill in its contents.
Because it is a pointer, you access its elements via "->" (arrow) Since it is a pointer, you access its elements via "->" (arrow)
rather than "." (dot). rather than "." (dot).
Required Plugin Functions Required Plugin Functions
@ -183,9 +183,9 @@ Magic Tool Plugin API Documentation
initialization was successful, or '0' if not (and Tux Paint will initialization was successful, or '0' if not (and Tux Paint will
not present any 'Magic' tools from the plugin). not present any 'Magic' tools from the plugin).
Note: Called once by Tux Paint, at startup. It is called first. It Note: Called once by Tux Paint, at startup. It is called after
is called after "api_version()", if Tux Paint believes your plugin "api_version()", if Tux Paint believes your plugin to be
to be compatible. compatible.
int get_tool_count(magic_api * api) int get_tool_count(magic_api * api)
@ -195,6 +195,29 @@ Magic Tool Plugin API Documentation
Note: Called once by Tux Paint, at startup. It is called after Note: Called once by Tux Paint, at startup. It is called after
your "init()", if it succeeded. your "init()", if it succeeded.
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.
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 should return a string containing the name of a magic tool.
@ -212,28 +235,26 @@ Magic Tool Plugin API Documentation
Use this to group tools together within sections of the 'Magic' Use this to group tools together within sections of the 'Magic'
selector. A number of groups are pre-defined within an enum found selector. A number of groups are pre-defined within an enum found
in "tp_magic_api.h": in "tp_magic_api.h":
* MAGIC_TYPE_DISTORTS mdash; Tools that distort the shape of * MAGIC_TYPE_DISTORTS — Tools that distort the shape of the
the image, like Blur, Emboss, and Ripples image, like Blur, Emboss, and Ripples
* MAGIC_TYPE_COLOR_FILTERS mdash; Tools that mostly affect the * MAGIC_TYPE_COLOR_FILTERS — Tools that mostly affect the
colors of the image without distortion, like Darken, colors of the image without distortion, like Darken,
Negative, and Tint Negative, and Tint
* MAGIC_TYPE_PICTURE_WARPS mdash; Tools that warp or move the * MAGIC_TYPE_PICTURE_WARPS — Tools that warp or move the entire
entire picture, like Shift, Flip, and Waves picture, like Shift, Flip, and Waves
* MAGIC_TYPE_PAINTING mdash; Tools that generally paint new * MAGIC_TYPE_PAINTING — Tools that generally paint new content
content at the cursor position, like Grass, Bricks, and Rails at the cursor position, like Grass, Bricks, and Rails
* MAGIC_TYPE_PATTERN_PAINTING mdash; Tools that paint in * MAGIC_TYPE_PATTERN_PAINTING — Tools that paint in multiple
multiple places at once, like Kaleidoscope and the Symmetry places at once, like Kaleidoscope and the Symmetry tools
tools * MAGIC_TYPE_PICTURE_DECORATIONS — Tools that apply decorations
* MAGIC_TYPE_PICTURE_DECORATIONS mdash; Tools that apply to the entire picture, like Blinds and Checkboard
decorations to the entire picture, like Blinds and Checkboard * MAGIC_TYPE_ARTISTIC — Special-purpose artistic tools, like
* MAGIC_TYPE_ARTISTIC mdash; Special-purpose artistic tools, Flower, the String tools, and the Rainbow-arc-drawing tools.
like Flower, the String tools, and the Rainbow-arc-drawing
tools.
Note: Called once for each Magic tool your plugin claims to Note: Called once for each Magic tool your plugin claims to
contain (by your "get_tool_count()"). contain (by your "get_tool_count()").
Note: Added to Tux Paint 0.9.27; Magic API version '0x00000005' Note: Added to Tux Paint 0.9.27; Magic API version 0x00000005.
SDL_Surface * get_icon(magic_api * api, int which) SDL_Surface * get_icon(magic_api * api, int which)
@ -274,29 +295,6 @@ Magic Tool Plugin API Documentation
Note: Called once for each Magic tool your plugin claims to Note: Called once for each Magic tool your plugin claims to
contain (by your "get_tool_count()"). 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) void shutdown(magic_api * api)
The plugin should do any cleanup here. If you allocated any memory The plugin should do any cleanup here. If you allocated any memory
@ -347,7 +345,7 @@ Magic Tool Plugin API Documentation
pieces of that copy could be drawn on the canvas when they draw pieces of that copy could be drawn on the canvas when they draw
with the Magic tool. with the Magic tool.
Note: Added to Tux Paint 0.9.21; Magic API version '0x00000002' Note: Added to Tux Paint 0.9.21; Magic API version 0x00000002.
void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g) 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 Tux Paint will call this function to inform the plugin of the RGB
@ -507,7 +505,7 @@ Tux Paint Functions and Data
char * tp_version char * tp_version
A string containing the version of Tux Paint that's running (e.g., A string containing the version of Tux Paint that's running (e.g.,
"0.9.18"). "0.9.29").
int canvas_w int canvas_w
int canvas_h int canvas_h
@ -652,7 +650,7 @@ Constant Defintions in "tp_magic_api.h"
your plugin is compatible. your plugin is compatible.
Note: This version number does not correspond to Tux Paint's own 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 release number (e.g., "0.9.29"). The API will not change every
time a new version of Tux Paint is released, which means plugins time a new version of Tux Paint is released, which means plugins
compiled for earlier versions of Tux Paint will often run under compiled for earlier versions of Tux Paint will often run under
newer versions. newer versions.
@ -699,9 +697,9 @@ Linux and other Unix-like Platforms
The first line sets up Makefile variable ("CFLAGS") that contains flags The first line sets up Makefile variable ("CFLAGS") that contains flags
for the compiler. "-Wall" asks for all compiler warnings to be shown. for the compiler. "-Wall" asks for all compiler warnings to be shown.
"-O2" asks for level 2 optimization. "($shell tp-magic-config --cflags)" "-O2" asks for level 2 optimization. "( tp-magic-config --cflags)" runs
runs "tp-magic-config" to retrieve additional compiler flags that "Magic" "tp-magic-config" to retrieve additional compiler flags that "Magic" tool
tool plugins require. (The "$(shell ...)" directive is similar to the ` plugins require. (The "$(shell ...)" directive is similar to the `
("grave") character in the BASH shell examples, above.) ("grave") character in the BASH shell examples, above.)
The next line defines a Makefile target, "my_plugin.so", and states that The next line defines a Makefile target, "my_plugin.so", and states that
@ -911,7 +909,7 @@ macOS
char * my_plugin_snd_filenames[NUM_TOOLS] = { char * my_plugin_snd_filenames[NUM_TOOLS] = {
"one.ogg", "another.ogg", "yet_another.ogg" }; "one.ogg", "another.ogg", "yet_another.ogg" };
Mix_Chunk * my_plugin_snds[NUM_TOOLS]; Mix_Chunk * my_plugin_snds[NUM_TOOLS]") ?>;
* Use a C "for"-loop to load or create the effect-specific data (such as * Use a C "for"-loop to load or create the effect-specific data (such as
loading sound effects during your "init()"). loading sound effects during your "init()").
@ -925,7 +923,7 @@ macOS
"/usr/share/tuxpaint/sounds/magic/one.ogg" */ "/usr/share/tuxpaint/sounds/magic/one.ogg" */
snprintf(fname, sizeof(fname), "%s/sounds/magic/%s", snprintf(fname, sizeof(fname), "%s/sounds/magic/%s",
api->data_prefix, my_plugin_snd_filenames[i]; api->data_prefix, my_plugin_snd_filenames[i]);
my_plugin_snds[i] = Mix_LoadWAV(fname); my_plugin_snds[i] = Mix_LoadWAV(fname);
} }
@ -967,13 +965,13 @@ macOS
* ampersand: "&". A symbol in C that allows you to refer to the memory * 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 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 i;". Later, "&i" refers to the memory where "i" is stored, not the
value of "i" itself; it is a 'pointer to "i"'.) (See also "star") value of "i" itself; it is a 'pointer to "i"'.) See also: "star"
* API: Application Programming Interface. TBD * API: Application Programming Interface. TBD
* argument: A value sent to a function. * argument: A value sent to a function.
* arrow: "->". A symbol in C that references an element within a pointer * arrow: "->". A symbol in C that references an element within a pointer
to a struct. to a struct.
* backquote: See "grave." * backquote: See "grave"
* backtick: See "grave." * backtick: See "grave"
* bit: "Binary digit." Bits are the basic storage unit in a computer's * bit: "Binary digit." Bits are the basic storage unit in a computer's
memory, disk, networking, etc. They represent either 0 or 1. (Compared 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 to a decimal digit, which can be anything between 0 and 9.) Just as a
@ -981,14 +979,14 @@ macOS
"5" is fifteen (15)), so can bits (e.g., "1" and "0", is two). In "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 decimal, we go from right to left: ones place, tens place, hundreds
place, thousands place, etc. In binary, it is: ones place, twos place, place, thousands place, etc. In binary, it is: ones place, twos place,
fours place, eights place, etc. (See also "byte.") fours place, eights place, etc. See also: "byte"
* blue: See "RGBA" * blue: See "RGBA"
* boolean 'or': A mathematical operation that results in a true value if * 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 either operand is true. ("1 | 0", "0 | 1" and "1 | 1" all result in
"1". "0 | 0" results in "0".) "1". "0 | 0" results in "0".)
* |: See "boolean 'or'" * |: See "boolean 'or'"
* .: See "dot" * .: See "dot"
* `: See "grave." * `: See "grave"
* *: See "star" * *: See "star"
* byte: A unit of memory made up of 8 bits. As a signed value, it can * 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 represent -128 through 127. As an unsigned value, it can represent 0
@ -1035,17 +1033,18 @@ macOS
* floating point: TBD * floating point: TBD
* format: An SDL_Surface element (a pointer to an SDL_PixelFormat * format: An SDL_Surface element (a pointer to an SDL_PixelFormat
structure) that contains information about a surface; for example, the structure) that contains information about a surface; for example, the
number of bits used to represent each pixel). (See also the number of bits used to represent each pixel). See also the
"SDL_PixelFormat(3) man page) "SDL_PixelFormat(3)" man page)
* free(): A C function that frees (deallocates) memory allocated by * free(): A C function that frees (deallocates) memory allocated by
other C functions (such as "strdup()"). other C functions (such as "strdup()").
* function: See "C function" * function: See "C function"
* gcc: The GNU C compiler, a portable Open Source compiler. (See also * gcc: The GNU C compiler, a portable Open Source compiler. See also the
the "gcc(1)" man page) "gcc(1)" man page)
* GIMP: An Open Source image manipulation and paint program.
* GNU C Compiler: See "gcc" * GNU C Compiler: See "gcc"
* grave: The "`" character; used by the BASH shell to use the output of * grave: The "`" character; used by the BASH shell to use the output of
a command as the command-line arguments to another. a command as the command-line arguments to another.
* green: See "RGBA" * グリーン: See "RGBA"
* ->: See "arrow" * ->: See "arrow"
* .h: See "C header file" * .h: See "C header file"
* header: See "C header file" * header: See "C header file"
@ -1069,7 +1068,7 @@ macOS
that exposes data and functions within the running copy of Tux Paint. that exposes data and functions within the running copy of Tux Paint.
* make: A utility that automatically determines which pieces of a larger * make: A utility that automatically determines which pieces of a larger
program need to be recompiled, and issues the commands to recompile program need to be recompiled, and issues the commands to recompile
them. (See also "Makefile") them. See also: "Makefile"
* Makefile: A text file used by the "make" utility; it describes the * Makefile: A text file used by the "make" utility; it describes the
relationships among files in your program, and the commands for relationships among files in your program, and the commands for
updating each file. (For example, to compile a human-readable updating each file. (For example, to compile a human-readable
@ -1083,25 +1082,25 @@ macOS
* Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg * Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg
Vorbis, etc.) and returns it as a "Mix_Chunk *". Vorbis, etc.) and returns it as a "Mix_Chunk *".
* namespace: TBD * namespace: TBD
* OGG: See "Ogg Vorbis" * .ogg: See "Ogg Vorbis"
* Ogg Vorbis: TBD (See also: "WAV") * Ogg Vorbis: See also: "WAV"
* Plugin: TBD * Plugin: TBD
* PNG: Portable Network Graphics. An extensible file format for the * .png: Portable Network Graphics. An extensible file format for the
lossless, portable, well-compressed storage of raster images. It's 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 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 stamps. It's an easy way to store 32bpp RGBA images (24bpp true color
with full 8bpp alpha transparency), excellent for use in graphics with full 8bpp alpha transparency), excellent for use in graphics
programs like Tux Paint. (See also the "png(5) man page) programs like Tux Paint. See also the "png(5)" man page)
* pointer: See "C pointer" * pointer: See "C pointer"
* prototype: See "C function prototype" * prototype: See "C function prototype"
* red: See "RGBA" * red: See "RGBA"
* release: The action of releasing a button on a mouse. * release: The action of releasing a button on a mouse.
* RGBA: "Red, Green, Blue, Alpha." TBD * RGBA: "Red, Green, Blue, Alpha." TBD
* RGB: See "RBGA" * RGB: See "RGBA"
* saturation: See "HSV" * saturation: See "HSV"
* SDL: See "Simple DirectMedia Layer" * SDL: See "Simple DirectMedia Layer"
* SDL_FreeSurface(): An libSDL function that frees (deallocates) memory * SDL_FreeSurface(): An libSDL function that frees (deallocates) memory
allocated for an SDL surface ("SDL_Surface *"). (See also the allocated for an SDL surface ("SDL_Surface *"). See also the
"SDL_FreeSurface(3)" man page) "SDL_FreeSurface(3)" man page)
* SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value * SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value
(e.g., one returned from the Tux Paint's Magic tool API helper (e.g., one returned from the Tux Paint's Magic tool API helper
@ -1109,13 +1108,13 @@ macOS
from, and pointers to three Uint8 variables, will place the Red, Green from, and pointers to three Uint8 variables, will place the Red, Green
and Blue (RGB) values of the pixel into the three Uint8 variables. and Blue (RGB) values of the pixel into the three Uint8 variables.
(Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g,
&b);".) (See also the "SDL_GetRGB(3)" man page) &b);".) See also the "SDL_GetRGB(3)" man page)
* SDL_MapRGB(): A libSDL function that, given the format of a surface * SDL_MapRGB(): A libSDL function that, given the format of a surface
and Uint8 values representing Red, Green and Blue values for a pixel, 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., returns a Uint32 pixel value that can be placed in the surface (e.g.,
using Tux Paint's Magic tool API helper function "putpixel()"). using Tux Paint's Magic tool API helper function "putpixel()").
(Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".)
(See also the "SDL_MapRGB(3)" man page) See also the "SDL_MapRGB(3)" man page)
* SDL_image: A library on top of libSDL that can load various kinds of * 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 *". 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 * SDL_mixer: A library on top of libSDL that can load various kinds of
@ -1124,9 +1123,9 @@ macOS
* SDL_Rect: A C structure defined by libSDL that represents a * SDL_Rect: A C structure defined by libSDL that represents a
rectangular area. It contains elements representing the coordinates of rectangular area. It contains elements representing the coordinates of
the top left corner of the rectange (x,y) and the dimensions of the 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) rectangle (w,h). See also the "SDL_Rect(3)" man page)
* SDL_Surface *: (A pointer to) a C structure defined by libSDL that * SDL_Surface *: (A pointer to) a C structure defined by libSDL that
contains a drawing surface. (See also the "SDL_Surface(3)" man page) contains a drawing surface. See also the "SDL_Surface(3)" man page)
* Shared Object: A piece of code that's compiled separately from the * Shared Object: A piece of code that's compiled separately from the
main application, and loaded dynamically, at runtime. main application, and loaded dynamically, at runtime.
* Simple DirectMedia Layer: A programming library that allows programs * Simple DirectMedia Layer: A programming library that allows programs
@ -1138,7 +1137,7 @@ macOS
string, making sure not to go beyond the string's buffer size (which 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];" must also be supplied). For example, assume a string "char str[20];"
has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill", has been declared; "snprintf(str, 20, "Name: %s, Age: %d", "Bill",
"32");" will store "Name: Bill, Age: 32" into 'str'. (See also the "32");" will store "Name: Bill, Age: 32" into 'str'. See also the
"snprintf(3)" man page) "snprintf(3)" man page)
* .so: See "Shared Object" * .so: See "Shared Object"
* sRBG: See "RGBA" * sRBG: See "RGBA"
@ -1149,19 +1148,18 @@ macOS
variable. (For example, later "*p = 50;" assigns the value of 50 to 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", 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 which is still a pointer to an integer. In essence, it changed the
integer that's being pointed to.) (See also "ampersand") integer that's being pointed to.) See also: "ampersand"
* strdup(): A C function that allocates enough memory to store a copy of * 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 a string, copies the string to it, and returns a "char *" pointer to
the new copy. (See also the "strdup(3)" man page) the new copy. See also the "strdup(3)" man page)
* struct: See "C structure" * 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. * tp_magic_api.h: A header file that defines Tux Paint's Magic tool API.
Plugins must '#include' it. Plugins must '#include' it.
* tp-magic-config: A command-line program that provides information * tp-magic-config: A command-line program that provides information
about the installed version of Tux Paint to plugin developers (such as about the installed version of Tux Paint to plugin developers (such as
what C compiler flags they should compile with, and where plugin what C compiler flags they should compile with, and where plugin
shared objects and data files should be installed). (See also the shared objects and data files should be installed). See also the
"tp-magic-config(3)" man page.) "tp-magic-config(3)" man page)
* Uint32: A 32-bit, unsigned integer (defined by libSDL). In other * Uint32: A 32-bit, unsigned integer (defined by libSDL). In other
words, four bytes that can represent 0 through 4294967295. (Typically words, four bytes that can represent 0 through 4294967295. (Typically
used to hold enough information to store three or four bytes used to hold enough information to store three or four bytes
@ -1185,6 +1183,6 @@ macOS
someone's age could be declared as an integer: "int a;". It can be someone's age could be declared as an integer: "int a;". It can be
examined later: "if (a >= 18) { /* they are an adult */ } else { /* examined later: "if (a >= 18) { /* they are an adult */ } else { /*
they are not an adult */ }". they are not an adult */ }".
* WAV: TBD (See also "Ogg Vorbis") * .wav: See also: "Ogg Vorbis"
* (w,h): See "Dimensions" * (w,h): See "Dimensions"
* (x,y): See "Coordinates" * (x,y): See "Coordinates"

1006
docs/ja_JP.UTF-8/html/MAGIC-API.html
View file

File diff suppressed because it is too large Load diff