manpagez: man pages & more
man GLwDrawingArea(3)
Home | html | info | man
GLwDrawingArea(3)                                          GLwDrawingArea(3)




NAME

       GLwDrawingArea, GLwMDrawingArea -- OpenGL drawing widgets.



SYNOPSIS

       #include <X11/GLw/GLwDrawA.h>
       ld ... -lGLw -lGL -l<anywidgetlibrary> -lXext -lXt -lX11 -lm

       #include <X11/GLw/GLwMDrawA.h>
       ld ... -lGLw -lGL -lXm -lXext -lXt -lX11 -lm



DESCRIPTION

       GLwDrawingArea  and  GLwMDrawingArea  are  widgets  suitable for OpenGL
       drawing.  They provide a window with the appropriate  visual  and  col-
       ormaps needed for OpenGL, based on supplied parameters.  GLwDrawingArea
       and GLwMDrawingArea also provide callbacks for redraw,  resize,  input,
       and initialization.

       GLwDrawingArea is not a part of any widget set, but depends only on Xt.
       GLwDrawingArea can be used with any  widget  set.   GLwMDrawingArea  is
       identical  to  GLwDrawingArea except that it is a subclass of the Motif
       widget class XmPrimitive and has resources and  defaults  suitable  for
       use  with  Motif.   For  example,  GLwMDrawingArea provides the default
       Motif background and foreground colors for resources, and deals  better
       with  keyboard  traversal.   Although  the GLwDrawingArea widget can be
       used in a Motif program, it is recommended that GLwMDrawingArea be used
       instead.

       Since  both  GLwDrawingArea  and  GLwMDrawingArea widgets behave almost
       identically, the remainder of this manual page will refer only to  GLw-
       DrawingArea,  except  when  the  behaviors  differ.   Unless explicitly
       stated,  all  statements  about  GLwDrawingArea  also  apply  to  GLwM-
       DrawingArea.

       Among the information provided when creating a GLwDrawingArea is infor-
       mation necessary to determine the visual.   This  may  be  provided  in
       three  ways,  all  of  them  through  resources.  A specific visualInfo
       structure may be passed in.  (This visualInfo must have  been  obtained
       elsewhere; it is the application designer's responsibility to make sure
       that it is compatible with the OpenGL rendering done  by  the  applica-
       tion).   Alternatively,  an  attribute  list  may  be  provided.   This
       attribute list is formatted identically to that used for direct open GL
       programming.  Finally, each attribute can be specified as an individual
       resource.  The latter method is the simplest, and is  the  only  method
       that works from resource files.

       In  addition  to  allocating  the  visual, the GLwDrawingArea will also
       allocate the colormap unless one is provided by the  application.   (If
       one  is provided it is the application writer's responsibility to guar-
       antee compatibility between the colormap and the visual).  If an appli-
       cation  creates multiple GLwDrawingAreas with the same visual, the same
       colormap will be used.  (However the colormap will not be shared  among
       separate applications).

       Creating  the  widget  does  not actually create the window until it is
       realized, and consequently, the  application  should  not  perform  any
       OpenGL  operations  to  the window immediately after creation.  Instead
       the application must wait until  after  it  has  realized  the  window.
       Alternatively, the ginit callback may be used to indicate when the win-
       dow has been created.  Upon receiving this  callback,  the  application
       can  perform  all  OpenGL initialization for the window, and can subse-
       quently perform other operations on it.   The  initialization  is  dis-
       cussed in more detail below.

       Applications  select  which  GLwDrawingArea  they  are  accessing using
       either glXMakeCurrent or the convenience  function  GLwDrawingAreaMake-
       Current  which uses a widget instead of a display and window.  If there
       is only one GLwDrawingArea this need only be called  once,  however  if
       there  is more than one GLwDrawingArea it should be called at the start
       of each callback.  Callbacks in this case include  not  only  callbacks
       provided  by the widget itself, but any other callback that leads to GL
       activity such as a timeout or a workproc.

       If an application is using double buffering, it may call  GLwDrawingAr-
       eaSwapBuffers  instead  of  glXSwapBuffers.  This allows the use of the
       widget instead of the display and window.

   GLwDrawingArea Classes
       GLwDrawingArea inherits behavior and resources from the Core class.
       The class pointer is glwDrawingAreaWidgetClass.
       The class name is GLwDrawingArea.


   GLwMDrawingArea Classes
       GLwMDrawingArea inherits behavior and resources  from  the  XmPrimitive
       and Core classes.
       The class pointer is glwMDrawingAreaWidgetClass.
       The class name is GLwMDrawingArea.


   New Resources
       The  following tables define a set of widget resources used by the pro-
       grammer to specify data.  The programmer can also set the resource val-
       ues  for  the  inherited classes to set attributes for this widget.  To
       reference a resource by name or by class in a .Xdefaults  file,  remove
       the  GLwN  or GLwC prefix and use the remaining letters.  There are two
       tables included.  The first table includes  resources  that  correspond
       directly to the attributes used by glXChooseVisual.  As with glXChoose-
       Visual,  all  Boolean  resources  default  to  FALSE  and  all  integer
       resources  default  to  0, except redSize, greenSize and blueSize which
       default to 1.  These resources can all be set only  at  creation  time,
       and  are used to determine the visual.  If either the GLwNattribList or
       GLwNvisualInfo resource is set, these resources are ignored.  The  spe-
       cific  meaning  of  these resources is discussed in the glXChooseVisual
       manual page and will not be discussed here.


      +-------------------+--------------------+---------+----------------------+
      |Name               | Class              | Type    | OpenGL attribute     |
      +-------------------+--------------------+---------+----------------------+
      |GLwNbufferSize     | GLwCBufferSize     | int     | GLX_BUFFER_SIZE      |
      +-------------------+--------------------+---------+----------------------+
      |GLwNlevel          | GLwCLevel          | int     | GLX_LEVEL            |
      +-------------------+--------------------+---------+----------------------+
      |GLwNrgba           | GLwCRgba           | Boolean | GLX_RGBA             |
      +-------------------+--------------------+---------+----------------------+
      |GLwNdoublebuffer   | GLwCDoublebuffer   | Boolean | GLX_DOUBLEBUFFER     |
      +-------------------+--------------------+---------+----------------------+
      |GLwNstereo         | GLwCStereo         | Boolean | GLX_STEREO           |
      +-------------------+--------------------+---------+----------------------+
      |GLwNauxBuffers     | GLwCAuxBuffers     | Boolean | GLX_AUX_BUFFERS      |
      +-------------------+--------------------+---------+----------------------+
      |GLwNredSize        | GLwCColorSize      | int     | GLX_RED_SIZE         |
      +-------------------+--------------------+---------+----------------------+
      |GLwNgreenSize      | GLwCColorSize      | int     | GLX_GREEN_SIZE       |
      +-------------------+--------------------+---------+----------------------+
      |GLwNblueSize       | GLwCColorSize      | int     | GLX_BLUE_SIZE        |
      +-------------------+--------------------+---------+----------------------+
      |GLwNalphaSize      | GLwCAlphaSize      | int     | GLX_ALPHA_SIZE       |
      +-------------------+--------------------+---------+----------------------+
      |GLwNdepthSize      | GLwCDepthSize      | int     | GLX_DEPTH_SIZE       |
      +-------------------+--------------------+---------+----------------------+
      |GLwNstencilSize    | GLwCStencilSize    | int     | GLX_STENCIL_SIZE     |
      +-------------------+--------------------+---------+----------------------+
      |GLwNaccumRedSize   | GLwCAccumColorSize | int     | GLX_ACCUM_RED_SIZE   |
      +-------------------+--------------------+---------+----------------------+
      |GLwNaccumGreenSize | GLwCAccumColorSize | int     | GLX_ACCUM_GREEN_SIZE |
      +-------------------+--------------------+---------+----------------------+
      |GLwNaccumBlueSize  | GLwCAccumColorSize | int     | GLX_ACCUM_BLUE_SIZE  |
      +-------------------+--------------------+---------+----------------------+
      |GLwNaccumAlphaSize | GLwCAccumAlphaSize | int     | GLX_ACCUM_ALPHA_SIZE |
      +-------------------+--------------------+---------+----------------------+

       The following table lists other resources of the GLwDrawingArea widget.
       each  of these will be described subsequently.  The codes in the access
       column indicate if the given resource can be set at creation time  (C),
       set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
       not applicable (N/A).


    Name                      Class                   Type             Def    Acc
    ------------------------------------------------------------------------------
    GLwNallocateBackground    GLwCAllocateColors      Boolean          F      CG
    GLwNallocateOtherColors   GLwCAllocateColors      Boolean          F      CG
    GLwNattribList            GLwCAttribList          int *            NULL   CG
    GLwNexposeCallback        GLwCCallback            XtCallbackList   NULL   C
    GLwNginitCallback         GLwCCallback            XtCallbackList   NULL   C
    GLwNinputCallback         GLwCCallback            XtCallbackList   NULL   C
    GLwNinstallBackground     GLwCInstallBackground   Boolean          T      CG
    GLwNinstallColormap       GLwCInstallColormap     Boolean          T      CG
    GLwNresizeCallback        GLwCCallback            XtCallbackList   NULL   C
    GLwNvisualInfo            GLwCVisualInfo          XVisualInfo*     NULL   CG


       GLwNallocateBackground
              If TRUE, the background pixel and pixmap will  be  allocated  if
              appropriate  using the newly calculated colormap and visual.  If
              FALSE, they will retain values  calculated  using  the  parent's
              colormap  and  visual.   Applications which wish to have X clear
              their background for them will usually set this to TRUE.  Appli-
              cations  clearing  their  own  background will often set this to
              FALSE, although they may set this to  TRUE  if  they  query  the
              background for their own use.  One reason to leave this resource
              FALSE is that if color index mode is in use this avoid using  up
              a  pixel  from  the newly allocated colormap.  Also, on hardware
              that supports only one colormap, the application may need to  do
              more  careful  color  allocation  to  avoid flashing between the
              OpenGL colormap and the default X colormap.  (Note that  because
              of the way Xt works, the background colors are originally calcu-
              lated using the default colormap; if this resource is  set  they
              can  be  recalculated  correctly.   If a colormap was explicitly
              supplied to the widget rather than being dynamically calculated,
              these resources are always calculated using that colormap.)

       GLwNallocateOtherColors
              This  is  similar to GLwNallocateBackground, but allocates other
              colors  normally  allocated  by  widgets.   Although  the   GLw-
              DrawingArea  and GLwMDrawingArea widget do not make use of these
              colors the application may choose to query them.  For  the  non-
              Motif GLwDrawingArea widget there are no other colors allocated,
              so this resource is a no-op.  For the Motif GLwMDrawingArea  are
              widget,  the  XmPrimitive resources XmNforeground, XmNhighlight-
              Color, and XmNhighlightPixmap are calculated.

       GLwNattribList
              Contains the list of attributes suitable for a call to  glXChoo-
              seVisual.   If  this resource is NULL, it is calculated based on
              the attribute resources.  If  it  is  not  NULL,  the  attribute
              resources are ignored.

       GLwNexposeCallback
              Specifies  the  list of callbacks that is called when the widget
              receives  an   exposure   event.    The   callback   reason   is
              GLwCR_EXPOSE.  The callback structure also includes the exposure
              event.  The application will generally want to redraw the scene.

       GLwNginitCallback
              Specifies  the  list of callbacks that is called when the widget
              is first realized.  Since  no  OpenGL  operations  can  be  done
              before the widget is realized, this callback can be used to per-
              form any appropriate OpenGL initialization such  as  creating  a
              context.  The callback reason is GLwCR_GINIT.

       GLwNinputCallback
              Specifies  the  list of callbacks that is called when the widget
              receives a keyboard or mouse event.  By default, the input call-
              back  is called on each key press and key release, on each mouse
              button press and release, and whenever the mouse is moved  while
              a button is pressed.  However this can be changed by providing a
              different  translation  table.   The  callback  structure   also
              includes the input event.  The callback reason is GLwCR_INPUT.

              The  input callback is provided as a programming convenience, as
              it provides a convenient way to catch all  input  events.   How-
              ever,  a more modular program can often be obtained by providing
              specific actions and translations in the application rather than
              using a single catch all callback.  Use of explicit translations
              can also provide for more customization.

       GLwNinstallBackground
              If set to TRUE, the background is installed on the  window.   If
              set  to  FALSE, the window has no background.  This resource has
              no effect unless GLwNallocateBackground is also TRUE.

       GLwNinstallColormap
              If set to TRUE, the widget will  call  XSetWMColormapWindows  to
              tell  the  window  manager to install the colormap when the win-
              dow's shell has focus.  If  set  to  FALSE,  this  will  not  be
              called.   For applications with multiple GLwDrawingAreas sharing
              a single colormap, it is most efficient to set this resource  to
              TRUE  for  exactly one GLwDrawingArea with each colormap.  If an
              application needs additional control  over  the  order  of  col-
              ormaps,  this resource can be set to FALSE, with the application
              calling XSetWMColormapWindows explicitly.

       GLwNresizeCallback
              Specifies the list of callbacks that is  called  when  the  GLw-
              DrawingArea is resized.  The callback reason is GLwCR_RESIZE.

       GLwNvisualInfo
              Contains  a  pointer  to the window's visual info structure.  If
              NULL, the visualInfo is calculated at widget creation time based
              on  the  GLwNattributeList  resource (which is itself calculated
              from the various resources).  If GLwNvisualInfo is not NULL  the
              GLwNattributList and the attribute resources are ignored.


   Inherited Resources
       Both  GLwDrawingArea and GLwMDrawingArea inherit behavior and resources
       from the core superclass.  Other than the behavior of the colormap  and
       background resources described previously, all defaults are the same as
       for core.

       In addition, the  Motif  version  GLwMDrawingArea  also  inherits  from
       XmPrimitive.   The  behavior  of the color resources has been described
       previously.  The TraversalOn resource is disabled for this widget,  but
       if  keyboard input is required it should be enabled.  (Also, the appli-
       cation should call XmProcessTraversal(widget, XmTRAVERSE_CURRENT) when-
       ever  mouse  button 1 is clicked in the widget.  This is similar to the
       requirements of the Motif Drawing area.)  Because Motif  gets  confused
       by  having multiple visuals in one top level shell, XmNhighlightOnEnter
       has been disabled, and XmNhighlightThickness has been set to 0.

   Callback Information
       A pointer to the following structure is passed to each callback:

       typedef struct
       {
         int         reason;
         XEvent     *event;
         Dimension   width, height;
       } GLwDrawingAreaCallbackStruct;


       reason Indicates why the callback was invoked.  Appropriate values  are
              stated  in  the above resource descriptions.  For Motif program-
              mers, the values GLwCR_EXPOSE, GLwCR_RESIZE, and GLwCR_INPUT are
              equal  to XmCR_EXPOSE, XmCR_RESIZE, and XmCR_INPUT respectively.
              GLwCR_GINIT does not have a Motif equivalent.

       event  Points to the XEvent that triggered the callback.  This is  NULL
              for GLwNginitCallback and GLwNresizeCallback.

       width and height
              Are set to the width and height of the window.


   Translations
       GLwDrawingArea has the translations listed below.
       <KeyDown>:     glwInput()
       <KeyUp>:       glwInput()
       <BtnDown>:     glwInput()
       <BtnUp>:       glwInput()
       <BtnMotion>:   glwInput()

       GLwMDrawingArea has the following additional translation:
       <Key>osfHelp:  PrimitiveHelp()

       An application wishing to catch other events than these defaults can do
       so by installing a different translation table.


   Action Routines
       The GLwDrawingArea has the following action routine:

       glwInput():
              Called whenever one of the  above  translations  specifies  that
              input has occurred.  Its sole purpose is to call the input call-
              back.



