GlxDraw(3X)
GlxDraw, GlxMDraw -- GL drawing widgets.
As shipped in IRIX 6.5.19. Last changed in IRIX 6.5.5.
NAME GlxDraw, GlxMDraw -- GL drawing widgets. SYNOPSIS #include <Sgm/GlxDraw.h> widget = XtCreateWidget(widget, glxDrawWidgetClass, ...); ld ... -lSgm -l<anywidgetlibrary> -lXt -lgl -lX11 ... #include <Sgm/GlxMDraw.h> widget = XtCreateWidget(widget, glxMDrawWidgetClass, ...); ld ... -lSgm -lXm -lXt -lgl -lX11 ... VERSION This page documents the version of Sgm that accompanies Motif 1.2. DESCRIPTION GlxDraw and GlxMDraw are widgets suitable for GL drawing. They provide a window with the appropriate visual and colormaps needed for GL, based on supplied parameters. GlxDraw and GlxMdraw also provides callbacks for re- draw, resize, input, and initialization. GlxDraw is not a part of any widget set, but depends only on Xt. GlxDraw can be used with any widget set. GlxMDraw is identical to GlxDraw except that it is a subclass of the Motif widget class XmPrimitive and has re- sources and defaults suitable for use with Motif. For example, GlxMDraw provides the default Motif background and foreground colors for resources, and deals better with keyboard traversal. Although the GlxDraw widget can be used in a Motif program, it is recommended that GlxMDraw be used in- stead. Since both GlxDraw and GlxMDraw widgets behave almost identically, the re- mainder of this manual page will refer only to GlxDraw, except when the be- haviors differ. Unless explicitly stated, all statements about GlxDraw also apply to GlxMDraw. To create a GlxDraw, the application must first set up a GLXconfig struc- ture as described in GLXgetconfig(3G). The GLXconfig structure describes the desired GL configuration of the window being created, including infor- mation such as single or double buffering, RGB vs. color index mode, use of the overlay planes, etc. The GLXconfig parameter must be passed in as the glxConfig resource when creating the widget. When created, the widget will automatically choose the appropriate visual and colormap, as well as returning the in the glxConfig resource the actual GL configuration chosen. Creating the widget does not actually create the window until it is real- ized, and consequently, the application should not perform any GL 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 window has been created. Upon receiving this callback, the application can perform all GL initialization for the window, and can subsequently perform other GL operations on it. The initialization is discussed in more detail below. The widget will create additional windows for overlays, underlays, or popup planes if required, and if underlying support is available. The remainder of this manual page will use the term auxiliary windows to refer to these additional windows. The main window in the normal planes will be referred to as the normal window. If an application contains more than one GL window, it must use the GLXwin- set(3G) call before doing any GL operations to a window. This will select the appropriate window for the operation. There are two common situations where there is more than one GL window. One is where more than on GlxDraw widget is used in a program. The other is where auxiliary windows are used. Normally, the call to GLXwinset would be the first function called in 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. The call to GLXwinset should be of the form GLXwinset(display, call_data->window); Using the window passed in the call_data has two purposes over using XtWin- dow(3X) to obtain the window. First, it is more efficient, since it avoids the function call. Second, if auxiliary windows are used, it obtains the correct window if this is an expose callback. For other callbacks it may be necessary to use XtGetValues(3X) to obtain the values of GlxNoverlayWin- dow, GlxNunderlayWindow, or GlxNpopupWindow to determine the proper parame- ter to GLXwinset when using auxiliary windows. GlxDraw Classes GlxDraw inherits behavior and resources from the Core class. The class pointer is glxDrawClass. The class name is GlxDraw. GlxMDraw Classes GlxMDraw inherits behavior and resources from the XmPrimitive and Core classes. The class pointer is glxMDrawClass. The class name is GlxMDraw. New Resources The following table defines a set of widget resources used by the program- mer 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 GlxN or GlxC prefix and use the remaining letters. The codes in the access column indi- cate 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 Default Access ---------------------------------------------------------------------------------------- GlxNexposeCallback GlxCCallback XtCallbackList NULL C GlxNginitCallback GlxCCallback XtCallbackList NULL C GlxNglxConfig GlxCGlxConfig GLXconfig* {{0,0,0}} CG GlxNinputCallback GlxCCallback XtCallbackList NULL C GlxNoverlayColormap GlxCColormap Colormap dynamic CG GlxNoverlayDepth GlxCDepth int dynamic G GlxNoverlayExposeCallback GlxCCallback XtCallbackList NULL C GlxNoverlayVisual GlxCVisual XVisualInfo* dynamic G GlxNoverlayWindow GlxCWindow Window dynamic G GlxNresizeCallback GlxCCallback XtCallbackList NULL C GlxNoverrideColormap GlxCOverrideColormap Boolean TRUE CG GlxNpopupColormap GlxCColormap Colormap dynamic CG GlxNpopupDepth GlxCDepth int dynamic G GlxNpopupExposeCallback GlxCCallback XtCallbackList NULL C GlxNpopupVisual GlxCVisual XVisualInfo* dynamic G GlxNpopupWindow GlxCWindow Window dynamic G GlxNunderlayColormap GlxCColormap Colormap dynamic CG GlxNunderlayExposeCallback GlxCCallback XtCallbackList NULL C GlxNunderlayDepth GlxCDepth int dynamic G GlxNunderlayVisual GlxCVisual XVisualInfo* dynamic G GlxNunderlayWindow GlxCWindow Window dynamic G GlxNuseOverlay GlxCUseOverlay Boolean FALSE CG GlxNusePopup GlxCUsePopup Boolean FALSE CG GlxNuseUnderlay GlxCUseUndrlay Boolean FALSE CG GlxNvisual GlxCVisual XVisualInfo* Dynamic G GlxNexposeCallback Specifies the list of callbacks that is called when the widget re- ceives an exposure event. The callback reason is GlxCR_EXPOSE. The callback structure also includes the exposure event. The applica- tion will generally want to redraw the scene. GlxNginitCallback Specifies the list of callbacks that is called when the widget is first realized. Since no GL operations can be done before the wid- get is realized, this callback can be used to perform any appropri- ate GL initialization. The callback reason is GlxCR_GINIT. GlxNglxConfig On widget creation, specifies the GL configuration information that is to be passed to GLXgetconfig(3G). The default is an empty con- figuration structure, providing the same default as GLXgetconfig Af- ter the widget is created, the actual configuration chosen can be obtained by doing an XtGetValues(3Xt) on this resource. The passed in configuration structure may be freed after the widget is created. GlxNinputCallback Specifies the list of callbacks that is called when the widget re- ceives 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 GlxCR_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 ac- tions and translations in the application rather than using a single catch all callback. Use of explicit translations can also provide for more customizability. GlxNoverlayColormap Specifies the colormap to use in the overlay planes. It is only meaningful if overlay planes were selected in the configuration. If the colormap is not provided when the widget is created, the col- ormap returned by GLXgetconfig(3X) will be used. If a colormap is provided, it is the application programmer's responsible for guaran- teeing that the colormap is compatible with the depths of the over- lay planes. Note that unlike the normal window, it is not necessary to specify an additional resource stating whether the colormap should be used; it will always be used if provided. GlxNoverlayDepth Returns the depth of the overlay. It is only meaningful if the overlays are in use. GlxNoverlayExposeCallback Specifies the list of callbacks that is called when the overlay re- ceives an exposure event. The callback reason is GlxCR_EXPOSE. The callback structure also includes the exposure event. The applica- tion will generally want to redraw the overlay. GlxNoverlayVisual Returns the visual for the overlay. It is only meaningful if the overlays are in use. GlxNoverlayWindow Returns the window that is used for the overlay. It is only mean- ingful if the overlays are in use. GlxNoverrideColormap If TRUE, specifies that the colormap returned by GLXgetconfig should be installed by the widget. In this case, the XtNcolormap Core re- source will be overridden when the widget is created. After creat- ing the widget, the XtNcolormap resource is set to the new colormap. This is the default case. If GlxNoverrideColormap is FALSE, the colormap specified in the XtNcolormap Core resource will be used. When setting this resource to FALSE, the programmer is responsible for making sure that the colormap is consistent with the request pa- rameters to GLXgetconfig such as the depth. Specifying an inconsis- tent colormap will result in an X Bad Match error. This resource only has an effect if set at widget creation time. GlxNpopupColormap Similar to GlxNoverlayColormap, but for the popup planes. GlxNpopupDepth Similar to GlxNoverlayDepth, but for the popup planes. GlxNpopupExposeCallback Similar to GlxNoverlayCallback, but for the popup planes. GlxNpopupVisual Similar to GlxNoverlayVisual, but for the popup planes. GlxNpopupWindow Similar to GlxNoverlayWindow, but for the popup planes. GlxNresizeCallback Specifies the list of callbacks that is called when the GlxDraw is resized. The callback reason is GlxCR_RESIZE. The application may wish to call viewport(3G) using the supplied width and height para- meters, and then redraw the scene. GlxNunderlayColormap Similar to GlxNoverlayColormap, but for the underlay planes. Note that underlay support is not currently provided in GLX. GlxNunderlayDepth Similar to GlxNoverlayDepth, but for the underlay planes. Note that underlay support is not currently provided in GLX. GlxNunderlayExposeCallback Similar to GlxNoverlayCallback, but for the underlay planes. Note that underlay support is not currently provided in GLX. GlxNunderlayVisual Similar to GlxNoverlayVisual, but for the underlay planes. Note that underlay support is not currently provided in GLX. GlxNunderlayWindow Similar to GlxNoverlayWindow, but for the underlay planes. Note that underlay support is not currently provided in GLX. GlxNuseOverlay To use the overlays this must be set to TRUE when creating the wid- get. GlxNusePopup To use the popup planes this must be set to TRUE when creating the widget. GlxNuseUnderlay To use the underlays this must be set to TRUE when creating the wid- get. Note that underlay support is not currently provided in GLX. GlxNvisual Specifies the normal window's visual. It is always computed when the widget is created, and cannot be specified by the application. Inherited Resources Both GlxDraw and GlxMDraw inherit behavior and resources from the core su- perclass. For a complete description of each resource, refer to the man page for that superclass. Motif programmers may use Xm prefixes instead of Xt prefixes where appropriate. Name Class Type Default Access -------------------------------------------------------------------------------------------------------------- XtNaccelerators XtCAccelerators XtAccelerators dynamic CSG XtNancestorSensitive XtCSensitive Boolean dynamic G XtNbackground XtCBackground Pixel dynamic CSG XtNbackgroundPixmap XtCPixmap Pixmap unspecified CSG XtNborderColor XtCBorderColor Pixel XtDefaultForeground CSG XtNborderPixmap XtCPixmap Pixmap unspecified CSG XtNborderWidth XtCBorderWidth Dimension 0 CSG XtNcolormap XtCColormap Colormap dynamic CG XtNdepth XtCDepth int dynamic G XtNdestroyCallback XtCCallback XtCallbackList NULL C XtNheight XtCHeight Dimension dynamic CSG XtNinitialResourcesPersistent XtCInitialResourcesPersistent Boolean True C XtNmappedWhenManaged XtCMappedWhenManaged Boolean True CSG XtNscreen XtCScreen Screen * dynamic CG XtNsensitive XtCSensitive Boolean True CSG XtNtranslations XtCTranslations XtTranslations dynamic CSG XtNwidth XtCWidth Dimension dynamic CSG XtNx XtCPosition Position 0 CSG XtNy XtCPosition Position 0 CSG A few of the resources above behave somewhat differently in the GL widget. XtNdepth is calculated when the visual is created; the depth cannot be specified explicitly except indirectly through the GlxNglxConfig resource. If GlxNoverrideColormap is TRUE, than the default for GlxNcolormap is to calculate it dynamically based on the GlxNglxConfig parameter. In addition, the Motif version GlxMDraw also inherits from XmPrimitive. Name Class Type Default Access ------------------------------------------------------------------------------------------------- XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 0 G XmNnavigationType XmCNavigationType XmNavigationType XmNONE G XmNshadowThickness XmCShadowThickness Dimension 0 G XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean False CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData Pointer NULL CSG The resources XmNhighlightThickness and XmNshadowThickness are unsupported and may not be changed. Callback Information A pointer to the following structure is passed to each callback: typedef struct { int reason; XEvent * event; Window window; int buffer; Dimensionwidth, height; } GlxDrawCallbackStruct; reason Indicates why the callback was invoked. Appropriate values are stated in the above resource descriptions. For Motif programmers, the values GlxCR_EXPOSE, GlxCR_RESIZE, and GlxCR_INPUT are equal to XmCR_EXPOSE, XmCR_RESIZE, and XmCR_INPUT respectively. GlxCR_GINIT does not have a Motif equivalent. event Points to the XEvent that triggered the callback. This is NULL for GlxNginitCallback and GlxNresizeCallback. window Is set to the appropriate window. Generally, this is the normal window. However, for the auxiliary expose callbacks, this is the appropriate auxiliary window. buffer Is the buffer type of window (as described in GLXgetconfig(3G)). It is one of GLX_NORMAL, GLX_OVERLAY, GLX_UNDERLAY, and GLX_POPUP. width and height Are set to the width and height of the window. Translations GlxDraw has the translations listed below. <KeyDown>: glxInput() <KeyUp>: glxInput() <BtnDown>: glxInput() <BtnUp>: glxInput() <BtnMotion>: glxInput() GlxMDraw 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 GlxDraw has the following action routine: glxInput(): Called whenever one of the above translations specifies that input has occurred. Its sole purpose is to call the input callback. INITIALIZATION When the widget is initially created (e.g. through XtCreateWidget(3X)) the associated window is not actually created. Instead, window creation is de- layed until the widget is realized. However, GLXgetconfig(3G) 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: * No GL operations can be done to the window * No resize callbacks are generated. * Neither the normal window nor the auxiliary windows are available. When the widget is realized, the following actions take place: * The normal window and any auxiliary windows are created. * GLXlink(3G) is called. An application using the GlxDraw widget should never need to call GLXlink(3G). (Similarly it should never need to call GLXunlink(3G) as that is called when the widget is de- stroyed.) * GLXwinset(3G) is called on the normal window. If an application has only one GL window, it need never call GLXwinset(3G). * The ginit callback is called. The user may use this callback to perform any needed GL initialization to the window. The GlxDraw widget will generally use a different colormap than the X based portion of the application. The colormap may need to be installed using XSetWMColormapWindows(3X11). (Auxiliary windows will also need their col- ormaps installed, as describe in the next section.) OVERLAYS, UNDERLAYS, and POPUP PLANES To include auxiliary windows, the following steps must be taken: * Verify that there is support for the appropriate type of auxiliary window. Not all hardware supports overlays. Currently, the under- lying GLX does not support underlays. * Set the GlxNuseOverlay, GlxNuseUnderlay, or GlxNusePopup resources as appropriate to TRUE. * Set the appropriate entries in the GlxNconfig parameter as described in GLXgetconfig(3G). * Create the widget as normal. * Make sure that the auxiliary colormap is installed along with the GlxDraw colormap using XSetWMColormapWindows(3X11). (Note that the call to XSetWMColormapWindows(3X11) will usually specify three win- dows in this case: the overlay window, the GlxDraw window, and the top level window.) * Provide an expose callback routine for each auxiliary used, by set- ting GlxNoverlayExposeCallback, GlxNunderlayExposeCallback, or GlxN- popupExposeCallback. * Before drawing to an auxiliary window, do a GLXwinset(3G) to that window. The window ID can be obtained from the callback if the drawing is in response to an expose, or by querying the GlxNoverlay- Window, GlxNunderlayWindow or GlxNpopupWindow resources. 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 XLookup- String(3X) to do the conversion. Keyboard input can also be dealt using translations, in which case no such conversion is required. GL programs will typically draw their backgrounds by using clear(3G), gclear(3G), or some similar routine in a specified color. Thus, the XtNbackground resource will have no direct effect. To get a matching back- ground in GL, first use XtGetValues on the XtNbackground resource to find the background color and use that color explicitly. However, be aware that the background pixel was set relative to the parent's colormap, not the GlxDraw widget's colormap. Motif programs may also choose to make use of the XtNforeground resource in a similar manner. GL functions such as getsize(3G) and getorigin(3G) require round trips to the server and are thus slow. It is quicker to use XtGetValues to obtain the XtNx, XtNy, XtNheight, and XtNwidth values directly from the widget. To work properly over the network using the Distributed Graphics Library (DGL), applications may need to call gflush(3G) after drawing using GL. The end of each callback and action routine is a good place to include the call. Alternatively, if there is a common drawing routine used by all callbacks and actions, the gflush(3G) call may be placed at the end of that routine. Providing a user colormap is handled slightly differently for normal and for auxiliary windows. For normal windows, the colormap is a standard Core resource for which a default already exists. Consequently, the default colormap will be overridden by the result of GLXgetconfig(3G) unless GlxNoverrideColormap resource is set to FALSE. For auxiliary windows, there is no preexisting default colormap, so if a user provided colormap is provided, it will always be used. 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 trans- lation should specify <key>osfCancel instead of <key>Escape. Motif programmers may also create a GlxMDraw widget with the Motif style GlxCreateMDraw(3X). EXAMPLE Here are some code fragments that create a GlxDraw widget, and manage the appropriate callbacks. #include <Sgm/GlxDraw.h> . . . /* The following configuration should match your hardware needs as */ /* Described in GLXgetconfig(3X) */ GLXconfig db_rgb_desc[] = { { GLX_NORMAL, GLX_RGB,TRUE }, { GLX_NORMAL, GLX_DOUBLE,TRUE }, { 0, 0, 0 } }; main() { Arg args[10]; int n; Widget parent; /* The parent of the gl widget */ Widget glw; /* The glxDraw widget */ . . . n = 0; XtSetArg(args[n], GlxNglxConfig, db_rgb_desc); n++; glw = XtCreateManagedWidget("glx", glxDrawWidgetClass, parent, args, n); XtAddCallback(glw, GlxNexposeCallback, exposeCB, 0); XtAddCallback(glw, GlxNresizeCallback, resizeCB, 0); XtAddCallback(glw, GlxNginitCallback, ginitCB, 0); /* Also add input callback if need be */ . . . } static void exposeCB(w, client_data, call_data) Widget w; caddr_t client_data; GlxDrawCallbackStruct *call_data; { GLXwinset(display, call_data->window); /* redraw the display */ } static void resizeCB(w, client_data, call_data) Widget w; caddr_t client_data; GlxDrawCallbackStruct *call_data; { GLXwinset(display, call_data->window); viewport(0, (Screencoord) call_data->width-1, 0, (Screencoord) call_data->height-1); /* redraw the display */ } static void ginitCB(w, client_data, call_data) Widget w; caddr_t client_data; GlxDrawCallbackStruct *call_data; { GLXwinset(display, call_data->window); /* Perform any necessary graphics initialization.*/ } The Motif program need only differ by including GlxMDraw.h instead of Glx- Draw.h and by creating a widget of type GlxMDrawWidgetClass instead of Glx- DrawWidgetClass. As an alternative, the Motif program could use GlxCre- ateMDraw(3X) instead. WARNINGS The GlxDraw should be used only for GL drawing. Using X drawing to a Glx- Draw is unsupported. All color resources (e.g XtNbackground) specify pixels in the GlxDraw's parent's colormap. Since GL does not directly make use of these resources, this won't normally be a problem. However, if a program wishes to query such a color (for example, to make a matching background in the GlxDraw widget), it should use the parent's colormap. Colormaps should be installed using XSetWMColormapWindows(3X11). This re- quests that the window manager install the appropriate colormaps every time the pointer enters the window. Colormaps should not be installed with XIn- stallColormap(3X11). If a GlxDraw widget is created as a child of an already realized widget, the GlxDraw 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 GlxDraw widget is used in a Motif program and keyboard traversal is attempted, the behavior is undefined if the user traverses into the GlxDraw widget. RELATED INFORMATION GLXgetconfig(3G), GLXwinset(3G), GlxCreateMDraw(3X), Core(3X), XmPrimi- tive(3X), VirtualBindings(3X), Gflush(3G), XSetWMColormapWindows(3X11) and the "IRIS NeWS to X Transition Guide" GlxDraw(3X)