3    Programming in the Tru64 UNIX X Window Environment

Use the X Window System (Scheifler and Gettys) and X Window System Toolkit (Asente and Swick) (Digital Press) manuals as the primary references for information on how to program X Window System applications.

However, information specific to the Tru64 UNIX X server is not covered in those manuals. This chapter includes information on the following topics:

3.1    Extensions to the X Server

Tru64 UNIX supports a number of protocol X server extensions. Many of these extensions are built and dynamically loaded as sharable libraries. Section 1.7 lists the components of the Tru64 UNIX extension library and explains the processes for loading and making calls to the component libraries.

The following list contains the X11 R6.3 protocol X server extensions that Tru64 UNIX supports:

Documentation on many of the extensions is available from the X Consortium. Header files for several of the extensions are in the /usr/include/X11/extensions directory. The following sections provide brief descriptions of each extension.

3.1.1    Application Group

The Application Group extension provides the framework that allows more than one program to manage X applications on the desktop. Use of this extension allows embedding or inserting X programs into the windows of another program, such as a web browser.

An Application Group is a set of one or more applications that are managed by an application that is known as the Application Group Leader. The purpose of the Application Group is to share the Substructure-Redirect attribute of the root window with the application manager and one or more Application Group Leaders.

3.1.2    BIG-REQUESTS

The standard X protocol only allows requests up to 2 18 bytes long. BIG_REQUESTS , a new protocol extension, has been added. This extension allows a client to extend the length field in protocol requests to be a 32-bit value. This is useful for extensions that transmit complex information to the server.

3.1.3    DPMS - Display Power Management Signaling

The Display Power Manger Signaling extension supports powerdown capable monitors.

Not all graphics adapters and monitors are DPMS capable. It is important to check the equipment specifications of your monitors because monitors that do not support DPMS can be damaged by the activation of the DPMS feature.

The time required for a monitor to return from the power saver state is dependent on the amount of time the monitor has been in power saver state. This is the result of the cooling of the monitor phosphor and the time required to reheat the phosphor. It is not a function of the operating system or the X Window system.

3.1.4    Low Bandwidth Extension

The Low Bandwidth X (LBX) extension defines compression and local caching techniques that improve performance of X applications in wide area networks and across slow speed network connections. Performance is improved by reducing the amount of protocol data that is transported over the network and by reducing the number of client to server round trips required for common application start-up operations.

This extension is implemented using an X server extension and a proxy application. The X server extension provides a new optimized protocol. The proxy application, lbxproxy, translates a normal client X protocol stream into the LBX stream. This permits an existing application to benefit from the optimized protocol without any changes to the application.

The proxy is useful when multiple applications are running on a local area network that is separated from the X server by a slower network. In this case, the local cache is shared by each application using the same proxy process.

3.1.5    MIT-SCREEN-SAVER Extension

The Screen Saver extension enables a client to receive notification when the screen has been inactive for a specified amount of time or whenever it cycles. The extension is useful to those writing screensaver programs.

3.1.6    MIT-SHM - MIT Shared Memory Extension

This extension allows images to be placed in shared memory segments accessible by both the application and X server. Using shared memory reduces the amount of bandwidth required to transfer the images between the application and the server.

3.1.7    MIT-SUNDRY-NONSTANDARD Protocol Extension

This extension permits tolerance of old X bugs. See the xset(1X) reference page for a description of the -bc flag.

3.1.8    Multibuffering Extension

This extension enables a client application to perform the following operations:

3.1.9    OpenGL - Open Graphics Library Extension

This extension provides a software interface to graphics hardware. The interface consists of a set of procedures and functions that allows a programmer to specify the objects and operations involved in producing high-quality graphical images - specifically color images of three-dimensional objects.

To the programmer, OpenGL is a set of commands that allows the specification of geometric objects in two or three dimensions, together with commands that control how these objects are rendered into the frame buffer. For the most part, OpenGL provides an immediate-mode interface, so that specifying an object causes it to be drawn.

A typical program that uses OpenGL begins with calls to open a window in the frame buffer into which the program will draw. Then, calls are made to allocate a GL context and associate it with the window. Once a GL context is allocated, the programmer can issue OpenGL commands. Some commands are used to draw simple geometric objects for example, points, line segments, and polygons. Other commands affect the rendering of these primitives, including how they are lit or colored and how they are mapped from the user's two- or three-dimensional model space to the two-dimensional screen. OpenGL also has commands that affect direct control of the frame buffer, such as those that read and write pixels.

