Tux Paint
                                 útgáfa 0.9.34

                  ### Magic Tool Plugin API Documentation ###

   Höfundarréttur © 2007-2024 eftir various contributors; sjá AUTHORS-skrá.
                             https://tuxpaint.org/

                              17. september 2024

+--------------------------------------------------+
|                   Efnisyfirlit                   |
|--------------------------------------------------|
|   * Forkröfur                                    |
|   * Interfaces                                   |
|       + 'Magic' tool plugin functions            |
|           o Common arguments to plugin functions |
|           o Required Plugin Functions            |
|               # Plugin "housekeeping" functions  |
|               # Plugin event functions           |
|       + Tux Paint Functions and Data             |
|           o Pixel Manipulations                  |
|           o Helper Functions                     |
|           o Til upplýsingar                      |
|           o Sound Functions                      |
|           o Tux Paint System Calls               |
|           o Color Conversions                    |
|       + Helper Macros in "tp_magic_api.h"        |
|       + Constant Definitions in "tp_magic_api.h" |
|   * Compiling                                    |
|       + Linux and other Unix-like Platforms      |
|       + Windows                                  |
|       + macOS                                    |
|   * Installing                                   |
|       + Linux and other Unix-like Platforms      |
|       + Windows                                  |
|       + macOS                                    |
|   * Creating plugins with multiple effects       |
|   * Example Code                                 |
|   * Til að fá hjálp                              |
|   * Orðasafn                                     |
+--------------------------------------------------+

Yfirlit

Beginning with version 0.9.18, Tux Paint's 'Magic' tools were converted from
routines that lived within the application itself, to a set of 'plugins' that
are loaded when Tux Paint starts up.

This division allows more rapid development of 'Magic' tools, and allows
programmers to create and test new tools without needing to integrate them
within the main Tux Paint source code. (Users of more professional graphics
tools, such as GIMP, should be familiar with this plugin concept.)

Prerequisites

Tux Paint is written in the C programming language, and uses the Simple
DirectMedia Layer library ('libSDL', or simply 'SDL'; available from https://
www.libsdl.org/). Therefore, for the moment at least, one must understand the C
language and how to compile C-based programs. Familiarity with the SDL API is
highly recommended, but some basic SDL concepts will be covered in this
document.

Interfaces

Those who create 'Magic' tool plugins for Tux Paint must provide some
interfaces (C functions) that Tux Paint may invoke.

Tux Paint utilizes SDL's "SDL_LoadObject()" and "SDL_LoadFunction()" routines
to load plugins (shared objects files; e.g., ".so" files on Linux or ".dll"
files on Windows) and find the functions within.

In turn, Tux Paint provides a number of helper functions that the plugin may
(or sometimes is required to) use. This is exposed as a C structure (or
"struct") which contains pointers to functions and other data inside Tux Paint.
A pointer to this structure gets passed along to the plugin's functions as an
argument when Tux Paint invokes them.

Plugins should #include the C header file "tp_magic_api.h", which exposes the
'Magic' tool plugin API. Also, when you run the C compiler to build a plugin,
you should use the command-line tool "tp-magic-config" to get the appropriate
compiler flags (such as where the compiler can find the Tux Paint plugin header
file, as well as SDL's header files) for building a plugin. (See "Compiling",
below.)

The C header file and command-line tool mentioned above are included with Tux
Paint — or in some cases, as part of a "Tux Paint 'Magic' Tool Plugin
Development package".

                     ### 'Magic' tool plugin functions ###

'Magic' tool plugins must contain the functions listed below. Note: To avoid
'namespace' collisions, each function's name must start with the shared
object's filename (e.g., "blur.so" or "blur.dll" would have functions whose
names begin with "blur_"). This includes private functions (ones not used by
Tux Paint directly), unless you declare those as 'static'.

## Common arguments to plugin functions ##

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

→ magic_api * api ←

    Pointer to a C structure containing pointers to Tux Paint functions and
    other data that the plugin can (and sometimes should) use. The contents of
    this struct are described below.

    Note: The magic_api struct is defined in the C header file
    "tp_magic_api.h", which you should include at the top of your plugin's C
    source file:

        #include "tp_magic_api.h"


     
→ int which ←
    An index the plugin should use to differentiate different 'Magic' tools, if
    the plugin provides more than one. (If not, "which" will always be 0.) See
    "Creating plugins with multiple effects", below.
     
→ SDL_Surface * snapshot ←
    A snapshot of the previous Tux Paint canvas, taken when the the mouse was
    first clicked to activate the current magic tool. If you don't continuously
    affect the image during one hold of the mouse button, you should base your
    effects off the contents of this canvas. (That is, read from "snapshot" and
    write to "canvas", below.)
     
→ SDL_Surface * canvas ←
    The current Tux Paint drawing canvas. Your magical effects should end up
    here!
     
→ SDL_Rect * update_rect ←
    A pointer to an SDL 'rectangle' structure that you use to tell Tux Paint
    what part of the canvas has been updated. If your effect affects a 32x32
    area centered around the mouse pointer, you would fill the SDL_Rect as
    follows:

        update_rect->x = x - 16;
        update_rect->y = y - 16;
        update_rect->w = 32;
        update_rect->h = 32;

    Or, if your effect changes the entire canvas (e.g., flips it upside-down),
    you'd fill it as follows:

        update_rect->x = 0;
        update_rect->y = 0;
        update_rect->w = canvas->w;
        update_rect->h = canvas->h;

    Note: "update_rect" is a C pointer (an "SDL_Rect *" rather than just an
    "SDL_Rect") because you need to fill in its contents. Since it is a
    pointer, you access its elements via "->" (arrow) rather than "." (dot).
     

## Required Plugin Functions ##

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

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

# Plugin "housekeeping" functions #

→ Uint32 api_version(void) ←

    The plugin should return an integer value representing the version of the
    Tux Paint 'Magic' tool plugin API the plugin was built against. The safest
    thing to do is return the value of TP_MAGIC_API_VERSION, which is defined
    in "tp_magic_api.h". If Tux Paint deems your plugin to be compatible, it
    will go ahead and use it.

    Note: Called once by Tux Paint, at startup. It is called first.


     
