The Direct Access Cycle

The fundamental concept of DPA is the direct access cycle. In a direct access cycle (or cycle), the DPA user (for example, you or the DPS extension) follows these steps:

1. Call the directAccessOK() function to inquire whether DPA is allowed for a given drawable or pair of drawables.

2. If DPA is allowed, call the directAccessStart() function to begin a cycle.

3. Access the pixels.

4. Call the directAccessEnd() function to end the cycle.

Requirements for Drawables Using DPA

DPA can only be used for the pixmap and window drawables on devices with memory-mapped frame buffers that meet the following requirements. (Note that these requirements are similar to the requirements of cfb and mfb packages).

• The byte order and pixel order must match the native order of the server:

  · SPARC Big-endian

  · x86 Little-endian

• Table 12-1 shows how pixels must be packed in memory:

Table 12-1

bitsPerPixel	bytesPerPixel
32	4
16	2
8	1
4	1/2
2	1/4
1	1/8

• Given the return values from directAccessStart(), p and bytesPerRow, the pointer to the beginning of a scanline y is given by:

   CARD8* pStart = p + ((y+pDraw->y) * pixelsPerRow)

If bytesPerPixel >= 1, the pointer to pixel at (x,y) is:

   pStart + ((x + pDraw->x) * bytesPerPixel)

And if bytesPerPixel < 1, the pointer to the byte containing pixel at (x,y) is:

pStart + ((x + pDraw->x) >> shift)

bitsPerPixel Shift 1

3

2	2
4	1

Initialization

sunDPAScreenRec

typedef struct{ sunDPAMode mode; sunDPAMode dpsMarkMode; sunDPAcessType (*directAccessOK)(DrawablePtr, DrawablePtr); Bool (*directAccessDPS)(DrawablePtr); Bool (*directAccessStart)(DrawablePtr, CARD8**, int*); void (*directAccessEnd)(DrawablePtr); CARD32 reserved[8] } sunDPAScreenRec;

Arguments..dpsMarkMode is described in "directAccessDPS" on page 249.

mode is described in "sunDPAMode" on page 245.

directAccessOK(), directAccessDPS(),
directAccessStart() and directAccessEnd() are

defined in "Device-Supplied Routines" on page 247.

The final member of the structure is an array of integers reserve for future versions of this interface. Set these members to 0.

sunDPAMode

mode is one of these available modes defined in sunDPAMode:

typedef enum { sunDPANone, sunDPACustom, sunDPAPixmap, sunDPAAllDrawables } sunDPAMode;

If the mode is set to sunDPANone, DPA is disabled for screens controlled by your DDX handler.

If your DDX handler's pixmaps are simple-memory pixmaps, such as cfb pixmaps, set the mode to sunDPAPixmap to enable DPA for all pixmaps.

If your DDX handler's windows are memory mapped and the device is stateless, set the mode to sunDPAAllDrawables to enable DPA for windows and pixmaps.

If your DDX handler cannot use either of the predefined implementations, set the mode to sunDPACustom and provide your own DPA routines.

sunDPAMode and sunDPAScreenRec are defined in the dpa/sundpascr.h header file.

sunDPAScreenInit

Call the following initialization function from your DDX handler's InitOutput() function.

int sunDPAScreenInit(pScreen, pDPAdevfuncs) ScreenPtr pScreen; sunDPAScreenRec*pDPAdevfuncs;

Arguments..pDPAdevfuncs is a pointer to a sunDPAScreenRec.

If a handler does not call sunDPAScreenInit, DPA is disabled for screens controlled by your DDX handler.

Since many DDX handlers require very simple and common DPA handler functions, two predefined implementations are provided. For these two modes the function pointers directAccessOK(), directAccessStart(), and directAccessEnd() are ignored.

Device-Supplied Routines

sunDPAAccessType

sunDPAAccessType (*directAccessOk)(DrawablePtr pDraw1, DrawablePtr pDraw2)

Purpose	This function determines whether simultaneous DPA is possible for two drawables. You must provide this function if your DDX handler's DPA mode is sunDPACustom.
Returns	pDraw1 and pDraw2 are sunDPAAccess types for the two drawables. If pDraw2 is NULL, call directAccessOK() to determine whether or not DPA is possible for a single drawable. The return codes are defined in dpa/sundpatype.h.

If DPA is not allowed for either of the drawables, sunDPANeither should be returned.

If DPA is allowed for both drawables at the same time, sunDPABoth should be returned.

If DPA is allowed for the first drawable, but not the second (or if pDraw2 is NULL), sunDPAOne should be returned.

If DPA is only allowed for the second drawable, sunDPATwo should be returned.

Finally, if DPA is allowed for either of the drawables, but not at the same time, sunDPAEitherNotBoth should be returned. This might occur, for example, if the hardware register settings are different for the two drawables.

directAccessStart

Bool (*directAccessStart)(DrawablePtr pDraw, CARD8 **p, int *pLineBytes)

Purpose....This function is called to begin a cycle for a drawable. Your DDX handler should set up any device state required to access the pixels in the drawable. Then set the contents of p to the pointer at the beginning of the drawable's frame buffer, and set *pLineBytes to the number of bytes per scanline in the drawable.

This function must be provided if the DDX handler's DPA mode is sunDPACustom.

While a cycle is in progress, the only other DDX functions that might be called are directAccessStart() and pScreen->SourceValidate. No other functions are called until the cycle has ended.

ReturnsdirectAccessEnd	If the cycle can be started, directAccessStart() should return TRUE. If a cycle cannot be started, it should return FALSE.
void (*directAccessEnd)(DrawablePtr pDraw)
Purpose	This function is called to end a cycle for a given drawable. If your DDX handler never needs to do anything at the end of a cycle, this function pointer can be NULL.

directAccessDPS

Boll (*directAccessDPS)(DrawablePtr pDraw)

Purpose....This function allows the DPS extension to determine whether or not it should use DPA to mark a given drawable as accessible.

Note that the return value from directAccessOK() tells whether DPA is allowed for a drawable. directAccessDPS() tells you whether DPS should use DPA. It is a performance hint. The values returned for given drawable types should be determined during performance tuning. This function must be provided if the handler specified dpsMarkMode as sunDPACustom. If dpsMarkMode is set to sunDPAAllDrawables or sunDPAPixmap, predefined implementations of directAccessDPS will be used. directAccessStart and directAccessEnd will be used to begin and end a cycle as usual.

Returns....If DPS can and should use DPA to mark to the drawable, directAccessDPS() should return TRUE; otherwise, return FALSE.

---

Note - If directAccessDPS() returns TRUE for a given drawable, directAccessStart() must always succeed for that drawable. This is a requirement due to the design of the DPS extension.

---

---

Note - Currently, this function is not called by the window server. The system will behave as though the dpsMarkMode were sunDPANone for all drawables. This function will be used in a future release.

---