More detailed documentation about drawing to other surfaces than the computer display.

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

FL/Fl_Device.H

@@ -101,8 +101,8 @@ public:
  in the \ref fl_drawings and \ref fl_attributes modules.
  
  \p The Fl_Graphics_Driver class is of interest if one wants to perform new kinds of drawing operations.
- An example would be to draw to a PDF file. This would involve creating a new Fl_Graphics_Driver derived class,
- say, my_PDF_Graphics_Driver. This new class should implement all virtual methods of the Fl_Graphics_Driver class
+ An example would be to draw to a PDF file. This would involve creating a new Fl_Graphics_Driver derived 
+ class. This new class should implement all virtual methods of the Fl_Graphics_Driver class
  to support all FLTK drawing functions.
   */
 class FL_EXPORT Fl_Graphics_Driver : public Fl_Device {
@@ -534,17 +534,17 @@ public:
 /**
  \brief A drawing surface that's susceptible to receive graphical output.
  A drawing surface is typically used as follows:
- \li Create \c surface, an object from a particular Fl_Surface_Device derived class (e.g., Fl_Copy_Surface, Fl_Printer).
- \li Memorize what is the current drawing surface with <tt> Fl_Surface_Device *old_current = Fl_Surface_Device::surface();</tt>
- \li Call \c surface->set_current(); to redirect all graphics requests to \c surface which becomes the new 
+ <ol><li> Create \c surface, an object from a particular Fl_Surface_Device derived class (e.g., Fl_Copy_Surface, Fl_Printer).
+ <li> Memorize what is the current drawing surface with <tt> Fl_Surface_Device *old_current = Fl_Surface_Device::surface();</tt>
+ <li> Call \c surface->set_current(); to redirect all graphics requests to \c surface which becomes the new
  current drawing surface (not necessary with class Fl_Printer because it is done by Fl_Printer::start_job()).
- \li At this point any of the \ref fl_drawings (e.g., fl_rect()) or the \ref fl_attributes or \ref drawing_images functions 
- (e.g., fl_draw_image(), Fl_Image::draw()) operate on the new current drawing surface. 
+ <li> At this point any of the \ref fl_drawings (e.g., fl_rect()) or the \ref fl_attributes or \ref drawing_images functions
+ (e.g., fl_draw_image(), Fl_Image::draw()) operates on the new current drawing surface.
  Certain drawing surfaces allow additional ways to draw to them (e.g., Fl_Printer::print_widget(), Fl_Image_Surface::draw()).
- \li After all drawing requests have been performed, redirect graphics requests back to their previous destination 
+ <li> After all drawing requests have been performed, redirect graphics requests back to their previous destination
  with \c old_current->set_current();.
- \li Delete \c surface.
- 
+ <li> Delete \c surface.
+ </ol>
  The current drawing surface is initially the computer's display, an instance of the Fl_Display_Device class.
  */
 class FL_EXPORT Fl_Surface_Device : public Fl_Device {
@@ -562,7 +562,8 @@ public:
   inline void driver(Fl_Graphics_Driver *graphics_driver) {_driver = graphics_driver;};
   /** \brief Returns the graphics driver of this drawing surface. */
   inline Fl_Graphics_Driver *driver() {return _driver; };
-  /** \brief the surface that currently receives graphics output */
+  /** The current drawing surface.
+   In other words, the Fl_Surface_Device object that currently receives all graphics output */
   static inline Fl_Surface_Device *surface() {return _surface; }; 
   /** \brief The destructor. */
   virtual ~Fl_Surface_Device() {}

documentation/src/drawing.dox

@@ -6,7 +6,8 @@ This chapter covers the drawing functions that are provided with FLTK.
 
 \section sect_WhenCanYouDraw When Can You Draw Things in FLTK?
 
-There are only certain places you can execute drawing code in FLTK.
+There are only certain places you can execute FLTK code 
+that draws to the computer's display.
 Calling these functions at other places will result in undefined behavior!
 
 \li The most common place is inside the virtual Fl_Widget::draw() method.
@@ -21,6 +22,33 @@ Calling these functions at other places will result in undefined behavior!
 
 \li You can call Fl_Window::make_current() to do incremental update of a
     widget. Use Fl_Widget::window() to find the window.
+    
+In contrast, code that draws to other drawing surfaces than the display
+(i.e., instances of derived classes of the Fl_Surface_Device class, except 
+Fl_Display_Device, such as Fl_Printer and Fl_Copy_Surface) can be executed 
+at any time as follows:
+<ol><li> Memorize what is the current drawing surface calling Fl_Surface_Device::surface(),
+and make your surface the new current drawing surface calling the surface's 
+set_current() function;
+<li> Make a series of calls to any of the drawing functions described below;
+these will operate on the new current drawing surface;
+<li> Set the current drawing surface back to its previous state calling 
+the previous surface's set_current().
+</ol>
+
+\subsection ssect_DrawingUnit What Drawing Unit do FLTK drawing functions use?
+
+When drawing to the display or to instances of Fl_Copy_Surface and Fl_Image_Surface, 
+the unit of drawing functions corresponds
+generally to one pixel. The so-called 'retina' displays of some recent
+Apple computers are an exception to this rule: one drawing unit corresponds
+to the width or the height of 2 display pixels on a retina display.
+
+When drawing to surfaces that are instances of Fl_Paged_Device
+derived classes (i.e., Fl_Printer or Fl_PostScript_File_Device), the drawing unit
+is initially one point, that is, 1/72 of an inch. But this unit is changed
+after calls to Fl_Paged_Device::scale().
+
 
 
 \section sect_DrawingFunctions Drawing Functions
@@ -961,10 +989,12 @@ standard image types for common file formats:
 \li Fl_XBM_Image 
 \li Fl_XPM_Image
 
-Each of these image classes load a named file of the
+Each of these image classes loads a named file of the
 corresponding format. The Fl_Shared_Image class
 can be used to load any type of image file - the class examines
-the file and constructs an image of the appropriate type.
+the file and constructs an image of the appropriate type. It can also be used
+to scale an image to a certain size in drawing units, independently from its size 
+in pixels (see Fl_Shared_Image::scale()).
 
 Finally, FLTK provides a special image class called Fl_Tiled_Image to
 tile another image object in the specified area. This class can be

src/Fl_Device.cxx

@@ -37,7 +37,8 @@ const char *Fl_Xlib_Graphics_Driver::class_id = "Fl_Xlib_Graphics_Driver";
 #endif
 
 
-/** \brief Use this drawing surface for future graphics requests. */
+/** \brief Make this surface the current drawing surface.
+ This surface will receive all future graphics requests. */
 void Fl_Surface_Device::set_current(void)
 {
   fl_graphics_driver = _driver;