The DDX layer has several kinds of resources:

The type names of the more important server structs usually end in "Rec," such as "DeviceRec;" the pointer types usually end in "Ptr," such as "DevicePtr."

The structs and important defined constants are declared in .h files that have names that suggest the name of the object. For instance, there are two .h files for windows, window.h and windowstr.h. window.h defines only what needs to be defined in order to use windows without peeking inside of them; windowstr.h defines the structs with all of their components in great detail for those who need it.

Three kinds of fields are in these structs:

DIX calls through the struct's procedure pointers to do its tasks. These procedures are set either directly or indirectly by DDX procedures. Most of the procedures described in the remainder of this document are accessed through one of these structs. For example, the procedure to create a pixmap is attached to a ScreenRec and might be called by using the expression

All procedure pointers must be set to some routine unless noted otherwise; a null pointer will have unfortunate consequences.

Procedure routines will be indicated in the documentation by this convention:

as opposed to a free routine, not in a data structure:

The attribute fields are mostly set by DIX; DDX should not modify them unless noted otherwise.

These functions should also be called from your extensionInitProc to allocate all of the various resource classes and types required for the extension. Each time the server resets, these types must be reallocated as the old allocations will have been discarded. Resource types are integer values starting at 1. Get a resource type by calling

deleteFunc will be called to destroy all resources with this type. name will be used to identify this type of resource to clients using the X-Resource extension, to security extensions such as SELinux, and to tracing frameworks such as DTrace. [The name argument was added in xorg-server 1.8.]

Resource classes are masks starting at 1 << 31 which can be or'ed with any resource type to provide attributes for the type. To allocate a new class bit, call

There are two ways of looking up resources, by type or by class. Classes are non-exclusive subsets of the space of all resources, so you can lookup the union of multiple classes. (RC_ANY is the union of all classes).

Note that the appropriate class bits must be or'ed into the value returned by CreateNewResourceType when calling resource lookup functions.

If you need to create a ``private'' resource ID for internal use, you can call FakeClientID.

This allocates from ID space reserved for the server.

To associate a resource value with an ID, use AddResource.

The type should be the full type of the resource, including any class bits. If AddResource fails to allocate memory to store the resource, it will call the deleteFunc for the type, and then return False.

To free a resource, use one of the following.

FreeResource frees all resources matching the given id, regardless of type; the type's deleteFunc will be called on each matching resource, except that skipDeleteFuncType can be set to a single type for which the deleteFunc should not be called (otherwise pass RT_NONE). FreeResourceByType frees a specific resource matching a given id and type; if skipFree is true, then the deleteFunc is not called.

To look up a resource, use one of the following.

dixLookupResourceByType finds a resource with the given id and exact type. dixLookupResourceByClass finds a resource with the given id whose type is included in any one of the specified classes. The client and access_mode must be provided to allow security extensions to check if the client has the right privileges for the requested access. The bitmask values defined in the dixaccess.h header are or'ed together to define the requested access_mode.

Similarly, the X server or an extension may need to wait for some timeout. Early X releases implemented this functionality using block and wakeup handlers, but this has been rewritten to use a general timer facilty, and the internal screen saver facilities reimplemented to use Timers. These functions are TimerInit, TimerForce, TimerSet, TimerCheck, TimerCancel, and TimerFree, as defined in Xserver/include/os.h. A callback function will be called when the timer fires, along with the current time, and a user provided argument.

TimerSet returns a pointer to a timer structure and sets a timer to the specified time with the specified argument. The flags can be TimerAbsolute and TimerForceOld. The TimerSetOld flag controls whether if the timer is reset and the timer is pending, the whether the callback function will get called. The TimerAbsolute flag sets the callback time to an absolute time in the future rather than a time relative to when TimerSet is called. TimerFree should be called to free the memory allocated for the timer entry.

TimerInit frees any existing timer entries. TimerForce forces a call to the timer's callback function and returns true if the timer entry existed, else it returns false and does not call the callback function. TimerCancel will cancel the specified timer. TimerFree calls TimerCancel and frees the specified timer. Calling TimerCheck will force the server to see if any timer callbacks should be called.

DIX can insert data into the client stream, and can cause a "replay" of the current request.

InsertFakeRequest() must insert the specified number of bytes of data into the head of the input buffer for the client. This may be a complete request, or it might be a partial request. For example, NextAvailableCient() will insert a partial request in order to read the initial connection data sent by the client. The routine returns FALSE if memory could not be allocated. ResetCurrentRequest() should "back up" the input buffer so that the currently executing request will be reexecuted. DIX may have altered some values (e.g. the overall request length), so you must recheck to see if you still have a complete request. ResetCurrentRequest() should always cause a yield (isItTimeToYield).

DIX keeps a global directory of devices in a central data structure called InputInfo. For each device there is a device structure called a DeviceRec. DIX can locate any DeviceRec through InputInfo. In addition, it has a special pointer to identify the main pointing device and a special pointer to identify the main keyboard.

The DeviceRec (Xserver/include/input.h) is a device-independent structure that contains the state of an input device. A DevicePtr is simply a pointer to a DeviceRec.

An xEvent describes an event the server reports to a client. Defined in Xproto.h, it is a huge struct of union of structs that have fields for all kinds of events. All of the variants overlap, so that the struct is actually very small in memory.

The main DDX input interface is the following routine:

You must write this routine to deliver input events from the user. DIX calls it when input is pending (see next section), and possibly even when it is not. You should write it to get events from each device and deliver the events to DIX. To deliver the events to DIX, DDX should call the following routine:

This is the "input proc" for the device, a DIX procedure. DIX will fill in this procedure pointer to one of its own routines by the time ProcessInputEvents() is called the first time. Call this input proc routine as many times as needed to deliver as many events as should be delivered. DIX will buffer them up and send them out as needed. Count is set to the number of event records which make up one atomic device event and is always 1 for the core devices (see the X Input Extension for descriptions of devices which may use count > 1).

For example, your ProcessInputEvents() routine might check the mouse and the keyboard. If the keyboard had several keystrokes queued up, it could just call the keyboard's processInputProc as many times as needed to flush its internal queue.

event is an xEvent struct you pass to the input proc. When the input proc returns, it is finished with the event rec, and you can fill in new values and call the input proc again with it.

You should deliver the events in the same order that they were generated.

For keyboard and pointing devices the xEvent variant should be keyButtonPointer. Fill in the following fields in the xEvent record:

The rest of the fields are filled in by DIX.

The time stamp is maintained by your code in the DDX layer, and it is your responsibility to stamp all events correctly.

The x and y coordinates of the pointing device and the time must be filled in for all event types including keyboard events.

The pointing device must report all button press and release events. In addition, it should report a MotionNotify event every time it gets called if the pointing device has moved since the last notify. Intermediate pointing device moves are stored in a special GetMotionEvents buffer, because most client programs are not interested in them.

There are quite a collection of sample implementations of this routine, one for each supported device.

In the server's dispatch loop, DIX checks to see if there is any device input pending whenever WaitForSomething() returns. If the check says that input is pending, DIX calls the DDX routine ProcessInputEvents().

This check for pending input must be very quick; a procedure call is too slow. The code that does the check is a hardwired IF statement in DIX code that simply compares the values pointed to by two pointers. If the values are different, then it assumes that input is pending and ProcessInputEvents() is called by DIX.

You must pass pointers to DIX to tell it what values to compare. The following procedure is used to set these pointers:

You should call it sometime during initialization to indicate to DIX the correct locations to check. You should pay special attention to the size of what they actually point to, because the locations are assumed to be longs.

These two pointers are initialized by DIX to point to arbitrary values that are different. In other words, if you forget to call this routine during initialization, the worst thing that will happen is that ProcessInputEvents will be called when there are no events to process.

p1 and p2 might point at the head and tail of some shared memory queue. Another use would be to have one point at a constant 0, with the other pointing at some mask containing 1s for each input device that has something pending.

