README.Cairo.txt

   1 README.Cairo.txt - 2010-10-25 - Cairo rendering support for FLTK
   2 ----------------------------------------------------------------
   3
   4
   5
   6  CONTENTS
   7 ==========
   8
   9  1   INTRODUCTION
  10  2   CAIRO SUPPORT FOR FLTK 1.3
  11    2.1   Configuration
  12    2.2   Currently supported features
  13    2.3   Future considerations
  14  3   DOCUMENT HISTORY
  15
  16
  17
  18  iINTRODUCTION
  19 ===============
  20
  21 Cairo is a software library used to provide a vector graphics-based,
  22 device-independent API for software developers. It is designed to provide
  23 primitives for 2-dimensional drawing across a number of different
  24 wbackends. Cairo is designed to use hardware acceleration when available.
  25
  26
  27  CAIRO SUPPORT FOR FLTK 1.3
  28 =============================
  29
  30 It is now possible to integrate cairo rendering in your fltk application
  31 more easily and transparently.
  32 In 1.3, we provide minimum support for Cairo,
  33 In particular, no "total" cairo rendering layer support is achieved,
  34 as in fltk2.
  35
  36
  37  Configuration
  38 ---------------
  39
  40 All the changes are *inactive*  as long as the new configuration
  41 option --enable-cairo is not added to the configure command.
  42 For non configure based platforms/ide, the FLTK_HAVE_CAIRO preprocess var.
  43 has to be defined.
  44 All configure based build files has now this feature integrated,
  45 also vc2005 build files have 2 new build modes "Release Cairo" and
  46 "Debug Cairo".
  47 Others IDE's will be updated progressively.
  48
  49
  50  Currently supported features
  51 ------------------------------
  52
  53 - Adding a new Fl_Cairo_Window class permitting transparent and easy
  54 integration of a Cairo draw callback without the need to achieve subclassing.
  55
  56 - Adding a Fl::cairo_make_current(Fl_Window*) function only providing
  57 transparently a cairo context to your custom Fl_Window derived class.
  58 This function is intended to be used in your overloaded draw() method.
  59
  60 - Adding an optional cairo autolink context mode support (disabled by default)
  61   which permits complete & automatic synchronization of OS dependent graphical
  62   context and cairo contexts, thus furthering a valid cairo context anytime,
  63   in any current window.
  64   This feature should be only necessary in the following cases:
  65   -  Intensive and almost systematic use of cairo contexts in an fltk application
  66   -  Creation of a new cairo based scheme for fltk ...
  67   -  Other uses of cairo necessiting the flk internals instrumentation
  68      to automatically making possible the use of a cairo context
  69      in any fltk window.
  70
  71 - A new cairo demo that is available in the test subdirectory and has been
  72    used as a testcase durings the multiplatform tests.
  73
  74 For more details, please have a look to the doxygen documentation,
  75 in the Modules section.
  76
  77
  78  Future considerations
  79 -----------------------
  80
  81 From Bill:
  82 First there is the FLTK_HAVE_CAIRO configuration option. This indicates that
  83 any cairo calls are available. In this case you get something like this:
  84
  85 // static variable holding the last cairo context fltk set:
  86 cairo_t* Fl::cr;
  87
  88 // Make cr draw in this window. This hides the ugly platform-dependent
  89 // part of getting cairo going:
  90 void Fl::cairo_make_current(Fl_Window*)
  91
  92 *** POST 1.3 potential cairo use:
  93 // Set cr to something you made yourself. This lets you reuse functions
  94 // that use cr, and also tells fltk that cr is not one of it's own and
  95 // thus cannot be destroyed or reused for a different window:
  96 void Fl::cairo_make_current(cairo_t*)
  97
  98 Second there is the FLTK_USE_CAIRO configuration option. This means that all
  99 drawing is done using Cairo. In this case when a widget draw() method is
 100 called, it is exactly as though cairo_make_current(window) has been done.
 101 ***
 102
 103 Note that it should be possible to compile so FLTK_HAVE_CAIRO works even if
 104 FLTK_USE_CAIRO does not, and so that turning on FLTK_USE_CAIRO does not break any
 105 programs written for FLTK_HAVE_CAIRO.
 106
 107
 108  DOCUMENT HISTORY
 109 ==================
 110
 111 Dec 20 2010 - matt: restructured document