Add Doxygen comments for members of the Fl_Graphics_Driver class.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3-porting@11689 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

FL/Fl_Graphics_Driver.H

@@ -33,7 +33,12 @@
 #include <stdlib.h>
 
 class Fl_Graphics_Driver;
-class Fl_Font_Descriptor;
+/** a platform-specific class implementing a system font */
+class Fl_Font_Descriptor
+#ifdef FL_DOXYGEN
+{}
+#endif
+;
 /** \brief Points to the driver that currently receives all graphics requests */
 FL_EXPORT extern Fl_Graphics_Driver *fl_graphics_driver;
 
@@ -66,14 +71,19 @@ typedef void (*Fl_Draw_Image_Cb)(void* data,int x,int y,int w,uchar* buf);
   */
 class FL_EXPORT Fl_Graphics_Driver {
   friend class Fl_Surface_Device;
+  friend class Fl_Display_Device;
   friend class Fl_Pixmap;
   friend class Fl_Bitmap;
   friend class Fl_RGB_Image;
   friend int fl_draw_pixmap(const char*const* cdata, int x, int y, Fl_Color bg);
+  friend void gl_start();
 public:
   // The following functions create the various graphics drivers that are required
   // for core operations. They must be implemented as members of Fl_Graphics_Driver,
   // but located in the device driver module that is linked to the core library
+  /** Instantiate the graphics driver adequate to draw to the platform's display driver.
+   Each platform implements this method its own way.
+   */
   static Fl_Graphics_Driver *newMainGraphicsDriver();
   //static Fl_Graphics_Driver *newOpenGLGraphicsDriver();
   //static Fl_Graphics_Driver *newPrinterGraphicsDriver();
@@ -87,57 +97,84 @@ public:
     PRINTER = 2 /**< graphics driver for a printer drawing surface */
   } driver_feature;
 
-  int fl_clip_state_number;
 protected:
-  static const matrix m0;
-  Fl_Font font_; // current font
-  Fl_Fontsize size_; // current font size
-  Fl_Color color_; // current color
-  int sptr;
-  static const int matrix_stack_size = FL_MATRIX_STACK_SIZE;
-  matrix stack[FL_MATRIX_STACK_SIZE];
-  matrix m;
-  int n, gap_;
-  int what;
-  int rstackptr;
-  static const int region_stack_max = FL_REGION_STACK_SIZE - 1;
-  Fl_Region rstack[FL_REGION_STACK_SIZE];
-  Fl_Font_Descriptor *font_descriptor_;
+  int fl_clip_state_number; ///< For internal use by FLTK
+  static const matrix m0; ///< For internal use by FLTK
+  Fl_Font font_; ///< current font
+  Fl_Fontsize size_; ///< current font size
+  Fl_Color color_; ///< current color
+  int sptr;///< For internal use by FLTK
+  static const int matrix_stack_size = FL_MATRIX_STACK_SIZE; ///< For internal use by FLTK
+  matrix stack[FL_MATRIX_STACK_SIZE]; ///< For internal use by FLTK
+  matrix m; ///< current transformation matrix
+  int n; ///< For internal use by FLTK
+  int gap_; ///< For internal use by FLTK
+  int what; ///< For internal use by FLTK
+  int rstackptr; ///< For internal use by FLTK
+  static const int region_stack_max = FL_REGION_STACK_SIZE - 1; ///< For internal use by FLTK
+  Fl_Region rstack[FL_REGION_STACK_SIZE]; ///< For internal use by FLTK
+  Fl_Font_Descriptor *font_descriptor_; ///< For internal use by FLTK
 #ifndef FL_DOXYGEN
   enum {LINE, LOOP, POLYGON, POINT_};
   inline int vertex_no() { return n; }
   inline int vertex_kind() {return what;}
 #endif
   matrix *fl_matrix; /**< Points to the current coordinate transformation matrix */
