1 #ifndef MYPAINTBRUSH_H 2 #define MYPAINTBRUSH_H 3 4 /* libmypaint - The MyPaint Brush Library 5 * Copyright (C) 2008 Martin Renold <martinxyz@gmx.ch> 6 * Copyright (C) 2012 Jon Nordby <jononor@gmail.com> 7 * 8 * Permission to use, copy, modify, and/or distribute this software for any 9 * purpose with or without fee is hereby granted, provided that the above 10 * copyright notice and this permission notice appear in all copies. 11 * 12 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 13 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 15 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 18 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19 */ 20 21 #include "mypaint-config.h" 22 #include "mypaint-surface.h" 23 #include "mypaint-brush-settings.h" 24 25 G_BEGIN_DECLS 26 /*! 27 * @struct MyPaintBrush 28 * Maintains the data and state required to perform brush strokes. 29 * 30 * This is the hub and core of the brush engine, holding the settings, 31 * mappings and state that is used to calculate the location, and other 32 * properties, of the dabs that make up painted strokes. 33 * 34 * The brush is an opaque struct using manual reference counting and handles 35 * its own destruction based on that. 36 * See #mypaint_brush_ref and #mypaint_brush_unref. 37 */ 38 typedef struct MyPaintBrush MyPaintBrush; 39 40 /*! 41 * Create a new brush 42 * 43 * @memberof MyPaintBrush 44 */ 45 MyPaintBrush * 46 mypaint_brush_new(void); 47 48 /*! 49 * Create a new brush with smudge buckets enabled. 50 * 51 * This kind of brush is required to make use of the 52 * @ref MYPAINT_BRUSH_SETTING_SMUDGE_BUCKET setting. 53 * 54 * Smudge buckets are an array of smudge data states, used to allow 55 * dabs in offset locations to use smudge data consistent with their location, 56 * when those location-sequential dabs are not actually drawn consecutively. 57 * 58 * @memberof MyPaintBrush 59 */ 60 MyPaintBrush * 61 mypaint_brush_new_with_buckets(int num_smudge_buckets); 62 63 /*! 64 * Decrease the reference count by one, destroying the brush if it reaches 0. 65 * 66 * Not safe to call with NULL! 67 * 68 * @memberof MyPaintBrush 69 */ 70 void 71 mypaint_brush_unref(MyPaintBrush *self); 72 73 /*! 74 * Increase the reference count by one. 75 * 76 * Not safe to call with NULL! 77 * 78 * @memberof MyPaintBrush 79 */ 80 void 81 mypaint_brush_ref(MyPaintBrush *self); 82 83 /*! 84 * Request a reset if the brush state. 85 * 86 * The request is not acted on immediately, but only in subsequent calls 87 * to mypaint_brush_stroke_to and/or mypaint_brush_stroke_to2. 88 * 89 * Only state values (including smudge buckets, if used) are affected upon reset, 90 * not settings/mappings. 91 * 92 * @memberof MyPaintBrush 93 */ 94 void 95 mypaint_brush_reset(MyPaintBrush *self); 96 97 /*! 98 * Start a new stroke. 99 * 100 * Reset the stroke time parameters. 101 * Not directly related to mypaint_stroke_to (and varieties), calling 102 * the former does not require calling mypaint_brush_new_stroke. 103 * 104 * @memberof MyPaintBrush 105 */ 106 void 107 mypaint_brush_new_stroke(MyPaintBrush *self); 108 109 /*! 110 * Use the brush to draw a stroke segment on a MyPaintSurface 111 * 112 * @memberof MyPaintBrush 113 */ 114 int 115 mypaint_brush_stroke_to( 116 MyPaintBrush* self, MyPaintSurface* surface, float x, float y, float pressure, float xtilt, float ytilt, 117 double dtime); 118 119 /*! 120 * Use the brush to draw a stroke segment on a MyPaintSurface2 121 * 122 * @memberof MyPaintBrush 123 */ 124 int 125 mypaint_brush_stroke_to_2( 126 MyPaintBrush* self, MyPaintSurface2* surface, float x, float y, float pressure, float xtilt, float ytilt, 127 double dtime, float viewzoom, float viewrotation, float barrel_rotation); 128 129 /*! 130 * Same as mypaint_brush_stroke_to_2, but using linear sRGB for color dynamics. 131 * 132 * The settings that are handled differently from the other call are: 133 * 134 * - ::MYPAINT_BRUSH_SETTING_CHANGE_COLOR_H 135 * - ::MYPAINT_BRUSH_SETTING_CHANGE_COLOR_L 136 * - ::MYPAINT_BRUSH_SETTING_CHANGE_COLOR_HSL_S 137 * - ::MYPAINT_BRUSH_SETTING_CHANGE_COLOR_V 138 * - ::MYPAINT_BRUSH_SETTING_CHANGE_COLOR_HSV_S 139 * 140 * @memberof MyPaintBrush 141 */ 142 int 143 mypaint_brush_stroke_to_2_linearsRGB( 144 MyPaintBrush* self, MyPaintSurface2* surface, float x, float y, float pressure, float xtilt, float ytilt, 145 double dtime, float viewzoom, float viewrotation, float barrel_rotation); 146 147 /*! 148 * Set the base value of a brush setting. 149 * 150 * @memberof MyPaintBrush 151 */ 152 void 153 mypaint_brush_set_base_value(MyPaintBrush *self, MyPaintBrushSetting id, float value); 154 155 /*! 156 * Get the base value of a brush setting. 157 * 158 * @memberof MyPaintBrush 159 */ 160 float 161 mypaint_brush_get_base_value(MyPaintBrush *self, MyPaintBrushSetting id); 162 163 /*! 164 * Check if there are no dynamics/mappings for a brush setting. 165 * 166 * This will return FALSE if any input mappings exist for the setting with 167 * the given id, even if all such mappings themselves are constant. 168 * 169 * @memberof MyPaintBrush 170 */ 171 gboolean 172 mypaint_brush_is_constant(MyPaintBrush *self, MyPaintBrushSetting id); 173 174 /*! 175 * Get the number of input mappings for a brush setting. 176 * 177 * @memberof MyPaintBrush 178 */ 179 int 180 mypaint_brush_get_inputs_used_n(MyPaintBrush *self, MyPaintBrushSetting id); 181 182 /*! 183 * Set the number of points in an input mapping for a brush setting. 184 * 185 * @memberof MyPaintBrush 186 */ 187 void 188 mypaint_brush_set_mapping_n(MyPaintBrush *self, MyPaintBrushSetting id, MyPaintBrushInput input, int n); 189 190 /*! 191 * Get the number of points in an input mapping for a brush setting. 192 * 193 * @memberof MyPaintBrush 194 */ 195 int 196 mypaint_brush_get_mapping_n(MyPaintBrush *self, MyPaintBrushSetting id, MyPaintBrushInput input); 197 198 /*! 199 * Set the coordinates of a point in an input mapping for a brush setting. 200 * 201 * @memberof MyPaintBrush 202 */ 203 void 204 mypaint_brush_set_mapping_point(MyPaintBrush *self, MyPaintBrushSetting id, MyPaintBrushInput input, int index, float x, float y); 205 206 /*! 207 * Get the coordinates of a point in an input mapping for a brush setting. 208 * 209 * @memberof MyPaintBrush 210 */ 211 void 212 mypaint_brush_get_mapping_point(MyPaintBrush *self, MyPaintBrushSetting id, MyPaintBrushInput input, int index, float *x, float *y); 213 214 /*! 215 * Get the value of a brush state. 216 * 217 * @memberof MyPaintBrush 218 */ 219 float 220 mypaint_brush_get_state(MyPaintBrush *self, MyPaintBrushState i); 221 222 /*! 223 * Set the value of a brush state. 224 * 225 * @memberof MyPaintBrush 226 */ 227 void 228 mypaint_brush_set_state(MyPaintBrush *self, MyPaintBrushState i, float value); 229 230 /*! 231 * Get the total time recorded since the last call to mypaint_brush_reset 232 * 233 * @memberof MyPaintBrush 234 */ 235 double 236 mypaint_brush_get_total_stroke_painting_time(MyPaintBrush *self); 237 238 /*! 239 * Enable/Disable debug printouts 240 * 241 * @memberof MyPaintBrush 242 */ 243 void 244 mypaint_brush_set_print_inputs(MyPaintBrush *self, gboolean enabled); 245 246 /*! 247 * Initialize a brush with default values for all settings. 248 * 249 * @memberof MyPaintBrush 250 */ 251 void 252 mypaint_brush_from_defaults(MyPaintBrush *self); 253 254 255 /*! 256 * Initialize a brush from a JSON string. 257 * 258 * @memberof MyPaintBrush 259 */ 260 gboolean 261 mypaint_brush_from_string(MyPaintBrush *self, const char *string); 262 263 264 G_END_DECLS 265 266 #endif // MYPAINTBRUSH_H 267