INITIALIZATION

       When the widget is initially created (e.g. through  XtCreateWidget(3X))
       the  associated  window  is not actually created.  Instead, window cre-
       ation is delayed until the widget is realized.   However,  glXchooseVi-
       sual  is  called  immediately,  so  information based on its results is
       available.

       Between the time the widget is created and it is realized, the  follow-
       ing apply:

       o      No OpenGL operations can be done to the window

       o      No resize callbacks are generated.

       o      The normal window is available (XtWindow returns NULL).

       o      GLwDrawingAreaMakeCurrent  (and  glXMakeCurrent)  should  not be
              called.

       When the widget is realized, the following actions take place:


       o      The window is created.

       o      The ginit callback is called.  The user may use this callback to
              perform any needed OpenGL initialization to the window.



NOTES

       When using the input callback to receive keyboard input, the keycode in
       the event must be converted to  a  KeySym.   Use  XLookupKeysym(3X)  or
       XLookupString(3X)  to  do  the  conversion.  Keyboard input can also be
       dealt using translations, in which case no such conversion is required.

       Motif  programmers  should  keep in mind that OSF uses virtual bindings
       and replaces some of the key bindings.  As a common example, if the ESC
       key  is to be used to exit the program (as it often is in GL programs),
       the translation should specify <key>osfCancel instead of <key>Escape.

       Motif programmers may also create a  GLwMDrawingArea  widget  with  the
       Motif style GLwCreateMDrawingArea.