+  /** Returns whether the graphics driver is currently drawing to a high resolution surface */
+  virtual bool high_resolution() { return false; }
+  virtual void global_gc();
+  virtual fl_uintptr_t cache(Fl_Pixmap *img, int w, int h, const char *const*array) { return 0; }
+  virtual fl_uintptr_t cache(Fl_Bitmap *img, int w, int h, const uchar *array) { return 0; }
+  virtual void uncache(Fl_RGB_Image *img, fl_uintptr_t &id_, fl_uintptr_t &mask_) { }
 
-  // === all code below in this class has been to the reorganisation FL_PORTING process
 public:
   Fl_Graphics_Driver();
-  virtual ~Fl_Graphics_Driver() {}
+  virtual ~Fl_Graphics_Driver() {} ///< Destructor
   static Fl_Graphics_Driver &default_driver();
+  /** Return whether the graphics driver can do alpha blending */
   virtual char can_do_alpha_blending() { return 0; }
   // --- implementation is in src/fl_rect.cxx which includes src/drivers/xxx/Fl_xxx_Graphics_Driver_rect.cxx
+  /** see fl_point() */
   virtual void point(int x, int y) = 0;
+  /** see fl_rect() */
   virtual void rect(int x, int y, int w, int h) = 0;
   virtual void focus_rect(int x, int y, int w, int h);
+  /** see fl_rectf() */
   virtual void rectf(int x, int y, int w, int h) = 0;
+  /** see fl_line(int, int, int, int) */
   virtual void line(int x, int y, int x1, int y1) = 0;
+  /** see fl_line(int, int, int, int, int, int) */
   virtual void line(int x, int y, int x1, int y1, int x2, int y2) = 0;
+  /** see fl_xyline(int, int, int) */
   virtual void xyline(int x, int y, int x1) = 0;
+  /** see fl_xyline(int, int, int, int) */
   virtual void xyline(int x, int y, int x1, int y2) = 0;
+  /** see fl_xyline(int, int, int, int, int) */
   virtual void xyline(int x, int y, int x1, int y2, int x3) = 0;
+  /** see fl_yxline(int, int, int) */
   virtual void yxline(int x, int y, int y1) = 0;
+  /** see fl_yxline(int, int, int, int) */
   virtual void yxline(int x, int y, int y1, int x2) = 0;
+  /** see fl_yxline(int, int, int, int, int) */
   virtual void yxline(int x, int y, int y1, int x2, int y3) = 0;
+  /** see fl_loop(int, int, int, int, int, int) */
   virtual void loop(int x0, int y0, int x1, int y1, int x2, int y2) = 0;
+  /** see fl_loop(int, int, int, int, int, int, int, int) */
   virtual void loop(int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3) = 0;
+  /** see fl_polygon(int, int, int, int, int, int) */
   virtual void polygon(int x0, int y0, int x1, int y1, int x2, int y2) = 0;
+  /** see fl_polygon(int, int, int, int, int, int, int, int) */
   virtual void polygon(int x0, int y0, int x1, int y1, int x2, int y2, int x3, int y3) = 0;
   // --- clipping
+  /** see fl_push_clip() */
   virtual void push_clip(int x, int y, int w, int h) = 0;
+  /** see fl_clip_box() */
   virtual int clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H) = 0;
+  /** see fl_not_clipped() */
   virtual int not_clipped(int x, int y, int w, int h) = 0;
+  /** see fl_push_no_clip() */
   virtual void push_no_clip() = 0;
+  /** see fl_pop_clip() */
   virtual void pop_clip() = 0;
   virtual Fl_Region clip_region();              // has default implementation
   virtual void clip_region(Fl_Region r);        // has default implementation
@@ -154,57 +191,83 @@ public:
   virtual void begin_line();
   virtual void begin_loop();
   virtual void begin_polygon();
+  /** see fl_begin_complex_polygon() */
   virtual void begin_complex_polygon() = 0;
   virtual double transform_x(double x, double y);
   virtual double transform_y(double x, double y);
   virtual double transform_dx(double x, double y);
   virtual double transform_dy(double x, double y);
+  /** see fl_transformed_vertex() */
   virtual void transformed_vertex(double xf, double yf) = 0;
+  /** see fl_vertex() */
   virtual void vertex(double x, double y) = 0;
+  /** see fl_end_points() */
   virtual void end_points() = 0;
