Hardware Window IDs

Some graphics devices use WIDs to control the video output circuitry and drawing functions of their frame buffer. The term display ID (DID) is also used. For each pixel, a portion of the frame buffer describes how that pixel is to be output to the monitor. Examples of these attributes are: the specific buffer the color data is to be taken from, the other buffers it is to be combined with, and the output lookup tables to use. These video output aspects are called WID pixel attributes and are meaningful to the video display circuitry by a distinct bit pattern.

On indirect WID devices, the WID value in the frame buffer is used to look up the WID pixel attributes in a hardware table called a WID lookup table. On these devices, the WID value serves as an index into this table.

On direct WID devices the WID value in the frame buffer is the actual bit pattern of the WID pixel attributes. In this case, there is no indirection through a lookup table.

Usually, the pixels for a given window all share the same pixel attributes. For example, the pixels are all the same depth and all possess Z buffer information. Because of this, a distinct WID is allocated for use by the window and the WID plane group in the window's visible region is filled with the value of this WID.

---

Note - In this release, the WID interface refers to direct WID devices that are not supported in this release.

---

Software WID Object

The OpenWindows DDX interface provides a software object to represent hardware WIDs. On a direct WID device, each software WID represents a single hardware WID value. On indirect WID devices, a software WID can represent one or more contiguous hardware WID values.

The DDX interface provides functions a device handler can use to allocate WIDs. It also provides routines to initialize WID management. These routines are included in the MPG package.

On indirect WID devices there is a concept of a WID free pool. These are the WIDs in the hardware WID table that are not already being used by some window.

An opaque type, WidPtr, points to the software WID object. Opaque means that the format of the memory pointed to is known only by MPG. WID object attributes are only accessible with the routines defined in "Window ID Functions" on page 87.

The purpose of the software WID object is to be general enough that all device architectures can share WID properties, and to be extensible enough to accommodate device dependencies.

WID Object Attributes

A WID object has the following attributes. READ ONLY means that the attribute is set at WID allocation time by WID or a device-dependent WID routine. After allocation, the attribute cannot be changed by clients of WID.

• Screen....READ ONLY

  The device that owns the WID.

• Visual....READ ONLY

  The visual of the window passed to the allocation function.

• Value....READ ONLY

  The bit pattern rendered into the WID plane group that uses the WID.

• Number...READ ONLY

  The number of contiguous WIDs described by the WID object. For direct WID devices, this will always be 1. For indirect WID devices, the value of the WID object is the index into the WID table of the first WID in the group. The values of the other WIDs in the group are in sequentially ascending order relative to the first WID. To be specific, if n is the value of the WID object, the values of subsequent WIDs in the group are n+1, n+2, ..., n+(number-1).

• Unique...READ ONLY

  A Boolean that indicates whether the WID can be shared among multiple windows. A value of TRUE means that the WID is not sharable; a value of FALSE means that the WID can be shared.

  For example, the unique attribute of the WID of a hardware double-buffered window might be TRUE. Another example of a unique WID is for hardware clipping. This type of WID must be unique because if another window shares the WID, drawing to the first window could happen in the other window sharing the WID, which is not the desired behavior.

• Flavor....READ ONLY

  A small integer representing the union of all pixel attributes for the device, not including unique fields and colormap control. Unique fields include display buffer control and hardware clipping. Non-unique fields include depth and Z buffer. The values of this attribute are device-dependent. For more information on flavors, see Chapter 8, "Colormap Interface."

• DevData...READ/WRITE

  An opaque handle to arbitrary device-specific data.

• ColorLut...READ/WRITE

  The identifier of the hardware color lookup table to use for displaying windows using WID.

For devices supporting only a single hardware color lookup table, the value of this attribute is undefined and setting it is ignored.

Two WID objects are considered to be equal if their values are equal.

Accessing WID

All files using the WID routines of MPG must include the following header file:

#include "mpg/wid.h"

Dynamically link all shared objects using WID with libmpg.so.

Using MPG

Devices that use WIDs are multiple plane group (MPG) devices because there must be a plane group filled with the proper WID values when a window is moved. MPG does this filling with a process called WID preparation.

Device handlers that use WIDs must first initialize MPG by calling mpgScreenInit, mpgInsertplanegroup, and other MPG functions.

How to Use WID

This section describes the purpose for and usage of the WID function listed in "Window ID Functions" on page 87.

DDX Handler

DDX handlers use the WID function to:

