1#ifndef TP_MAGIC_API_H
2#define TP_MAGIC_API_H
3
4#include "SDL.h"
5#include "SDL_mixer.h"
6#include "libintl.h"
7#ifndef gettext_noop
8#define gettext_noop(String) String
9#endif
10
11/* min() and max() variable comparisons: */
12
13#ifdef __GNUC__
14// This version has strict type checking for safety.
15// See the "unnecessary" pointer comparison. (from Linux)
16#define min(x,y) ({ \
17  typeof(x) _x = (x);     \
18  typeof(y) _y = (y);     \
19  (void) (&_x == &_y);            \
20  _x < _y ? _x : _y; })
21#define max(x,y) ({ \
22  typeof(x) _x = (x);     \
23  typeof(y) _y = (y);     \
24  (void) (&_x == &_y);            \
25  _x > _y ? _x : _y; })
26#else
27#define min(a,b) (((a) < (b)) ? (a) : (b))
28#define max(a,b) (((a) > (b)) ? (a) : (b))
29#endif
30
31/* clamp() returns 'value', unless it's less than 'lo' or greater than 'hi',
32   in which cases it returns 'lo' or 'hi', respectively: */
33
34#define clamp(lo,value,hi)    (min(max(value,lo),hi))
35
36
37/* Flags you can send to 'special_notify' */
38
39/* The image has been mirrored (so starter should be, too) */
40/* (as of API version 0x00000001) */
41#define SPECIAL_MIRROR	0x0001
42
43/* The image has been flipped (so starter should be, too) */
44/* (as of API version 0x00000001) */
45#define SPECIAL_FLIP	0x0002
46
47
48/* Flags you return when asked what modes you work in */
49
50/* User can paint the tool, freehand */
51/* (Icon: Paint) */
52#define MODE_PAINT              0x0001 /* (as of API version 0x00000002) */
53
54/* User can apply effect to entire canvas at once */
55/* (Icon: Fullscreen) */
56#define MODE_FULLSCREEN         0x0002 /* (as of API version 0x00000002) */
57
58/* User can paint the tool, freehand -- shows a preview in the meantime */
59/* (Icon: Paint) */
60#define MODE_PAINT_WITH_PREVIEW 0x0004 /* (as of API version 0x00000003) */
61
62/* User can click once at different points on the canvas */
63/* (Icon: Paint) */
64#define MODE_ONECLICK           0x0008 /* (as of API version 0x00000003) */
65
66/* Note: You can "|" (OR) together MODE_FULLSCREEN with one of the other modes
67   (e.g., "MODE_PAINT | MODE_FULLSCREEN", or "MODE_ONECLICK | MODE_FULLSCREEN")
68   You cannot OR those others together (e.g., "MODE_PAINT | MODE_ONECLICK");
69   "MODE_PAINT" will take precedence */
70
71#define MAX_MODES 2 /* Paint & Fullscreen */
72
73
74typedef struct magic_api_t {
75  /* A string containing the current version of Tux Paint (e.g., "0.9.18") */
76  char * tp_version;
77
78  /* A string containing Tux Paint's data directory
79     (e.g., "/usr/local/share/tuxpaint/") */
80  char * data_directory;
81
82  /* Call to have Tux Paint draw (and animate) its progress bar */
83  void (*update_progress_bar)(void);
84
85  /* Call to request special events; see "SPECIAL_..." flags, above */
86  void (*special_notify)(int);
87
88  /* Converts an RGB byte to a linear float */
89  float (*sRGB_to_linear)(Uint8);
90
91  /* Converts a linear float to an RGB byte */
92  Uint8 (*linear_to_sRGB)(float);
93
94  /* Returns whether an (x,y) location is within a circle of a particular
95     radius (centered around the origin: (0,0)); useful for creating tools
96     that have a circular 'brush' */
97  int (*in_circle)(int,int,int);
98
99  /* Receives an SDL pixel value from the surface at an (x,y) location;
100     use "SDL_GetRGB()" to convert the Uint32 into a Uint8 RGB values;
101     NOTE: Use SDL_LockSurface() on the surface before doing (a batch of)
102     this call!  Use SDL_UnlockSurface() when you're done.
103     SDL_MustLockSurface() can tell you whether a surface needs to be locked. */
104  Uint32 (*getpixel)(SDL_Surface *, int, int);
105
106  /* Assigns an SDL pixel value on a surface at an (x,y) location;
107     use "SDL_MapRGB()" to convert a triplet of Uint8 RGB values to a Uint32;
108     NOTE: Use SDL_LockSurface() on the surface before doing (a batch of)
109     this call!  Use SDL_UnlockSurface() when you're done.
110     SDL_MustLockSurface() can tell you whether a surface needs to be locked. */
111  void (*putpixel)(SDL_Surface *, int, int, Uint32);
112
113  /* XOR's the pixel at (x,y) location of the surface. */
114  Uint32 (*xorpixel)(SDL_Surface *, int, int);
115
116  /* Asks Tux Paint to play a sound (one loaded via SDL_mixer library);
117     the first value is for left/right panning (0 is left, 128 is center,
118     255 is right); the second value is for total volume (0 is off, 255 is
119     loudest) */
120  void (*playsound)(Mix_Chunk *, int, int);
121
122  /* Asks Tux Paint to stop playing the sound played by 'playsound()' */
123  void (*stopsound)(void);
124
125  /* Asks Tux Paint to calculate a line between (x1,y1) and (x2,y2);
126     every 'step' iterations, it will call your callback function
127     (which must accept a 'magic_api *' Magic API pointer and 'which' integer
128     for which tool is being used, the 'last' and current ('canvas')
129     SDL_Surfaces, and an (x,y) position) */
130  void (*line)(void *, int, SDL_Surface *, SDL_Surface *, int, int, int, int, int, void (*)(void *, int, SDL_Surface *, SDL_Surface *, int, int));
131
132  /* Returns whether the mouse button is down */
133  int (*button_down)(void);
134
135  /* Converts RGB bytes into HSV floats */
136  void (*rgbtohsv)(Uint8, Uint8, Uint8, float *, float *, float *);
137
138  /* Converts HSV floats into RGB bytes */
139  void (*hsvtorgb)(float, float, float, Uint8 *, Uint8 *, Uint8 *);
140
141  /* Holds Tux Paint's canvas dimensions */
142  int canvas_w;
143  int canvas_h;
144
145  /* Returns a new surface containing the scaled contents of an input
146     surface, scaled to, at maximum, w x h dimensions
147     (keeping aspect ratio, if requested; check the return surface's
148     'w' and 'h' elements to confirm the actual size) */
149  SDL_Surface * (*scale)(SDL_Surface *, int, int, int);
150
151  /* Returns whether a particular position of the canvas has been labeled
152     as 'touched,' since the mouse was first clicked; this function ALSO
153     assigns the position as touched, until the next time the mouse is
154     clicked; useful for not applying the same effect from 'last' to 'canvas'
155     more than once per click-and-drag sequence */
156  Uint8 (*touched)(int, int);
157} magic_api;
158
159
160/* The version of the Tux Paint Magic tool API you are being compiled
161   against.  Your 'XYZ_api_version()' should return this value.
162   If Tux Paint deems you compatible, it will call your 'XYZ_init()' (etc.)
163   and you will be active. */
164
165#define TP_MAGIC_API_VERSION __APIVERSION__
166
167#ifndef ATTRIBUTE_UNUSED
168#define ATTRIBUTE_UNUSED __attribute__ ((__unused__))
169#endif /* ATTRIBUTE_UNUSED */
170
171#endif
172
173