The DDX layer of the sample server calls SetInputCheck() once when the server's private internal queue is initialized. It passes pointers to the queue's head and tail. See Xserver/mi/mieq.c.

DDX must time stamp all hardware input events. But DIX sometimes needs to know the time and the OS layer needs to know the time since the last hardware input event in order for the screen saver to work. TimeSinceLastInputEvent() returns the this time in milliseconds.

You must write four routines to do various device-specific things with the keyboard and pointing device. They can have any name you wish because you pass the procedure pointers to DIX routines.

You write this DDX routine to fill in coords with all the motion events that have times (32-bit count of milliseconds) between time start and time stop. It should return the number of motion events returned. If there is no motion events support, this routine should do nothing and return zero. The maximum number of coords to return is set in InitPointerDeviceStruct(), below.

When the user drags the pointing device, the cursor position theoretically sweeps through an infinite number of points. Normally, a client that is concerned with points other than the starting and ending points will receive a pointer-move event only as often as the server generates them. (Move events do not queue up; each new one replaces the last in the queue.) A server, if desired, can implement a scheme to save these intermediate events in a motion buffer. A client application, like a paint program, may then request that these events be delivered to it through the GetMotionProc routine.

You need to write this routine to ring the bell on the keyboard. loud is a number from 0 to 100, with 100 being the loudest. Class is either BellFeedbackClass or KbdFeedbackClass (from XI.h).

You write two versions of this procedure, one for the keyboard and one for the pointing device. DIX calls it to inform DDX when a client has requested changes in the current settings for the particular device. For a keyboard, this might be the repeat threshold and rate. For a pointing device, this might be a scaling factor (coarse or fine) for position reporting. See input.h for the ctrl structures.

Input initialization is a bit complicated. It all starts with InitInput(), a routine that you write to call AddInputDevice() twice (once for pointing device and once for keyboard.)

When you Add the devices, a routine you supply for each device gets called to initialize them. Your individual initialize routines must call InitKeyboardDeviceStruct() or InitPointerDeviceStruct(), depending upon which it is. In other words, you indicate twice that the keyboard is the keyboard and the pointer is the pointer.

InitInput is a DDX routine you must write to initialize the input subsystem in DDX. It must call AddInputDevice() for each device that might generate events.

AddInputDevice is a DIX routine you call to create a device object. deviceProc is a DDX routine that is called by DIX to do various operations. AutoStart should be TRUE for devices that need to be turned on at initialization time with a special call, as opposed to waiting for some client application to turn them on. This routine returns NULL if sufficient memory cannot be allocated to install the device.

Note also that except for the main keyboard and pointing device, an extension is needed to provide for a client interface to a device.

The following DIX procedures return the specified DevicePtr. They may or may not be useful to DDX implementors.

LookupKeyboardDevice returns pointer for current main keyboard device.

LookupPointerDevice returns pointer for current main pointing device.

A DeviceProc (the kind passed to AddInputDevice()) in the following form:

You must write a DeviceProc for each device. device points to the device record. action tells what action to take; it will be one of these defined constants (defined in input.h):

InitPointerDeviceStruct is a DIX routine you call at DEVICE_INIT time to declare some operating routines and data structures for a pointing device. map and mapLength are as described in the X Window System protocol specification. ControlProc and GetMotionEvents are DDX routines, see above.

numMotionEvents is for the motion-buffer-size for the GetMotionEvents request. A typical length for a motion buffer would be 100 events. A server that does not implement this capability should set numMotionEvents to zero.

You call this DIX routine when a keyboard device is initialized and its device procedure is called with DEVICE_INIT. The formats of the keysyms and modifier maps are defined in Xserver/include/input.h. They describe the layout of keys on the keyboards, and the glyphs associated with them. ( See the next section for information on setting up the modifier map and the keysym map.) ControlProc and Bell are DDX routines, see above.

When you send a keyboard event, you send a report that a given key has either been pressed or has been released. There must be a keycode for each key that identifies the key; the keycode-to-key mapping can be any mapping you desire, because you specify the mapping in a table you set up for DIX. However, you are restricted by the protocol specification to keycode values in the range 8 to 255 inclusive.

The keycode mapping information that you set up consists of the following:

Once the map is set up, DIX keeps and maintains the client's changes to it.

The X protocol defines standard names to indicate the symbol(s) printed on each keycap. (See X11/keysym.h)

Legal modifier keys must generate both up and down transitions. When a client tries to change a modifier key (for instance, to make "A" the "Control" key), DIX calls the following routine, which should return TRUE if the key can be used as a modifier on the given device:

The only requirement on screens is that you be able to both read and write locations in the frame buffer. All screens must have a depth of 32 or less (unless you use an X extension to allow a greater depth). All screens must fit into one of the classes listed in the section in this document on Visuals and Depths.

X uses the pixel as its fundamental unit of distance on the screen. Therefore, most programs will measure everything in pixels.

The sample server assumes square pixels. Serious WYSIWYG (what you see is what you get) applications for publishing and drawing programs will adjust for different screen resolutions automatically. Considerable work is involved in compensating for non-square pixels (a bit in the DDX code for the sample server but quite a bit in the client applications).

X supports multiple screens that are connected to the same server. Therefore, all the per-screen information is bundled into one data structure of attributes and procedures, which is the ScreenRec (see Xserver/include/scrnintstr.h). The procedure entry points in a ScreenRec operate on regions, colormaps, cursors, and fonts, because these resources can differ in format from one screen to another.

Windows are areas on the screen that can be drawn into by graphic routines. "Pixmaps" are off-screen graphic areas that can be drawn into. They are both considered drawables and are described in the section on Drawables. All graphic operations work on drawables, and operations are available to copy patches from one drawable to another.

The pixel image data in all drawables is in a format that is private to DDX. In fact, each instance of a drawable is associated with a given screen. Presumably, the pixel image data for pixmaps is chosen to be conveniently understood by the hardware. All screens in a single server must be able to handle all pixmaps depths declared in the connection setup information.

Pixmap images are transferred to the server in one of two ways: XYPixmap or ZPimap. XYPixmaps are a series of bitmaps, one for each bit plane of the image, using the bitmap padding rules from the connection setup. ZPixmaps are a series of bits, nibbles, bytes or words, one for each pixel, using the format rules (padding and so on) for the appropriate depth.

All screens in a given server must agree on a set of pixmap image formats (PixmapFormat) to support (depth, number of bits per pixel, etc.).

There is no color interpretation of bits in the pixmap. Pixmaps do not contain pixel values. The interpretation is made only when the bits are transferred onto the screen.

The screenInfo structure (in scrnintstr.h) is a global data structure that has a pointer to an array of ScreenRecs, one for each screen on the server. (These constitute the one and only description of each screen in the server.) Each screen has an identifying index (0, 1, 2, ...). In addition, the screenInfo struct contains global server-wide details, such as the bit- and byte- order in all bit images, and the list of pixmap image formats that are supported. The X protocol insists that these must be the same for all screens on the server.

Upon initialization, your DDX routine InitOutput() is called by DIX. It is passed a pointer to screenInfo to initialize. It is also passed the argc and argv from main() for your server for the command-line arguments. These arguments may indicate what or how many screen device(s) to use or in what way to use them. For instance, your server command line may allow a "-D" flag followed by the name of the screen device to use.

Your InitOutput() routine should initialize each screen you wish to use by calling AddScreen(), and then it should initialize the pixmap formats that you support by storing values directly into the screenInfo data structure. You should also set certain implementation-dependent numbers and procedures in your screenInfo, which determines the pixmap and scanline padding rules for all screens in the server.

You should call AddScreen(), a DIX procedure, in InitOutput() once for each screen to add it to the screenInfo database. The first argument is an initialization procedure for the screen that you supply. The second and third are the argc and argv from main(). It returns the screen number of the screen installed, or -1 if there is either insufficient memory to add the screen, or (*scrInitProc) returned FALSE.

The scrInitProc should be of the following form:

