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

@@ -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();

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 <FL/fl_draw.H>
 #include <math.h>
 
+/**
+  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,

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
+             <tt> X' = aX + cY + x </tt> and <tt> Y' = bX +dY + y </tt>
+*/
 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);