home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / qt3_emx.zip / examples / opengl / overlay_x11 / README.X11-OVERLAYS < prev    next >
Encoding:
Text File  |  2001-05-07  |  4.0 KB  |  93 lines
  1.  
  2.      HOW TO USE X11 OVERLAYS WITH THE QT OPENGL EXTENSION
  3.  
  4. X11 overlays is a powerful mechanism that allows one to draw
  5. annotations etc. on top of an image without destroying it, thus saving
  6. much image rendering time. For more information, consult the highly
  7. recommended book "OpenGL Programming for the X Window System" (Mark
  8. Kilgard, Addison Wesley Developers Press 1996).
  9.  
  10. -----------------------------------------------------------------------
  11. UPDATE: From version 5.0 onwards, the Qt OpenGL Extension includes
  12. direct support for use of OpenGL overlays. For many uses of overlays,
  13. this makes the technique described below redundant. See the 'overlay'
  14. example program. The following is a discussion on how to use non-QGL
  15. widgets in overlay planes.
  16. -----------------------------------------------------------------------
  17.  
  18. In the typical case, X11 overlays can easily be used together with the
  19. current version of Qt and the Qt OpenGL Extension. The following
  20. requirements apply:
  21.  
  22. 1) Your X server and graphics card/HW must support overlays (of
  23.    course). For many X servers, overlay support can be turned on with
  24.    a configuration option; consult your X server installation
  25.    documentation.
  26.  
  27. 2) Your X server must (be configured to) use an overlay visual as the
  28.    default visual. Most modern X servers do this, since this has the
  29.    added advantage that pop-up menus, overlapping windows etc. will
  30.    automatically not destroy underlying images in the main plane,
  31.    causing expensive redraws.
  32.  
  33. 3) The best (deepest) visual for OpenGL rendering is in the main
  34.    plane. This is the normal case. Typically, X servers that support
  35.    overlays provide a 24 bit deep TrueColor visuals in the main plane,
  36.    and an 8 bit PseudoColor (default) visual in the overlay plane.
  37.  
  38. The provided example program "overlayrubber" will check for all this
  39. and tell you what is wrong, if anything. See "About X11 Visuals" below
  40. for more information.
  41.  
  42.  
  43. How it works:
  44. -------------
  45.  
  46. Given the above, a QGLWidget will by default use the main plane
  47. visual, while all other widgets will use the overlay visual. Thus, one
  48. can place a normal widget on top of the QGLWidget, and do drawing in
  49. it, without destroying the image in the OpenGL window. In other words,
  50. one can use all the drawing capabilities of QPainter to draw the
  51. annotations, rubberbands, whatever. For the typical use of overlays,
  52. this is much easier than using OpenGL for rendering the annotations.
  53.  
  54. An overlay plane has a specific color called the transparent
  55. color. Pixels drawn in this color will not be visible, in stead the
  56. underlying OpenGL image will show through. In the example program
  57. "overlayrubber", the file main.cpp contains a routine that returns a
  58. QColor containing the transparent color. For the overlay widget, one
  59. will typically want to set the background color to the transparent
  60. color, so that the OpenGL image shows through unless where explicitly
  61. overpainted.
  62.  
  63. Note: To use this technique, you must not use the "ManyColor" or
  64. "TrueColor" ColorSpec for the QApplication, because this will force
  65. the normal Qt widgets to use a TrueColor visual, which will typically
  66. be in the main plane, not in the overlay plane as desired.
  67.  
  68.  
  69.  
  70. About X11 visuals:
  71. ------------------
  72.  
  73. The utilities directory contains to small programs that can help you
  74. determine the capabilities of your X server. These programs are from
  75. the OpenGL book mentioned above, see utilities/NOTICE for copyright
  76. information. The full set of example programs from this book is
  77. available at ftp://ftp.sgi.com/pub/opengl/opengl_for_x/
  78.  
  79. "glxvisuals" will list all the GL-capable visuals the X server provides,
  80. together with the depth and other GL-specific information for
  81. each. Note especially the column "lvl"; a number in this column means
  82. the visual is in an overlay plane.
  83.  
  84. "sovinfo" will list all available visuals, and provides special
  85. transparency information for overlay visuals.
  86.  
  87. The overlayrubber example program will output what visual is used for
  88. the normal Qt widgets, and what visual is used by the QGLWidget.
  89.  
  90.  
  91.  
  92. Comments are welcome at info@trolltech.com.
  93.