• Initialize WID

  widScreenInit is used to initialize WID for the screen and should be called before any other WID functions.

• Create windows

The DDX handler wraps pScreen->CreateWindow. If the device has a single color lookup table, call widAllocate to create a new WID for that window and then call widSetWindowWid to attach it.

If the device has multiple color lookup tables, the DDX handler calls cmapMhcWindowAttachWid.

See Chapter 8, "Colormap Interface" for more information on devices with multiple color lookup tables.

MPG

MPG uses WID to:

• Change WIDs

  MPG uses widDecref to indicate there is one less window using old WID and widIncref to indicate there is one more window using the new WID.

• Prepare Window WIDs

  MPG uses widGetValue to get the value with which to fill the WID plane group.

CMAP

CMAP uses WID function to:

• Avoid unnecessary preparations

  If CMAP assigns a WID to a window that was the same as the old, it does not try to reprepare the WID. It uses widGetValue and the comparison operator == to make the necessary test.

• Notify WIDs of color lookup table changes

  When XInstallColormap changes the hardware color lookup table assignment of a colormap, the WIDs of all windows using that colormap are notified of the change so that the given color lookup table can be displayed in these windows. To do this notification, CMAP calls widSetColorLut. This can also occur in XUninstallColormap if it tries to implicitly reinstall a colormap that previously lost its color lookup table because of another installation.

• Manage flavors

  CMAP attempts to share WIDs between windows of the same flavor. It uses widGetWindowWid, widGetFlavor, widGetValue, and the comparison operator == to do the necessary tests. When CMAP attempts to share WIDs, it ignores unique WIDs by calling widGetUnique.

• Assign new WIDs

  When an XSetWindowColormap occurs, CMAP attempts to find an existing WID of the same flavor as the window. If it cannot, it creates a new one, using widAllocate, and assigns it to the window using mpgSetWindowWid.

See Chapter 8, "Colormap Interface" for more information on WID creation and manipulation by the CMAP package.

WID Data Types

The function that initializes WID is widScreenInit. The following WID data types describe the device-dependent WID functions that must be supplied to the widScreenInit function.

WidPtr

A pointer to a WID object. A WID object represents one or more device WIDs. This pointer is not passed as an argument to widScreenInit (see page 87), but it is central to the set of functions described in this chapter.

typedef void *WidPtr;

---

Note - This pointer is opaque. The internal format of _WidObj is not exposed to the DDX handler. Use the utility functions provided to access WidPtr.

---

WidAllocFunc

typedef WidPtr (*WidAllocFunc)(ScreenPtr pScreen, VisualID visual, int count, Bool unique, CARD32 flavor);

Purpose	This is the WID allocation routine supplied by the device handler.
Results	It allocates one or more contiguous WIDs from a WID table. The location and format of the WID table is device, and possibly visual, dependent.
Arguments	visual is used by devices whose WID allocation depends on the window's visual. This type of device internally associates a visual with device-dependent WID data, such as the location of the WID table. When the allocate function is called, the device data associated with pWin's visual is retrieved and used as appropriate.

count is the number of contiguous WIDs to allocate. For direct WID devices, a WID object is limited to a single hardware WID, so this value must always be 1. The base WID value is aligned on a power-of-two boundary, which is determined by rounding up count to the next power of two. If n is the base WID value, subsequent WID values in the sequence are n+1, n+2, ..., n+(count - 1).

unique is TRUE if the WID is non-sharable. This argument is used by devices that allocate unique WIDs in different tables from the non-unique ones.

flavor is an additional argument to use for your own purposes. For example, if hardware clipping WIDs are allocated in a different WID table than software WIDs, flavor would be used to indicate the allocation of a hardware WID versus a software WID. See "Flavors" on page 116 for a detailed description of how to assign flavor values.

Returns....On direct WID devices, this routine returns NULL if count <> 1. For indirect WID devices, if count > 1, multiple contiguous hardware WIDs are allocated.

On indirect WID devices, this function marks the returned WID(s) as allocated and removes them from the free pool.

WidFreeFunc

typedef void (*WidFreeFunc)(WidPtr pWid);

Purpose	The WID free routine supplied by the device handler.
Returns	On indirect WID devices, WidFreeFunc returns the WID(s) represented by the given WID object to the free pool and frees the WID object memory.

On direct WID devices, this routine frees the WID object memory.

WidSetColorLutFunc

typedef void (*WidSetColorLutFunc) (WidPtr pWid, CARD32 clutId);