iScreen is the index for this screen; 0 for the first one initialized, 1 for the second, etc. pScreen is the pointer to the screen's new ScreenRec. argc and argv are as before. Your screen initialize procedure should return TRUE upon success or FALSE if the screen cannot be initialized (for instance, if the screen hardware does not exist on this machine).

This procedure must determine what actual device it is supposed to initialize. If you have a different procedure for each screen, then it is no problem. If you have the same procedure for multiple screens, it may have trouble figuring out which screen to initialize each time around, especially if InitOutput() does not initialize all of the screens. It is probably easiest to have one procedure for each screen.

The initialization procedure should fill in all the screen procedures for that screen (windowing functions, region functions, etc.) and certain screen attributes for that screen.

A region is a dynamically allocated data structure that describes an irregularly shaped piece of real estate in XY pixel space. You can think of it as a set of pixels on the screen to be operated upon with set operations such as AND and OR.

A region is frequently implemented as a list of rectangles or bitmaps that enclose the selected pixels. Region operators control the "clipping policy," or the operations that work on regions. (The sample server uses YX-banded rectangles. Unless you have something already implemented for your graphics system, you should keep that implementation.) The procedure pointers to the region operators are located in the ScreenRec data structure. The definition of a region can be found in the file Xserver/include/regionstr.h. The region code is found in Xserver/mi/miregion.c. DDX implementations using other region formats will need to supply different versions of the region operators.

Since the list of rectangles is unbounded in size, part of the region data structure is usually a large, dynamically allocated chunk of memory. As your region operators calculate logical combinations of regions, these blocks may need to be reallocated by your region software. For instance, in the sample server, a RegionRec has some header information and a pointer to a dynamically allocated rectangle list. Periodically, the rectangle list needs to be expanded with Xrealloc(), whereupon the new pointer is remembered in the RegionRec.

Most of the region operations come in two forms: a function pointer in the Screen structure, and a macro. The server can be compiled so that the macros make direct calls to the appropriate functions (instead of indirecting through a screen function pointer), or it can be compiled so that the macros are identical to the function pointer forms. Making direct calls is faster on many architectures.

RegionCreate creates a region that describes ONE rectangle. The caller can avoid unnecessary reallocation and copying by declaring the probable maximum number of rectangles that this region will need to describe itself. Your region routines, though, cannot fail just because the region grows beyond this size. The caller of this routine can pass almost anything as the size; the value is merely a good guess as to the maximum size until it is proven wrong by subsequent use. Your region procedures are then on their own in estimating how big the region will get. Your implementation might ignore size, if applicable.

Given an existing raw region structure (such as an local variable), this routine fills in the appropriate fields to make this region as usable as one returned from RegionCreate. This avoids the additional dynamic memory allocation overhead for the region structure itself.

RegionCopy copies the description of one region, srcrgn, to another already-created region, dstrgn; returning TRUE if the copy succeeded, and FALSE otherwise.

RegionDestroy destroys a region and frees all allocated memory.

Frees everything except the region structure itself, useful when the region was originally passed to RegionInit instead of received from RegionCreate. When this call returns, pRegion must not be reused until it has been RegionInit'ed again.

The above four calls all do basic logical operations on regions. They set the new region (which already exists) to describe the logical intersection, union, set difference, or inverse of the region(s) that were passed in. Your routines must be able to handle a situation where the newReg is the same region as one of the other region arguments.

The subtract function removes the Subtrahend from the Minuend and puts the result in newReg.

The inverse function returns a region that is the pBox minus the region passed in. (A true "inverse" would make a region that extends to infinity in all directions but has holes in the middle.) It is undefined for situations where the region extends beyond the box.

Each routine must return the value TRUE for success.

RegionReset sets the region to describe one rectangle and reallocates it to a size of one rectangle, if applicable.

TranslateRegion simply moves a region +x in the x direction and +y in the y direction.

RectIn returns one of the defined constants rgnIN, rgnOUT, or rgnPART, depending upon whether the box is entirely inside the region, entirely outside of the region, or partly in and partly out of the region. These constants are defined in Xserver/include/region.h.

PointInRegion returns true if the point x, y is in the region. In addition, it fills the rectangle pBox with coordinates of a rectangle that is entirely inside of pRegion and encloses the point. In the mi implementation, it is the largest such rectangle. (Due to the sample server implementation, this comes cheaply.)

This routine used by DIX when tracking the pointing device and deciding whether to report mouse events or change the cursor. For instance, DIX needs to change the cursor when it moves from one window to another. Due to overlapping windows, the shape to check may be irregular. A PointInRegion() call for every pointing device movement may be too expensive. The pBox is a kind of wake-up box; DIX need not call PointInRegion() again until the cursor wanders outside of the returned box.

RegionNotEmpty is a boolean function that returns true or false depending upon whether the region encloses any pixels.

RegionEmpty sets the region to be empty.

RegionExtents returns a rectangle that is the smallest possible superset of the entire region. The caller will not modify this rectangle, so it can be the one in your region struct.

