diff options
Diffstat (limited to 'nx-X11/extras/ogl-sample/main/doc/man/manglw/glwdrawingarea.gl')
| -rw-r--r-- | nx-X11/extras/ogl-sample/main/doc/man/manglw/glwdrawingarea.gl | 485 |
1 files changed, 485 insertions, 0 deletions
diff --git a/nx-X11/extras/ogl-sample/main/doc/man/manglw/glwdrawingarea.gl b/nx-X11/extras/ogl-sample/main/doc/man/manglw/glwdrawingarea.gl new file mode 100644 index 000000000..f25a4f5c6 --- /dev/null +++ b/nx-X11/extras/ogl-sample/main/doc/man/manglw/glwdrawingarea.gl @@ -0,0 +1,485 @@ +.\" ** +.\" ** (c) Copyright 1993, 1994, 1995, 1996 Silicon Graphics, Inc. +.\" ** +.\" ** (c) Copyright 1989, 1990, 1991 Open Software Foundation, Inc. +.\" ** All Rights Reserved. +.\" ** +.\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company +.\" ** +.\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, +.\" ** Maynard, MA. All Rights Reserved. +.\" ** +.\" ** +.TH GLwDrawingArea 3X "" "" "" "" +.SH NAME +\fBGLwDrawingArea, GLwMDrawingArea \(em OpenGL drawing widgets.\fP +.iX "GLwDrawingArea" "GLwMDrawingArea" +.iX "widget class" "OpenGL" "Draw" +.sp 1 +.SH SYNOPSIS +\fB#include <X11/GLw/GLwDrawA.h> +.br +\fBld ... -lGLw -lGL -l<anywidgetlibrary> -lXext -lXt -lX11 -lm +.sp +\fB#include <X11/GLw/GLwMDrawA.h> +.br +\fBld ... -lGLw -lGL -lXm -lXext -lXt -lX11 -lm +.sp 1 +.SH DESCRIPTION +\fBGLwDrawingArea\fP and \fBGLwMDrawingArea\fP 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. +.PP +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\(Tm 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. +.PP +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 GLwMDrawingArea. +.PP +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. +.PP +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). +.PP +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 +\fBginit\fP callback may be used to indicate when the window has been +created. Upon receiving this callback, the application can perform +all OpenGL initialization for the window, and can subsequently perform +other operations on it. The initialization is discussed in more +detail below. +.PP +Applications select which GLwDrawingArea they are accessing using either +\fBglXMakeCurrent\fP or the convenience function +\fBGLwDrawingAreaMakeCurrent\fP 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. +.PP +If an application is using double buffering, it may call +\fBGLwDrawingAreaSwapBuffers\fP instead of \fBglXSwapBuffers\fP. This +allows the use of the widget instead of the display and window. +.ne 5 +.SS "GLwDrawingArea Classes" +GLwDrawingArea inherits behavior and resources from the \fBCore\fP class. +.br +The class pointer is \fBglwDrawingAreaWidgetClass\fP. +.br +The class name is \fBGLwDrawingArea\fP. +.PP +.ne 5 +.SS "GLwMDrawingArea Classes" +GLwMDrawingArea inherits behavior and resources from the +\fBXmPrimitive\fP and \fBCore\fP classes. +.br +The class pointer is \fBglwMDrawingAreaWidgetClass\fP. +.br +The class name is \fBGLwMDrawingArea\fP. +.sp 1 +.SS "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 \fBGLwN\fP or +\fBGLwC\fP prefix and use the remaining letters. +There are two tables included. The first table includes resources +that correspond directly to the attributes used by \fBglXChooseVisual\fP. +As with \fBglXChooseVisual\fP, 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 \fIGLwNattribList\fP or \fIGLwNvisualInfo\fP resource is +set, these resources are ignored. The specific meaning of these +resources is discussed in the \fBglXChooseVisual\fP manual page and +will not be discussed here. +.sp 1 +.ne 18 +.TS +center allbox; +lBp8 lBp8 lBp8 lBp8 +lp8 lp8 lp8 lp8. +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 +.TE +.sp 1 +.PP +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 (\fBC\fP), +set by using \fBXtSetValues\fP (\fBS\fP), +retrieved by using \fBXtGetValues\fP (\fBG\fP), or is not applicable +(\fBN/A\fP). +.sp 1 +.ne 12 +.TS +center; +lp8B lp8B lp8B lp8B lp8B +lp8 lp8 lp8 lp8 lp8. +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 +.TE +.sp 1 +.IP "\fBGLwNallocateBackground\fP" +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 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.) +.IP "\fBGLwNallocateOtherColors\fP" +This is similar to \fBGLwNallocateBackground\fP, 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 \fBXmNforeground\fP, \fBXmNhighlightColor\fP, +and \fBXmNhighlightPixmap\fP are calculated. +.IP "\fBGLwNattribList\fP" +Contains the list of attributes suitable for a call to +\fBglXChooseVisual\fP. If this resource is NULL, it is calculated +based on the attribute resources. If it is not NULL, the attribute +resources are ignored. +.IP "\fBGLwNexposeCallback\fP" +Specifies the list of callbacks that is +called when the widget receives an exposure event. +The callback reason is \fBGLwCR_EXPOSE\fP. +The callback structure also includes the exposure event. The +application will generally want to redraw the scene. +.IP "\fBGLwNginitCallback\fP" +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 \fBGLwCR_GINIT\fP. +.IP "\fBGLwNinputCallback\fP" +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 \fBGLwCR_INPUT\fP. +.IP "" +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. +.IP "\fBGLwNinstallBackground\fP" +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 \fBGLwNallocateBackground\fP is also TRUE. +.IP "\fBGLwNinstallColormap\fP" +If set to TRUE, the widget will call \fIXSetWMColormapWindows\fP 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 +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 \fIXSetWMColormapWindows\fP +explicitly. +.IP "\fBGLwNresizeCallback\fP" +Specifies the list of callbacks that is +called when the GLwDrawingArea is resized. +The callback reason is \fBGLwCR_RESIZE\fP. +.IP "\fBGLwNvisualInfo\fP" +Contains a pointer to the window's visual info structure. If NULL, +the visualInfo is calculated at widget creation time based on the +\fIGLwNattributeList\fP resource (which is itself calculated from the +various resources). If \fBGLwNvisualInfo\fP is not NULL the +\fIGLwNattributList\fP and the attribute resources are ignored. +.sp 1 +.SS "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. +.PP +In addition, the Motif version GLwMDrawingArea also inherits from XmPrimitive. +The behavior of the color resources has been described previously. +The \fITraversalOn\fP resource is disabled for this widget, but if +keyboard input is required it should be enabled. (Also, the +application should call \fBXmProcessTraversal(widget, XmTRAVERSE_CURRENT)\fP +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, +\fBXmNhighlightOnEnter\fP has been disabled, and +\fBXmNhighlightThickness\fP has been set to 0. +.SS "Callback Information" +A pointer to the following structure is passed to each callback: +.sp 1 +.ne 6 +.nf +.ta .25i 1.3i +\fBtypedef struct\fP +{ + \fBint\fP \fIreason\fP; + \fBXEvent\fP \fI*event\fP; + \fBDimension\fP \fIwidth, height\fP; +} \fBGLwDrawingAreaCallbackStruct\fP; +.fi +.sp 1 +.IP "\fIreason\fP" .75i +Indicates why the callback was invoked. Appropriate values are +stated in the above resource descriptions. For Motif programmers, the +values \fBGLwCR_EXPOSE\fP, \fBGLwCR_RESIZE\fP, and \fBGLwCR_INPUT\fP +are equal to \fBXmCR_EXPOSE\fP, \fBXmCR_RESIZE\fP, and +\fBXmCR_INPUT\fP respectively. \fBGLwCR_GINIT\fP does not have a +Motif equivalent. +.IP "\fIevent\fP" .75i +Points to the \fBXEvent\fP that triggered the callback. +This is NULL for \fBGLwNginitCallback and \fBGLwNresizeCallback\fP. +.IP "\fIwidth\fP and \fIheight\fP" .75i +Are set to the width and height of the window. +.br +.ne 10 +.sp 1 \"Adds space before the SS +.SS "Translations" +GLwDrawingArea has the translations listed below. +\fB +.nf +.ta 1.5i +.ne 5 +<KeyDown>: glwInput() +<KeyUp>: glwInput() +<BtnDown>: glwInput() +<BtnUp>: glwInput() +<BtnMotion>: glwInput() +.fi +.PP +GLwMDrawingArea has the following additional translation: +\fB +.nf +.ta 1.5i +<Key>osfHelp: PrimitiveHelp() +.fi +.PP +An application wishing to catch other events than these defaults can +do so by installing a different translation table. +\fP +.sp 1 \"Adds space before the SS +.SS "Action Routines" +The GLwDrawingArea has the following action routine: +.IP "\fBglwInput()\fP:" +Called whenever one of the above translations specifies that input has +occurred. Its sole purpose is to call the input callback. +.sp 1 +.SH INITIALIZATION +.PP +When the widget is initially created (e.g. through +\fBXtCreateWidget(3X)\fP) the associated window is not actually +created. Instead, window creation is delayed until the widget is +realized. However, \fBglXchooseVisual\fP is called immediately, so +information based on its results is available. +.PP +Between the time the widget is created and it is realized, +the following apply: +.TP +\(bu +No OpenGL operations can be done to the window +.TP +\(bu +No resize callbacks are generated. +.TP +\(bu +The normal window is available (XtWindow returns NULL). +.TP +\(bu +\fBGLwDrawingAreaMakeCurrent\fP (and \fBglXMakeCurrent\fP) should not +be called. +.PP +When the widget is realized, the following actions take place: +.PP +.TP +\(bu +The window is created. +.TP +\(bu +The \fBginit\fP callback is called. The user may use this callback to +perform any needed OpenGL initialization to the window. +.sp 1 +.SH NOTES +.PP +When using the input callback to receive keyboard input, the keycode +in the event must be converted to a KeySym. Use +\fBXLookupKeysym(3X)\fP or \fBXLookupString(3X)\fP to do the +conversion. Keyboard input can also be dealt using translations, in +which case no such conversion is required. +.PP +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. +.PP +Motif programmers may also create a GLwMDrawingArea widget with the Motif +style \fBGLwCreateMDrawingArea\fP. +.sp 1 +.ne 10 +.SH EXAMPLE +Here are some code fragments that create a GLwDrawingArea widget, and manage +the appropriate callbacks. +.sp +.nf +\f(CW + #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 */ + . . . + + /* 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.*/ + } +\fP +.fi +.P +The Motif program need only differ by including +\fBGLwMDrawingArea.h\fP instead of \fBGLwDrawingArea.h\fP and by creating a widget of type +\fBGLwMDrawingAreaWidgetClass\fP instead of \fBGLwDrawingAreaWidgetClass\fP. As an +alternative, the Motif program could use \fBGLwCreateMDraw(3X)\fP instead. +.sp 1 +.SH WARNINGS +.PP +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 \fBginit\fP callback. In such a +case, initialization should be done immediately after creating the +widget rather than by using the callback. +.PP +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. +.SH SEE ALSO +\fBglXChooseVisual(3G)\fP, \fBGLwDrawingAreaMakeCurrent(3X)\fP, +\fBglXMakeCurrent(3G)\fP, \fBGLwDrawingAreaSwapBuffers(3X)\fP +\fBGLwCreateMDraw(3X)\fP, \fBCore(3X)\fP, \fBXmPrimitive(3X)\fP, +\fBVirtualBindings(3X)\fP, \fBXSetWMColormapWindows(3X11)\fP +and the OpenGL spec. |