+  /** see fl_end_line() */
   virtual void end_line() = 0;
+  /** see fl_end_loop() */
   virtual void end_loop() = 0;
+  /** see fl_end_polygon() */
   virtual void end_polygon() = 0;
+  /** see fl_end_complex_polygon() */
   virtual void end_complex_polygon() = 0;
+  /** see fl_gap() */
   virtual void gap() = 0;
+  /** see fl_circle() */
   virtual void circle(double x, double y, double r) = 0;
   // --- implementation is in src/fl_arc.cxx which includes src/drivers/xxx/Fl_xxx_Graphics_Driver_arc.cxx if needed
   virtual void arc(double x, double y, double r, double start, double end);
   // --- implementation is in src/fl_arci.cxx which includes src/drivers/xxx/Fl_xxx_Graphics_Driver_arci.cxx
+  /** see fl_arc(int x, int y, int w, int h, double a1, double a2) */
   virtual void arc(int x, int y, int w, int h, double a1, double a2) = 0;
+  /** see fl_pie() */
   virtual void pie(int x, int y, int w, int h, double a1, double a2) = 0;
   // --- implementation is in src/fl_curve.cxx which includes src/drivers/xxx/Fl_xxx_Graphics_Driver_curve.cxx if needed
   virtual void curve(double X0, double Y0, double X1, double Y1, double X2, double Y2, double X3, double Y3);
   // --- implementation is in src/fl_line_style.cxx which includes src/cfg_gfx/xxx_line_style.cxx
+  /** see fl_line_style() */
   virtual void line_style(int style, int width=0, char* dashes=0) = 0;
   // --- implementation is in src/fl_color.cxx which includes src/cfg_gfx/xxx_color.cxx
+  /** see fl_color(Fl_Color) */
   virtual void color(Fl_Color c) { color_ = c; }
   virtual void set_color(Fl_Color i, unsigned int c);
   virtual void free_color(Fl_Color i, int overlay);
+  /** see fl_color(void) */
   virtual Fl_Color color() { return color_; }
+  /** see fl_color(uchar, uchar, uchar) */
   virtual void color(uchar r, uchar g, uchar b) = 0;
   // --- implementation is in src/fl_font.cxx which includes src/drivers/xxx/Fl_xxx_Graphics_Driver_font.cxx
+  /** see fl_draw(const char *str, int n, int x, int y) */
   virtual void draw(const char *str, int n, int x, int y) = 0;
+  /** Draw the first \p n bytes of the string \p str starting at position \p x , \p y */
   virtual void draw(const char *str, int n, float x, float y) { draw(str, n, (int)(x+0.5), (int)(y+0.5));}
+  /** see fl_draw(int angle, const char *str, int n, int x, int y) */
   virtual void draw(int angle, const char *str, int n, int x, int y) { draw(str, n, x, y); }
+  /** see fl_rtl_draw(const char *str, int n, int x, int y) */
   virtual void rtl_draw(const char *str, int n, int x, int y) { draw(str, n, x, y); }
   /** Returns non-zero if the graphics driver possesses the \p feature */
   virtual int has_feature(driver_feature feature) { return 0; }
+  /** see fl_font(Fl_Font, Fl_Fontsize) */
   virtual void font(Fl_Font face, Fl_Fontsize fsize) {font_ = face; size_ = fsize;}
+  /** see fl_font(void) */
   virtual Fl_Font font() {return font_; }
+  /** Return the current font size */
   virtual Fl_Fontsize size() {return size_; }
+  /** Compute the width of the first \p n bytes of the string \p str if drawn with current font */
   virtual double width(const char *str, int n) { return 0; }
+  /** Compute the width of Unicode character \p c if drawn with current font */
   virtual double width(unsigned int c) { char ch = (char)c; return width(&ch, 1); }
   virtual void text_extents(const char*, int n, int& dx, int& dy, int& w, int& h);
+  /** Return the current line height */
   virtual int height() { return size(); }
+  /** Return the current line descent */
   virtual int descent() { return 0; }
