/src/wrappers/cairo/library/cairo_path.e
Specman e | 497 lines | 50 code | 31 blank | 416 comment | 2 complexity | 8121bbda6b180275d034fc6122089264 MD5 | raw file
1note 2 description: "Paths: Creating paths and manipulating path data." 3 copyright: "[ 4 Copyright (C) 2007-2017: Paolo Redaelli, 5 Soluciones Informaticas Libres S.A. (Except), 6 Cairo team 7 8 This library is free software; you can redistribute it and/or 9 modify it under the terms of the GNU Lesser General Public License 10 as published by the Free Software Foundation; either version 2.1 of 11 the License, or (at your option) any later version. 12 13 This library is distributed in the hope that it will be useful, but 14 WITHOUT ANY WARRANTY; without even the implied warranty of 15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 Lesser General Public License for more details. 17 18 You should have received a copy of the GNU Lesser General Public 19 License along with this library; if not, write to the Free Software 20 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 21 02110-1301 USA 22 ]" 23 date: "$Date:$" 24 revision: "$Revision:$" 25 wrapped_version: "1.2.4" 26 27class CAIRO_PATH 28 -- Notes for the implementator of cairo_path_t wrapper 29 30 -- The cairo_path_t type is one area in which most language 31 -- bindings will differ significantly from the C API. The C API for 32 -- cairo_path_t is designed for efficiency and to avoid auxiliary 33 -- objects that would be have to be manually memory managed by the 34 -- application. However, a language binding should not present 35 -- cairo_path_t as an array, but rather as an opaque that can be 36 -- iterated over. Different languages have quite different 37 -- conventions for how iterators work, so it is impossible to give 38 -- an exact specification for how this API should work, but the 39 -- type names and methods should be similar to the language's 40 -- mapping of the following: 41 42 -- typedef struct cairo_path_iterator cairo_path_iterator_t; 43 -- typedef struct cairo_path_element cairo_path_element_t; 44 45 -- cairo_path_iterator_t *cairo_path_get_iterator (cairo_path_t *path); 46 47 -- cairo_bool_t cairo_path_iterator_has_next (cairo_path_iterator_t *iterator); 48 49 -- cairo_path_element_t *cairo_path_iterator_next (cairo_path_iterator_t *iterator); 50 51 -- cairo_path_element_type_t cairo_path_element_get_type (cairo_path_element_t *element); 52 53 -- void cairo_path_element_get_point (cairo_path_element_t *element, int index, double *x, double *y); 54 55 -- The above is written using the Java conventions for 56 -- iterators. To illustrate how the API for PathIterator might 57 -- depend on the native iteration conventions of the API, examine 58 -- three versions of the loop, first written in a hypothetical Java 59 -- binding: 60 61 -- PathIterator iter = cr.copyPath().iterator(); 62 -- while (cr.hasNext()) { 63 -- PathElement element = iter.next(); 64 -- if (element.getType() == PathElementType.MOVE_TO) { 65 -- Point p = element.getPoint(0); 66 -- doMoveTo (p.x, p.y); 67 -- } 68 -- } 69 70 -- And then in a hypothetical C++ binding: 71 72 -- Path path = cr.copyPath(); 73 -- for (PathIterator iter = path.begin(); iter != path.end(); iter++) { 74 -- PathElement element = *iter; 75 -- if (element.getType() == PathElementType.MOVE_TO) { 76 -- Point p = element.getPoint(0); 77 -- doMoveTo (p.x, p.y); 78 -- } 79 -- } 80 81 -- And then finally in a Python binding: 82 83 -- for element in cr.copy_path(): 84 -- if element.getType == cairo.PATH_ELEMENT_MOVE_TO: 85 -- (x, y) = element.getPoint(0) 86 -- doMoveTo (x, y); 87 88 -- While many of the API elements stay the same in the three 89 -- examples, the exact iteration mechanism is quite different, to 90 -- match how users of the language would expect to iterate over a 91 -- container. 92 93 -- You should not present an API for mutating or for creating new 94 -- cairo_path_t objects. In the future, these guidelines may be 95 -- extended to present an API for creating a cairo_path_t from 96 -- scratch for use with cairo_append_path() but the current 97 -- expectation is that cairo_append_path() will mostly be used with 98 -- paths from cairo_copy_path(). 99 100inherit 101 C_STRUCT 102 103insert 104 CAIRO_PATH_EXTERNALS 105 CAIRO_PATH_STRUCT 106 CAIRO_STATUS 107 108create {ANY} from_external_pointer 109 110feature {} -- Creation 111 112 dispose 113 -- Immediately releases all memory associated with 114 -- path. 115 116 -- NOTE: cairo_path_destroy function should only be called 117 -- with a pointer to a cairo_path_t returned by a cairo 118 -- function. Any path that is created manually (ie. outside 119 -- of cairo) should be destroyed manually as well. 120 do 121 cairo_path_destroy(handle) 122 handle := default_pointer 123 end 124 125 -- TODO: features to manually build a path, instead of getting it 126 -- from a context. 127 128 append (another: CAIRO_PATH) 129 -- Append `another' path onto the current path. The path may 130 -- be either the return value from one of `copy_path' or 131 -- `copy_path_flat' or it may be constructed manually. See 132 -- cairo_path_t for details on how the path data structure 133 -- should be initialized, and note that another.status must be 134 -- initialized to `cairo_status_success'. 135 require 136 another_not_void: another /= Void 137 do 138 cairo_append_path(handle, another.handle) 139 end 140 141 -- get_current_point () 142 -- 143 -- void cairo_get_current_point (cairo_t *cr, 144 -- double *x, 145 -- double *y); 146 -- 147 -- Gets the current point of the current path, which is conceptually the 148 -- final point reached by the path so far. 149 -- 150 -- The current point is returned in the user-space coordinate system. If 151 -- there is no defined current point then x and y will both be set to 0.0. 152 -- 153 -- Most path construction functions alter the current point. See the 154 -- following for details on how they affect the current point: 155 -- 156 -- cairo_new_path(), cairo_move_to(), cairo_line_to(), cairo_curve_to(), 157 -- cairo_arc(), cairo_rel_move_to(), cairo_rel_line_to(), 158 -- cairo_rel_curve_to(), cairo_arc(), cairo_text_path(), 159 -- cairo_stroke_to_path() 160 -- 161 -- cr : a cairo context 162 -- x : return value for X coordinate of the current point 163 -- y : return value for Y coordinate of the current point 164 -- 165 -- -------------------------------------------------------------------------- 166 -- 167 -- cairo_new_path () 168 -- 169 -- void cairo_new_path (cairo_t *cr); 170 -- 171 -- Clears the current path. After this call there will be no path and no 172 -- current point. 173 -- 174 -- cr : a cairo context 175 -- 176 -- -------------------------------------------------------------------------- 177 -- 178 -- cairo_new_sub_path () 179 -- 180 -- void cairo_new_sub_path (cairo_t *cr); 181 -- 182 -- Begin a new sub-path. Note that the existing path is not affected. After 183 -- this call there will be no current point. 184 -- 185 -- In many cases, this call is not needed since new sub-paths are frequently 186 -- started with cairo_move_to(). 187 -- 188 -- A call to cairo_new_sub_path() is particularly useful when beginning a new 189 -- sub-path with one of the cairo_arc() calls. This makes things easier as it 190 -- is no longer necessary to manually compute the arc's initial coordinates 191 -- for a call to cairo_move_to(). 192 -- 193 -- cr : a cairo context 194 -- 195 -- Since 1.2 196 -- 197 -- -------------------------------------------------------------------------- 198 -- 199 -- cairo_close_path () 200 -- 201 -- void cairo_close_path (cairo_t *cr); 202 -- 203 -- Adds a line segment to the path from the current point to the beginning of 204 -- the current sub-path, (the most recent point passed to cairo_move_to()), 205 -- and closes this sub-path. After this call the current point will be at the 206 -- joined endpoint of the sub-path. 207 -- 208 -- The behavior of cairo_close_path() is distinct from simply calling 209 -- cairo_line_to() with the equivalent coordinate in the case of stroking. 210 -- When a closed sub-path is stroked, there are no caps on the ends of the 211 -- sub-path. Instead, there is a line join connecting the final and initial 212 -- segments of the sub-path. 213 -- 214 -- If there is no current point before the call to cairo_close_path, this 215 -- function will have no effect. 216 -- 217 -- Note: As of cairo version 1.2.4 any call to cairo_close_path will place an 218 -- explicit MOVE_TO element into the path immediately after the CLOSE_PATH 219 -- element, (which can be seen in cairo_copy_path() for example). This can 220 -- simplify path processing in some cases as it may not be necessary to save 221 -- the "last move_to point" during processing as the MOVE_TO immediately 222 -- after the CLOSE_PATH will provide that point. 223 -- 224 -- cr : a cairo context 225 -- 226 -- -------------------------------------------------------------------------- 227 -- 228 -- cairo_arc () 229 -- 230 -- void cairo_arc (cairo_t *cr, 231 -- double xc, 232 -- double yc, 233 -- double radius, 234 -- double angle1, 235 -- double angle2); 236 -- 237 -- Adds a circular arc of the given radius to the current path. The arc is 238 -- centered at (xc, yc), begins at angle1 and proceeds in the direction of 239 -- increasing angles to end at angle2. If angle2 is less than angle1 it will 240 -- be progressively increased by 2*M_PI until it is greater than angle1. 241 -- 242 -- If there is a current point, an initial line segment will be added to the 243 -- path to connect the current point to the beginning of the arc. 244 -- 245 -- Angles are measured in radians. An angle of 0.0 is in the direction of the 246 -- positive X axis (in user space). An angle of M_PI/2.0 radians (90 degrees) 247 -- is in the direction of the positive Y axis (in user space). Angles 248 -- increase in the direction from the positive X axis toward the positive Y 249 -- axis. So with the default transformation matrix, angles increase in a 250 -- clockwise direction. 251 -- 252 -- (To convert from degrees to radians, use degrees * (M_PI / 180.).) 253 -- 254 -- This function gives the arc in the direction of increasing angles; see 255 -- cairo_arc_negative() to get the arc in the direction of decreasing angles. 256 -- 257 -- The arc is circular in user space. To achieve an elliptical arc, you can 258 -- scale the current transformation matrix by different amounts in the X and 259 -- Y directions. For example, to draw an ellipse in the box given by x, y, 260 -- width, height: 261 -- 262 -- cairo_save (cr); 263 -- cairo_translate (cr, x + width / 2., y + height / 2.); 264 -- cairo_scale (cr, 1. / (height / 2.), 1. / (width / 2.)); 265 -- cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI); 266 -- cairo_restore (cr); 267 -- 268 -- cr : a cairo context 269 -- xc : X position of the center of the arc 270 -- yc : Y position of the center of the arc 271 -- radius : the radius of the arc 272 -- angle1 : the start angle, in radians 273 -- angle2 : the end angle, in radians 274 -- 275 -- -------------------------------------------------------------------------- 276 -- 277 -- cairo_arc_negative () 278 -- 279 -- void cairo_arc_negative (cairo_t *cr, 280 -- double xc, 281 -- double yc, 282 -- double radius, 283 -- double angle1, 284 -- double angle2); 285 -- 286 -- Adds a circular arc of the given radius to the current path. The arc is 287 -- centered at (xc, yc), begins at angle1 and proceeds in the direction of 288 -- decreasing angles to end at angle2. If angle2 is greater than angle1 it 289 -- will be progressively decreased by 2*M_PI until it is greater than angle1. 290 -- 291 -- See cairo_arc() for more details. This function differs only in the 292 -- direction of the arc between the two angles. 293 -- 294 -- cr : a cairo context 295 -- xc : X position of the center of the arc 296 -- yc : Y position of the center of the arc 297 -- radius : the radius of the arc 298 -- angle1 : the start angle, in radians 299 -- angle2 : the end angle, in radians 300 -- 301 -- -------------------------------------------------------------------------- 302 -- 303 -- cairo_curve_to () 304 -- 305 -- void cairo_curve_to (cairo_t *cr, 306 -- double x1, 307 -- double y1, 308 -- double x2, 309 -- double y2, 310 -- double x3, 311 -- double y3); 312 -- 313 -- Adds a cubic Bezier spline to the path from the current point to position 314 -- (x3, y3) in user-space coordinates, using (x1, y1) and (x2, y2) as the 315 -- control points. After this call the current point will be (x3, y3). 316 -- 317 -- If there is no current point before the call to cairo_curve_to() this 318 -- function will behave as if preceded by a call to cairo_move_to (cr, x1, 319 -- y1). 320 -- 321 -- cr : a cairo context 322 -- x1 : the X coordinate of the first control point 323 -- y1 : the Y coordinate of the first control point 324 -- x2 : the X coordinate of the second control point 325 -- y2 : the Y coordinate of the second control point 326 -- x3 : the X coordinate of the end of the curve 327 -- y3 : the Y coordinate of the end of the curve 328 -- 329 -- -------------------------------------------------------------------------- 330 -- 331 -- cairo_line_to () 332 -- 333 -- void cairo_line_to (cairo_t *cr, 334 -- double x, 335 -- double y); 336 -- 337 -- Adds a line to the path from the current point to position (x, y) in 338 -- user-space coordinates. After this call the current point will be (x, y). 339 -- 340 -- If there is no current point before the call to cairo_line_to() this 341 -- function will behave as cairo_move_to (cr, x, y). 342 -- 343 -- cr : a cairo context 344 -- x : the X coordinate of the end of the new line 345 -- y : the Y coordinate of the end of the new line 346 -- 347 -- -------------------------------------------------------------------------- 348 -- 349 -- cairo_move_to () 350 -- 351 -- void cairo_move_to (cairo_t *cr, 352 -- double x, 353 -- double y); 354 -- 355 -- Begin a new sub-path. After this call the current point will be (x, y). 356 -- 357 -- cr : a cairo context 358 -- x : the X coordinate of the new position 359 -- y : the Y coordinate of the new position 360 -- 361 -- -------------------------------------------------------------------------- 362 -- 363 -- cairo_rectangle () 364 -- 365 -- void cairo_rectangle (cairo_t *cr, 366 -- double x, 367 -- double y, 368 -- double width, 369 -- double height); 370 -- 371 -- Adds a closed sub-path rectangle of the given size to the current path at 372 -- position (x, y) in user-space coordinates. 373 -- 374 -- This function is logically equivalent to: 375 -- 376 -- cairo_move_to (cr, x, y); 377 -- cairo_rel_line_to (cr, width, 0); 378 -- cairo_rel_line_to (cr, 0, height); 379 -- cairo_rel_line_to (cr, -width, 0); 380 -- cairo_close_path (cr); 381 -- 382 -- cr : a cairo context 383 -- x : the X coordinate of the top left corner of the rectangle 384 -- y : the Y coordinate to the top left corner of the rectangle 385 -- width : the width of the rectangle 386 -- height : the height of the rectangle 387 -- 388 -- -------------------------------------------------------------------------- 389 -- 390 -- cairo_glyph_path () 391 -- 392 -- void cairo_glyph_path (cairo_t *cr, 393 -- cairo_glyph_t *glyphs, 394 -- int num_glyphs); 395 -- 396 -- cr : 397 -- glyphs : 398 -- num_glyphs : 399 -- 400 -- -------------------------------------------------------------------------- 401 -- 402 -- cairo_text_path () 403 -- 404 -- void cairo_text_path (cairo_t *cr, 405 -- const char *utf8); 406 -- 407 -- cr : 408 -- utf8 : 409 -- 410 -- -------------------------------------------------------------------------- 411 -- 412 -- cairo_rel_curve_to () 413 -- 414 -- void cairo_rel_curve_to (cairo_t *cr, 415 -- double dx1, 416 -- double dy1, 417 -- double dx2, 418 -- double dy2, 419 -- double dx3, 420 -- double dy3); 421 -- 422 -- Relative-coordinate version of cairo_curve_to(). All offsets are relative 423 -- to the current point. Adds a cubic Bezier spline to the path from the 424 -- current point to a point offset from the current point by (dx3, dy3), 425 -- using points offset by (dx1, dy1) and (dx2, dy2) as the control points. 426 -- After this call the current point will be offset by (dx3, dy3). 427 -- 428 -- Given a current point of (x, y), cairo_rel_curve_to (cr, dx1, dy1, dx2, 429 -- dy2, dx3, dy3) is logically equivalent to cairo_curve_to (cr, x + dx1, y + 430 -- dy1, x + dx2, y + dy2, x + dx3, y + dy3). 431 -- 432 -- It is an error to call this function with no current point. Doing so will 433 -- cause cr to shutdown with a status of CAIRO_STATUS_NO_CURRENT_POINT. 434 -- 435 -- cr : a cairo context 436 -- dx1 : the X offset to the first control point 437 -- dy1 : the Y offset to the first control point 438 -- dx2 : the X offset to the second control point 439 -- dy2 : the Y offset to the second control point 440 -- dx3 : the X offset to the end of the curve 441 -- dy3 : the Y offset to the end of the curve 442 -- 443 -- -------------------------------------------------------------------------- 444 -- 445 -- cairo_rel_line_to () 446 -- 447 -- void cairo_rel_line_to (cairo_t *cr, 448 -- double dx, 449 -- double dy); 450 -- 451 -- Relative-coordinate version of cairo_line_to(). Adds a line to the path 452 -- from the current point to a point that is offset from the current point by 453 -- (dx, dy) in user space. After this call the current point will be offset 454 -- by (dx, dy). 455 -- 456 -- Given a current point of (x, y), cairo_rel_line_to(cr, dx, dy) is 457 -- logically equivalent to cairo_line_to (cr, x + dx, y + dy). 458 -- 459 -- It is an error to call this function with no current point. Doing so will 460 -- cause cr to shutdown with a status of CAIRO_STATUS_NO_CURRENT_POINT. 461 -- 462 -- cr : a cairo context 463 -- dx : the X offset to the end of the new line 464 -- dy : the Y offset to the end of the new line 465 -- 466 -- -------------------------------------------------------------------------- 467 -- 468 -- cairo_rel_move_to () 469 -- 470 -- void cairo_rel_move_to (cairo_t *cr, 471 -- double dx, 472 -- double dy); 473 -- 474 -- Begin a new sub-path. After this call the current point will offset by (x, 475 -- y). 476 -- 477 -- Given a current point of (x, y), cairo_rel_move_to(cr, dx, dy) is 478 -- logically equivalent to cairo_move_to (cr, x + dx, y + dy). 479 -- 480 -- It is an error to call this function with no current point. Doing so will 481 -- cause cr to shutdown with a status of CAIRO_STATUS_NO_CURRENT_POINT. 482 -- 483 -- cr : a cairo context 484 -- dx : the X offset 485 -- dy : the Y offset 486 487feature {ANY} -- Access 488 489 status: INTEGER 490 -- The current error status 491 do 492 Result := cairo_path_get_status (handle) 493 ensure 494 is_valid_cairo_status (Result) 495 end 496 497end -- class CAIRO_PATH