These functions provide an optimization for clip list generation and must be used in conjunction. The combined effect is to produce the union of a collection of regions, by using RegionAppend several times, and finally calling RegionValidate which takes the intermediate representation (which needn't be a valid region) and produces the desired union. pOverlap is set to TRUE if any of the original regions overlap; FALSE otherwise.

Given a depth-1 pixmap, this routine must create a valid region which includes all the areas of the pixmap filled with 1's and excludes the areas filled with 0's. This routine returns NULL if out of memory.

Given a client-supplied list of rectangles, produces a region which includes the union of all the rectangles. Ordering may be used as a hint which describes how the rectangles are sorted. As the hint is provided by a client, it must not be required to be correct, but the results when it is not correct are not defined (core dump is not an option here).

SendGraphicsExpose dispatches a list of GraphicsExposure events which span the region to the specified client. If the region is empty, or a NULL pointer, a NoExpose event is sent instead.

A cursor is the visual form tied to the pointing device. The default cursor is an "X" shape, but the cursor can have any shape. When a client creates a window, it declares what shape the cursor will be when it strays into that window on the screen.

For each possible shape the cursor assumes, there is a CursorRec data structure. This data structure contains a pointer to a CursorBits data structure which contains a bitmap for the image of the cursor and a bitmap for a mask behind the cursor, in addition, the CursorRec data structure contains foreground and background colors for the cursor. The CursorBits data structure is shared among multiple CursorRec structures which use the same font and glyph to describe both source and mask. The cursor image is applied to the screen by applying the mask first, clearing 1 bits in its form to the background color, and then overwriting on the source image, in the foreground color. (One bits of the source image that fall on top of zero bits of the mask image are undefined.) This way, a cursor can have transparent parts, and opaque parts in two colors. X allows any cursor size, but some hardware cursor schemes allow a maximum of N pixels by M pixels. Therefore, you are allowed to transform the cursor to a smaller size, but be sure to include the hot-spot.

CursorBits in Xserver/include/cursorstr.h is a device-independent structure containing a device-independent representation of the bits for the source and mask. (This is possible because the bitmap representation is the same for all screens.)

When a cursor is created, it is "realized" for each screen. At realization time, each screen has the chance to convert the bits into some other representation that may be more convenient (for instance, putting the cursor into off-screen memory) and set up its device-private area in either the CursorRec data structure or CursorBits data structure as appropriate to possibly point to whatever data structures are needed. It is more memory-conservative to share realizations by using the CursorBits private field, but this makes the assumption that the realization is independent of the colors used (which is typically true). For instance, the following are the device private entries for a particular screen and cursor:

This is done because the change from one cursor shape to another must be fast and responsive; the cursor image should be able to flutter as fast as the user moves it across the screen.

You must implement the following routines for your hardware:

RealizeCursor and UnrealizeCursor should realize (allocate and calculate all data needed) and unrealize (free the dynamically allocated data) a given cursor when DIX needs them. They are called whenever a device-independent cursor is created or destroyed. The source and mask bits pointed to by fields in pCurs are undefined for bits beyond the right edge of the cursor. This is so because the bits are in Bitmap format, which may have pad bits on the right edge. You should inhibit UnrealizeCursor() if the cursor is currently in use; this happens when the system is reset.

DisplayCursor should change the cursor on the given screen to the one passed in. It is called by DIX when the user moves the pointing device into a different window with a different cursor. The hotspot in the cursor should be aligned with the current cursor position.

RecolorCursor notifies DDX that the colors in pCurs have changed and indicates whether this is the cursor currently being displayed. If it is, the cursor hardware state may have to be updated. Whether displayed or not, state created at RealizeCursor time may have to be updated. A generic version, miRecolorCursor, may be used that does an unrealize, a realize, and possibly a display (in micursor.c); however this constrains UnrealizeCursor and RealizeCursor to always return TRUE as no error indication is returned here.

ConstrainCursor should cause the cursor to restrict its motion to the rectangle pBox. DIX code is capable of enforcing this constraint by forcefully moving the cursor if it strays out of the rectangle, but ConstrainCursor offers a way to send a hint to the driver or hardware if such support is available. This can prevent the cursor from wandering out of the box, then jumping back, as DIX forces it back.

PointerNonInterestBox is DIX's way of telling the pointing device code not to report motion events while the cursor is inside a given rectangle on the given screen. It is optional and, if not implemented, it should do nothing. This routine is called only when the client has declared that it is not interested in motion events in a given window. The rectangle you get may be a subset of that window. It saves DIX code the time required to discard uninteresting mouse motion events. This is only a hint, which may speed performance. Nothing in DIX currently calls PointerNonInterestBox.

CursorLimits should calculate the box that the cursor hot spot is physically capable of moving within, as a function of the screen pScr, the device-independent cursor pCurs, and a box that DIX hypothetically would want the hot spot confined within, pHotBox. This routine is for informing DIX only; it alters no state within DDX.

SetCursorPosition should artificially move the cursor as though the user had jerked the pointing device very quickly. This is called in response to the WarpPointer request from the client, and at other times. If generateEvent is True, the device should decide whether or not to call ProcessInputEvents() and then it must call DevicePtr->processInputProc. Its effects are, of course, limited in value for absolute pointing devices such as a tablet.

If your ddx provides some mechanism for the user to magically move the pointer between multiple screens, you need to inform DIX when this occurs. You should call NewCurrentScreen to accomplish this, specifying the new screen and the new x and y coordinates of the pointer on that screen.

The "depth" of a image is the number of bits that are used per pixel to display it.

The "bits per pixel" of a pixmap image that is sent over the client byte stream is a number that is either 4, 8, 16, 24 or 32. It is the number of bits used per pixel in Z format. For instance, a pixmap image that has a depth of six is best sent in Z format as 8 bits per pixel.

A "pixmap image format" or a "pixmap format" is a description of the format of a pixmap image as it is sent over the byte stream. For each depth available on a server, there is one and only one pixmap format. This pixmap image format gives the bits per pixel and the scanline padding unit. (For instance, are pixel rows padded to bytes, 16-bit words, or 32-bit words?)

For each screen, you must decide upon what depth(s) it supports. You should only count the number of bits used for the actual image. Some displays store additional bits to indicate what window this pixel is in, how close this object is to a viewer, transparency, and other data; do not count these bits.

A "display class" tells whether the display is monochrome or color, whether there is a lookup table, and how the lookup table works.

A "visual" is a combination of depth, display class, and a description of how the pixel values result in a color on the screen. Each visual has a set of masks and offsets that are used to separate a pixel value into its red, green, and blue components and a count of the number of colormap entries. Some of these fields are only meaningful when the class dictates so. Each visual also has a screen ID telling which screen it is usable on. Note that the depth does not imply the number of map_entries; for instance, a display can have 8 bits per pixel but only 254 colormap entries for use by applications (the other two being reserved by hardware for the cursor).

Each visual is identified by a 32-bit visual ID which the client uses to choose what visual is desired on a given window. Clients can be using more than one visual on the same screen at the same time.

The class of a display describes how this translation takes place. There are three ways to do the translation.

In addition, the lookup table can be static (resulting colors are fixed for each pixel value) or dynamic (lookup entries are under control of the client program). This leads to a total of six classes:

Here are some examples:

A display has 8 bits per pixel. The 8 bits select one entry out of 256 entries in a lookup table, each entry consisting of 24 bits (8bits each for red, green, and blue). The display can show any 256 of 16 million colors on the screen at once. This is a pseudocolor display. The client application gets to fill the lookup table in this class of display.

Imagine the same hardware from the last example. Your server software allows the user, on the command line that starts up the server program, to fill the lookup table to his liking once and for all. From then on, the server software would not change the lookup table until it exits. For instance, the default might be a lookup table with a reasonable sample of colors from throughout the color space. But the user could specify that the table be filled with 256 steps of gray scale because he knew ahead of time he would be manipulating a lot of black-and-white scanned photographs and not very many color things. Clients would be presented with this unchangeable lookup table. Although the hardware qualifies as a PseudoColor display, the facade presented to the X client is that this is a Static Color display.

You have to decide what kind of display you have or want to pretend you have. When you initialize the screen(s), this class value must be set in the VisualRec data structure along with other display characteristics like the depth and other numbers.

The allowable DepthRec's and VisualRec's are pointed to by fields in the ScreenRec. These are set up when InitOutput() is called; you should Xalloc() appropriate blocks or use static variables initialized to the correct values.

A colormap is a device-independent mapping between pixel values and colors displayed on the screen.

Different windows on the same screen can have different colormaps at the same time. At any given time, the most recently installed colormap(s) will be in use in the server so that its (their) windows' colors will be guaranteed to be correct. Other windows may be off-color. Although this may seem to be chaotic, in practice most clients use the default colormap for the screen.

The default colormap for a screen is initialized when the screen is initialized. It always remains in existence and is not owned by any regular client. It is owned by client 0 (the server itself). Many clients will simply use this default colormap for their drawing. Depending upon the class of the screen, the entries in this colormap may be modifiable by client applications.

You need to implement the following routines to handle the device-dependent aspects of color maps. You will end up placing pointers to these procedures in your ScreenRec data structure(s). The sample server implementations of many of these routines are in fbcmap.c.

This routine is called by the DIX CreateColormap routine after it has allocated all the data for the new colormap and just before it returns to the dispatcher. It is the DDX layer's chance to initialize the colormap, particularly if it is a static map. See the following section for more details on initializing colormaps. The routine returns FALSE if creation failed, such as due to memory limitations. Notice that the colormap has a devPriv field from which you can hang any colormap specific storage you need. Since each colormap might need special information, we attached the field to the colormap and not the visual.

This routine is called by the DIX FreeColormap routine after it has uninstalled the colormap and notified all interested parties, and before it has freed any of the colormap storage. It is the DDX layer's chance to free any data it added to the colormap.

InstallColormap should fill a lookup table on the screen with which the colormap is associated with the colors in pColormap. If there is only one hardware lookup table for the screen, then all colors on the screen may change simultaneously.

In the more general case of multiple hardware lookup tables, this may cause some other colormap to be uninstalled, meaning that windows that subscribed to the colormap that was uninstalled may end up being off-color. See the note, below, about uninstalling maps.

UninstallColormap should remove pColormap from screen pColormap->pScreen. Some other map, such as the default map if possible, should be installed in place of pColormap if applicable. If pColormap is the default map, do nothing. If any client has requested ColormapNotify events, the DDX layer must notify the client. (The routine WalkTree() is be used to find such windows. The DIX routines TellNoMap(), TellNewMap() and TellGainedMap() are provided to be used as the procedure parameter to WalkTree. These procedures are in Xserver/dix/colormap.c.)

ListInstalledColormaps fills the pCmapList in with the resource ids of the installed maps and returns a count of installed maps. pCmapList will point to an array of size MaxInstalledMaps that was allocated by the caller.

StoreColors changes some of the entries in the colormap pmap. The number of entries to change are ndef, and pdefs points to the information describing what to change. Note that partial changes of entries in the colormap are allowed. Only the colors indicated in the flags field of each xColorItem need to be changed. However, all three color fields will be sent with the proper value for the benefit of screens that may not be able to set part of a colormap value. If the screen is a static class, this routine does nothing. The structure of colormap entries is nontrivial; see colormapst.h and the definition of xColorItem in Xproto.h for more details.

Given a requested color, ResolveColor returns the nearest color that this hardware is capable of displaying on this visual. In other words, this rounds off each value, in place, to the number of bits per primary color that your screen can use. Remember that each screen has one of these routines. The level of roundoff should be what you would expect from the value you put in the bits_per_rgb field of the pVisual.

Each value is an unsigned value ranging from 0 to 65535. The bits least likely to be used are the lowest ones.

For example, if you had a pseudocolor display with any number of bits per pixel that had a lookup table supplying 6 bits for each color gun (a total of 256K different colors), you would round off each value to 6 bits. Please don't simply truncate these values to the upper 6 bits, scale the result so that the maximum value seen by the client will be 65535 for each primary. This makes color values more portable between different depth displays (a 6-bit truncated white will not look white on an 8-bit display).

A font is a set of bitmaps that depict the symbols in a character set. Each font is for only one typeface in a given size, in other words, just one bitmap for each character. Parallel fonts may be available in a variety of sizes and variations, including "bold" and "italic." X supports fonts for 8-bit and 16-bit character codes (for oriental languages that have more than 256 characters in the font). Glyphs are bitmaps for individual characters.

The source comes with some useful font files in an ASCII, plain-text format that should be comprehensible on a wide variety of operating systems. The text format, referred to as BDF, is a slight extension of the current Adobe 2.1 Bitmap Distribution Format (Adobe Systems, Inc.).

A short paper in PostScript format is included with the sample server that defines BDF. It includes helpful pictures, which is why it is done in PostScript and is not included in this document.

Your implementation should include some sort of font compiler to read these files and generate binary files that are directly usable by your server implementation. The sample server comes with the source for a font compiler.

It is important the font properties contained in the BDF files are preserved across any font compilation. In particular, copyright information cannot be casually tossed aside without legal ramifications. Other properties will be important to some sophisticated applications.

All clients get font information from the server. Therefore, your server can support any fonts it wants to. It should probably support at least the fonts supplied with the X11 tape. In principle, you can convert fonts from other sources or dream up your own fonts for use on your server.

You must supply several other screen-specific routines for your X server implementation. Some of these are described in other sections:

QueryBestSize() returns the best sizes for cursors, tiles, and stipples in response to client requests. kind is one of the defined constants CursorShape, TileShape, or StippleShape (defined in X.h). For CursorShape, return the maximum width and height for cursors that you can handle. For TileShape and StippleShape, start with the suggested values in pWidth and pHeight and modify them in place to be optimal values that are greater than or equal to the suggested values. The sample server implementation is in Xserver/fb/fbscreen.c.

SourceValidate should be called by CopyArea/CopyPlane primitives when the SourceValidate function pointer in the screen is non-null. If you know that you will never need SourceValidate, you can avoid this check. Currently, SourceValidate is used by the mi software cursor code to remove the cursor from the screen when the source rectangle overlaps the cursor position. x,y,width,height describe the source rectangle (source relative, that is) for the copy operation. subWindowMode comes from the GC or source Picture.

SaveScreen() is used for Screen Saver support (see WaitForSomething()). pScreen is the screen to save.

When the server is reset, it calls this routine for each screen.

If this routine is not NULL, it will be called once per screen per server initialization/reset after all modules have had a chance to request private space on all structures that support them (see the section called “Wrappers and Privates” below). You may create resources in this function instead of in the screen init function passed to AddScreen in order to guarantee that all pre-allocated space requests have been registered first. With the new devPrivates mechanism, this is not strictly necessary, however. This routine returns TRUE if successful.

A pixmap is a three-dimensional array of bits stored somewhere offscreen, rather than in the visible portion of the screen's display frame buffer. It can be used as a source or destination in graphics operations. There is no implied interpretation of the pixel values in a pixmap, because it has no associated visual or colormap. There is only a depth that indicates the number of significant bits per pixel. Also, there is no implied physical size for each pixel; all graphic units are in numbers of pixels. Therefore, a pixmap alone does not constitute a complete image; it represents only a rectangular array of pixel values.

Note that the pixmap data structure is reference-counted.

The server implementation is free to put the pixmap data anywhere it sees fit, according to its graphics hardware setup. Many implementations will simply have the data dynamically allocated in the server's address space. More sophisticated implementations may put the data in undisplayed framebuffer storage.

In addition to dynamic devPrivates (see the section called “Wrappers and Privates” below), the pixmap data structure has two fields that are private to the device. Although you can use them for anything you want, they have intended purposes. devKind is intended to be a device specific indication of the pixmap location (host memory, off-screen, etc.). In the sample server, since all pixmaps are in memory, devKind stores the width of the pixmap in bitmap scanline units. devPrivate is usually a pointer to the bits in the pixmap.

A bitmap is a pixmap that is one bit deep.

This ScreenRec procedure must create a pixmap of the size requested. It must allocate a PixmapRec and fill in all of the fields. The reference count field must be set to 1. If width or height are zero, no space should be allocated for the pixmap data, and if the implementation is using the devPrivate field as a pointer to the pixmap data, it should be set to NULL. If successful, it returns a pointer to the new pixmap; if not, it returns NULL. See Xserver/fb/fbpixmap.c for the sample server implementation.

This ScreenRec procedure must "destroy" a pixmap. It should decrement the reference count and, if zero, it must deallocate the PixmapRec and all attached devPrivate blocks. If successful, it returns TRUE. See Xserver/fb/fbpixmap.c for the sample server implementation.

This routine takes a pixmap header and initializes the fields of the PixmapRec to the parameters of the same name. pPixmap must have been created via pScreen->CreatePixmap with a zero width or height to avoid allocating space for the pixmap data. pPixData is assumed to be the pixmap data; it will be stored in an implementation-dependent place (usually pPixmap->devPrivate.ptr). This routine returns TRUE if successful. See Xserver/mi/miscrinit.c for the sample server implementation.

DDX should use these two DIX routines when it has a buffer of raw image data that it wants to manipulate as a pixmap temporarily, usually so that some other part of the server can be leveraged to perform some operation on the data. The data should be passed in pPixData, and will be stored in an implementation-dependent place (usually pPixmap->devPrivate.ptr). The other fields go into the corresponding PixmapRec fields. If successful, GetScratchPixmapHeader returns a valid PixmapPtr which can be used anywhere the server expects a pixmap, else it returns NULL. The pixmap should be released when no longer needed (usually within the same function that allocated it) with FreeScratchPixmapHeader.

A window is a visible, or potentially visible, rectangle on the screen. DIX windowing functions maintain an internal n-ary tree data structure, which represents the current relationships of the mapped windows. Windows that are contained in another window are children of that window and are clipped to the boundaries of the parent. The root window in the tree is the window for the entire screen. Sibling windows constitute a doubly-linked list; the parent window has a pointer to the head and tail of this list. Each child also has a pointer to its parent.

The border of a window is drawn by a DDX procedure when DIX requests that it be drawn. The contents of the window is drawn by the client through requests to the server.

Window painting is orchestrated through an expose event system. When a region is exposed, DIX generates an expose event, telling the client to repaint the window and passing the region that is the minimal area needed to be repainted.

As a favor to clients, the server may retain the output to the hidden parts of windows in off-screen memory; this is called "backing store". When a part of such a window becomes exposed, it can quickly move pixels into place instead of triggering an expose event and waiting for a client on the other end of the network to respond. Even if the network response is insignificant, the time to intelligently paint a section of a window is usually more than the time to just copy already-painted sections. At best, the repainting involves blanking out the area to a background color, which will take about the same amount of time. In this way, backing store can dramatically increase the performance of window moves.

On the other hand, backing store can be quite complex, because all graphics drawn to hidden areas must be intercepted and redirected to the off-screen window sections. Not only can this be complicated for the server programmer, but it can also impact window painting performance. The backing store implementation can choose, at any time, to forget pieces of backing that are written into, relying instead upon expose events to repaint for simplicity.

In X, the decision to use the backing-store scheme is made by you, the server implementor. The sample server implements backing store "for free" by reusing the infrastructure for the Composite extension. As a side effect, it treats the WhenMapped and Always hints as equivalent. However, it will never forget pixel contents when the window is mapped.

When a window operation is requested by the client, such as a window being created or moved, a new state is computed. During this transition, DIX informs DDX what rectangles in what windows are about to become obscured and what rectangles in what windows have become exposed. This provides a hook for the implementation of backing store. If DDX is unable to restore exposed regions, DIX generates expose events to the client. It is then the client's responsibility to paint the window parts that were exposed but not restored.

If a window is resized, pixels sometimes need to be moved, depending upon the application. The client can request "Gravity" so that certain blocks of the window are moved as a result of a resize. For instance, if the window has controls or other items that always hang on the edge of the window, and that edge is moved as a result of the resize, then those pixels should be moved to avoid having the client repaint it. If the client needs to repaint it anyway, such an operation takes time, so it is desirable for the server to approximate the appearance of the window as best it can while waiting for the client to do it perfectly. Gravity is used for that, also.

The window has several fields used in drawing operations:

Most of the other fields are for DIX use only.

At screen initialization, a screen must supply a GC creation procedure. At GC creation, the screen must fill in GC funcs and GC ops vectors (Xserver/include/gcstruct.h). For any particular GC, the func vector must remain constant, while the op vector may vary. This invariant is to ensure that Wrappers work correctly.

When a client request is processed that results in a change to the GC, the device-independent state of the GC is updated. This includes a record of the state that changed. Then the ChangeGC GC func is called. This is useful for graphics subsystems that are able to process state changes in parallel with the server CPU. DDX may opt not to take any action at GC-modify time. This is more efficient if multiple GC-modify requests occur between draws using a given GC.

Validation occurs at the first draw operation that specifies the GC after that GC was modified. DIX calls then the ValidateGC GC func. DDX should then update its internal state. DDX internal state may be stored as one or more of the following: 1) device private block on the GC; 2) hardware state; 3) changes to the GC ops.

