diff options
| -rw-r--r-- | documentation/src/drawing.dox | 76 |
1 files changed, 64 insertions, 12 deletions
diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox index d983c89e8..40e970f94 100644 --- a/documentation/src/drawing.dox +++ b/documentation/src/drawing.dox @@ -37,18 +37,70 @@ Fl_Surface_Device::pop_current(). \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(). - - +Before version 1.4, all graphical quantities used by FLTK are in pixel units: +a window of width 500 units is 500-pixel wide, a line of length 10 units is +10-pixel long, lines of text written using a 14-point font are 14 pixels below +each other. This organization is not sufficient to support GUI apps that can be drawn on +displays of varying pixel density, especially on High-DPI displays, because +widgets become very small and text becomes unreadable. + +FLTK version 1.4 introduces a new feature, a display-specific <b>scale factor</b> which is +a float number with a typical value in the 1-2.5 range and is used as follows: any graphical +element with an FLTK value of \e v units is drawn on the display with \e v * \e scale units. +Thus, a window with width 500 units is 500*scale-pixel wide, a line of length 10 units is +10*scale-pixel long, lines of text written using a 14-point font are 14*scale pixels below +each other. Consider a system with two displays, one with regular DPI and one with +a twice higher DPI. If the first display's scale factor is set to 1 and that of the +second display to 2, the GUI of any FLTK app appears equally sized on the two displays. + +FLTK uses several units to measure graphical elements: +<ul><li>All data visible by the public API (e.g., window widths, line lengths, font sizes, +clipping regions) are in <b>FLTK units</b> which are both system- and DPI-independent. +<li>Just before drawing to a display, the library internally multiplies all quantities +expressed in FLTK units by the current value of the scale factor +for the display in use and obtains quantities in <b>drawing units</b>. +The current scale factor value, for an Fl_Window named \e window, is given by +\code +int nscreen = window->driver()->screen_num(); // the screen where window is mapped +float s = Fl::screen_driver()->scale(nscreen); // this screen's scale factor +\endcode +One drawing unit generally corresponds to one display pixel... +<li>...but not on Mac OS X and for retina displays, where drawing units correspond +to two pixels. +</ul> + +At application start time, FLTK attempts to detect the adequate scale factor value for +each display of the system. If this attempt fails, it's possible to set the +<tt>FLTK_SCALING_FACTOR</tt> environmental variable to the desired numerical value +(e.g., 1.75) and any FLTK app will start scaled with that value. Furthermore, +it's possible to change the scale factor value of any display at run time +with ctrl/+/-/0/ keystrokes which enlarge, shrink, and reset, respectively, +the GUI of all FLTK windows on a display. +Under Mac OS X, the corresponding GUI scaling shortcuts are cmd/+/-/0/. + +When drawing images to a display whose scale value is > 1, the image pixel data +are mapped to the larger number of pixels present in +a display area sized (in FLTK units) as the image. This operation is done internally +by the library using diverse scaling methods that vary with the image type +(Fl_Pixmap, Fl_Bitmap or Fl_RGB_Image) and the platform. +A situation of special interest arises when drawing Fl_Shared_Image's. The +Fl_Shared_Image::scale() member function allows to set the image drawing size +(in FLTK units) independently of its pixel size. Image pixels are mapped to the +pixels of the image drawing area on the display which is determined by the scale +factor value. Therefore, the image data can fill the drawing area of the display at +full physical resolution even for high scale values if the original image is large enough. + +The Fl_Image_Surface class is intended to create an Fl_RGB_Image from a series +of FLTK drawing operations. The Fl_Image_Surface constructor allows to control +whether the size in pixels of the resulting image matches the FLTK units used when +performing drawing operations, or matches the number of pixels corresponding to +these FLTK units given the current scale factor value. The first result is obtained +with <tt>new Fl_Image_Surface(w, h)</tt>, the second with +<tt>new Fl_Image_Surface(w, h, 1)</tt>. + +When drawing to Fl_Printer or Fl_PostScript_File_Device, the drawing unit +is initially one point, that is, 1/72 of an inch. This unit is changed +by calls to Fl_Paged_Device::scale(). \section sect_DrawingFunctions Drawing Functions |