














		   Big Requests Extension



			Version 2.0
		   X Consortium Standard
		 X Version 11, Release 6.4






		       Bob Scheifler
		     X Consortium, Inc.









Copyright (C) 1993, 1994 X Consortium

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documenta-
tion files (the ``Software''), to deal in the Software with-
out restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to
whom the Software is furnished to do so, subject to the fol-
lowing conditions:

The above copyright notice and this permission notice shall
be included in all copies or substantial portions of the
Software.

THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR-
POSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR-
TIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING












FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of the X Con-
sortium shall not be used in advertising or otherwise to
promote the sale, use or other dealings in this Software
without prior written authorization from the X Consortium.



























































1.  Overview

This extension enables the use of protocol requests that
exceed 262140 bytes in length.

The core protocol restricts the maximum length of a protocol
request to 262140 bytes, in that it uses a 16-bit length
field specifying the number of 4-byte units in the request.
This is a problem in the core protocol when joining large
numbers of lines (PolyLine) or arcs (PolyArc), since these
requests cannot be broken up into smaller requests without
disturbing the rendering of the join points.  It is also
much more of a problem for protocol extensions, such as the
PEX extension for 3D graphics and the XIE extension for
imaging, that need to send long data lists in output com-
mands.

This extension defines a mechanism for extending the length
field beyond 16 bits.  If the normal 16-bit length field of
the protocol request is zero, then an additional 32-bit
field containing the actual length (in 4-byte units) is
inserted into the request, immediately following the 16-bit
length field.

For example, a normal PolyLine encoding is:


PolyLine
  1  65 		 opcode
  1			 coordinate-mode
     0	       Origin
     1	       Previous
  2  3+n		 request length
  4  DRAWABLE		 drawable
  4  GCONTEXT		 gc
  4n LISTofPOINT	 points


An extended-length PolyLine encoding is:


PolyLine
  1  65 		 opcode
  1			 coordinate-mode
     0	       Origin
     1	       Previous
  2  0			 extended length flag
  4  4+n		 request length
  4  DRAWABLE		 drawable
  4  GCONTEXT		 gc
  4n LISTofPOINT	 points






			      1





		   Big Requests Extension


Extended-length protocol encodings, once enabled, can be
used on all protocol requests, including all extensions.

2.  Requests

BigReqEnable

   =>

     maximum-request-length: CARD32

     This request enables extended-length protocol requests
     for the requesting client.  It also returns the maximum
     length of a request, in 4-byte units, that can be used
     in extended-length protocol requests.  This value will
     always be greater than the maximum-request-length
     returned in the connection setup information.

3.  Events and Errors

No new events or errors are defined by this extension.

4.  Encoding

Please refer to the X11 Protocol Encoding document as this
document uses conventions established there.

The name of this extension is ``BIG-REQUESTS''.



BigReqEnable
  1  CARD8		 opcode
  1  0			 bigreq opcode
  2  1			 request length


 =>
  1  1			 Reply
  1			 unused
  2  CARD16		 sequence number
  4  0			 length
  4  CARD32		 maximum-request-length
  20			 unused


5.  C language binding

It is desirable for core Xlib, and other extensions, to use
this extension internally when necessary.  It is also desir-
able to make the use of this extension as transparent as
possible to the X client.  For example, if enabling of the
extension were delayed until the first time it was needed,
an application that used XNextRequest to determine the



			      2





		   Big Requests Extension


sequence number of a request would no longer get the correct
sequence number.  As such, XOpenDisplay will determine if
the extension is supported by the server and, if it is,
enable extended-length encodings.

The core Xlib functions XDrawLines, XDrawArcs, XFillPolygon,
XChangeProperty, XSetClipRectangles, and XSetRegion are
required to use extended-length encodings when necessary, if
supported by the server.  Use of extended-length encodings
in other core Xlib functions (XDrawPoints, XDrawRectangles,
XDrawSegments, XFillArcs, XFillRectangles, XPutImage) is
permitted but not required; an Xlib implementation may
choose to split the data across multiple smaller requests
instead.

To permit clients to know what the maximum-request-length
for extended-length encodings is, the following function is
added to Xlib:

long
XExtendedMaxRequestSize (display)
     Display   *display;

     Returns zero (0) if the specified display does not sup-
     port this extension, otherwise returns the maximum-
     request-length (in 4-byte units) supported by the
     server through the extended-length encoding.

6.  Acknowledgements

Clive Feather (IXI) originated the extended-length encoding
used in this extension proposal.

























			      3


