Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for glwdrawingarea (redhat section 3X)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

GLwDrawingArea(3X)							       GLwDrawingArea(3X)

       GLwDrawingArea, GLwMDrawingArea -- OpenGL drawing widgets.

       #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

       GLwDrawingArea  and GLwMDrawingArea are widgets suitable for OpenGL drawing.  They provide
       a window with the appropriate visual and colormaps 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 GLwDrawingArea, except when the behaviors
       differ.	Unless explicitly stated, all statements about GLwDrawingArea also apply to GLwM-

       Among  the information provided when creating a GLwDrawingArea is information 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 application).	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 guarantee compatibility between the colormap and the visual).
       If an application 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 conse-
       quently, the application should not perform any OpenGL operations to  the  window  immedi-
       ately  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  window  has
       been  created.	Upon receiving this callback, the application can perform all OpenGL ini-
       tialization for the window, and can subsequently perform other operations on it.  The ini-
       tialization is discussed in more detail below.

       Applications select which GLwDrawingArea they are accessing using either glXMakeCurrent or
       the convenience function GLwDrawingAreaMakeCurrent which uses a widget instead of  a  dis-
       play  and window.  If there is only one GLwDrawingArea this need only be called once, how-
       ever 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 GLwDrawingAreaSwapBuffers 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 programmer to specify
       data.  The programmer can also set the resource values 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 glXChooseVisual, 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 specific 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

	      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.  Applications 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 col-
	      ormap, the application may need to do more careful color allocation to avoid flash-
	      ing  between the OpenGL colormap and the default X colormap.  (Note that because of
	      the way Xt works, the background colors are originally calculated using the default
	      colormap;  if  this  resource is set they can be recalculated correctly.	If a col-
	      ormap was explicitly supplied to the widget rather than  being  dynamically  calcu-
	      lated, these resources are always calculated using that colormap.)

	      This  is	similar  to  GLwNallocateBackground,  but allocates other colors normally
	      allocated by widgets.  Although the GLwDrawingArea 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, XmNhighlightColor, and XmNhighlightPixmap are calculated.

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

	      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.

	      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 perform any appropriate OpenGL initialization  such  as  creating	a
	      context.	The callback reason is GLwCR_GINIT.

	      Specifies  the list of callbacks that is called when the widget receives a keyboard
	      or mouse event.  By default, the input callback 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  con-
	      venient  way  to catch all input events.	However, 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.

	      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 GLwNallocateBack-
	      ground is also TRUE.

	      If set to TRUE, the widget will call XSetWMColormapWindows to tell the window  man-
	      ager  to	install the colormap when the window'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  colormaps,  this resource can be set to FALSE, with the application
	      calling XSetWMColormapWindows explicitly.

	      Specifies the list of callbacks that is called when the GLwDrawingArea is  resized.
	      The callback reason is GLwCR_RESIZE.

	      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 behav-
       ior  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  application should call XmProcessTraversal(widget, XmTRAVERSE_CURRENT) whenever mouse
       button 1 is clicked in the widget.  This is similar to the requirements of the Motif Draw-
       ing 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	programmers,   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 GLwNginitCall-
	      back and GLwNresizeCallback.

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

       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:

	      Called  whenever	one  of the above translations specifies that input has occurred.
	      Its sole purpose is to call the input callback.

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

       Between the time the widget is created and it is realized, the following 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.

       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

       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

       Motif programmers may also create a GLwMDrawingArea widget with the  Motif  style  GLwCre-

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

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

	      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  GLw-
       DrawingArea.h  and by creating a widget of type GLwMDrawingAreaWidgetClass instead of GLw-
       DrawingAreaWidgetClass.	As an alternative, the Motif program could use GLwCreateMDraw(3X)

       If  a  GLwDrawingArea widget is created as a child of an already realized widget, the GLw-
       DrawingArea 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 widget 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 wid-

       glXChooseVisual(3G),  GLwDrawingAreaMakeCurrent(3X),   glXMakeCurrent(3G),   GLwDrawingAr-
       eaSwapBuffers(3X)   GLwCreateMDraw(3X),	Core(3X),  XmPrimitive(3X),  VirtualBindings(3X),
       XSetWMColormapWindows(3X11) and the OpenGL spec.

Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 05:57 AM.