→ int init(magic_api * api, Uint8 disabled_features, Uint8 complexity_level) ←

    The plugin should do any initialization here. Return '1' if initialization
    was successful, or '0' if not (and Tux Paint will not present any 'Magic'
    tools from the plugin).

    Note: Called once by Tux Paint, at startup. It is called after "api_version
    ()", if Tux Paint believes your plugin to be compatible.

    The disabled_features value contains bits set for any Tux Paint features
    relevant to Magic tools which have been disabled in this session. Test
    using the C bitwise 'and' operator, '&'. The features are defined in
    tp_magic_api.h:
      o MAGIC_FEATURE_CONTROL: Magic tool controls (paint vs fullscreen)
        (--nomagiccontrols)
      o MAGIC_FEATURE_SIZE: Magic tool size (--nomagicsizes)
    Your Magic tool(s) may wish to react differently depending on whether one
    or more features have been disabled. (For example, the "Brick" Magic tool
    always offered two tool variations: large and small. With the addition of
    the size feature, only one tool is necessary. However, with the size option
    disabled, the plugin is able to revert back to providing two separate
    tools.)

    The complexity_level variable contains the "complexity level" that Tux
    Paint magic tools may offer — that is, the expertise level of the user. The
    levels are defined in tp_magic_api.h:
      o MAGIC_COMPLEXITY_NOVICE (0): Novice (--complexity=novice)
      o MAGIC_COMPLEXITY_BEGINNER (1): Beginner (--complexity=beginner)
      o MAGIC_COMPLEXITY_ADVANCED (2): Advanced (default) (--complexity=
        advanced)
    Your Magic tool(s) may wish to react differently depending on the expertise
    level of the user, either simplifying how each tool works, or excluding one
    or all of them entirely. (For example, the 1-, 2-, and 3-point perspective
    toolsets are totally inactive when in "novice" mode. In "beginner" mode,
    the drawing tools are available, but the tools to edit the vanishing point
    positions are disabled; the default vanishing points are used. In fact, in
    "beginner" mode, an additional 3-point perspective drawing tool appears,
    with alternative vanishing points.)

    Note: Changed most recently in Tux Paint 0.9.32; Magic API version
    0x00000009.


     
→ int get_tool_count(magic_api * api) ←

    This should return the number of Magic tools this plugin provides to Tux
    Paint.

    Note: Called once by Tux Paint, at startup. It is called after your "init()
    ", if it succeeded.

    Note: You may wish to resond differently, based on whether certain features
    have been disabled (e.g., 'paint' versus 'entire picture' controls, or
    'Magic sizes' controls).


     
→ 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:
      o MODE_PAINT - freehand paint (click and drag)
      o MODE_FULLSCREEN - applies to full image with one click
      o MODE_PAINT_WITH_PREVIEW - freehand paint, with preview (click and drag)
      o 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) ←

    This should return a string containing the name of a magic tool. This will
    appear on the button in the 'Magic' selector within Tux Paint.

    Tux Paint will free() the string upon exit, so you should wrap it in a C
    strdup() call.

    Note: Called once for each Magic tool your plugin claims to contain (by
    your "get_tool_count()").


     
→ int get_group(magic_api * api, int which) ←

    Use this to group tools together within sections of the 'Magic' selector. A
    number of groups are pre-defined within an enum found in "tp_magic_api.h":
      o MAGIC_TYPE_DISTORTS — Tools that distort the shape of the image, like
        Blur, Emboss, and Ripples
      o MAGIC_TYPE_COLOR_FILTERS — Tools that mostly affect the colors of the
        image without distortion, like Darken, Negative, and Tint
      o MAGIC_TYPE_PICTURE_WARPS — Tools that warp or move the entire picture,
        like Shift, Flip, and Waves
      o MAGIC_TYPE_PAINTING — Tools that generally paint new content at the
        cursor position, like Grass, Bricks, and Rails
      o MAGIC_TYPE_PATTERN_PAINTING — Tools that paint in multiple places at
        once, like Kaleidoscope and the Symmetry tools
      o MAGIC_TYPE_PICTURE_DECORATIONS — Tools that apply decorations to the
        entire picture, like Blinds and Checkboard
      o MAGIC_TYPE_ARTISTIC — Special-purpose artistic tools, like Flower, the
        String tools, and the Rainbow-arc-drawing tools.

    Note: Called once for each Magic tool your plugin claims to contain (by
    your "get_tool_count()").

    Note: Added to Tux Paint 0.9.27; Magic API version 0x00000005.


     
→ SDL_Surface * get_icon(magic_api * api, int which) ←

    This should return an SDL_Surface containing the icon representing the
    tool. (A greyscale image with alpha, no larger than 40x40.) This will
    appear on the button in the 'Magic' selector within Tux Paint.

    Tux Paint will free ("SDL_FreeSurface()") the surface upon exit.

    Note: Called once for each Magic tool your plugin claims to contain (by
    your "get_tool_count()").


     
→ char * get_description(magic_api * api, int which, int mode) ←

    This should return a string containing the description of how to use a
    particular magic tool. This will appear as a help tip, explained by Tux the
    Penguin, within Tux Paint.

    Tux Paint will free() the string upon exit, so you should wrap it in a C
    strdup() call.

    Note: For each Magic tool your plugin claims to contain (reported by your
    "get_tool_count()" function), this function will be called for each mode
    the tool claims to support (reported by your "modes()" function).

    In other words, if your plugin contains two tools, one which works in paint
    mode only, and the other that works in both paint mode and full-image mode,
    your plugin's "get_description()" will be called three times.


     
→ int requires_colors(magic_api * api, int which) ←

    Return a '1' if the 'Magic' tool accepts colors (the 'Colors' palette in
    Tux Paint will be available), or '0' if not.

    Note: Called once for each Magic tool your plugin claims to contain (by
    your "get_tool_count()").


     
