appc

linux图形界面x liberary手册

.SH
Hooks onto Xlib Data Structures

<P>

Various Xlib data structures have provisions for extension procedures
to chain extension supplied data onto a list.
These structures are
.PN GC , 
.PN Visual , 
.PN Screen , 
.PN ScreenFormat , 
.PN Display , 
and 
.PN XFontStruct .
Because the list pointer is always the first member in the structure, 
a single set of procedures can be used to manipulate the data
on these lists.

<P>

The following structure is used in the functions in this section
and is defined in 
<B><TT>X11/Xlib.h :</TT></B>

<P>

<!.IN "XExtData" "" "@DEF@">
.sM
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct _XExtData {
	int number;	/* number returned by XInitExtension */
	struct _XExtData *next;	/* next item on list of data for structure */
	int (*free_private)();	/* if defined,  called to free private */
	XPointer private_data;	/* data private to this extension. */
} XExtData;
.De

<P>

.eM
When any of the data structures listed above are freed, 
the list is walked, and the structure's free procedure (if any) is called. 
If free is NULL, 
then the library frees both the data pointed to by the private_data member
and the structure itself. 

<P>

.sM
.Ds 0
.TA .5i
.ta .5i
union {	Display *display;
	GC gc;
	Visual *visual;
	Screen *screen;
	ScreenFormat *pixmap_format;
	XFontStruct *font } XEDataObject;
.De

<P>

.eM
<!.IN "XEHeadOfExtensionList" "" "@DEF@">
.sM
.FD 0
XExtData **XEHeadOfExtensionList(\fIobject\fP)
	XEDataObject \fIobject\fP;
.FN
.IP \fIobject\fP 1i
Specifies the object.

<P>

.eM
The
.PN XEHeadOfExtensionList
function returns a pointer to the list of extension structures attached
to the specified object.
In concert with 
.PN XAddToExtensionList ,
.PN XEHeadOfExtensionList
allows an extension to attach arbitrary data to any of the structures
of types contained in
.PN XEDataObject .

<P>

<!.IN "XAddToExtensionList" "" "@DEF@">
.sM
.FD 0
XAddToExtensionList(\fIstructure\fP, \fIext_data\fP)
.br
      XExtData **\fIstructure\fP;
.br
      XExtData *\fIext_data\fP;
.FN
.IP \fIstructure\fP 1i
Specifies the extension list.
.IP \fIext_data\fP 1i
Specifies the extension data structure to add.

<P>

.eM
The structure argument is a pointer to one of the data structures
enumerated above.
You must initialize ext_data->number with the extension number
before calling this function.
<!.IN "XFindOnExtensionList" "" "@DEF@">
.sM
.FD 0
XExtData *XFindOnExtensionList(\fIstructure\fP, \fInumber\fP)
.br
      struct _XExtData **\fIstructure\fP;
.br
      int \fInumber\fP;
.FN
.IP \fIstructure\fP 1i
Specifies the extension list.
.IP \fInumber\fP 1i
Specifies the extension number from
.PN XInitExtension .

<P>

.eM
The
.PN XFindOnExtensionList
function returns the first extension data structure
for the extension numbered number.
It is expected that an extension will add at most one extension
data structure to any single data structure's extension data list.
There is no way to find additional structures.

<P>

The 
.PN XAllocID 
macro, which allocates and returns a resource ID, is defined in 
<B><TT>X11/Xlib.h .</TT></B>
<!.IN "XAllocID" "" "@DEF@">
.sM
.FD 0
XAllocID(\fIdisplay\fP)
.br
     Display *\fIdisplay\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.

<P>

.eM
This macro is a call through the 
.PN Display
structure to an internal resource ID allocator.
It returns a resource ID that you can use when creating new resources.

<P>

The 
.PN XAllocIDs
macro allocates and returns an array of resource ID.
<!.IN "XAllocIDs" "" "@DEF@">
.sM
.FD 0
XAllocIDs(\fIdisplay\fP, \fIids_return\fP, \fIcount\fP)
.br
     Display *\fIdisplay\fP;
.br
     XID *\fIids_return\fP;
.br
     int \fIcount\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIids_return\fP 1i
Returns the resource IDs.
.IP \fIrep\fP 1i
Specifies the number of resource IDs requested.

<P>

.eM
This macro is a call through the 
.PN Display
structure to an internal resource ID allocator.
It returns resource IDs to the array supplied by the caller.
To correctly handle automatic reuse of resource IDs, you must call
.PN XAllocIDs
when requesting multiple resource IDs.  This call might generate
protocol requests.
.SH
GC Caching

<P>

GCs are cached by the library to allow merging of independent change
requests to the same GC into single protocol requests.
This is typically called a write-back cache.
Any extension procedure whose behavior depends on the contents of a GC
must flush the GC cache to make sure the server has up-to-date contents
in its GC.

<P>

The 
.PN FlushGC
macro checks the dirty bits in the library's GC structure and calls
.PN _XFlushGCCache 
if any elements have changed.
The
.PN FlushGC
macro is defined as follows:
<!.IN "FlushGC" "" "@DEF@">
.sM
.FD 0
FlushGC(\fIdisplay\fP, \fIgc\fP)
.br
      Display *\fIdisplay\fP;
.br
      GC \fIgc\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIgc\fP 1i
Specifies the GC.

<P>

.eM
Note that if you extend the GC to add additional resource ID components,
you should ensure that the library stub sends the change request immediately.
This is because a client can free a resource immediately after
using it, so if you only stored the value in the cache without
forcing a protocol request, the resource might be destroyed before being
set into the GC.
You can use the
.PN _XFlushGCCache 
procedure 
to force the cache to be flushed.
The
.PN _XFlushGCCache 
procedure
is defined as follows:
<!.IN "_XFlushGCCache" "" "@DEF@">
.sM
.FD 0
_XFlushGCCache(\fIdisplay\fP, \fIgc\fP)
.br
      Display *\fIdisplay\fP;