In the X Window System, OpenGL rendering is made available as an extension to X in the formal X sense: connection and authentication are accomplished with the normal X mechanisms. As with other X extensions, there is a defined network protocol for the OpenGL rendering commands that are encapsulated within the X byte stream.

Information on OpenGL is provided in the OpenGL Reference Manual.

3.1.10    PanoramiX Extension (Xinerama)

The PanoramiX extension allows a system configured with multiple video monitors (a multi-headed system) to operate the monitors as a single large screen. Windows can span multiple screens and can move from one screen to another. This extension is only supported in homogeneous graphics environments. That is, the environment must consist of common devices, visuals, depths, resolutions, and so on.

Monitor configurations can easily be enhanced by enabling the PanoramiX extension in combination with use of the -screenOrder option, which allows screen ordering based on physical monitor location.

The Xnest and Xvbf servers are not configured to work with the PanoramiX extension. In addition, the Open3D layered product is not supported with the PanoramiX extension.

The extension causes applications to display on multiple screens of a workstation as if the workstation is supporting only a single screen (screen :0). The size of the composite screen equals the size of the multiple screens combined.

It is necessary to create multiple instances of some resources because these resources are screen unique or they contain a back pointer to a ScreetPtr. These resources include GCs, windows, pixmaps, or colormaps. When the server handles a client request that creates a resource, the extension creates an equivalent instance of the resource for each physical screen. PanoramiX uses linked lists to keep track of these resources. Each entry in the list contains the following information:

3.1.11    Remote Execution Extension (RX)

The Remote Execution (RX) extension defines a MIME type document and defines how the document is used to execute a remote application from a Web Browser. The document is provided to the browser so that the browser can set up an environment for the application to run in. The RX document can list both required and optional services and allows the preferences of the browser to determine which services to use. The RX plug-in is loaded as a default application helper for the Netscape Web Browser.

3.1.12    Security Extension

The Security extension contains new protocol that provides enhanced X server security. This extension adds to the X protocol the concepts of trusted and untrusted clients. The trust status of a client is determined by the authorization used at connection setup. All clients using host-based authorization are considered trusted. Clients using other authorization protocols may be either trusted or untrusted depending on the data included in the connection authorization phase.

The requests in the security extension permit a trusted client to create multiple authorization entries for a single authorization protocol. Each entry is tagged with the trust status to be associated with any client presenting that authorization.

When a connection identifying an untrusted client is accepted, the client is restricted from performing certain operations that would steal or modify data that is held by the server for trusted clients. An untrusted client performing a disallowed operation will receive protocol errors.

When a client is untrusted, the server will also limit the extensions that are available to the client. Each X protocol extension is responsible for defining what operations are permitted to untrusted clients. By default, the entire extension is hidden.

3.1.13    SHAPE - X11 Nonrectangular Window Shape Extension

This extension provides arbitrary window and border shapes within the X11 protocol. The oclock program, for example, uses this extension to produce a round clock-face display.

3.1.14    SMT - Shared Memory Transport Extension

The Shared Memory Transport (SMT) extension provides a completely shared memory transport for requests. For many operations, performance significantly increases when this extension is used. Unlike the MIT-SHM (shared memory transport) extension which supports only image transfers, the Digital SMT supports the full protocol.

All requests are passed to the server by means of a shared memory queue. The server and client control the flow by using X protocol requests over UNIX Domain sockets. All events, replies, and errors are returned through UNIX Domain sockets.

This transport is suitable only for high-bandwidth applications that typically use large requests. Short requests may take longer to process with SMT than with UNIX Domain sockets because of synchronization overhead. For example, XNoOp requests will take twice as much time to execute.

The DISPLAY environment variable must be set to local:0 when SMT is used.

When using SMT, the X server may not be able to allocate a shared memory segment. This problem occurs if the system shared memory resources are depleted; a warning message appears on the client side.

3.1.15    SYNC - Synchronization Extension

The synchronization extension, SYNC, provides primitive calls that allow synchronization between clients to take place within the X server. This feature eliminates network errors that can arise when two communicating systems are running a distributed application that requires both systems to be synchronized.