The GC contains a serial number, which is loaded with a number fetched from the window that was drawn into the last time the GC was used. The serial number in the drawable is changed when the drawable's clipList or absCorner changes. Thus, by comparing the GC serial number with the drawable serial number, DIX can force a validate if the drawable has been changed since the last time it was used with this GC.

In addition, the drawable serial number is always guaranteed to have the most significant bit set to 0. Thus, the DDX layer can set the most significant bit of the serial number to 1 in a GC to force a validate the next time the GC is used. DIX also uses this technique to indicate that a change has been made to the GC by way of a SetGC, a SetDashes or a SetClip request.

The ScreenRec data structure has a pointer for CreateGC().

This routine must fill in the fields of a dynamically allocated GC that is passed in. It does NOT allocate the GC record itself or fill in the defaults; DIX does that.

This must fill in both the GC funcs and ops; none of the drawing functions will be called before the GC has been validated, but the others (dealing with allocating of clip regions, changing and destroying the GC, etc.) might be.

The GC funcs vector contains pointers to 7 routines and a devPrivate field:

This GC func is called immediately after a field in the GC is changed. changes is a bit mask indicating the changed fields of the GC in this request.

The ChangeGC routine is useful if you have a system where state-changes to the GC can be swallowed immediately by your graphics system, and a validate is not necessary.