+  /** Return the current Fl_Font_Descriptor */
   virtual Fl_Font_Descriptor *font_descriptor() { return font_descriptor_;}
+  /** Set the current Fl_Font_Descriptor */
   virtual void font_descriptor(Fl_Font_Descriptor *d) { font_descriptor_ = d;}
   // --- implementation is in src/fl_image.cxx which includes src/drivers/xxx/Fl_xxx_Graphics_Driver_font.cxx
   virtual Fl_Bitmask create_bitmask(int w, int h, const uchar *array) = 0;
-  virtual fl_uintptr_t cache(Fl_Pixmap *img, int w, int h, const char *const*array) { return 0; }
-  virtual fl_uintptr_t cache(Fl_Bitmap *img, int w, int h, const uchar *array) { return 0; }
-  virtual void uncache(Fl_RGB_Image *img, fl_uintptr_t &id_, fl_uintptr_t &mask_) { }
   virtual void delete_bitmask(Fl_Bitmask bm) = 0;
   virtual void draw_image(const uchar* buf, int X,int Y,int W,int H, int D=3, int L=0) {}
   virtual void draw_image_mono(const uchar* buf, int X,int Y,int W,int H, int D=1, int L=0) {}
@@ -240,8 +303,10 @@ public:
   /** Support for pixmap drawing */
   virtual void mask_bitmap(uchar **) {}
   // default implementation may be enough
+  /** Support for PostScript drawing */
   virtual float scale_font_for_PostScript(Fl_Font_Descriptor *desc, int s) { return float(s); }
   // default implementation may be enough
+  /** Support for PostScript drawing */
   virtual float scale_bitmap_for_PostScript() { return 2; }
   virtual void set_spot(int font, int size, int X, int Y, int W, int H, Fl_Window *win);
   virtual void reset_spot();
@@ -249,11 +314,6 @@ public:
   virtual void add_rectangle_to_region(Fl_Region r, int x, int y, int w, int h);
   virtual Fl_Region XRectangleRegion(int x, int y, int w, int h);
   virtual void XDestroyRegion(Fl_Region r);
-  // the default implementation may be enough
-  virtual bool high_resolution() { return false; }
-protected:
-  // --- implementation is in src/fl_vertex.cxx which includes src/cfg_gfx/xxx_rect.cxx
-  virtual void global_gc();
 };
 
 #endif // FL_GRAPHICS_DRIVER_H

src/Fl_Device.cxx

@@ -78,6 +78,7 @@ Fl_Display_Device *Fl_Display_Device::display_device() {
   return display;
 };
 