With this extension, clients on different hosts running different operating systems can be synchronized. Multimedia applications can use this extension to synchronize audio, video, and graphics data streams. In addition, the extension provides internal timers within the X server that can be used to synchronize client requests. Using this feature, simple animation applications can be implemented without having to use round-trip requests. The extension allows applications to make the best use of buffering within the client, server, and network.

3.1.16    XC-MISC

The XC-MISC protocol allows clients to get back ID ranges from the server. Xlib handles this automatically, making this useful for long-running applications that use many IDs over their lifetime.

3.1.17    XIE - X Imaging Extension

The X Imaging extension provides mechanisms for the transfer and display of virtually any image on any X-capable hardware. Although this extension is not intended to serve as a general purpose imaging processor, it provides a large number of primitives for image rendering and image enhancement. These primitives can be combined to form complex expressions. XIE also includes facilities for importing and exporting images between clients and servers, facilities for moving images between client and servers as well as between core X modules and XIE modules, and facilities that enable applications to access images as resources.

The X Consortium provides documentation for XIE in PostScript format. That documentation is located on the Tru64 UNIX system in the /usr/doc/xie directory. The following list describes the documents:

3.1.18    X Input Extension

This extension supports input devices other than the core X keyboard and pointer. The extension is designed to handle request and event definitions that are analogous to core request and event definitions. This design allows extension input devices to be individually distinguishable from each other as well as from core input devices. The extension requests and events use a device identifier and support the reporting of n-dimensional motion data as well as other data that is not reportable through core input events.

3.1.19    X Keyboard Extension for X11 R6

The X Keyboard Extension (XKB) server extension is new for X11 R6.1. XKB enhances control and customization of the keyboard under the X Window System by providing the following:

In addition, the X11 R5 (for versions of Tru64 UNIX earlier than Version 4.0) AccessX server extension for people with physical impairments has been incorporated into the XKB server extension. These accessibility features include StickyKeys, SlowKeys, BounceKeys, MouseKeys, and ToggleKeys, as well as complete control over the autorepeat delay rate.

3.1.20    XKME - X Server Keyboard Management Extension

This extension enables an X client application to access the server mode-switch modifier. The mode switch is designed to meet the needs of character sets of languages that require native characters (for example, Hebrew and Japanese). The mode switch enables a client application to switch back and forth between character groups: Group 1 (ASCII characters) and Group 2 (native characters).

The function of the mode switch is similar to that of the Shift or Shift Lock key. These mechanisms both enable multiple symbols (keysym) to be generated from single keys, with one symbol for one mode or shift or shift-lock state and another symbol for the other state. For example, on the American keyboard, 3 and # can be switched by the shift state.

The combination of the mode-switch and shift/lock mechanisms allows up to four keysyms to be established for a single key.

The entry point XKMEDoKBModeSwitch is defined for the mode-switch modifier and can be set to the following modes of operation:

LockDownModeSwitch Locks down the mode-switch modifier; that is, switches to Group 2.
UnlockModeSwitch Unlocks the mode-switch modifier; that is, switches to Group 1.

The dxkeycaps(1X) reference page describes how to access the shift modifier from client applications and contains general information on keyboard mappings.

3.1.21    Xp (X Print Service Extension)

X Print service is an X extension that allows X imaging to non-display devices such as printers and fax machines. The core of the X Print service is the X Print Server.

Applications that require printing operations can make a connection to the X Print Server and list the available printers using the GetPrinterList request. After selecting a printer, an application creates and sets a print context using the PrintCreateContext and PrintSetContext requests.

The print context is a fundamental X print service concept. The print context:

A print context also affects how the DDX driver generates page description language (PDL), and how the PDL is submitted to the spooler. It may also affect fonts and other elements of the DDX layer of the X print server.

Printer capabilities are determined by attribute pools within the print context. These pools can contain information related to context's server, printer, job, document, and page options. PrintGetAttributes and PrintSetAttributes are used to access and modify attribute pools.

PrintStartJob and PrintEndJob are used to delineate print jobs. A job is a collection of documents defined by PrintStartDoc and PrintEndDoc. Each document is a collection of pages. Upon completion of a job, the server sends any resulting PDL to a print spooler, or makes it available for retrieval by an application.

3.1.22    XTrap Extension

This extension allows a client application to track and use information about input events occurring on a remote X server. XTrap also allows a client application to provide input to the remote server.