ValidateGC is called by DIX just before the GC will be used when one of many possible changes to the GC or the graphics system has happened. It can modify devPrivates data attached to the GC, change the op vector, or change hardware according to the values in the GC. It may not change the device-independent portion of the GC itself.

In almost all cases, your ValidateGC() procedure should take the regions that drawing needs to be clipped to and combine them into a composite clip region, which you keep a pointer to in the private part of the GC. In this way, your drawing primitive routines (and whatever is below them) can easily determine what to clip and where. You should combine the regions clientClip (the region that the client desires to clip output to) and the region returned by NotClippedByChildren(), in DIX. An example is in Xserver/fb/fbgc.c.

Some kinds of extension software may cause this routine to be called more than originally intended; you should not rely on algorithms that will break under such circumstances.

See the Strategies document for more information on creatively using this routine.

This routine is called by DIX when a GC is being copied to another GC. This is for situations where dynamically allocated chunks of memory are stored in the GC's dynamic devPrivates and need to be transferred to the destination GC.

This routine is called before the GC is destroyed for the entity interested in this GC to clean up after itself. This routine is responsible for freeing any auxiliary storage allocated.

The GC clientClip field requires three procedures to manage it. These procedures are in the GC funcs vector. The underlying principle is that dix knows nothing about the internals of the clipping information, (except when it has come from the client), and so calls ddX whenever it needs to copy, set, or destroy such information. It could have been possible for dix not to allow ddX to touch the field in the GC, and require it to keep its own copy in devPriv, but since clip masks can be very large, this seems like a bad idea. Thus, the server allows ddX to do whatever it wants to the clientClip field of the GC, but requires it to do all manipulation itself.

This routine is called whenever the client changes the client clip region. The pGC points to the GC involved, the type tells what form the region has been sent in. If type is CT_NONE, then there is no client clip. If type is CT_UNSORTED, CT_YBANDED or CT_YXBANDED, then pValue pointer to a list of rectangles, nrects long. If type is CT_REGION, then pValue pointer to a RegionRec from the mi region code. If type is CT_PIXMAP pValue is a pointer to a pixmap. (The defines for CT_NONE, etc. are in Xserver/include/gc.h.) This routine is responsible for incrementing any necessary reference counts (e.g. for a pixmap clip mask) for the new clipmask and freeing anything that used to be in the GC's clipMask field. The lists of rectangles passed in can be freed with Xfree(), the regions can be destroyed with the RegionDestroy field in the screen, and pixmaps can be destroyed by calling the screen's DestroyPixmap function. DIX and MI code expect what they pass in to this to be freed or otherwise inaccessible, and will never look inside what's been put in the GC. This is a good place to be wary of storage leaks.

In the sample server, this routine transforms either the bitmap or the rectangle list into a region, so that future routines will have a more predictable starting point to work from. (The validate routine must take this client clip region and merge it with other regions to arrive at a composite clip region before any drawing is done.)

This routine is called whenever the client clip region must be destroyed. The pGC points to the GC involved. This call should set the clipType field of the GC to CT_NONE. In the sample server, the pointer to the client clip region is set to NULL by this routine after destroying the region, so that other software (including ChangeClip() above) will recognize that there is no client clip region.

This routine makes a copy of the clipMask and clipType from pgcSrc into pgcDst. It is responsible for destroying any previous clipMask in pgcDst. The clip mask in the source can be the same as the clip mask in the dst (clients do the strangest things), so care must be taken when destroying things. This call is required because dix does not know how to copy the clip mask from pgcSrc.

This section describes the fields in the GC that affect each drawing primitive. The only primitive that is not affected is GetImage, which does not use a GC because its destination is a protocol-style bit image. Since each drawing primitive mirrors exactly the X protocol request of the same name, you should refer to the X protocol specification document for more details.

ALL of these routines MUST CLIP to the appropriate regions in the drawable. Since there are many regions to clip to simultaneously, your ValidateGC routine should combine these into a unified clip region to which your drawing routines can quickly refer. This is exactly what the fb routines supplied with the sample server do. The mi implementation passes responsibility for clipping while drawing down to the Pixblit routines.

