1 files changed, 69 insertions, 0 deletions
diff --git a/documentation/src/opengl.dox b/documentation/src/opengl.dox
index 793b9834e..668e26ef9 100644
--- a/documentation/src/opengl.dox
+++ b/documentation/src/opengl.dox
@@ -257,6 +257,75 @@ adhere to for maximum portability:
 Do \e not call \p gl_start() or
 \p gl_finish() when drawing into an Fl_Gl_Window !
 
+
+\section opengl_with_fltk_widgets Using FLTK widgets in OpenGL Windows
+
+FLTK widgets can be added to `Fl_Gl_Window`s just as they would be added to
+`Fl_Window`s. They are rendered as an overlay over the user defined
+OpenGL graphics using 'fl_..' graphics calls that are implemented in GL.
+
+`Fl_Gl_Window` does not add subsequent widgets as children by default as
+`Fl_Window` does. Call `myGlWindow->begin()` after creating the GL window to
+automatically add following widgets. Remember to call `myGlWindow->end()`.
+
+\code
+class My_Gl_Window : public Fl_Gl_Window {
+...
+  void draw();
+...
+};
+
+...
+myGlWindow = new My_Gl_Window(0, 0, 500, 500);
+myGlWindow->begin();
+myButton = new Fl_Button(10, 10, 120, 24, "Hello!");
+myGlWindow->end();
+...
+
+void My_Gl_Window::draw() {
+  // ... user GL drawing code
+  Fl_Gl_Window::draw(); // Draw FLTK child widgets.
+}
+\endcode
+
+Users can draw into the overlay by using GL graphics calls as well as all
+`fl_...` graphics calls from the "Drawing Fast Shapes" section.
+
+\code
+void My_Gl_Window::draw() {
+  // ... user GL drawing code
+  Fl_Gl_Window::draw_begin(); // Set up 1:1 projection
+  Fl_Window::draw();          // Draw FLTK children
+  fl_color(FL_RED);
+  fl_rect(10, 10, 100, 100);
+  Fl_Gl_Window::draw_end();   // Restore GL state
+}
+\endcode
+
+Widgets can be drawn with transparencies by assigning an alpha value to a
+colormap entry and using that color in the widget.
+
+\code
+Fl::set_color(FL_FREE_COLOR, 255, 255, 0, 127); // 50% transparent yellow
+myGlWindow = new My_Gl_Window(0, 0, 500, 500);
+myGlWindow->begin();
+myButton = new Fl_Button(10, 10, 120, 24, "Hello!");
+myButton->box(FL_BORDER_BOX);
+myButton->color(FL_FREE_COLOR);
+myGlWindow->end();
+\endcode
+
+Transparencies can also be set directly when drawing. This can be used to
+create custom box types and RGB overlay drawings with an alpha channel.
+
+\code
+fl_color(0, 255, 0, 127); // 50% transparent green
+fl_rectf(10, 10, 100, 100);
+fl_color(FL_RED); // back to opaque red
+fl_rect(20, 20, 80, 80);
+\endcode
+
+
 \section opengl_drawing OpenGL Drawing Functions
 
 FLTK provides some useful OpenGL drawing functions. They can