From e08fffdfe08bbc9320e39a15d162b6501abd4925 Mon Sep 17 00:00:00 2001 From: engelsman Date: Tue, 14 Oct 2008 21:42:24 +0000 Subject: [PATCH] copied more documentation from drawing.dox to {fl_curve,fl_vertex}.cxx git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6430 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- FL/fl_draw.H | 3 +- src/fl_curve.cxx | 18 ++++++++ src/fl_vertex.cxx | 109 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 129 insertions(+), 1 deletion(-) diff --git a/FL/fl_draw.H b/FL/fl_draw.H index 370f1cb0b..eb83c6f47 100644 --- a/FL/fl_draw.H +++ b/FL/fl_draw.H @@ -115,6 +115,7 @@ FL_EXPORT void fl_yxline(int x, int y, int y1, int x2, int y3); // circular lines and pie slices (code in fl_arci.C): FL_EXPORT void fl_arc(int x, int y, int w, int h, double a1, double a2); FL_EXPORT void fl_pie(int x, int y, int w, int h, double a1, double a2); +/** fl_chord declaration is a place holder - the function does not yet exist */ FL_EXPORT void fl_chord(int x, int y, int w, int h, double a1, double a2); // nyi // scalable drawing code (code in fl_vertex.C and fl_arc.C): @@ -130,7 +131,7 @@ FL_EXPORT void fl_begin_line(); FL_EXPORT void fl_begin_loop(); FL_EXPORT void fl_begin_polygon(); FL_EXPORT void fl_vertex(double x, double y); -FL_EXPORT void fl_curve(double, double, double, double, double, double, double, double); +FL_EXPORT void fl_curve(double X0, double Y0, double X1, double Y1, double X2, double Y2, double X3, double Y3); FL_EXPORT void fl_arc(double x, double y, double r, double start, double a); FL_EXPORT void fl_circle(double x, double y, double r); FL_EXPORT void fl_end_points(); diff --git a/src/fl_curve.cxx b/src/fl_curve.cxx index 9a47a10a3..26750d89b 100644 --- a/src/fl_curve.cxx +++ b/src/fl_curve.cxx @@ -25,6 +25,16 @@ // http://www.fltk.org/str.php // +/** + \file fl_curve.cxx + \brief Utility for drawing Bezier curves, adding the points to the + current fl_begin/fl_vertex/fl_end path. + + Incremental math implementation: + I very much doubt this is optimal! From Foley/vanDam page 511. + If anybody has a better algorithim, please send it! +*/ + // Utility for drawing Bezier curves, adding the points to // the current fl_begin/fl_vertex/fl_end path. // Incremental math implementation: @@ -34,6 +44,14 @@ #include #include +/** + Add a series of points on a Bezier curve to the path. + The curve ends (and two of the points) are at X0,Y0 and X3,Y3. + \param[in] X0,Y0 curve start point + \param[in] X1,Y1 curve control point + \param[in] X2,Y2 curve control point + \param[in] X3,Y3 curve end point +*/ void fl_curve(double X0, double Y0, double X1, double Y1, double X2, double Y2, diff --git a/src/fl_vertex.cxx b/src/fl_vertex.cxx index acc8db9af..d563166e7 100644 --- a/src/fl_vertex.cxx +++ b/src/fl_vertex.cxx @@ -25,6 +25,12 @@ // http://www.fltk.org/str.php // +/** + \file fl_vertex.cxx + \brief Portable drawing code for drawing arbitrary shapes with + simple 2D transformations. +*/ + // Portable drawing code for drawing arbitrary shapes with // simple 2D transformations. See also fl_arc.cxx @@ -45,6 +51,10 @@ static matrix m = {1, 0, 0, 1, 0, 0}; static matrix stack[32]; static int sptr = 0; +/** + Save the current transformation matrix on the stack. + The maximum depth of the stack is 4. +*/ void fl_push_matrix() { if (sptr==32) Fl::error("fl_push_matrix(): matrix stack overflow."); @@ -52,6 +62,9 @@ void fl_push_matrix() { stack[sptr++] = m; } +/** + Restore the current transformation matrix from the stack. +*/ void fl_pop_matrix() { if (sptr==0) Fl::error("fl_pop_matrix(): matrix stack underflow."); @@ -59,6 +72,11 @@ void fl_pop_matrix() { m = stack[--sptr]; } +/** + Concatenate another transformation onto the current one. + \param[in] a,b,c,d,x,y transformation matrix elements such that + X' = aX + cY + x and Y' = bX +dY + y +*/ void fl_mult_matrix(double a, double b, double c, double d, double x, double y) { matrix o; o.a = a*m.a + b*m.c; @@ -70,12 +88,28 @@ void fl_mult_matrix(double a, double b, double c, double d, double x, double y) m = o; } +/** + Concatenate scaling transformation onto the current one. + \param[in] x,y scale factors in x-direction and y-direction +*/ void fl_scale(double x,double y) {fl_mult_matrix(x,0,0,y,0,0);} +/** + Concatenate scaling transformation onto the current one. + \param[in] x scale factor in both x-direction and y-direction +*/ void fl_scale(double x) {fl_mult_matrix(x,0,0,x,0,0);} +/** + Concatenate translation transformation onto the current one. + \param[in] x,y translation factor in x-direction and y-direction +*/ void fl_translate(double x,double y) {fl_mult_matrix(1,0,0,1,x,y);} +/** + Concatenate rotation transformation onto the current one. + \param[in] d - rotation angle, counter-clockwise in degrees (not radians) +*/ void fl_rotate(double d) { if (d) { double s, c; @@ -109,20 +143,48 @@ static int n; static int what; enum {LINE, LOOP, POLYGON, POINT_}; +/** + Start drawing a list of points. Points are added to the list with fl_vertex() +*/ void fl_begin_points() {n = 0; what = POINT_;} +/** + Start drawing a list of lines. +*/ void fl_begin_line() {n = 0; what = LINE;} +/** + Start drawing a closed sequence of lines. +*/ void fl_begin_loop() {n = 0; what = LOOP;} +/** + Start drawing a convex filled polygon. +*/ void fl_begin_polygon() {n = 0; what = POLYGON;} +/** + Transform coordinate using current transformation matrix. + \param[in] x,y coordinate +*/ double fl_transform_x(double x, double y) {return x*m.a + y*m.c + m.x;} +/** + Transform coordinate using current transformation matrix. + \param[in] x,y coordinate +*/ double fl_transform_y(double x, double y) {return x*m.b + y*m.d + m.y;} +/** + Transform distance using current transformation matrix. + \param[in] x,y coordinate +*/ double fl_transform_dx(double x, double y) {return x*m.a + y*m.c;} +/** + Transform distance using current transformation matrix. + \param[in] x,y coordinate +*/ double fl_transform_dy(double x, double y) {return x*m.b + y*m.d;} static void fl_transformed_vertex(COORD_T x, COORD_T y) { @@ -137,6 +199,10 @@ static void fl_transformed_vertex(COORD_T x, COORD_T y) { } } +/** + Add coordinate pair to the vertex list without further transformations. + \param[in] xf,yf transformed coordinate +*/ void fl_transformed_vertex(double xf, double yf) { #ifdef __APPLE_QUARTZ__ fl_transformed_vertex(COORD_T(xf), COORD_T(yf)); @@ -145,10 +211,17 @@ void fl_transformed_vertex(double xf, double yf) { #endif } +/** + Add a single vertex to the current path. + \param[in] x,y coordinate +*/ void fl_vertex(double x,double y) { fl_transformed_vertex(x*m.a + y*m.c + m.x, x*m.b + y*m.d + m.y); } +/** + End list of points, and draw +*/ void fl_end_points() { #if defined(USE_X11) if (n>1) XDrawPoints(fl_display, fl_window, fl_gc, p, n, 0); @@ -167,6 +240,9 @@ void fl_end_points() { #endif } +/** + End list of lines, and draw +*/ void fl_end_line() { if (n < 2) { fl_end_points(); @@ -191,12 +267,18 @@ static void fixloop() { // remove equal points from closed path while (n>2 && p[n-1].x == p[0].x && p[n-1].y == p[0].y) n--; } +/** + End closed sequence of lines, and draw +*/ void fl_end_loop() { fixloop(); if (n>2) fl_transformed_vertex((COORD_T)p[0].x, (COORD_T)p[0].y); fl_end_line(); } +/** + End convex filled polygon, and draw +*/ void fl_end_polygon() { fixloop(); if (n < 3) { @@ -228,6 +310,19 @@ static int counts[20]; static int numcount; #endif +/** + Start drawing a complex filled polygon. The polygon may be concave, may + have holes in it, or may be several disconnected pieces. Call fl_gap() to + seperate loops of the path. + + To outline the polygone, use fl_begin_loop() and reaplace each fl_gap() + with fl_end_loop();fl_begin_loop() pairs. + + \note + For portability, you should only draw polygons that appear the same + whether "even/odd" or "non-zero" winding rules are used to fill them. + Holes should be drawn in the opposite direction to the outside loop. +*/ void fl_begin_complex_polygon() { fl_begin_polygon(); gap = 0; @@ -236,6 +331,11 @@ void fl_begin_complex_polygon() { #endif } +/** + Call fl_gap() to separate loops of the path. + It is unnecessary but harmless to call fl_gap() before the first vertex, + after the last vertex, or several times in a row. +*/ void fl_gap() { while (n>gap+2 && p[n-1].x == p[gap].x && p[n-1].y == p[gap].y) n--; if (n > gap+2) { @@ -249,6 +349,9 @@ void fl_gap() { } } +/** + End complex filled polygon, and draw +*/ void fl_end_complex_polygon() { fl_gap(); if (n < 3) { @@ -278,6 +381,12 @@ void fl_end_complex_polygon() { // warning: these do not draw rotated ellipses correctly! // See fl_arc.c for portable version. +/** + fl_circle() is equivalent to fl_arc(...,0,360) but may be faster. + It must be the \e only thing in the path: if you want a circle as part of + a complex polygon you must use fl_arc() + \param[in] x,y,r center and radius of circle +*/ void fl_circle(double x, double y,double r) { double xt = fl_transform_x(x,y); double yt = fl_transform_y(x,y);