+/** Returns whether the drawing system is currently targetted to a high resolution display */
 bool Fl_Display_Device::high_resolution()
 {
   return Fl_Display_Device::display_device()->driver()->high_resolution();

src/Fl_Graphics_Driver.cxx

@@ -22,11 +22,13 @@
 #include <FL/Fl_Image.H>
 #include <FL/fl_draw.H>
 
-FL_EXPORT Fl_Graphics_Driver *fl_graphics_driver; // the current target device of graphics operations
+FL_EXPORT Fl_Graphics_Driver *fl_graphics_driver; // the current driver of graphics operations
 
 const Fl_Graphics_Driver::matrix Fl_Graphics_Driver::m0 = {1, 0, 0, 1, 0, 0};
 
-Fl_Graphics_Driver::Fl_Graphics_Driver() {
+/** Constructor */
+Fl_Graphics_Driver::Fl_Graphics_Driver()
+{
   font_ = 0;
   size_ = 0;
   sptr=0; rstackptr=0; 
@@ -37,7 +39,7 @@ Fl_Graphics_Driver::Fl_Graphics_Driver() {
   font_descriptor_ = NULL;
 };
 
-
+/** Return the graphics driver used when drawing to the platform's display */
 Fl_Graphics_Driver &Fl_Graphics_Driver::default_driver()
 {
   static Fl_Graphics_Driver *pMainDriver = 0L;
@@ -48,7 +50,7 @@ Fl_Graphics_Driver &Fl_Graphics_Driver::default_driver()
 }
 
 
-
+/** see fl_text_extents() */
 void Fl_Graphics_Driver::text_extents(const char*t, int n, int& dx, int& dy, int& w, int& h)
 {
   w = (int)width(t, n);
@@ -57,6 +59,7 @@ void Fl_Graphics_Driver::text_extents(const char*t, int n, int& dx, int& dy, int
   dy = descent();
 }
 
+/** see fl_focus_rect() */
 void Fl_Graphics_Driver::focus_rect(int x, int y, int w, int h)
 {
   line_style(FL_DOT);
@@ -81,50 +84,54 @@ void Fl_Graphics_Driver::copy_offscreen(int x, int y, int w, int h, Fl_Offscreen
   delete[] img;
 }
 
-
+/** see fl_set_spot() */
 void Fl_Graphics_Driver::set_spot(int font, int size, int X, int Y, int W, int H, Fl_Window *win)
 {
   // nothing to do, reimplement in driver if needed
 }
 
 
+/** see fl_reset_spot() */
 void Fl_Graphics_Driver::reset_spot()
 {
   // nothing to do, reimplement in driver if needed
 }
 
 
+/** Sets the value of the fl_gc global variable when it changes */
 void Fl_Graphics_Driver::global_gc()
 {
   // nothing to do, reimplement in driver if needed
 }
 
 
-void Fl_Graphics_Driver::set_color(Fl_Color i, unsigned int c)
+/** see Fl::set_color(Fl_Color, unsigned) */
+void Fl_Graphics_Driver::set_color(Fl_Color i, unsigned c)
 {
   // nothing to do, reimplement in driver if needed
 }
 
 
+/** see Fl::free_color(Fl_Color, int) */
 void Fl_Graphics_Driver::free_color(Fl_Color i, int overlay)
 {
   // nothing to do, reimplement in driver if needed
 }
 
-
+/** Add a rectangle to an Fl_Region */
 void Fl_Graphics_Driver::add_rectangle_to_region(Fl_Region r, int x, int y, int w, int h)
 {
   // nothing to do, reimplement in driver if needed
 }
 
-
+/** Create a rectangular Fl_Region */
 Fl_Region Fl_Graphics_Driver::XRectangleRegion(int x, int y, int w, int h)
 {
   // nothing to do, reimplement in driver if needed
   return 0;
 }
 
-
+/** Delete an Fl_Region */
 void Fl_Graphics_Driver::XDestroyRegion(Fl_Region r)
 {
   // nothing to do, reimplement in driver if needed

src/Fl_Image_Surface.cxx

@@ -58,6 +58,7 @@ void Fl_Image_Surface::translate(int x, int y) {platform_surface->translate(x, y
 
 void Fl_Image_Surface::untranslate() {platform_surface->untranslate();}
 
+/** Returns the Fl_Offscreen object associated to the image surface */
 Fl_Offscreen Fl_Image_Surface::offscreen() {return platform_surface->offscreen;}
 
 int Fl_Image_Surface::printable_rect(int *w, int *h)  {return platform_surface->printable_rect(w, h);}

src/Fl_Printer.cxx

@@ -187,6 +187,11 @@ void Fl_Printer::end_job (void)
   printer->end_job();
 }
 
+/** Prints the widget on the drawing surface. 
+ \param[in] widget Any FLTK widget (e.g., standard, custom, window, GL window).
+ \param[in] delta_x,delta_y Optional offsets for positioning the widget's
+ top-left corner relatively to the current origin of graphics functions.
+ */
 void Fl_Printer::print_widget(Fl_Widget* widget, int delta_x, int delta_y)
 {
   printer->draw(widget, delta_x, delta_y);

src/fl_arc.cxx

@@ -34,6 +34,7 @@ static double _fl_hypot(double x, double y) {
   return sqrt(x*x + y*y);
 }
 
+/** see fl_arc(double x, double y, double r, double start, double end) */
 void Fl_Graphics_Driver::arc(double x, double y, double r, double start, double end) {
 
   // draw start point accurately:

src/fl_curve.cxx

@@ -29,6 +29,7 @@
 #include <FL/fl_draw.H>
 #include <math.h>
 
+/** see fl_curve() */
 void Fl_Graphics_Driver::curve(double X0, double Y0,
 	      double X1, double Y1,
 	      double X2, double Y2,

src/fl_rect.cxx

@@ -39,11 +39,12 @@
 extern int fl_line_width_;
 
 
+/** see fl_restore_clip() */
 void Fl_Graphics_Driver::restore_clip() {
   fl_clip_state_number++;
 }
 
-
+/** see fl_clip_region(Fl_Region) */
 void Fl_Graphics_Driver::clip_region(Fl_Region r) {
   Fl_Region oldr = rstack[rstackptr];
   if (oldr) XDestroyRegion(oldr);
@@ -52,6 +53,7 @@ void Fl_Graphics_Driver::clip_region(Fl_Region r) {
 }
 
 
+/** see fl_clip_region(void) */
 Fl_Region Fl_Graphics_Driver::clip_region() {
   return rstack[rstackptr];
 }

src/fl_vertex.cxx

@@ -37,7 +37,7 @@
 #include <FL/math.h>
 #include <stdlib.h>
 
-
+/** see fl_push_matrix() */
 void Fl_Graphics_Driver::push_matrix() {
   if (sptr==matrix_stack_size)
     Fl::error("fl_push_matrix(): matrix stack overflow.");
@@ -45,6 +45,7 @@ void Fl_Graphics_Driver::push_matrix() {
     stack[sptr++] = m;
 }
 
+/** see fl_pop_matrix() */
 void Fl_Graphics_Driver::pop_matrix() {
   if (sptr==0)
     Fl::error("fl_pop_matrix(): matrix stack underflow.");
@@ -52,6 +53,7 @@ void Fl_Graphics_Driver::pop_matrix() {
     m = stack[--sptr];
 }
 
+/** see fl_mult_matrix() */
 void Fl_Graphics_Driver::mult_matrix(double a, double b, double c, double d, double x, double y) {
   matrix o;
   o.a = a*m.a + b*m.c;
@@ -63,6 +65,7 @@ void Fl_Graphics_Driver::mult_matrix(double a, double b, double c, double d, dou
   m = o;
 }
 
+/** see fl_rotate() */
 void Fl_Graphics_Driver::rotate(double d) {
   if (d) {
     double s, c;
@@ -75,50 +78,61 @@ void Fl_Graphics_Driver::rotate(double d) {
   }
 }
 
+/** see fl_scale(double, double) */
 void Fl_Graphics_Driver::scale(double x, double y) {
   mult_matrix(x,0,0,y,0,0);
 }
 
+/** see fl_scale(double) */
 void Fl_Graphics_Driver::scale(double x) {
   mult_matrix(x,0,0,x,0,0);
 }
 
+/** see fl_translate() */
 void Fl_Graphics_Driver::translate(double x,double y) {
   mult_matrix(1,0,0,1,x,y);
 }
 
+/** see fl_begin_points() */
 void Fl_Graphics_Driver::begin_points() {
   n = 0;
   what = POINT_;
 }
 
+/** see fl_begin_line() */
 void Fl_Graphics_Driver::begin_line() {
   n = 0;
   what = LINE;
 }
 
+/** see fl_begin_loop() */
 void Fl_Graphics_Driver::begin_loop() {
   n = 0;
   what = LOOP;
 }
 
+/** see fl_begin_polygon() */
 void Fl_Graphics_Driver::begin_polygon() {
   n = 0;
   what = POLYGON;
 }
 
+/** see fl_transform_x() */
 double Fl_Graphics_Driver::transform_x(double x, double y) {
   return x*m.a + y*m.c + m.x;
 }
 
+/** see fl_transform_y() */
 double Fl_Graphics_Driver::transform_y(double x, double y) {
   return x*m.b + y*m.d + m.y;
 }
 
+/** see fl_transform_dx() */
 double Fl_Graphics_Driver::transform_dx(double x, double y) {
   return x*m.a + y*m.c;
 }
 
+/** see fl_transform_dy() */
 double Fl_Graphics_Driver::transform_dy(double x, double y) {
   return x*m.b + y*m.d;
 }