3.1.23    XTEST Extension

This extension contains a minimal set of X client and server extensions that are required to completely test the X11 server with no user intervention. The extension is designed to meet the following goals:

3.1.24    XV - X Video Extension

This extension performs the following functions:

3.2    X Display Manager Greeter Module

In the X Display Manager ( xdm ), the greeter module is a separate dynamically loadable library. The greeter collects identifying information from the user (for example, name and password), authenticates the user, and optionally starts the login session. Application programmers can customize this module to suit the needs of their application.

The greeter library that is used is determined by the value of the DisplayManager.greeterLib resource in the /var/X11/xdm/xdm-config file. This library is required to define a function named GreetUser().

The X Display Manager uses dlopen() to dynamically load the greeter library. It uses dlsym() to find the GreetUser() function.

The GreetUser() function can either handle the user's session itself or allow xdm to do so. The return value of GreetUser() indicates to xdm whether or not to start a session.

The GreetUser() function is passed the xdm struct display pointer, a pointer to a Display Struct (defined in /usr/include/X11/Xlib.h), and pointers to greet and verify structures. If GreetUser() expects xdm to run the session, it fills in the Display pointer and the fields of the greet and verify structs.

Definitions of struct display, struct verify_info, and struct greet_info are located in /usr/examples/xdm/dm.h. The GreetUser() function prototype is defined in /usr/examples/xdm/greet.h.

Any greeter library compiled on a Tru64 UNIX system prior to Version 4.0 must be recompiled to integrate data structure changes made in X11 R6. The use of a version field on these structs eliminates the need to recompile for future versions of the operating system.

The GreetUser() function is defined in greet.h as follows: 

int GreetUser(
	struct display          *d,
	Display                 ** dpy,
	struct verify_info      *verify,
	struct greet_info       *greet,
 struct dlfuncs          *dlfcns)

The parameters for the function are as follows:

The GreetUser() function returns an enumerated type, greet_user_rtn, defined in greet.h. 

Greet_Session_Over     0    session managed and over
Greet_Success          1    greet succeeded, session not managed
Greet_Failure          -1   greet failed

3.3    Programming Updates

This section contains new information about programming in the X Window System environment. The section covers the following topics:

3.3.1    XChangeProperty and GetWindowProperty Functions

The X Consortium has refined the behavior of the XChangeProperty and GetWindowProperty functions. This refinement primarily affects programs that have arrays of integers (int) with format 32. If you have used or plan to use either function, you should use arrays of longwords (longs) instead.

Until recently, the data type used with a format of 32 was implied, not specified. With the new refinements, the data that is provided in format 32 to the XChangeProperty function or returned from the GetWindowProperty function should be accessed as arrays of longwords or typedefs based on longwords such as Window or Atom.

3.3.2    Link Order for Static X Clients

There are certain steps you must follow when compiling, loading, or linking X client applications against a static or nonshared library.

Specify either the -ldnet_stub or -ldnet flag when:

If you link your X client application to the nonshared version of the /usr/lib/libDXm.a library, you must include libbkr in the link line. If you omit libbkr, the warning messages appear about the following undefined symbols: 

DXmHelpSystemClose
DXmHelpSystemDisplay
DXmHelpSystemOpen

3.3.3    DECnet Transport for X Client/Server Connections

The X server, X libraries, and various X clients use a DECnet transport mechanism for client/server connections when the appropriate DECnet product is installed on the system or on two systems, if the X client and X server are running on different nodes. If DECnet is not installed, attempts to make these client/server connections fail.

The loadable X server, as well as clients and libraries that directly execute calls to DECnet functions, are built using the libdnet_stub.so shared library in the ld command that links the object files. DECnet functions that are commonly called include getnodename, dnet_addr, and dnet_conn.

X clients that are built fully static and include libX11.a or libXmu.a must incorporate the libdnet_stub.a library if they do not use the DECnet transport. If they do use the DECnet transport, they must incorporate the libdnet.a library. One of these libdnet libraries must be included to resolve function calls from within the libX11 or libXmu modules. If the X client is not fully static, but is using libX11.a or libXmu.a for some other reason, libdnet_stub.so should be included in the ld command information so that the client can be used whether or not DECnet is installed.

Note that DECnet/OSI is not part of the Tru64 UNIX operating system.