EXAMPLE

       Here  are  some code fragments that create a GLwDrawingArea widget, and
       manage the appropriate callbacks.

          #include <stdlib.h>
          #include <X11/GLw/GLwDrawA.h>
          static GLXContext glx_context;
          . . .

          main()
          {
              Arg args[10];
              int n;

              Widget parent;
              Widget glw;
              . . .




              n = 0;
              XtSetArg(args[n], GLwNrgba, True); n++;
              glw = XtCreateManagedWidget("glw", glwDrawingAreaWidgetClass,
                                          parent, args, n);
              XtAddCallback(glw, GLwNexposeCallback, exposeCB, NULL);
              XtAddCallback(glw, GLwNresizeCallback, resizeCB, NULL);
              XtAddCallback(glw, GLwNginitCallback, ginitCB, NULL);

              . . .
          }

          static void
          exposeCB(Widget w, XtPointer client_data,
                   GLwDrawingAreaCallbackStruct *call_data)
          {
              GLwDrawingAreaMakeCurrent(w, glx_context);

          }

          static void
          resizeCB(Widget w, XtPointer client_data,
                   GLwDrawingAreaCallbackStruct *call_data)
          {
              GLwDrawingAreaMakeCurrent(w, glx_context);

          }

          static void
          ginitCB(Widget w, XtPointer client_data,
                  GLwDrawingAreaCallbackStruct *call_data)
          {
              Arg args[1];
              XVisualInfo *vi;

              XtSetArg(args[0], GLwNvisualInfo, &vi);
              XtGetValues(w, args, 1);


              glx_context = glXCreateContext(XtDisplay(w), vi,
                                             NULL, GL_FALSE);
              GLwDrawingAreaMakeCurrent(w, glx_context);

          }

       The Motif program  need  only  differ  by  including  GLwMDrawingArea.h
       instead  of  GLwDrawingArea.h  and  by  creating a widget of type GLwM-
       DrawingAreaWidgetClass instead  of  GLwDrawingAreaWidgetClass.   As  an
       alternative, the Motif program could use GLwCreateMDraw(3X) instead.



WARNINGS

       If a GLwDrawingArea widget is created as a child of an already realized
       widget, the GLwDrawingArea widget will be created immediately,  without
       giving  the  user  an opportunity to add the ginit callback.  In such a
       case, initialization should be done immediately after creating the wid-
       get rather than by using the callback.

       If  the  non-Motif GLwDrawingArea widget is used in a Motif program and
       keyboard traversal is attempted, the behavior is undefined if the  user
       traverses into the GLwDrawingArea widget.


SEE ALSO

       glXChooseVisual(3), GLwDrawingAreaMakeCurrent(3), glXMakeCurrent(3),
       GLwDrawingAreaSwapBuffers(3) GLwCreateMDraw(3), Core(3), 
       XmPrimitive(3), VirtualBindings(3), XSetWMColormapWindows(3) and the 
       OpenGL spec.



                                                            GLwDrawingArea(3)

Mac OS X 10.4 X11 - Generated Sat Apr 30 05:01:53 CDT 2005
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.