→ Uint8 accepted_sizes(magic_api * api, int which, int mode) ←

    Return how many size variations the 'Magic' tool accepts, in the given mode
    (i.e., 'MODE_PAINT' or 'MODE_FULLSCREEN). Return a '0' if the 'Magic' tool
    should not offer sizing options. Returning '1' is the same as returning
    '0'.

    Note: For each Magic tool your plugin claims to contain (reported by your
    "get_tool_count()" function), this function will be called for each mode
    the tool claims to support (reported by your "modes()" function).

    Note: Added to Tux Paint 0.9.30; Magic API version 0x00000008.


     
→ Uint8 default_size(magic_api * api, int which, int mode) ←

    Return the default size the 'Magic' tool should start out with, in the
    given mode. This will be the default setting for the tool the first time it
    is used during a Tux Paint session. If Tux Paint is being invoked with the
    sizing option disabled, this will be the only size requested by Tux Paint.
    Return a number between '1' and the amount you returned in accepted_sizes
    ().

    Note: For each Magic tool your plugin claims to contain (reported by your
    "get_tool_count()" function), this function will be called for each mode
    the tool claims to support (reported by your "modes()" function).

    Note: Added to Tux Paint 0.9.30; Magic API version 0x00000008.


     
→ void shutdown(magic_api * api) ←

    The plugin should do any cleanup here. If you allocated any memory or used
    SDL_Mixer to load any sounds during init(), for example, you should free()
    the allocated memory and Mix_FreeChunk() the sounds here.

    Note: This function is called once, when Tux Paint exits.


     

# Plugin event functions #

→ void switchin(magic_api * api, int which, int mode, SDL_Surface * snapshot,
SDL_Surface * canvas)
void switchout(magic_api * api, int which, int mode, SDL_Surface * snapshot,
SDL_Surface * canvas) ←

    switchin() is called whenever one of the plugin's Magic tools becomes
    active, and switchout() is called whenever one becomes inactive. This can
    be because the user just clicked a specific Magic tool (the current one is
    switched-out, and a new one is switched-in).

    It can also happen when user leaves/returns from the selection of "Magic"
    tools when doing some other activity (i.e., using a different tool, such as
    "Text" or "Brush", activating a momentary tool, such as "Undo" and "Redo",
    or returning from a dialog — possibly with a new picture when it switches
    back — such as "Open", "New" or "Quit"). In this case, the same Magic tool
    is first 'switched-out', and then 'switched-back-in', usually moments
    later.

    Finally, it can also happen when the user changes the 'mode' of a tool
    (i.e., from paint mode to full-image mode). First switchout() is called for
    the old mode, then switchin() is called for the new mode.

    These functions allow users to interact in complicated was with Magic tools
    (for example, a tool that lets the user draw multiple freehand strokes, and
    then uses that as input such as handwriting — normally, the user could
    click somewhere in the canvas to tell the Magic tool they are 'finished',
    but if they switch to another tool, the Magic tool may want to undo any
    temporary changes to the canvas).

    These functions could also be used to streamline certain effects; a
    behind-the-scenes copy of the entire canvas could be altered in some way
    when the user first switches to the canvas, and then pieces of that copy
    could be drawn on the canvas when they draw with the Magic tool.

    Note: Added to Tux Paint 0.9.21; Magic API version 0x00000002.


     
→ void set_color(magic_api * api, int which, SDL_Surface * canvas, SDL_Surface
* last, Uint8 r, Uint8 g, Uint8 b, SDL_Rect * update_rect) ←

    Tux Paint will call this function to inform the plugin of the RGB values of
    the currently-selected color in Tux Paint's 'Colors' palette. (It will be
    called whenever one of the plugin's Magic tools that accept colors becomes
    active, and whenever the user picks a new color while such a tool is
    currently active.)

    Generally, Magic tools will not alter the canvas in any way when receiving
    an updated color, but it is possible. (For example, the "Zoom" and
    "Perspective" tools apply effects which uses the current color choice as a
    solid background. The effects may be adjusted with subsequent click/drag
    operations, but you may also adjust the background color, without altering
    the zoom level or perspective, by simply picking a new color.)

    Note: Changed most recently in Tux Paint 0.9.29; Magic API version
    0x00000007.


     
→ void set_size(magic_api * api, int which, int mode, SDL_Surface * canvas,
SDL_Surface * last, Uint8 size, SDL_Rect * update_rect) ←

    Tux Paint will call this function to inform the plugin of the 'Magic' tool
    size option chosen. (It will be called whenever one of the plugin's Magic
    tools that accept sizes becomes active, and whenever the user picks a new
    size while such a tool is currently active.)

    Generally, Magic tools will not alter the canvas in any way when receiving
    an updated size, but it is possible.

    Note: Added to Tux Paint 0.9.30; Magic API version 0x00000008.


     
