GLwDrawingArea man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]



GLwDrawingArea(3X)			     GLwDrawingArea(3X)

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 appro-
       priate  visual  and  colormaps needed for OpenGL, based on
       supplied parameters.  GLwDrawingArea  and  GLwMDrawingArea
       also provide callbacks for redraw, resize, input, and ini-
       tialization.

       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   GLw-
       DrawingArea except that it is a subclass of the Motif wid-
       get class XmPrimitive and has resources and defaults suit-
       able  for  use  with  Motif.  For example, GLwMDrawingArea
       provides the default Motif background and foreground  col-
       ors  for resources, and deals better with keyboard traver-
       sal.  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 state-
       ments about GLwDrawingArea also apply to GLwMDrawingArea.

       Among  the  information	provided  when	creating  a  GLw-
       DrawingArea 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 else-
       where; 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

								1

GLwDrawingArea(3X)			     GLwDrawingArea(3X)

       will also allocate the colormap unless one is provided  by
       the  application.   (If one is provided it is the applica-
       tion 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 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.	Alterna-
       tively,	the  ginit  callback may be used to indicate when
       the window has been created.  Upon  receiving  this  call-
       back,  the  application can perform all OpenGL initializa-
       tion for the window, and can  subsequently  perform  other
       operations on it.  The initialization is discussed in more
       detail below.

       Applications select which GLwDrawingArea they are  access-
       ing  using  either glXMakeCurrent or the convenience func-
       tion GLwDrawingAreaMakeCurrent which uses a widget instead
       of  a  display  and  window.   If  there is only one GLw-
       DrawingArea 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
       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

								2

GLwDrawingArea(3X)			     GLwDrawingArea(3X)

       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 glX-
       ChooseVisual.   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 cre-
       ation 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  GLw-
       DrawingArea  widget.  each of these will be described sub-
       sequently.  The codes in the access column indicate if the

								3

GLwDrawingArea(3X)			     GLwDrawingArea(3X)

       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.   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 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 calculated using  the  default  col-
	      ormap; if this resource is set they can be recalcu-
	      lated correctly.	If a colormap was explicitly sup-
	      plied  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  wid-
	      gets.    Although the  GLwDrawingArea  and  GLwM-
	      DrawingArea 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 XmPrimi-
	      tive  resources  XmNforeground,  XmNhighlightColor,
	      and XmNhighlightPixmap are calculated.

								4

GLwDrawingArea(3X)			     GLwDrawingArea(3X)

       GLwNattribList
	      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.

       GLwNexposeCallback
	      Specifies the list of callbacks that is called when
	      the  widget  receives an exposure event.	The call-
	      back reason is GLwCR_EXPOSE.  The callback  struc-
	      ture  also includes the exposure event.  The appli-
	      cation 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  real-
	      ized,  this  callback  can  be  used to perform 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 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  convenient  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.

       GLwNinstallBackground
	      If set to TRUE, the background is installed on  the
	      window.	If  set to FALSE, the window has no back-
	      ground.  This resource has no effect unless GLwNal-
	      locateBackground is also TRUE.

       GLwNinstallColormap
	      If  set  to  TRUE,  the widget will call XSetWMCol-
	      ormapWindows to tell the window manager to  install
	      the colormap when the window's shell has focus.  If
	      set to FALSE, this will not be called.  For  appli-
	      cations  with  multiple  GLwDrawingAreas	sharing a

								5

GLwDrawingArea(3X)			     GLwDrawingArea(3X)

	      single colormap, it is most efficient to	set  this
	      resource	to  TRUE  for  exactly one GLwDrawingArea
	      with each colormap.  If an application needs  addi-
	      tional  control  over  the order of colormaps, this
	      resource can be set to FALSE, with the  application
	      calling XSetWMColormapWindows explicitly.

       GLwNresizeCallback
	      Specifies the list of callbacks that is called when
	      the GLwDrawingArea 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	 GLwNat-
	      tributeList 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 inher-
       its 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 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  Drawing  area.)
       Because	Motif gets confused by having multiple visuals in
       one top level shell,  XmNhighlightOnEnter  has  been  dis-
       abled, 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.

								6

GLwDrawingArea(3X)			     GLwDrawingArea(3X)

	       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 GLwNginitCallback and GLwNresize-
	       Callback.

       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 spec-
	      ifies that input has occurred.  Its sole purpose is
	      to call the input callback.

INITIALIZATION
       When the widget is initially created (e.g. through  XtCre-
       ateWidget(3X))  the associated window is not actually cre-
       ated.  Instead, window creation is delayed until the  wid-
       get is realized. However, glXchooseVisual is called imme-
       diately, 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

								7

GLwDrawingArea(3X)			     GLwDrawingArea(3X)

       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 initial-
	      ization 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 con-
       version. Keyboard input can also be dealt using	transla-
       tions, in which case no such conversion is required.

       Motif  programmers  should keep in mind that OSF uses vir-
       tual 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;  /* assume only one context */
	  . . .

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

	      Widget parent;	/* The parent of the gl widget */
	      Widget glw;	/* The GLwDrawingArea widget   */
	      . . .

								8

GLwDrawingArea(3X)			     GLwDrawingArea(3X)

	      /* Create the widget using RGB mode.  This can also be set
	       * in an X Defaults file
	       */
	      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);
	      /* Also add input callback if needed */
	      . . .
	  }

	  static void
	  exposeCB(Widget w, XtPointer client_data,
		   GLwDrawingAreaCallbackStruct *call_data)
	  {
	      GLwDrawingAreaMakeCurrent(w, glx_context);
	      /* redraw the display */
	  }

	  static void
	  resizeCB(Widget w, XtPointer client_data,
		   GLwDrawingAreaCallbackStruct *call_data)
	  {
	      GLwDrawingAreaMakeCurrent(w, glx_context);
	      /* perform any resize actions */
	  }

	  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);

	      /* create a visual context */
	      glx_context = glXCreateContext(XtDisplay(w), vi,
					     NULL, GL_FALSE);
	      GLwDrawingAreaMakeCurrent(w, glx_context);
	      /* Perform any necessary graphics initialization.*/
	  }

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

								9

GLwDrawingArea(3X)			     GLwDrawingArea(3X)

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 opportu-
       nity to add the ginit callback.	In such a case, initial-
       ization 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(3G),  GLwDrawingAreaMakeCurrent(3X),  glX-
       MakeCurrent(3G), GLwDrawingAreaSwapBuffers(3X) GLwCreateM-
       Draw(3X),  Core(3X), XmPrimitive(3X), VirtualBindings(3X),
       XSetWMColormapWindows(3X11) and the OpenGL spec.

							       10

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net