Also, all of them must adhere to the current plane mask. The plane mask has one bit for every bit plane in the drawable; only planes with 1 bits in the mask are affected by any drawing operation.

All functions except for ImageText calls must obey the alu function. This is usually Copy, but could be any of the allowable 16 raster-ops.

All of the functions, except for CopyArea, might use the current foreground and background pixel values. Each pixel value is 32 bits. These correspond to foreground and background colors, but you have to run them through the colormap to find out what color the pixel values represent. Do not worry about the color, just apply the pixel value.

The routines that draw lines (PolyLine, PolySegment, PolyRect, and PolyArc) use the line width, line style, cap style, and join style. Line width is in pixels. The line style specifies whether it is solid or dashed, and what kind of dash. The cap style specifies whether Rounded, Butt, etc. The join style specifies whether joins between joined lines are Miter, Round or Beveled. When lines cross as part of the same polyline, they are assumed to be drawn once. (See the X protocol specification for more details.)

Zero-width lines are NOT meant to be really zero width; this is the client's way of telling you that you can optimize line drawing with little regard to the end caps and joins. They are called "thin" lines and are meant to be one pixel wide. These are frequently done in hardware or in a streamlined assembly language routine.

Lines with widths greater than zero, though, must all be drawn with the same algorithm, because client software assumes that every jag on every line at an angle will come at the same place. Two lines that should have one pixel in the space between them (because of their distance apart and their widths) should have such a one-pixel line of space between them if drawn, regardless of angle.

The solid area fill routines (FillPolygon, PolyFillRect, PolyFillArc) all use the fill rule, which specifies subtle interpretations of what points are inside and what are outside of a given polygon. The PolyFillArc routine also uses the arc mode, which specifies whether to fill pie segments or single-edge slices of an ellipse.

The line drawing, area fill, and PolyText routines must all apply the correct "fill style." This can be either a solid foreground color, a transparent stipple, an opaque stipple, or a tile. Stipples are bitmaps where the 1 bits represent that the foreground color is written, and 0 bits represent that either the pixel is left alone (transparent) or that the background color is written (opaque). A tile is a pixmap of the full depth of the GC that is applied in its full glory to all areas. The stipple and tile patterns can be any rectangular size, although some implementations will be faster for certain sizes such as 8x8 or 32x32. The mi implementation passes this responsibility down to the Pixblit routines.

See the X protocol document for full details. The description of the CreateGC request has a very good, detailed description of these attributes.

The Drawing Primitives are as follows:

CopyArea copies a rectangle of pixels from one drawable to another of the same depth. To effect scrolling, this must be able to copy from any drawable to itself, overlapped. No squeezing or stretching is done because the source and destination are the same size. However, everything is still clipped to the clip regions of the destination drawable.

If pGC->graphicsExposures is True, any portions of the destination which were not valid in the source (either occluded by covering windows, or outside the bounds of the drawable) should be collected together and returned as a region (if this resultant region is empty, NULL can be returned instead). Furthermore, the invalid bits of the source are not copied to the destination and (when the destination is a window) are filled with the background tile. The sample routine miHandleExposures generates the appropriate return value and fills the invalid area using pScreen->PaintWindowBackground.

For instance, imagine a window that is partially obscured by other windows in front of it. As text is scrolled on your window, the pixels that are scrolled out from under obscuring windows will not be available on the screen to copy to the right places, and so an exposure event must be sent for the client to correctly repaint them. Of course, if you implement backing store, you could do this without resorting to exposure events.

An example implementation is fbCopyArea() in Xserver/fb/fbcopy.c.

CopyPlane must copy one plane of a rectangle from the source drawable onto the destination drawable. Because this routine only copies one bit out of each pixel, it can copy between drawables of different depths. This is the only way of copying between drawables of different depths, except for copying bitmaps to pixmaps and applying foreground and background colors to it. All other conditions of CopyArea apply to CopyPlane too.

An example implementation is fbCopyPlane() in Xserver/fb/fbcopy.c.

PolyPoint draws a set of one-pixel dots (foreground color) at the locations given in the array. mode is one of the defined constants Origin (absolute coordinates) or Previous (each coordinate is relative to the last). Note that this does not use the background color or any tiles or stipples.

Example implementations are fbPolyPoint() in Xserver/fb/fbpoint.c and miPolyPoint in Xserver/mi/mipolypnt.c.

Similar to PolyPoint, Polylines draws lines between the locations given in the array. Zero-width lines are NOT meant to be really zero width; this is the client's way of telling you that you can maximally optimize line drawing with little regard to the end caps and joins. mode is one of the defined constants Previous or Origin, depending upon whether the points are each relative to the last or are absolute.

Example implementations are miWideLine() and miWideDash() in mi/miwideline.c and miZeroLine() in mi/mizerline.c.

PolySegments draws unconnected lines between pairs of points in the array; the array must be of even size; no interconnecting lines are drawn.

An example implementation is miPolySegment() in mipolyseg.c.

PolyRectangle draws outlines of rectangles for each rectangle in the array.

An example implementation is miPolyRectangle() in Xserver/mi/mipolyrect.c.

PolyArc draws connected conic arcs according to the descriptions in the array. See the protocol specification for more details.

Example implementations are miZeroPolyArc in Xserver/mi/mizerarc. and miPolyArc() in Xserver/mi/miarc.c.

FillPolygon fills a polygon specified by the points in the array with the appropriate fill style. If necessary, an extra border line is assumed between the starting and ending lines. The shape can be used as a hint to optimize filling; it indicates whether it is convex (all interior angles less than 180), nonconvex (some interior angles greater than 180 but border does not cross itself), or complex (border crosses itself). You can choose appropriate algorithms or hardware based upon mode. mode is one of the defined constants Previous or Origin, depending upon whether the points are each relative to the last or are absolute.

An example implementation is miFillPolygon() in Xserver/mi/mipoly.c.

PolyFillRect fills multiple rectangles.

Example implementations are fbPolyFillRect() in Xserver/fb/fbfillrect.c and miPolyFillRect() in Xserver/mi/mifillrct.c.

PolyFillArc fills a shape for each arc in the list that is bounded by the arc and one or two line segments with the current fill style.

An example implementation is miPolyFillArc() in Xserver/mi/mifillarc.c.

PutImage copies a pixmap image into the drawable. The pixmap image must be in X protocol format (either Bitmap, XYPixmap, or ZPixmap), and format tells the format. (See the X protocol specification for details on these formats). You must be able to accept all three formats, because the client gets to decide which format to send. Either the drawable and the pixmap image have the same depth, or the source pixmap image must be a Bitmap. If a Bitmap, the foreground and background colors will be applied to the destination.

An example implementation is fbPutImage() in Xserver/fb/fbimage.c.

GetImage copies the bits from the source drawable into the destination pointer. The bits are written into the buffer according to the server-defined pixmap padding rules. pBinImage is guaranteed to be big enough to hold all the bits that must be written.

This routine does not correspond exactly to the X protocol GetImage request, since DIX has to break the reply up into buffers of a size requested by the transport layer. If format is ZPixmap, the bits are written in the ZFormat for the depth of the drawable; if there is a 0 bit in the planeMask for a particular plane, all pixels must have the bit in that plane equal to 0. If format is XYPixmap, planemask is guaranteed to have a single bit set; the bits should be written in Bitmap format, which is the format for a single plane of an XYPixmap.

An example implementation is miGetImage() in Xserver/mi/mibitblt.c.

ImageText8 draws text. The text is drawn in the foreground color; the background color fills the remainder of the character rectangles. The coordinates specify the baseline and start of the text.

An example implementation is miImageText8() in Xserver/mi/mipolytext.c.

PolyText8 works like ImageText8, except it draws with the current fill style for special effects such as shaded text. See the X protocol specification for more details.

An example implementation is miPolyText8() in Xserver/mi/mipolytext.c.

These two routines are the same as the "8" versions, except that they are for 16-bit character codes (useful for oriental writing systems).