Purpose	Specifies the color lookup table ID that a WID is to display. This function is supplied by the device handler.
Results	On indirect WID devices, this routine updates the WID table for the WID to display the given color lookup table.

On direct WID devices, this routine changes the Value attribute.

If the WID object consists of more than one hardware WID, the color lookup table selection attributes of all hardware WIDs is set to the same value, the appropriate value for clutId. Currently, this is only applicable to indirect WID devices.

---

Note - No WID preparation is done. The client is expected to call an MPG function to reprepare. This only affects direct WID devices.

---

Window ID Functions

This section lists the WID functions used by other parts of MPG, CMAP, and DDX handlers. "" on page 97 provides a description of the expected use of these routines.

General Routines

These routines are used by several different software components of the server, including MPG, CMAP, and the device handler. The device handler can call some of these routines from screen function wrappers such as CreateWindow, or from the device-dependent WID functions supplied to widScreenInit.

widScreenInit

Bool widScreenInit (ScreenPtr pScreen, WidAllocFunc allocFunc, WidFreeFunc freeFunc, WidSetColorLutFunc setClutFunc)

Purpose	This function initializes WID management for a screen.
Called by	A DDX handler at screen initialization.
ArgumentswidScreenClose	The argument functions are device-dependent functions that understand the device details for managing WIDs. These functions must be non-NULL.
void
Purpose	This function frees resources allocated by widScreenInit.

Called bywidAllocate	the device's ScreenClose procedure
WidPtr
Purpose	This function allocates a WID object appropriate for the specified visual on pScreen. Initially, the reference count for the WID is 0.
Arguments	flavor must be less than the maxFlavors of the WID's plane group, or NULL is returned. maxFlavors is the value passed to cmapScreenInit for the WID's plane group. See Chapter 8, "Colormap Interface" for more information.

If count is > 1 on direct WID devices, a WID object is limited to a single hardware WID, so this value must be 1. For indirect WID devices, if count > 1, multiple contiguous hardware WIDs are allocated. The base WID value is aligned on a power-of-two boundary, which is determined by rounding up count to the next power of two. The base WID value is retrieved by calling widGetValue. If this value is n, subsequent WID values in the sequence are n+1, n+2, ..., n+(count - 1).

ReturnswidIncref	On direct WID devices, this routine returns NULL if count > 1.
void
Purpose	This function increments the reference count of a WID object.

widDecref

void widDecref (WidPtr pWid)

Purpose	This function decrements the reference count of a WID object. If the reference count becomes less than or equal to 0, the device-dependent widFree function is called. This function frees the WID object memory (see below).
ReturnswidGetScreen	For indirect WID devices, the WID value(s) represented by the WID object are returned to the free pool.
ScreenPtr
ReturnswidGetVisual	A pointer to the WID object's screen.
VisualID
Returns	Returns the ID of the visual of the window with which the WID was created.

widGetValue

unsigned long widGetValue (WidPtr pWid)

Purpose	For single WID objects, this is the WID bit pattern to be rendered into the frame buffer. For multiple WID objects, this is the bit pattern of the first WID in the sequence.
ReturnswidSetValue	The value of the WID object.
void
Purpose	For single WID objects, this is the WID bit pattern to be rendered into the frame buffer.
ReturnswidWinGetValue	The value of the WID object.
unsigned long
ReturnswidGetNumber	The value of the WID object for the specified window.
unsigned int
Returns	The number of hardware WID values represented by the argument WID object.

widGetUnique

Bool widGetUnique (WidPtr pWid)

ReturnswidGetFlavor	Whether a WID is unique.
CARD32
ReturnswidSetDevData	The flavor of a WID.
void
PurposewidGetDevData	This function sets device-dependent data on a WID object.
pointer
Purpose	This function gets device-dependent data on a WID object.

widSetColorLut

void widSetColorLut (WidPtr pWid, CARD32 clutId)

Purpose	This function sets the color lookup table ID for a WID object.
Results	If the WID object consists of more than one hardware WID, the color lookup table selection attributes of the hardware WIDs are set to the same value, that is, the appropriate value for clutId.

---

Note - On devices with a single color lookup table, this value is ignored.

---

widGetColorLut

CARD32 widGetColorLut (WidPtr pWid)

Purpose....This function gets the color lookup table ID for a WID object.

---

Note - On devices with a single color lookup table, this value is undefined.

---

widSetWindowWid