.br
      GC \fIgc\fP;
.FN
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIgc\fP 1i
Specifies the GC.

<P>

.eM
.SH
Graphics Batching

<P>

If you extend X to add more poly graphics primitives, you may be able to
take advantage of facilities in the library to allow back-to-back 
single calls to be transformed into poly requests.
This may dramatically improve performance of programs that are not
written using poly requests. 
A pointer to an 
.PN xReq ,
called last_req in the display structure, is the last request being processed.  
By checking that the last request
type, drawable, gc, and other options are the same as the new one
and that there is enough space left in the buffer, you may be able
to just extend the previous graphics request by extending the length
field of the request and appending the data to the buffer.  
This can improve performance by five times or more in naive programs.  
For example, here is the source for the 
.PN XDrawPoint 
stub.
(Writing extension stubs is discussed in the next section.)
.IP
.sM
.nf

#include <X11/Xlibint.h>

/* precompute the maximum size of batching request allowed */

static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);

XDrawPoint(dpy, d, gc, x, y)
    register Display *dpy;
    Drawable d;
    GC gc;
    int x, y; /* INT16 */
{
    xPoint *point;
    LockDisplay(dpy);
    FlushGC(dpy, gc);
    {
    register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req;
    /* if same as previous request, with same drawable, batch requests */
    if (
          (req->reqType == X_PolyPoint)
       && (req->drawable == d)
       && (req->gc == gc->gid)
       && (req->coordMode == CoordModeOrigin)
       && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax)
       && (((char *)dpy->bufptr - (char *)req) < size) ) {
         point = (xPoint *) dpy->bufptr;
         req->length += sizeof (xPoint) >> 2;
         dpy->bufptr += sizeof (xPoint);
         }

    else {
        GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
        req->drawable = d;
        req->gc = gc->gid;
        req->coordMode = CoordModeOrigin;
        point = (xPoint *) (req + 1);
        }
    point->x = x;
    point->y = y;
    }
    UnlockDisplay(dpy);
    SyncHandle();
}
.fi

<P>

.eM
To keep clients from generating very long requests that may monopolize the 
server,
there is a symbol defined in
<B><TT>X11/Xlibint.h</TT></B>
of EPERBATCH on the number of requests batched.
Most of the performance benefit occurs in the first few merged requests.
Note that 
.PN FlushGC 
is called \fIbefore\fP picking up the value of last_req,
because it may modify this field.
.SH
Writing Extension Stubs

<P>

All X requests always contain the length of the request,
expressed as a 16-bit quantity of 32 bits.
This means that a single request can be no more than 256K bytes in
length.
Some servers may not support single requests of such a length.
The value of dpy->max_request_size contains the maximum length as
defined by the server implementation.
For further information,
see ``X Window System Protocol.''
.SH
Requests, Replies, and Xproto.h

<P>

The 
<B><TT>X11/Xproto.h</TT></B>
file contains three sets of definitions that
are of interest to the stub implementor:  
request names, request structures, and reply structures.

<P>

You need to generate a file equivalent to 
<B><TT>X11/Xproto.h</TT></B>
for your extension and need to include it in your stub procedure.
Each stub procedure also must include 
<B><TT>X11/Xlibint.h .</TT></B>

<P>

The identifiers are deliberately chosen in such a way that, if the
request is called X_DoSomething, then its request structure is
xDoSomethingReq, and its reply is xDoSomethingReply.  
The GetReq family of macros, defined in 
<B><TT>X11/Xlibint.h , </TT></B>
takes advantage of this naming scheme.

<P>

For each X request, 
there is a definition in 
<B><TT>X11/Xproto.h</TT></B>
that looks similar to this:

<P>

.Ds 
.R
#define X_DoSomething   42
.De
In your extension header file, 
this will be a minor opcode, 
instead of a major opcode.
.SH
Request Format

<P>

Every request contains an 8-bit major opcode and a 16-bit length field
expressed in units of four bytes.  
Every request consists of four bytes of header
(containing the major opcode, the length field, and a data byte) followed by
zero or more additional bytes of data. 
The length field defines the total length of the request, including the header.
The length field in a request must equal the minimum length required to contain 
the request. 
If the specified length is smaller or larger than the required length, 
the server should generate a 
.PN BadLength 
error.
Unused bytes in a request are not required to be zero.  
Extensions should be designed in such a way that long protocol requests
can be split up into smaller requests,
if it is possible to exceed the maximum request size of the server.
The protocol guarantees the maximum request size to be no smaller than
4096 units (16384 bytes).

<P>

Major opcodes 128 through 255 are reserved for extensions.
Extensions are intended to contain multiple requests, 
so extension requests typically have an additional minor opcode encoded 
in the second data byte in the request header, 
but the placement and interpretation of this minor opcode as well as all
other fields in extension requests are not defined by the core protocol.
Every request is implicitly assigned a sequence number (starting with one)
used in replies, errors, and events.

<P>

To help but not cure portability problems to certain machines, the
.PN B16
and
.PN B32
macros have been defined so that they can become bitfield specifications 
on some machines.
For example, on a Cray,
these should be used for all 16-bit and 32-bit quantities, as discussed below.

<P>

Most protocol requests have a corresponding structure typedef in
<B><TT>X11/Xproto.h ,</TT></B>
which looks like:

<P>

<!.IN "xDoSomethingReq" "" "@DEF@">