The primary difference is in the way the character information is looked up. The 8-bit and the 16-bit versions obviously have different kinds of character values to look up; the main goal of the lookup is to provide a pointer to the CharInfo structs for the characters to draw and to pass these pointers to the Glyph routines. Given a CharInfo struct, lower-level software can draw the glyph desired with little concern for other characteristics of the font.

16-bit character fonts have a row-and-column scheme, where the 2bytes of the character code constitute the row and column in a square matrix of CharInfo structs. Each font has row and column minimum and maximum values; the CharInfo structures form a two-dimensional matrix.

Example implementations are miPolyText16() and miImageText16() in Xserver/mi/mipolytext.c.

See the X protocol specification for more details on these graphic operations.

There is a hook in the GC ops, called LineHelper, that used to be used in the sample implementation by the code for wide lines. It no longer servers any purpose in the sample servers, but still exists, #ifdef'ed by NEED_LINEHELPER, in case someone needs it.

For these routines, all graphic operations have been reduced to "spans." A span is a horizontal row of pixels. If you can design these routines which write into and read from rows of pixels at a time, you can use the mi routines.

Each routine takes a destination drawable to draw into, a GC to use while drawing, the number of spans to do, and two pointers to arrays that indicate the list of starting points and the list of widths of spans.

FillSpans should fill horizontal rows of pixels with the appropriate patterns, stipples, etc., based on the values in the GC. The starting points are in the array at pPoints; the widths are in pWidths. If sorted is true, the scan lines are in increasing y order, in which case you may be able to make assumptions and optimizations.

GC components: alu, clipOrg, clientClip, and fillStyle.

GC mode-dependent components: fgPixel (for fillStyle Solid); tile, patOrg (for fillStyle Tile); stipple, patOrg, fgPixel (for fillStyle Stipple); and stipple, patOrg, fgPixel and bgPixel (for fillStyle OpaqueStipple).

For each span, this routine should copy pWidths bits from pSrc to pDrawable at pPoints using the raster-op from the GC. If sorted is true, the scan lines are in increasing y order. The pixels in pSrc are padded according to the screen's padding rules. These can be used to support interesting extension libraries, for example, shaded primitives. It does not use the tile and stipple.

GC components: alu, clipOrg, and clientClip

The above functions are expected to handle all modifiers in the current GC. Therefore, it is expedient to have different routines to quickly handle common special cases and reload the procedure pointers at validate time, as with the other output functions.

For each span, GetSpans gets bits from the drawable starting at pPoints and continuing for pWidths bits. Each scanline returned will be server-scanline padded. The routine can return NULL if memory cannot be allocated to hold the result.

GetSpans never translates -- for a window, the coordinates are already screen-relative. Consider the case of hardware that doesn't do translation: the mi code that calls ddX will translate each shape (rectangle, polygon,. etc.) before scan-converting it, which requires many fewer additions that having GetSpans translate each span does. Conversely, consider hardware that does translate: it can set its translation point to (0, 0) and get each span, and the only penalty is the small number of additions required to translate each shape being scan-converted by the calling code. Contrast the behavior of FillSpans and SetSpans (discussed above under miTranslate), which are expected to be used more often.

Thus, the penalty to hardware that does hardware translation is negligible, and code that wants to call GetSpans() is greatly simplified, both for extensions and the machine-independent core implementation.

You should write these routines to deal with device-dependent command line arguments. The routine ddxProcessArgument() is called with the command line, and the current index into argv; you should return zero if the argument is not a device-dependent one, and otherwise return a count of the number of elements of argv that are part of this one argument. For a typical option (e.g., "-realtime"), you should return the value one. This routine gets called before checks are made against device-independent arguments, so it is possible to peek at all arguments or to override device-independent argument processing. You can document the device-dependent arguments in ddxUseMsg(), which will be called from UseMsg() after printing out the device-independent arguments.

devPrivates provides a way to attach arbitrary private data to various server structures. Any structure which contains a devPrivates field of type PrivateRec supports this mechanism. Some structures allow allocating space for private data after some objects have been created, others require all space allocations be registered before any objects of that type are created. Xserver/include/privates.h lists which of these cases applies to each structure containing devPrivates.

To request private space, use

The first argument is a pointer to a DevPrivateKeyRec which will serve as the unique identifier for the private data. Typically this is the address of a static DevPrivateKeyRec in your code. The second argument is the class of objects for which this key will apply. The third argument is the size of the space being requested, or 0 to only allocate a pointer that the caller will manage. If space is requested, this space will be automatically freed when the object is destroyed. Note that a call to dixSetPrivate that changes the pointer value may cause the space to be unreachable by the caller, however it will still be automatically freed. The function returns TRUE unless memory allocation fails. If the function is called more than once on the same key, all calls must use the same value for size or the server will abort.

To request per-screen private space in an object, use

The type and size arguments are the same as those to dixRegisterPrivateKey but this function ensures the given key exists on objects of the specified type with distinct storage for the given pScreen. The key is usable on ScreenPrivate variants that are otherwise equivalent to the following Private functions.

To attach a piece of private data to an object, use:

The first argument is the address of the devPrivates field in the target structure. This field is managed privately by the DIX layer and should not be directly modified. The second argument is a pointer to the DevPrivateKeyRec which you registered with dixRegisterPrivateKey or allocated with dixCreatePrivateKey. Only one piece of data with a given key can be attached to an object, and in most cases each key is specific to the type of object it was registered for. (An exception is the PRIVATE_XSELINUX class which applies to multiple object types.) The third argument is the value to store.

If private data with the given key is already associated with the object, dixSetPrivate will overwrite the old value with the new one.

To look up a piece of private data, use one of:

The first argument is the address of the devPrivates field in the target structure. The second argument is the key to look up. If a non-zero size was given when the key was registered, or if private data with the given key is already associated with the object, then dixLookupPrivate will return the pointer value while dixLookupPrivateAddr will return the address of the pointer.

When implementing new server resource objects that support devPrivates, there are four steps to perform: Add a type value to the DevPrivateType enum in Xserver/include/privates.h, declare a field of type PrivateRec * in your structure; initialize this field to NULL when creating any objects; and when freeing any objects call the dixFreePrivates or dixFreeObjectWithPrivates function.

Wrappers are not a body of code, nor an interface spec. They are, instead, a technique for hooking a new module into an existing calling sequence. There are limitations on other portions of the server implementation which make using wrappers possible; limits on when specific fields of data structures may be modified. They are intended as a replacement for GCInterest queues, which were not general enough to support existing modules; in particular software cursors needed more control over the activity. The general mechanism for using wrappers is:

Thus the privateWrapperFunction provides hooks for performing work both before and after the wrapped function has been called; the process of resetting the functionVector is called "unwrapping" while the process of fetching the wrapped function and replacing it with the wrapping function is called "wrapping". It should be clear that GCInterest queues could be emulated using wrappers. In general, any function vectors contained in objects can be wrapped, but only vectors in GCs and Screens have been tested.

Wrapping screen functions is quite easy; each vector is individually wrapped. Screen functions are not supposed to change after initialization, so rewrapping is technically not necessary, but causes no problems.

Wrapping GC functions is a bit more complicated. GC's have two tables of function vectors, one hanging from gc->ops and the other from gc->funcs, which should be initially wrapped from a CreateGC wrapper. Wrappers should modify only table pointers, not the contents of the tables, as they may be shared by more than one GC (and, in the case of funcs, are probably shared by all gcs). Your func wrappers may change the GC funcs or ops pointers, and op wrappers may change the GC op pointers but not the funcs.

Thus, the rule for GC wrappings is: wrap the funcs from CreateGC and, in each func wrapper, unwrap the ops and funcs, call down, and re-wrap. In each op wrapper, unwrap the ops, call down, and rewrap afterwards. Note that in re-wrapping you must save out the pointer you're replacing again. This way the chain will be maintained when wrappers adjust the funcs/ops tables they use.