home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 45 / cda45.iso / Linux / XFree86-4.0 / doc / evi.TXT < prev    next >
Encoding:
Text File  |  2000-03-09  |  8.8 KB  |  463 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.        Extended Visual Information Extension
  19.  
  20.  
  21.  
  22.             Version 1.0
  23.           X Project Team Standard
  24.          X Version 11, Release 6.4
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.                Peter Daifuku
  32.            Silicon Graphics, Inc.
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42. Copyright (C) 1986-1997   The Open Group    All Rights
  43. Reserved
  44.  
  45. Permission is hereby granted, free of charge, to any person
  46. obtaining a copy of this software and associated documenta-
  47. tion files (the Software), to use the Software without
  48. restriction, including, without limitation, the rights to
  49. copy, modify, merge, publish, distribute and sublicense the
  50. Software, to make, have made, license and distribute deriva-
  51. tive works thereof, and to permit persons to whom the Soft-
  52. ware is furnished to do so, subject to the following condi-
  53. tions:
  54.  
  55. The above copyright notice and the following permission
  56. notice shall be included in all copies of the Software:
  57.  
  58. THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY
  59. KIND, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
  60. WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73. PURPOSE AND NON- INFRINGEMENT.    IN NO EVENT SHALL THE OPEN
  74. GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER USEABILITIY,
  75. WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  76. FROM, OUT OF, OR IN CONNNECTION WITH THE SOFTWARE OR THE USE
  77. OF OTHER DEALINGS IN THE SOFTWARE.
  78.  
  79. Except as contained in this notice, the name of The Open
  80. Group shall not be used in advertising or otherwise to pro-
  81. mote the use or other dealings in this Software without
  82. prior written authorization from The Open Group.
  83.  
  84. X Window System is a trademark of The Open Group.
  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.  Introduction
  140.  
  141. EVI (Extended Visual Information extension) allows a client
  142. to determine information about core X visuals beyond what
  143. the core protocol provides.
  144.  
  145. 2.  Goals
  146.  
  147. As the X Window System has evolved, it has become clear that
  148. the information returned by the core X protocol regarding
  149. Visuals is often insufficient for a client to determine
  150. which is the most appropriate visual for its needs. This
  151. extension allows clients to query the X server for addi-
  152. tional visual information, specifically as regards colormaps
  153. and framebuffer levels.
  154.  
  155. This extension is meant to address the needs of pure X
  156. clients only. It is specifically and purposefully not
  157. designed to address the needs of X extensions. Extensions
  158. that have an impact on visual information should provide
  159. their own mechanisms for delivering that information. For
  160. example, the Double Buffering Extension (DBE) provides its
  161. own mechanism for determining which visuals support double-
  162. buffering.
  163.  
  164. 3.  Requests
  165.  
  166. __
  167. |    GetVersion
  168.  
  169.      client_major_version: CARD8
  170.      client_minor_version: CARD8
  171.  
  172.   =>
  173.  
  174.      server_major_version: CARD8
  175.      server_minor_version: CARD8
  176. |__
  177.  
  178. If supplied, the client_major_version and client_minor_ver-
  179. sion indicate what version of the protocol the client wants
  180. the server to implement.  The server version numbers
  181. returned indicate the protocol this extension actually sup-
  182. ports. This might not equal the version sent by the client.
  183. An implementation can (but need not) support more than one
  184. version simultaneously. The server_major_version and the
  185. server_minor_version are a mechanism to support future revi-
  186. sions of the EVI protocol that may be necessary. In general,
  187. the major version would increment for incompatible changes,
  188. and the minor version would increment for small upward-com-
  189. patible changes. Servers that support the protocol defined
  190. in this document will return a server_major_version of one
  191. (1), and a server_minor_version of zero (0).
  192.  
  193.  
  194.  
  195.  
  196.                   1
  197.  
  198.  
  199.  
  200.  
  201.  
  202.       X11 Extended Visual Information extension
  203.  
  204. __
  205. |    GetVisualInfo
  206.  
  207.      visual_list: LISTofVISUALID
  208.  
  209.   =>
  210.  
  211.      per_visual_info: LISTofVISUALINFO
  212.  
  213. where:
  214.  
  215. VISUALINFO:   [core_visual_id: VISUALID
  216.            screen: CARD8
  217.            level: INT8
  218.            transparency_type: CARD8
  219.            unused: CARD8
  220.            transparency_value: CARD32
  221.            min_hw_colormaps: CARD8
  222.            max_hw_colormaps: CARD8
  223.            num_colormap_conflicts: CARD16
  224.            colormap_conflicts: LISTofVISUALID]
  225. |__
  226.  
  227.  
  228.  
  229.      - level is 0 for normal planes, > 0 for overlays, <
  230.      0 for underlays.
  231.      - transparency_type is 0 for none, 1 for transpar-
  232.      ent pixel, 2 for
  233.        transparent mask.
  234.      - transparency_value: value to get transparent
  235.      pixel if transparency
  236.      supported.
  237.      - min_hw_colormaps: minimum number of hardware col-
  238.      ormaps backing up the visual.
  239.      - max_hw_colormaps: maximum number of hardware col-
  240.      ormaps backing up the visual.
  241.      (architectures with static colormap alloca-
  242.      tion/reallocation would have min = max)
  243.      - num_colormap_conflicts: number of elements in
  244.      colormap_conflicts.
  245.      - colormap_conflicts: list of visuals that may con-
  246.      flict with this one. For
  247.      example, if a 12-bit colormap is overloaded to sup-
  248.      port 8-bit visuals, the
  249.      8-bit visuals would conflict with the 12-bit visu-
  250.      als.
  251.  
  252.  
  253. 4.  Events and Errors
  254.  
  255. No new events or errors are defined by this extension.
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.                   2
  263.  
  264.  
  265.  
  266.  
  267.  
  268.       X11 Extended Visual Information extension
  269.  
  270.  
  271. 5.  Changes to existing protocol.
  272.  
  273. None.
  274.  
  275.  
  276. 6.  Encoding
  277.  
  278. The name of this extension is "Extended-Visual-Information".
  279.  
  280. The conventions used here are the same as those for the core
  281. X11 Protocol Encoding.
  282.  
  283.  
  284. GetVersion
  285.   1  CARD8         opcode
  286.   1  0             EVI opcode
  287.   2  2             request length
  288.   2  CARD16         client_major_version
  289.   2  CARD16         client_minor_version
  290.  
  291.  
  292.  =>
  293.   1  1             reply
  294.   1             unused
  295.   2  CARD16         sequence number
  296.   4  0             length
  297.   2  CARD16         server_major_version
  298.   2  CARD16         server_minor_version
  299.   20             unused
  300.  
  301.  
  302.  
  303. GetVisualInfo
  304.   1  CARD8         opcode
  305.   1  1             EVI opcode
  306.   2  2+n         request length
  307.   4  CARD32         n_visual
  308.   4n CARD32         visual_ids
  309.  
  310.  
  311.  =>
  312.   1  1             reply
  313.   1             unused
  314.   2  CARD16         sequence number
  315.   4  n             length
  316.   4  CARD32         n_info
  317.   4  CARD32         n_conflicts
  318.   16             unused
  319.   16n           LISTofVISUALINFOitems
  320.  
  321.  
  322.  
  323.   VISUALINFO
  324.   4  VisualID         core_visual_id
  325.  
  326.  
  327.  
  328.                   3
  329.  
  330.  
  331.  
  332.  
  333.  
  334.       X11 Extended Visual Information extension
  335.  
  336.  
  337.   1  INT8         screen
  338.   1  INT8         level
  339.   1  CARD8         transparency_type
  340.   1  CARD8         unused
  341.   4  CARD32         transparency_value
  342.   1  CARD8         min_hw_colormaps
  343.   1  CARD8         max_hw_colormaps
  344.   2  CARD16         num_colormap_conflicts
  345.  
  346.  
  347.  
  348. 7.  C Language Binding
  349.  
  350. The C functions provide direct access to the protocol and
  351. add no additional semantics.  For complete details on the
  352. effects of these functions, refer to the appropriate proto-
  353. col request, which can be derived by deleting Xevi at the
  354. start of the function. All functions that have return type
  355. Status will return nonzero for success and zero for failure.
  356.  
  357. The include file for this extension is:
  358. <X11/extensions/XEVI.h>.
  359.  
  360. __
  361. |
  362. BoolXeviQueryVersion(
  363.     Display *display,
  364.     int *major_version_return,
  365.     int *minor_version_return)
  366.  
  367. |__
  368.  
  369.  
  370. display   Specifies the connection to the X server.
  371.  
  372. major_version_return
  373.       Returns the major version supported by the server.
  374.  
  375. minor_version_return
  376.       Returns the minor version supported by the server.
  377.  
  378. XeviQueryVersion sets major_version_return and minor_ver-
  379. sion_return to the major and minor EVI protocol version sup-
  380. ported by the server.  If the EVI library is compatible with
  381. the version returned by the server, it returns nonzero.  If
  382. dpy does not support the EVI extension, or if there was an
  383. error during communication with the server, or if the server
  384. and library protocol versions are incompatible, it returns
  385. zero.  No other Xevi functions may be called before this
  386. function. If a client violates this rule, the effects of all
  387. subsequent Xevi calls that it makes are undefined.
  388.  
  389. To get the extended information for any subset of visuals
  390. use XeviGetVisualInfo.
  391.  
  392.  
  393.  
  394.                   4
  395.  
  396.  
  397.  
  398.  
  399.  
  400.       X11 Extended Visual Information extension
  401.  
  402. __
  403. |
  404. intXeviGetVisualInfo(
  405.     Display *display,
  406.     VisualID *visual,
  407.     int n_visual,
  408.     ExtendedVisualInfo **evi_return,
  409.     int *n_info_return)
  410.  
  411. |__
  412.  
  413.  
  414. display   Specifies the connection to the X server.
  415.  
  416. visual      If NULL, then information for all visuals of all
  417.       screens is returned. Otherwise, a pointer to a
  418.       list of visuals for which extended visual informa-
  419.       tion is desired.
  420.  
  421. n_visual  If 0, then information for all visuals of all
  422.       screens is returned. Otherwise, the number of ele-
  423.       ments in the array visual.
  424.  
  425. evi_return
  426.       Returns a pointer to a list of ExtendedVisualInfo.
  427.       When done, the client should free the list using
  428.       XFree.
  429.  
  430. n_info_return
  431.       Returns the number of elements in the list of
  432.       ExtendedVisualInfo.
  433.  
  434. XeviGetVisualInfo returns a list of ExtendedVisualInfo
  435. structures that describe visual information beyond that sup-
  436. ported by the core protocol. This includes layer information
  437. relevant for systems supporting overlays and/or underlay
  438. planes, and information that allows applications better to
  439. determine the level of hardware support for multiple col-
  440. ormaps. XeviGetVisualInfo returns Success if successful, or
  441. an X error otherwise.
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.                   5
  461.  
  462.  
  463.