→ void click(magic_api * api, int which, int mode, SDL_Surface * snapshot,
SDL_Surface * canvas, int x, int y, SDL_Rect * update_rect) ←

    The plugin should apply the appropriate 'Magic' tool on the 'canvas'
    surface. The (x,y) coordinates are where the mouse was (within the canvas)
    when the mouse button was clicked, and you are told which 'mode' your tool
    is in (i.e., 'MODE_PAINT' or 'MODE_FULLSCREEN).

    The plugin should report back what part of the canvas was affected, by
    filling in the (x,y) and (w,h) elements of 'update_rect'.

    The contents of the drawing canvas immediately prior to the mouse button
    click is stored within the 'snapshot' canvas.


     
→ void drag(magic_api * api, int which, SDL_Surface * snapshot, SDL_Surface *
canvas, int ox, int oy, int x, int y, SDL_Rect * update_rect) ←

    The plugin should apply the appropriate 'Magic' tool on the 'canvas'
    surface. The (ox,oy) and (x,y) coordinates are the location of the mouse at
    the beginning and end of the stroke.

    Typically, plugins that let the user "draw" effects onto the canvas utilize
    Tux Paint's "line()" 'Magic' tool plugin helper function to calculate the
    points of the line between (ox,oy) and (x,y), and call another function
    within the plugin to apply the effect at each point. (See "Tux Paint
    Functions and Data," below).

    The plugin should report back what part of the canvas was affected, by
    filling in the (x,y) and (w,h) elements of 'update_rect'.

    Note: The contents of the drawing canvas immediately prior to the mouse
    button click remains as it was (when the plugin's "click()" function was
    called), and is still available in the 'snapshot' canvas.


     
→ void release(magic_api * api, int which, SDL_Surface * snapshot, SDL_Surface
* canvas, int x, int y, SDL_Rect * update_rect) ←

    The plugin should apply the appropriate 'Magic' tool on the 'canvas'
    surface. The (x,y) coordinates are where the mouse was (within the canvas)
    when the mouse button was released.

    The plugin should report back what part of the canvas was affected, by
    filling in the (x,y) and (w,h) elements of 'update_rect'.

    Note: The contents of the drawing canvas immediately prior to the mouse
    button click remains as it was (when the plugin's "click()" function was
    called), and is still available in the 'snapshot' canvas.


     

                     ### Tux Paint Functions and Data ###

Tux Paint provides a number of helper functions that plugins may access via the
"magic_api" structure, sent to all of the plugin's functions. (See "Required
Plugin Functions," above.)

## Pixel Manipulations ##

→ Uint32 getpixel(SDL_Surface * surf, int x, int y) ←
    Retreives the pixel value from the (x,y) coordinates of an SDL_Surface.
    (You can use SDL's "SDL_GetRGB()" function to convert the Uint32 'pixel' to
    a set of Uint8 RGB values.)
     
→ void putpixel(SDL_Surface * surf, int x, int y, Uint32 pixel) ←
    Sets the pixel value at position (x,y) of an SDL_Surface. (You can use
    SDL's "SDL_MapRGB()" function to convert a set of Uint8 RGB values to a
    Uint32 'pixel' value appropriate to the destination surface.)
     
→ Uint32 xorpixel(SDL_Surface * surf, int x, int y) ←
    Applies an XOR (exclusive-or) operation to the pixel at coordinates (x,y)
    of the SDL_Surface. Applying an XOR again at the same position will return
    the pixel to the original value. Useful for displaying temporary
    'rubberband' lines, outlines, and crosshairs, while utilizing a Magic Tool.
    → SDL_Surface * scale(SDL_Surface * surf, int w, int h, int keep_aspect) ←

        This accepts an existing SDL surface and creates a new one scaled to an
        arbitrary size. (The original surface remains untouched.)

        The "keep_aspect" flag can be set to '1' to force the new surface to
        stay the same shape (aspect ratio) as the original, meaning it may not
        be the same width and height you requested. (Check the "->w" and "->h"
        elements of the output "SDL_Surface *" to determine the actual size.)
         
   
    ## Helper Functions ##

    → int in_circle(int x, int y, int radius) ←
        Returns '1' if the (x,y) location is within a circle of a particular
        radius (centered around the origin: (0,0)). Returns '0' otherwise.
        Useful to create 'Magic' tools that affect the canvas with a circular
        brush shape.
         
    → void line(void * api, int which, SDL_Surface * canvas, SDL_Surface *
    snapshot, int x1, int y1, int x2, int y2, int step, FUNC callback) ←

        This function calculates all points on a line between the coordinates
        (x1,y1) and (x2,y2). Every 'step' iterations, it calls the 'callback'
        function.

        It sends the 'callback' function the (x,y) coordinates on the line, Tux
        Paint's "magic_api" struct (as a "void *" pointer which you need to
        send to it), a 'which' value, represening which of the plugin's 'Magic'
        tool is being used, and the current and snapshot canvases.

        Example prototype of a callback function that may be sent to Tux
        Paint's "line()" 'Magic' tool plugin helper function:

            void exampleCallBack(void * ptr_to_api, int which_tool, SDL_Surface
            * canvas, SDL_Surface * snapshot, int x, int y);

        Example use of the "line()" helper (e.g., within a plugin's draw()
        function):

            api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1,
            exampleCallBack);


         
    → Uint8 touched(int x, int y) ←

        This function allows you to avoid re-processing the same pixels
        multiple times when the user drags the mouse across an area of the
        canvas, thus increasing Tux Paint's response time, especially with
        math-heavy effects.

        If your effect's "click()", "drag()" and/or "release()" functions take
        the contents of the source surface ("snapshot") and always create the
        same results in the desintation surface ("canvas"), you should wrap the
        effect in a call to "api->touched()".

        This function simply returns whether or not it had already been called
        for the same (x,y) coordinates, since the user first clicked the mouse.
        In other words, the first time you call it for a particular (x,y)
        coordinate, it returns '0'. Future calls will return '1' until the user
        releases the mouse button.

        Note: Magic effects that continuously affect the destination surface
        ("canvas") (ignoring the "snapshot surface) have no reason to use this
        function. The "Blur" and "Smudge" tools that ship with Tux Paint are
        examples of such effects.


         
   
    ## Til upplýsingar ##

    → char * tp_version ←
        A string containing the version of Tux Paint that's running (e.g.,
        "0.9.34").
         
    → int canvas_w
    int canvas_h ←
        Returns the width (canvas_w) and height (canvas_h) of the drawing
        canvas (in pixels).
         
    → int button_down(void) ←
        A '1' is returned if the mouse button is down; '0' otherwise.
         
    → char * data_directory ←

        This string contains the directory where Tux Paint's data files are
        stored. For example, on Linux, this may be "/usr/share/tuxpaint/".

        Magic tools should include an icon (see "get_icon()", above) and are
        encouraged to include sound effects, it's useful for plugins to know
        where such things are located.

        When compiling and installing a plugin, the "tp-magic-config"
        command-line tool should be used to determine where such data should be
        placed for the installed version of Tux Paint to find them. (See "
        Installing," below.)

        Note: If your plugin is installed locally (e.g., in your "~/.tuxpaint/
        plugins/" directory), rather than globally (system-wide), the
        "data_directory" value will be different. (e.g., "/home/username
        /.tuxpaint/plugins/data/").


         
   
    ## Sound Functions ##

    → void playsound(Mix_Chunk * snd, int pan, int dist) ←

        This function plays a sound (one loaded by the SDL helper library
        "SDL_mixer"). It uses SDL_mixer's "Mix_SetPanning()" to set the volume
        of the sound on the left and right speakers, based on the 'pan' and
        'dist' values sent to it.

        A 'pan' of 128 causes the sound to be played at equal volume on the
        left and right speakers. A 'pan' of 0 causes it to be played completely
        on the left, and 255 completely on the right.

        The 'dist' value affects overall volume. 255 is loudest, and 0 is
        silent.

        The 'pan' and 'dist' values can be used to simulate location and
        distance of the 'Magic' tool effect.


         
    → void stopsound(void) ←
        This function stops playing a sound played by playsound(). It is useful
        to silence effects when the user stops using the tool (in your
        'release' function).
         
    → int playingsound(void) ←

        Call this function to determine whether a magic tool sound effect is
        still currently playing. Can be used by magic tools that pause and
        unpause their sounds (see below) to determine whether it's time to
        start a new sound — call playsound() instead of unpausesound(). A '1'
        is returned if a sound is playing; '0' otherwise.

        Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.


         
    → void pausesound(void) ←

        Pauses the magic tool sound effect; it may be unpaused to resume
        playing. Useful when a magic tool sound is very long; avoid repeatedly
        playing just a short clip of the beginning when the user draws small
        strokes by starting (playsound()) and stopping (stopsound()) the sound.
        Use playingsound() to determine whether you can unpause or must play
        from the start.

        Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.


         
    → void unpausesound(void) ←

        Resumes a paused magic tool sound effect, if one was playing.

        Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.


         
   
    ## Tux Paint System Calls ##

    → void update_progress_bar(void) ←
        Asks Tux Paint to animate and draw one frame of its progress bar (at
        the bottom of the screen). Useful for routines that may take a long
        time, to provide feedback to the user that Tux Paint has not crashed or
        frozen.
         
    void special_notify(int flag) ←
        This function notifies Tux Paint of special events. Various values
        defined in "tp_magic_api.h" can be 'or'ed together (using C's boolean
        'or': "|") and sent to this function.
        → SPECIAL_FLIP ←

            The contents of the canvas has been flipped vertically.

            If a 'Starter' image was used as the basis of this image, it should
            be flipped too, and a record of the flip should be stored as part
            of Tux Paint's undo buffer stack. Additionally, the fact that the
            starter has been flipped (or unflipped) should be recorded on disk
            when the current drawing is saved.


             
        → SPECIAL_MIRROR ←
            Similar to SPECIAL_FLIP, but for magic tools that mirror the
            contents of the canvas horizontally.
             

         
    void retract_undo(void) ←

        Each time the user clicks in the canvas while using your Magic tool, a
        new snapshot of the canvas is added to the "Undo" history. This allows
        the user to click "Undo" to return the image to the state it was in
        just before they clicked with your Magic tool. They may click "Redo" to
        bring the change back.

        However, some more sophisticated Magic tools require one or more steps
        to take place before the final "effect" is reached. For example,
        "Filled Polygon" requires placing at least three connected points, then
        connecting the first and last point together, to create a shape that
        gets added to the canvas. In the meantime, an interactive preview of
        the shape — an outline with large dots representing each point — is
        drawn onto the canvas. (The points may be moved, or even removed, prior
        to finishing the shape.)

        The retract_undo() API function may be used by a Magic tool to tell it
        to discard the "Undo" snapshot it just took, as a way to prevent
        previews shown during multi-step actions from appearing on the canvas
        when using the "Undo" and "Redo" commands.

        💡 This is an advanced feature.

        Note: Added to Tux Paint 0.9.33; Magic API version 0x0000000A.


         
   
    ## Color Conversions ##

    → float sRGB_to_linear(Uint8 srbg) ←
        Converts an 8-bit sRGB value (one between 0 and 255) to a linear
        floating point value (between 0.0 and 1.0).
         
    → uint8 linear_to_sRGB(float linear) ←
        Converts a linear floating point value (one between 0.0 and 1.0) to an
        8-bit sRGB value (between 0 and 255).
         
    → void rgbtohsv(Uint8 r, Uint8 g, Uint8 b, float * h, float * s, float * v)
    ←
        Converts 8-bit sRGB values (between 0 and 255) to floating-point HSV
        (Hue, Saturation and Value) values (Hue between 0.0 and 360.0, and
        Saturation and Value between 0.0 and 1.0).
         
    → void hsvtorgb(float h, float s, float v, Uint8 * r, Uint8 * g, Uint8 * b)
    ←
        Converts floating-point HSV (Hue, Saturation and Value) values (Hue
        between 0.0 and 360.0, and Saturation and Value between 0.0 and 1.0) to
        8-bit sRGB values (between 0 and 255).
         

    For more information, refer to the sRGB article at Wikipedia and the HSV
    Color Space article at Wikipedia.

                     ### Helper Macros in "tp_magic_api.h" ###

    Along with the "magic_api" C structure containing functions and data
    described above, the tp_magic_api.h C header file also contains some helper
    macros that you may use.

    → min(x, y)
    max(x, y) ←
        The minimum (min) or maxinum (max) of 'x' and 'y'. For example, min()
        will return the value of 'x' if it is less than or equal to 'y',
        otherwise it will return 'y'.
         
    → clamp(lo, value, hi) ←

        A value, clamped to be no smaller than 'lo', and no higher than 'hi'.
        (That is, if 'value' is less than 'lo', then 'lo' will be used; if
        'value' is greater than 'hi', then 'hi' will be used; otherwise,
        'value' will be used.)

        Example: red = clamp(0, n, 255); will set the variable 'red' to be the
        value of the variable 'n', but without allowing it to become less than
        0 or greater than 255.

        Note: This macro is simply a #define of: "(min(max(value,lo),hi))".


         
   
                 ### Constant Definitions in "tp_magic_api.h" ###

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

    → TP_MAGIC_API_VERSION ←

        This integer value represents which version of the Tux Paint 'Magic'
        tool API the header corresponds to.

        It should be referenced by your magic tool's "api_version()" function,
        to inform the running copy of Tux Paint whether or not your plugin is
        compatible.

        Note: This version number does not correspond to Tux Paint's own
        release number (e.g., "0.9.34"). The API will not change every time a
        new version of Tux Paint is released, which means plugins compiled for
        earlier versions of Tux Paint will often run under newer versions.


         
    → SPECIAL_MIRROR
    SPECIAL_FLIP ←
        These are flags for Tux Paint's "special_notify()" helper function.
        They are described above.
         
   
    Compiling

                    ### Linux and other Unix-like Platforms ###

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

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

    ## Command-Line Example ##

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


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

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

    ## Makefile Example ##

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

        CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)

        my_plugin.so: my_plugin.c
            gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c

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

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

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

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

    ## Advanced Makefile ##

    An even more generalized Makefile might look like this:

        CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)

        my_plugin_1.so: my_plugin_1.c
            $(CC) -shared $(CFLAGS) -o $@ $<

        my_plugin_2.so: my_plugin_2.c
            $(CC) -shared $(CFLAGS) -o $@ $<

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

    "$(CC)" gets expanded to your default C compiler (e.g., "gcc"). "-shared"
    and "$(CFLAGS)" are command-line arguments to the compiler, like above. "-o
    $@" tells the C compiler what the output file should be; "make" replaces
    "$@" with the name of the target, in this case "my_plugin_1.so" or
    "my_plugin_2.so". And finally, the last argument is the C file to compile;
    "make" replaces "$<" with the target's dependency, in this case
    "my_plugin_1.c" or "my_plugin_2.c".

                                  ### Windows ###

    TBD

                                   ### macOS ###

    TBD

    Installing

                    ### Linux and other Unix-like Platforms ###

    Use the "tp-magic-config" command-line tool, supplied as part of Tux Paint
    — or in some cases, as part of a "Tux Paint 'Magic' Tool Plugin Development
    package" — to determine where your plugins' files should go.

    ## Shared Object ##

    Use "tp-magic-config --pluginprefix" to determine where the plugin shared
    object (".so") files should be installed. The value returned by this
    command will be the global location where the installed copy of Tux Paint
    looks for plugins (e.g., "/usr/lib/tuxpaint/plugins").

    Alternatively, you may use "tp-magic-config --localpluginprefix" to find
    out where Tux Paint expects to find local plugins for the current user
    (e.g., "/home/username/.tuxpaint/plugins").

    As stand-alone commands, using the BASH shell, for example:

        # cp my_plugin.so `tp-magic-config --pluginprefix`
        # chmod 644 `tp-magic-config --pluginprefix`/my_plugin.so

    Note: See the note above regarding the "`" (grave) character.

    ## Documentation ##

    Use the "tp-magic-config --plugindocprefix" command to determine where
    documentation for your "Magic" tools should go. The value returned by this
    command will be the location where the documentation to the installed copy
    of Tux Paint is stored. The main documentation includes a link to a folder
    where "Magic" tools' documentation is expected to be installed

    (e.g., "/usr/share/doc/tuxpaint/magic-docs").

    Note: It's best to include both HTML and plain-text versions of your
    documentation. An "html" subdirectory exists within the "magic-docs"
    directory, and is where the HTML versions should go.

    As stand-alone commands, using the BASH shell, for example:

        # cp my_plugin.html `tp-magic-config --plugindocprefix`/html
        # cp my_plugin.txt `tp-magic-config --plugindocprefix`

    Note: See the note above regarding the "`" (grave) character.

    Note: Currently, there is no "--localplugindocprefix" option.

    ## Icons, Sounds and other Data Files ##

    Use the "tp-magic-config --dataprefix" command, supplied as part of Tux
    Paint, to determine where data files (PNG icon, Ogg Vorbis sound effects,
    etc.) should be installed. The value returned by this command will be the
    same as the value of the "data_directory" string stored within the
    "magic_api" structure that your plugin's functions receive (e.g., "/usr/
    share/tuxpaint/").

    For locally-installed plugins (for the current user only), use
    "tp-magic-config --localdataprefix". It will return the value of
    "data_directory" string that locally-installed plugins will see within
    their "magic_api" structure (e.g., "/home/username/.tuxpaint/plugins/data/
    ").

    Note: Tux Paint's default Magic tool plugins install their data within
    "magic" subdirectories of Tux Paint's "images" and "sounds" data
    directories (e.g., "/usr/share/tuxpaint/images/magic/"). You are encouraged
    to do the same.

    As stand-alone commands, using the BASH shell, for example:

        # cp my_plugin_icon.png `tp-magic-config --dataprefix`/images/magic/
        # chmod 644 `tp-magic-config --dataprefix`/images/magic/
        my_plugin_icon.png

    Note: See the note above regarding the "`" (grave) character.

    ## Putting it Together in a Makefile ##

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

        PLUGINPREFIX=$(shell tp-magic-config --pluginprefix)
        PLUGINDOCPREFIX=$(shell tp-magic-config --plugindocprefix)
        DATAPREFIX=$(shell tp-magic-config --dataprefix)

        install:
            #
            # Install plugin
            mkdir -p $(PLUGINPREFIX)
            cp *.so $(PLUGINPREFIX)/
            chmod 644 $(PLUGINPREFIX)/*.so
            #
            # Install icons
            mkdir -p $(DATAPREFIX)/images/magic
            cp icons/*.png $(DATAPREFIX)/images/magic/
            chmod 644 $(DATAPREFIX)/images/magic/*.png
            #
            # Install sound effects
            mkdir -p $(DATAPREFIX)/sounds/magic
            cp sounds/*.ogg $(DATAPREFIX)/sounds/magic/
            chmod 644 $(DATAPREFIX)/sounds/magic/*.ogg
            #
            # Install docs
            mkdir -p $(PLUGINDOCPREFIX)/html
            cp docs/*.html $(PLUGINDOCPREFIX)/html/
            cp docs/*.txt $(PLUGINDOCPREFIX)/
            chmod 644 $(PLUGINDOCPREFIX)/html/*.html
            chmod 644 $(PLUGINDOCPREFIX)/*.txt

    The first three lines set up Makefile variables that contain the paths
    returned by the "tp-magic-config" command-line tool. (The "$(shell ...)"
    directive is similar to the ` ("grave") character in the BASH shell
    examples, above.)

    Below that is an "install" target in the Makefile. (Invoked by, for
    example, "$ sudo make install" or "# make install".)

    The "install" target uses "mkdir -p" to make sure that the plugin directory
    exists, then uses "cp" to copy all plugin (".so") files into it, and
    invokes "chmod" to make sure they are readable.

    It then does a similar series of commands to install icon files (".png"
    images) and sound effects (".ogg" files) into subdirectories within Tux
    Paint's data directory, and to install documentation (".html" and ".txt"
    files) within Tux Paint's documentation directory.

    Note: The above Makefile example assumes the user will have priveleges to
    install Tux Paint plugins system-wide.

                                  ### Windows ###

    TBD

                                   ### macOS ###

    TBD

    Creating plugins with multiple effects

    Plugins for Tux Paint may contain more than one effect. If you have
    multiple effects that are similar, it may make sense to place them in one
    plugin file, to reduce overhead and share code.

    These following suggestions can help you create plugins that contain
    multiple effects:
      o Use a C "enum" to enumerate the effects, and count them.

            enum {
                ONE_TOOL,
                ANOTHER_TOOL,
                AND_YET_ANOTHER_TOOL,
                NUM_TOOLS };

      o Return the value of "NUM_TOOLS" when "get_tool_count()" is called, and
        compare "which" values sent to other functions with the other
        enumerated values.
      o Create arrays of "NUM_TOOLS" length to contain effect-specific data.

            char * my_plugin_snd_filenames[NUM_TOOLS] = {
                "one.ogg", "another.ogg", "yet_another.ogg" };
            Mix_Chunk * my_plugin_snds[NUM_TOOLS]");

      o Use a C "for"-loop to load or create the effect-specific data (such as
        loading sound effects during your "init()").

            int i;
            char fname[1024];

            for (i = 0; i < NUM_TOOLS; i++)
            {
                /* Becomes, for example, "/usr/share/tuxpaint/sounds/magic/
            one.ogg" */

                snprintf(fname, sizeof(fname), "%s/sounds/magic/%s",
                    api->data_prefix, my_plugin_snd_filenames[i]);

                my_plugin_snds[i] = Mix_LoadWAV(fname);
            }

      o Similarly, do the same to free them later (such as freeing sound
        effects during your "shutdown()").

                int i;

                for (i = 0; i < NUM_TOOLS; i++)
                    Mix_FreeChunk(my_plugin_snds[i]);

      o Use "which" values sent to your functions as an index into those arrays
        (e.g., for playing the appropriate sound effect for a tool).

    Note: Even if your plugin currently contains only one effect, it may be
    useful to follow the steps above so that you can add a new variation of an
    effect with little effort. ("NUM_TOOLS" will simply be '1', your arrays
    will be of length '1', etc.)

    Example Code

    The C source file "tp_magic_example.c" contains a complete example of a
    plugin with multiple simple effects.

    Til að fá hjálp

    For more information, check the Tux Paint website: https://tuxpaint.org/,
    and the Simple DirectMedia Layer library website: http://www.libsdl.org/.

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

    Orðasafn

    → & ←
        See "'og' merki"
         
    → * ←
        See "star"
         
    → -> ←
        See "arrow"
         
    → . ←
        See "punktur"
         
    → ` ←
        See "grave"
         
    → alfa ←
        See "RGBA"
         
    → API ←
        Application Programming Interface. Definition not yet presented.
         
    → arrow ←
        "->". A symbol in C that references an element within a pointer to a
        struct.
         
    → backquote / bakslag ←
        See "grave"
         
    → BASH ←
        The "Bourne Again Shell", a Unix shell and command language.
         
    → bitar ←
        "Binary digit." Bits are the basic storage unit in a computer's memory,
        disk, networking, etc. They represent either 0 or 1. (Compared to a
        decimal digit, which can be anything between 0 and 9.) Just as a series
        of decimal digits can represent a larger number (e.g., "1" and "5" is
        fifteen (15)), so can bits (e.g., "1" and "0", is two). In decimal, we
        go from right to left: ones place, tens place, hundreds place,
        thousands place, etc. In binary, it is: ones place, twos place, fours
        place, eights place, etc.
        See also: "bæti"
         
    → blátt ←
        See "RGBA"
         
    → boole gildið 'eða' ←
        A mathematical operation that results in a true value if either operand
        is true. ("1 | 0", "0 | 1" and "1 | 1" all result in "1". "0 | 0"
        results in "0".)
        See also: "bitar"
         
    → bæti ←
        A unit of memory made up of 8 bits. As a signed value, it can represent
        -128 through 127. As an unsigned value, it can represent 0 through 255.
        As a series of bits, for example, the byte "00001100" represents the
        decimal value 12.
        See also: "bitar"
         
    → C enumeration ←
        A construct in C that allows you to label numeric values (usually
        starting at 0 and incrementing by one). (e.g., "enum { ONE, TWO, THREE
        };"
         
    → C function / C function prototype / C header file ←
        Definition not yet presented.
        See also: "C function prototype"
         
    → C pointer ←
        A variable that contains the location of a piece of memory; usually
        used to 'point' to another variable. Since C functions can only return
        one value as a result, pointers are often sent to functions to allow
        the function to change the values of multiple variables. (For example,
        Tux Paint's "rgbtohsv()" and "hsvtorgb()".)
         
    → C structure ←
        A construct in C that allows you to declare a new variable 'type' which
        may contain other types within. For example, SDL's "SDL_Rect" contains
        four integer values, the coordinates of the rectangle (X,Y), and its
        dimensions (width and height).
         
    → colorspace ←
        Definition not yet presented.
        See also:
          @ RGBA
          @ HSV

         
    → #define ←
        A C statement that defines a substitution that can occur later in the
        code. Generally used for constant values (e.g., "#define RADIUS 16";
        all instances of "RADIUS" will be replaced with "16"), but can also be
        used to create macros. Typically placed within C header files.
         
    → .dll ←
        See "Shared Object"
         
    → draga ←
        The action of moving a mouse while the button remains held, or moving a
        finger or stylus across a screen or tablet, without removing it.
        See also:
          @ smellur
          @ sleppa

         
    → element ←
        A variable stored within a C structure. (Example: "w" and "h" elements
        of SDL_Surface store the surface's width and height, respectively.)
        See also:
          @ C structure
          @ punktur
          @ arrow

         
    → enum ←
        See "C enumeration"
         
    → fjölvi ←
        A C construct that looks similar to a C function, but is simply a #
        define that is expanded 'inline'. For example, if you declared the
        macro "#define ADD(A,B) ((A)+(B))", and then used it with "c = ADD
        (1,2);", that line of code would literally expand to "c = ((1) + (2));
        ", or more simply, "c = 1 + 2;".
         
    → float ←
        See "floating point"
         
    → floating point ←
        Definition not yet presented.
        See also: "integer"
         
    → format ←
        An SDL_Surface element (a pointer to an SDL_PixelFormat structure) that
        contains information about a surface; for example, the number of bits
        used to represent each pixel).
        Refer to the "SDL_PixelFormat(3)" man page.
         
    → free() ←
        A C function that frees (deallocates) memory allocated by other C
        functions (such as "strdup()").
        Refer to the "malloc(3)" man page.
         
    → frumgerð ←
        See "C function prototype"
         
    → function ←
        See "C function"
         
    → gcc ←
        See "GNU C Compiler"
         
    → gildi ←
        See "HSV"
         
    → GIMP ←
        GNU Image Manipulation Program, an Open Source image manipulation and
        paint program.
        See also: "Krita"
         
    → GNU C Compiler ←
        The GNU C compiler, a portable Open Source package for compiling and
        linking programs written in the C programming language.
        Refer to the "gcc(1)" man page.
         
    → grave ←
        The "`" character; used by the BASH shell to use the output of a
        command as the command-line arguments to another.
         
    → grænt ←
        See "RGBA"
         
    → .h / haus / header file ←
        See "C header file"
         
    → hnit ←
        A set of numbers corresponding to a physical position; for example, in
        a two-dimensional (2D) image, "X" and "Y" coordinates specify the
        position across (left-to-right) and down the image, respectively. In
        SDL, the coordinates (0,0) is the top-leftmost pixel of a surface.
         
    → HSV ←
        Hue, Saturation and Value.Definition not yet presented.
        See also:
          @ RGBA
          @ colorspace

         
    → IMG_Load() ←
        An SDL_image function that loads an image file (e.g., a PNG) and
        returns it as an "SDL_Surface *".
         
    → #include ←
        A C statement that asks the compiler to read the contents of another
        file (usually a header file).
         
    → int ←
        See "integer"
         
    → integer ←
        Definition not yet presented.
        See also: "floating point"
         
    → Krita ←
        An Open Source image manipulation and paint program.
        See also: "GIMP"
         
    → libSDL ←
        See "Simple DirectMedia Layer"
         
    → litblær ←
        See "HSV"
         
    → línulegt ←
        Definition not yet presented.
         
    → Magic tool ←
        One of a number of effects or drawing tools in Tux Paint, made
        available via the "Magic" tool button.
         
    → magic_api ←
        A C structure that is passed along to a plugin's functions that exposes
        data and functions within the running copy of Tux Paint.
         
    → make ←
        A utility that automatically determines which pieces of a larger
        program need to be recompiled, and issues the commands to recompile
        them.
        See also: "Makefile"
         
    → Makefile ←
        A text file used by the "make" utility; it describes the relationships
        among files in your program, and the commands for updating each file.
        (For example, to compile a human-readable source-code file into a
        computer-readable executable program file.)
         
    → Mix_Chunk * ←
        (A pointer to) a C structure defined by SDL_mixer that contains a
        sound.
         
    → Mix_FreeChunk() ←
        An SDL_mixer function that frees (deallocates) memory allocated for an
        SDL_mixer sound 'chunk' ("Mix_Chunk *").
         
    → Mix_LoadWAV() ←
        An SDL_mixer function that loads a sound file (WAV, Ogg Vorbis, etc.)
        and returns it as a "Mix_Chunk *".
         
    → namespace ←
        Definition not yet presented.
         
    → 'og' merki (bendlar) ←
        "&". A symbol in C that allows you to refer to the memory address of a
        variable; that is, a pointer. (For example, consider "int i;". Later, "
        &i" refers to the memory where "i" is stored, not the value of "i"
        itself; it is a 'pointer to "i"'.)
        See also: "star"
         
    → 'og' merki (bitwise operator) ←
        "&". A symbol in C that acts as a bitwise "and" operator. Only bits set
        in both values will be returned. For example, "11 & 6" compares the
        binary values '1011' to '0110'. Only the bit in the 2's place is set,
        so the result is 2 ('0010').
        See also: "bitar"
         
    → .ogg ←
        See "Ogg Vorbis"
         
    → Ogg Vorbis / plugin ←
        Definition not yet presented.
        See also: "WAVE"
         
    → .png ←
        See "Portable Network Graphics"
         
    → pointer ←
        See "C pointer"
         
    → Portable Network Graphics ←
        Portable Network Graphics. An extensible file format for the lossless,
        portable, well-compressed storage of raster images. It's the file
        format Tux Paint uses to save images, and for its brushes and stamps.
        It's an easy way to store 32bpp RGBA images (24bpp true color with full
        8bpp alpha transparency), excellent for use in graphics programs like
        Tux Paint.
        Refer to the "png(5)" man page.
        See also: "Scalable Vector Graphic"
         
    → punktur ←
        ".". A symbol in C that references an element within a struct.
        See also:
          @ C structure
          @ arrow

         
    → rautt / RGB ←
        See "RGBA"
         
    → RGBA ←
        Red, Green, Blue, and Alpha.Definition not yet presented.
        See also:
          @ HSV
          @ colorspace

         
    → rás ←
        Definition not yet presented.
         
    → saturation ←
        See "HSV"
         
    → SDL ←
        See "Simple DirectMedia Layer"
         
    → SDL_FreeSurface() ←
        A libSDL function that frees (deallocates) memory allocated for an SDL
        surface ("SDL_Surface *").
         
    → SDL_GetRGB() ←
        A libSDL function that, given a Uint32 pixel value (e.g., one returned
        from the Tux Paint's Magic tool API helper function "getpixel()"), the
        format of the surface the pixel was taken from, and pointers to three
        Uint8 variables, will place the Red, Green and Blue (RGB) values of the
        pixel into the three Uint8 variables. (Example: "SDL_GetRGB(getpixel
        (surf, x, y), surf->format, &r, &g, &b);".)
        Refer to the "SDL_GetRGB(3)" man page.
        See also:
          @ SDL_MapRGB()
          @ RGBA

         
    → SDL_image ←
        A library on top of libSDL that can load various kinds of image files
        (e.g., PNG) and return them as an "SDL_Surface *".
         
    → SDL_MapRGB() ←
        A libSDL function that, given the format of a surface and Uint8 values
        representing Red, Green and Blue values for a pixel, returns a Uint32
        pixel value that can be placed in the surface (e.g., using Tux Paint's
        Magic tool API helper function "putpixel()"). (Example: "putpixel(surf,
        x, y, SDL_MapRGB(surf->format, r, g, b));".)
        Refer to the "SDL_MapRGB(3)" man page.
        See also:
          @ SDL_GetRGB()
          @ RGBA

         
    → SDL_mixer ←
        A library on top of libSDL that can load various kinds of sound files
        (WAV, Ogg Vorbis, etc.) and play back multiple sounds at once (mix
        them).
         
    → SDL_Rect ←
        A C structure defined by libSDL that represents a rectangular area. It
        contains elements representing the coordinates of the top left corner
        of the rectange (x,y) and the dimensions of the rectangle (w,h).
        Refer to the "SDL_Rect(3)" man page.
         
    → SDL_Surface * ←
        (A pointer to) a C structure defined by libSDL that contains a drawing
        surface.
        Refer to the "SDL_Surface(3)" man page.
         
    → shared object ←
        A piece of code that's compiled separately from the main application,
        and loaded dynamically, at runtime.
         
    → shell ←
        See "BASH"
         
    → Simple DirectMedia Layer ←
        The Simple DirectMedia Layer (libSDL) is a programming library that
        provides portable low-level access to a video framebuffer, audio
        output, and mouse and keyboard input. (See: http://www.libsdl.org/)
         
    → sleppa ←
        The action of releasing a mouse button, or removing a finger or stylus
        from a screen or tablet.
        See also:
          @ smellur
          @ draga

         
    → smellur ←
        The action of pressing a button on a mouse, tapping a touchscreen, or
        pressing a stylus to a tablet.
        See also:
          @ draga
          @ sleppa

         
    → snprintf() ←
        A C function, related to "printf()", which takes a 'format' string and
        one or more additional arguments, and puts them together. "snprintf()"
        takes the resulting output and stores it into a string, making sure not
        to go beyond the string's buffer size (which must also be supplied).
        For example, assume a string "char str[20];" has been declared;
        "snprintf(str, 20, "Name: %s, Age: %d", "Bill", 32);" will store "Name:
        Bill, Age: 32" into 'str'.
        Refer to the "sprintf(3)" man page.
         
    → .so ←
        See "shared object"
         
    → sRGB ←
        See "RGBA"
         
    → star ←
        "*". A symbol in C that, when used in the declaration of variables
        (e.g., arguments to a function), denotes that the variable is a
        pointer. (For example, "int * p;" means that "p" is a pointer to an
        integer.) When used next to a pointer, it 'dereferences' the variable.
        (For example, later "*p = 50;" assigns the value of 50 to the memory
        that "p" points to; it does not change the value of "p", which is still
        a pointer to an integer. In essence, it changed the integer that's
        being pointed to.)
        See also: "'og' merki"
         
    → strdup() ←
        A C function that allocates enough memory to store a copy of a string,
        copies the string to it, and returns a "char *" pointer to the new
        copy.
        Refer to the "strdup(3)" man page.
         
    → struct ←
        See "C structure"
         
    → stærðir ←
        The size of an object, in terms of its width (left to right) and height
        (top to bottom).
         
    → svörun ←
        Definition not yet presented.
         
    → tap ←
        See "smellur"
         
    → tp-magic-config ←
        A command-line program that provides information about the installed
        version of Tux Paint to plugin developers (such as what C compiler
        flags they should compile with, and where plugin shared objects and
        data files should be installed).
        Refer to the "tp-magic-config(3)" man page.
         
    → tp_magic_api.h ←
        A header file that defines Tux Paint's Magic tool API. Plugins must '#
        include' it.
         
    → Uint32 ←
        A 32-bit, unsigned integer (defined by libSDL). In other words, four
        bytes that can represent 0 through 4,294,967,295. (Typically used to
        hold enough information to store three or four bytes representing a
        pixel's color; i.e., RBGA value).
        See also:
          @ Uint8
          @ integer
          @ unsigned

         
    → Uint8 ←
        An 8-bit, unsigned integer (defined by libSDL). In other words, a byte
        that can represent 0 through 255.
        See also:
          @ Uint32
          @ integer
          @ unsigned

         
    → variable ←
        A construct in computer programming that contains a value which can be
        referenced again later by referring to the variable's name, and
        typically changed later. For example, a variable to hold someone's age
        could be declared as an integer: "int age;". It can be examined later —
        e.g., "if (age >= 18) { /* they are an adult */ } else { /* they are
        not an adult */ }" — as well as modified later — e.g., age = 32; /* set
        age to 32 */
         
    → viðfang ←
        A value sent to a function.
         
    → (w,h) ←
        See "stærðir"
         
    → .wav ←
        See "WAVE"
         
    → WAVE ←
        Waveform Audio File Format (WAVE, or WAV). Definition not yet
        presented.
        See also: "Ogg Vorbis"
         
    → (x,y) ←
        See "hnit"
         
    → | ←
        See "boole gildið 'eða'"
         
    → óundirritað ←
        In C, a variable that can store a numeric value can be declared as
        either "signed" (the default), or "unsigned". In the former case, one
        bit of the value is used to denote the sign of the value (either
        positive or negative). In the latter case, the value can only be
        positive, but benefits from one extra bit of storage for the number. A
        signed byte (8 bits), for example, can represent any number between
        -128 and 127. An unsigned byte can go up to 255, but it cannot go below
        0. For the purposes of graphics in SDL, unsigned values should be used
        for RGB values, since each channel (red, green and blue) may be between
        0 (off) and 255 (brightest).
        See also:
          @ Uint8
          @ Uint32
          @ integer