void widSetWindowWid (WindowPtr pWin, WidPtr pWid, Bool prepare)

Purpose	This function specifies a window's WID.
Results	The reference count of pWid increases and the reference count of the old WID decreases.

If prepare is TRUE, the WID plane group in the window's visible region is filled with the WID value. This is done even if the old WID is the same as pWid.

widGetWindowWid

WidPtr widGetWindowWid (WindowPtr pWin)

Returns....The WID of a window. This is NULL if mpgWindowSetWid has not been called.

Handler-Specific Routines

Call these functions only from the device-dependent WID functions supplied to widScreenInit.

widAllocObj

WidPtr widAllocObj ()

Purpose	This function allocates memory for a software WID object.
Called by	The device-dependent allocFunc.
ResultswidSetValue	The reference count of this WID object is set to 0.
void
Purpose	This function sets the value of a WID.
Called by	The device-dependent allocFunc.

widFreeObj

void widFreeObj (WidPtr pWid)

Purpose	Frees memory allocated by widAllocObj.
Called by	The device-dependent freeFunc.

WID Device-Dependent Allocation and Free Functions Implementation

The widScreenInit function initializes WID for a device. Before calling this routine, make whatever device-dependent preparations are necessary to start using WIDs. For example, allocate a screen devPrivate slot for storing device-specific WID data on the screen.

On indirect WID devices, after widScreenInit is called, all of the device WIDs are considered to be unallocated and in the free pool. WID values returned in WID objects allocated by allocFunc are removed from this pool until freed.

For some plane groups of a device, there is only a single WID. In this case, the allocFunc can return a WID object with this WID as its value; ignore the WID reference count.

Allocation Function

widScreenInit takes an allocFunc argument. This is the device-dependent WID allocation function. This function calls widAllocObj, which returns a partially initialized WID object. allocFunc then fills in various device-dependent attributes of the WID. This is illustrated in the following example function.

/* Note: required for a bug workaround (described below) */ typedef struct { unsigned long opaque1[6]; CARD32 clutId; unsigned long opaque2[2]; } *WidInsidePtr; WidPtr myAllocFunc (ScreenPtr pScreen, VisualId visual, int count, Bool unique, CARD32 flavor) { WidPtr pWid; if (!(pWid = widAllocObj ()) return (NULL); <allocate a hardware WID value> widSetValue(pWid, <window ID value>); widSetDevData(pWid, <anything the handler wants>); /* ** Initialize the color LUT by reaching inside the ** opaque object. This is a temporary bug workaround. ** See note below. */ <initialize color LUT of hardware WID> { WidInsidePtr *pWidInside; pWidInside = (WidInsidePtr) pWid; pWidInside->clutId = <initial color LUT>; } }

value is of type unsigned long, clutId is of type CARD32, and devPrivate is of type pointer.

The client is required to initialize the value attribute. It is also required that clutId be initialized. Initialization of devPrivate is completely optional.

---

Note - There is a bug in this release: myAllocFunc cannot call widSetColorLut to initialize pWid's color LUT because the screen of pWid has not yet been initialized. pWid must have been assigned a screen for widSetColorLut to work. The workaround is to access the clutId field of the pWid object directly. To do this, the device handler must "reach inside" the otherwise opaque object. This implementation is allowed only for this workaround and will be removed in a future release when a widXXX function is provided for color LUT setting that does not require the screen to be initialized.

---

---

Note - Even if the device-dependent WID freeFunc calls cmapMhcReleaseOverload, myAllocFunc should never call cmapMhcForceOverload. This call is invoked at a higher level in the system.

---

---

Note - In general, you should not attempt to share WIDs between windows within this routine. Instead, you should use the facilities described in Chapter 8, "Colormap Interface." The only exception to this rule is when there is only a single WID for a visual. In this case, myAllocFunc can allocate pWid only once and return copies of the pointer to it.

---

Free Function

The widScreenInit function takes a freeFunc argument. This is the device-dependent WID free function.

If the device has multiple color lookup tables, this function should call cmapMhcReleaseOverload to notify CMAP that it might be possible to remove some overloading conditions. It passes the return value of widGetVisual as the argument to this routine. See Chapter 8, "Colormap Interface" for more information.

Next, it performs any device-dependent actions needed to free the WID. Finally, freeFunc frees the WID object memory by calling widFreeObj.

If the device does not have multiple color lookup tables, this function performs the device-dependent free actions followed by a call to widFreeObj.