Fix offscreen drawing under X11 (STR 3384)

- fix undefined 'GC' if no window has been shown/drawn yet
- may still need to call fl_open_display() prior to offscreen-drawing
- improve documentation, add example code

CHANGES

@@ -5,7 +5,7 @@ Bug fixes and other improvements
   Note to devs: the following list was created with:
     $ git shortlog release-1.3.5.. | sed -e's/^    //' | sed -e's/^/  /'
 
-  Albrecht Schlosser (8):
+  Albrecht Schlosser (10):
     Fix Fl::add_timeout() in draw() under Linux (STR 3188)
     Fix trailing whitespace in CHANGES
     X11: Fix X Input Methods (XIM) (STR 3502, 3192)
@@ -14,11 +14,13 @@ Bug fixes and other improvements
     Fix DND in read-only Fl_Input (Fl_Output) (#113)
     Update CHANGES and dependencies
     Minor CMake, docs, and test program updates
+    Fix doxygen warnings
+    Fix offscreen drawing under X11 (STR 3384)
 
   Greg Ercolano (1):
     fixes issue92, added -d debug flag to fluid
 
-  ManoloFLTK (13):
+  ManoloFLTK (14):
     X11: add support for copy+paste of image within one app
     Windows: add bitmap version of graphics when copying to clipboard
     Fix use of Xrender extension with old, 16-bit framebuffers.
@@ -32,6 +34,7 @@ Bug fixes and other improvements
     Have Fl_Pack::draw() call Fl_Group::init_sizes() on its parent group.
     CMake support of the Darwin+XQuartz test platform
     Add support of macOS "Big Sur" 11.0
+    Fix when building with SDK 10.15 and running with 11.0 Big Sur
 
   OKAMURA, Yasunobu (1):
     Fix JIS Keyboard dead keys

FL/x.H

@@ -77,10 +77,12 @@ typedef ulong Fl_Offscreen;
 // begin/end are macros that save the old state in local variables:
 #    define fl_begin_offscreen(pixmap) \
   Window _sw=fl_window; fl_window=pixmap; \
+  GC _sgc = fl_gc; if (!_sgc) fl_gc = XCreateGC(fl_display, pixmap, 0, 0); \
   Fl_Surface_Device *_ss = Fl_Surface_Device::surface(); Fl_Display_Device::display_device()->set_current(); \
   fl_push_no_clip()
 #    define fl_end_offscreen() \
-  fl_pop_clip(); fl_window = _sw; _ss->set_current()
+  fl_pop_clip(); fl_window = _sw; _ss->set_current(); \
+  if (!_sgc) XFreeGC(fl_display, fl_gc); fl_gc = _sgc
 
 extern FL_EXPORT void fl_copy_offscreen(int x, int y, int w, int h, Fl_Offscreen pixmap, int srcx, int srcy);
 #    define fl_delete_offscreen(pixmap) XFreePixmap(fl_display, pixmap)

documentation/src/drawing.dox

@@ -1052,9 +1052,48 @@ Sometimes it can be very useful to generate a complex drawing
 in memory first and copy it to the screen at a later point in 
 time. This technique can significantly reduce the amount of
 repeated drawing. Offscreen drawing functions are declared in <FL/x.H>.
-Fl_Double_Window uses offscreen rendering
-to avoid flickering on systems that don't support 
-double-buffering natively. 
+
+Fl_Double_Window uses offscreen rendering to avoid flickering on systems
+that don't support double-buffering natively.
+
+FLTK can draw into an offscreen buffer at any time. There is no need to
+wait for an Fl_Widget::draw() to occur.
+
+\note The X11 platform requires an open display for offscreen drawing,
+i.e. you may need to call fl_open_display() prior to creating and using
+offscreen buffers, particularly if no window has been shown yet.
+
+\par
+\note In FLTK 1.3.x and earlier versions all offscreen drawing functions
+described below are implemented as macros and create certain temporary
+variables to save context information. You may need to create local scope
+blocks with curly braces { ... } if you use offscreen functions more than
+once in a function or method.
+
+Example:
+\code
+  fl_open_display(); // necessary before showing the first window
+  Fl_Offscreen oscr = fl_create_offscreen(120, 120);
+  { // begin block
+    fl_begin_offscreen(oscr);
+    fl_color(FL_WHITE);
+    fl_rectf(0, 0, 120, 120);
+    fl_end_offscreen();
+  } // end block
+  // other code here
+  { // begin block
+    fl_begin_offscreen(oscr);
+    fl_color(FL_BLACK);
+    fl_rectf(10, 10, 100, 100);
+    fl_end_offscreen();
+  } // end block
+  // other code here
+  fl_delete_offscreen(oscr);
+\endcode
+
+\note In FLTK 1.4.0 and later neither calling fl_open_display() nor using
+  local blocks is necessary since the offscreen functions described below
+  are real functions (not macros as in 1.3.x).
 
 Fl_Offscreen fl_create_offscreen(int w, int h)
 
@@ -1070,8 +1109,6 @@ void fl_begin_offscreen(Fl_Offscreen)
 
 \par
 Send all subsequent drawing commands to this offscreen buffer. 
-FLTK can draw into a buffer at any time. There is no need to wait for 
-an Fl_Widget::draw() to occur.
 
 void fl_end_offscreen()