4 Programming in the Digital 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 Digital UNIX X server is not covered in those manuals. This chapter includes information on the following topics:

Extensions to the X server
X Display Manager greeter module
Programming update

4.1 Extensions to the X Server

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

The following list contains the X11 R6 protocol X server extensions that Digital UNIX supports:

BIG_REQUESTS
DPS (Display PostScript)
MIT-SCREEN-SAVER
MIT-SHM (MIT Shared Memory)
MIT-SUNDRY-NONSTANDARD
Multibuffering
OpenGL (Open Graphics Library) - Support available with the DEC Open3D layered product
PEX (PHIGS Extension) - Support available with the DEC Open3D layered product
SHAPE (Nonrectangular Window Shape)
SMT (Shared Memory Transport)
SYNC (Synchronization Extension)
XC-MISC
XIE (X Imaging Extension)
X Input Extension
X Keyboard Extensions (xkb)
XKME (X Keyboard Management Extension)
XTrap
XTEST
XV (X Video)

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.

4.1.1 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 PEX and other extensions that transmit complex information to the server.

4.1.2 DPS - Display PostScript Extension (Adobe Systems)

This extension provides a device-independent imaging model for displaying information on a screen. This imaging model is fully compatible with the imaging model used in PostScript printers. By allowing you to use the PostScript language to display text, graphics, and sampled images, it frees you from display-specific details such as screen resolution and the number of available colors. The Digital UNIX X server includes PostScript Level 2.

You can regard the Display PostScript system as part of the X Window System. Your application will use X Window System features for window placement and sizing, menu creation, and event handling, while using Display PostScript system features to take care of imaging inside the window.

Display PostScript system components include the Client Library, the PostScript interpreter, and the pswrap translator.

The Digital UNIX documentation set includes the Developing Applications for the Display PostScript System.

Associate multiple image buffers with a window
Paint in any image buffer associated with a window
Display a series of image buffers in a window in rapid succession to achieve smooth animation
Request simultaneous display of different image buffers in different windows

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

4.1.8 PEX (PHIGS Extension)

This extension is an X Consortium-sanctioned extension to the X Window System. It is designed to support three-dimensional graphics efficiently within the confines and rules of X. The PHIGS extension, PEX, provides capabilities that allow each window on the display to act as a complete, independent virtual three-dimensional graphics workstation. The PEX protocol supports those three-dimensional graphics primitives used by standard application programmer interfaces such as PHIGS, PHIGS PLUS, GKS, and GL.

The protocol version of PEX supported for Digital UNIX is PEX 5.1, which is available only through the DEC Open3D kit.

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

4.1.10 SMT - Shared Memory Transport Extension (Digital provided)

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.

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

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

4.1.13 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 Digital UNIX system in the /usr/doc/xie directory. The following list describes the documents:

X Image Extension Overview
This document provides general information about the X Image Extension code. Topics covered are: XIE design goals, XIE historical summary, XIE architecture, element definitions, and subsetting.
XIElib Specification
This document contains reference descriptions of all the XIElib functions, XIElib events, and XIElib errors. The Functions section covers the following types of functions: startup, LUT, photomap, ROI, photoflo, client data, abort and await, photoflo element, technique, and free.
XIE Sample Implementation Architecture
This document is for X Consortium members who have a working understanding of the X Imaging Extension. It provides an architecture overview as well as chapters on the following topics: extension initialization, memory management, request dispatching, data representation, data structures, protocol requests, DIXIE photoflo management, DDXIE photoflo management, and photo elements.
X Image Extension Protocol Reference Manual, Version 5.0
This document specifies the X wire protocol for the X Image Extension. It defines the syntax, structure, and semantics of the XIE protocol elements. Topics covered include syntax specification, parameter types, resources, pipelined processing, import elements, process elements, export elements, events and errors, techniques, service class, and protocol encodings.

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

4.1.15 X Keyboard Extension for X11 R6

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

Support for the ISO9996 standard for keyboard layouts
Compatibility with the core X keyboard handling (no client modifications are required).
Standard methods for handling keyboard LEDs and locking modifiers such as CapsLock and NumLock
Support for keyboard geometry

In addition, the X11 R5 (for versions of Digital 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.

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

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

4.1.18 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:

Minimize portability problems by confining the extension to an appropriate high level within the X server. In practice, this goal means that the extension should be at the DIX level, use the DIX/DDX interface, or both. This specification has effects, in particular, on the level at which input synthesis can occur.
Minimize the changes required in the rest of the X server.
Minimize the performance penalties that running the test produces on normal X server operation.

4.1.19 XV - X Video Extension

This extension performs the following functions:

Lists available video adapters
Identifies the number of ports each adapter supports
Describes what drawable formats each adapter supports
Describes what video encodings each adapter supports
Displays video from a port to a drawable format
Captures video from a drawable format to a port
Reserves ports for exclusive use and unreserves them
Sets and gets port attributes
Delivers event notification

4.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 Digital 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:

struct display *d [read-only]
This struct display is defined in /usr/examples/xdm/dm.h.

Display **dpy [write]

The parameter returns the Display pointer from XtOpenDisplay() or XOpenDisplay().

struct verify_info*verify [write]

This struct is defined in /usr/examples/xdm/dm.h. The GreetUser() function is passed a pointer to an existing verify-info struct. The function is expected to write the fields of this struct. These fields include the uid, gid, arguments to run the session; the environment variable for the session; and the environment variable for startup and reset.

struct greet_info *greet [write]

This struct is defined in /usr/examples/xdm/dm.h. The GreetUser() function is passed a pointer to an existing verify-info struct. The function is expected to write the user's name and password into the name and password fields, but these values are really needed only when xdm is compiled with SECURE_RPC defined.

struct dlfcns

This struct is a set of function pointers to xdm functions that GreetUser ( ) is likely to need.

Note that on Digital UNIX using these function pointers is not necessary since the symbols will be resolved by the dynamic loader.

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

4.3 Programming Updates

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

XChangeProperty and GetWindowProperty functions
Link order for static X clients
DECnet transport for client/server connections
Client events with Display PostScript libraries

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

4.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:

using the cc -non_shared command
using the ld -non_shared command
linking against the libX11.a static library

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

4.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 Digital UNIX operating system.