home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 45 / cda45.iso / Linux / XFree86-4.0 / doc / bigreq.TXT next >
Encoding:
Text File  |  2000-03-09  |  5.7 KB  |  331 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.            Big Requests Extension
  17.  
  18.  
  19.  
  20.             Version 2.0
  21.            X Consortium Standard
  22.          X Version 11, Release 6.4
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.                Bob Scheifler
  30.              X Consortium, Inc.
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40. Copyright (C) 1993, 1994 X Consortium
  41.  
  42. Permission is hereby granted, free of charge, to any person
  43. obtaining a copy of this software and associated documenta-
  44. tion files (the ``Software''), to deal in the Software with-
  45. out restriction, including without limitation the rights to
  46. use, copy, modify, merge, publish, distribute, sublicense,
  47. and/or sell copies of the Software, and to permit persons to
  48. whom the Software is furnished to do so, subject to the fol-
  49. lowing conditions:
  50.  
  51. The above copyright notice and this permission notice shall
  52. be included in all copies or substantial portions of the
  53. Software.
  54.  
  55. THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY
  56. KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  57. WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR-
  58. POSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR-
  59. TIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  60. WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73. FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
  74. OR OTHER DEALINGS IN THE SOFTWARE.
  75.  
  76. Except as contained in this notice, the name of the X Con-
  77. sortium shall not be used in advertising or otherwise to
  78. promote the sale, use or other dealings in this Software
  79. without prior written authorization from the X Consortium.
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. 1.  Overview
  140.  
  141. This extension enables the use of protocol requests that
  142. exceed 262140 bytes in length.
  143.  
  144. The core protocol restricts the maximum length of a protocol
  145. request to 262140 bytes, in that it uses a 16-bit length
  146. field specifying the number of 4-byte units in the request.
  147. This is a problem in the core protocol when joining large
  148. numbers of lines (PolyLine) or arcs (PolyArc), since these
  149. requests cannot be broken up into smaller requests without
  150. disturbing the rendering of the join points.  It is also
  151. much more of a problem for protocol extensions, such as the
  152. PEX extension for 3D graphics and the XIE extension for
  153. imaging, that need to send long data lists in output com-
  154. mands.
  155.  
  156. This extension defines a mechanism for extending the length
  157. field beyond 16 bits.  If the normal 16-bit length field of
  158. the protocol request is zero, then an additional 32-bit
  159. field containing the actual length (in 4-byte units) is
  160. inserted into the request, immediately following the 16-bit
  161. length field.
  162.  
  163. For example, a normal PolyLine encoding is:
  164.  
  165.  
  166. PolyLine
  167.   1  65          opcode
  168.   1             coordinate-mode
  169.      0           Origin
  170.      1           Previous
  171.   2  3+n         request length
  172.   4  DRAWABLE         drawable
  173.   4  GCONTEXT         gc
  174.   4n LISTofPOINT     points
  175.  
  176.  
  177. An extended-length PolyLine encoding is:
  178.  
  179.  
  180. PolyLine
  181.   1  65          opcode
  182.   1             coordinate-mode
  183.      0           Origin
  184.      1           Previous
  185.   2  0             extended length flag
  186.   4  4+n         request length
  187.   4  DRAWABLE         drawable
  188.   4  GCONTEXT         gc
  189.   4n LISTofPOINT     points
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                   1
  197.  
  198.  
  199.  
  200.  
  201.  
  202.            Big Requests Extension
  203.  
  204.  
  205. Extended-length protocol encodings, once enabled, can be
  206. used on all protocol requests, including all extensions.
  207.  
  208. 2.  Requests
  209.  
  210. BigReqEnable
  211.  
  212.    =>
  213.  
  214.      maximum-request-length: CARD32
  215.  
  216.      This request enables extended-length protocol requests
  217.      for the requesting client.  It also returns the maximum
  218.      length of a request, in 4-byte units, that can be used
  219.      in extended-length protocol requests.  This value will
  220.      always be greater than the maximum-request-length
  221.      returned in the connection setup information.
  222.  
  223. 3.  Events and Errors
  224.  
  225. No new events or errors are defined by this extension.
  226.  
  227. 4.  Encoding
  228.  
  229. Please refer to the X11 Protocol Encoding document as this
  230. document uses conventions established there.
  231.  
  232. The name of this extension is ``BIG-REQUESTS''.
  233.  
  234.  
  235.  
  236. BigReqEnable
  237.   1  CARD8         opcode
  238.   1  0             bigreq opcode
  239.   2  1             request length
  240.  
  241.  
  242.  =>
  243.   1  1             Reply
  244.   1             unused
  245.   2  CARD16         sequence number
  246.   4  0             length
  247.   4  CARD32         maximum-request-length
  248.   20             unused
  249.  
  250.  
  251. 5.  C language binding
  252.  
  253. It is desirable for core Xlib, and other extensions, to use
  254. this extension internally when necessary.  It is also desir-
  255. able to make the use of this extension as transparent as
  256. possible to the X client.  For example, if enabling of the
  257. extension were delayed until the first time it was needed,
  258. an application that used XNextRequest to determine the
  259.  
  260.  
  261.  
  262.                   2
  263.  
  264.  
  265.  
  266.  
  267.  
  268.            Big Requests Extension
  269.  
  270.  
  271. sequence number of a request would no longer get the correct
  272. sequence number.  As such, XOpenDisplay will determine if
  273. the extension is supported by the server and, if it is,
  274. enable extended-length encodings.
  275.  
  276. The core Xlib functions XDrawLines, XDrawArcs, XFillPolygon,
  277. XChangeProperty, XSetClipRectangles, and XSetRegion are
  278. required to use extended-length encodings when necessary, if
  279. supported by the server.  Use of extended-length encodings
  280. in other core Xlib functions (XDrawPoints, XDrawRectangles,
  281. XDrawSegments, XFillArcs, XFillRectangles, XPutImage) is
  282. permitted but not required; an Xlib implementation may
  283. choose to split the data across multiple smaller requests
  284. instead.
  285.  
  286. To permit clients to know what the maximum-request-length
  287. for extended-length encodings is, the following function is
  288. added to Xlib:
  289.  
  290. long
  291. XExtendedMaxRequestSize (display)
  292.      Display   *display;
  293.  
  294.      Returns zero (0) if the specified display does not sup-
  295.      port this extension, otherwise returns the maximum-
  296.      request-length (in 4-byte units) supported by the
  297.      server through the extended-length encoding.
  298.  
  299. 6.  Acknowledgements
  300.  
  301. Clive Feather (IXI) originated the extended-length encoding
  302. used in this extension proposal.
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                   3
  329.  
  330.  
  331.