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