path: root/src/shm.xml

<?xml version="1.0" encoding="utf-8"?>
<!--
Copyright (C) 2001-2004 Bart Massey, Jamey Sharp, and Josh Triplett.
All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without 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 following 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 PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS 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 names of the authors or their
institutions 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 authors.
-->
<xcb header="shm" extension-xname="MIT-SHM" extension-name="Shm"
    major-version="1" minor-version="2">
  <import>xproto</import>

  <xidtype name="SEG" />

  <event name="Completion" number="0">
    <pad bytes="1" />
    <field type="DRAWABLE" name="drawable" />
    <field type="CARD16" name="minor_event" />
    <field type="BYTE" name="major_event" />
    <pad bytes="1" />
    <field type="SEG" name="shmseg" />
    <field type="CARD32" name="offset" />
    <doc>
      <brief>Report that an XCB_SHM_PUT_IMAGE request has completed</brief>
      <description><![CDATA[
This is generated by the X server to report that an XCB_SHM_PUT_IMAGE request
has been successfully processed.
      ]]></description>
      <field name="drawable"><![CDATA[
The drawable used in the XCB_SHM_PUT_IMAGE request.
      ]]></field>
      <field name="minor_event"><![CDATA[
The minor opcode used in the request.  Always XCB_SHM_PUT_IMAGE.
      ]]></field>
      <field name="major_event"><![CDATA[
The major opcode used in the request.  Always the opcode of the MIT-SHM
extension.
      ]]></field>
      <field name="shmseg"><![CDATA[
The shared memory segment used in the request.
      ]]></field>
      <field name="offset"><![CDATA[
The offset in the shared memory segment used in the request.
      ]]></field>
    </doc>
  </event>

  <errorcopy name="BadSeg" number="0" ref="Value" />

  <request name="QueryVersion" opcode="0">
    <reply>
      <field type="BOOL" name="shared_pixmaps" />
      <field type="CARD16" name="major_version" />
      <field type="CARD16" name="minor_version" />
      <field type="CARD16" name="uid" />
      <field type="CARD16" name="gid" />
      <field type="CARD8" name="pixmap_format" />
      <pad bytes="15" />
      <doc>
	<brief>The version of the MIT-SHM extension supported by the server</brief>
	<description><![CDATA[
This contains the version of the MIT-SHM extension supported by the server, as
well as the server’s UID and GID.  Clients MUST obtain the version supproted by
the server before making other requests from this extension.  To prevent local
privilege escalation and local information leak security vulnerabilities,
clients MUST ensure that System V shared memory objects they use with this
extension can only be accessed by the client and the X server.  If this is not
possible, the requests in this extension that use System V shared memory MUST
NOT be used.  The file descriptor-passing versions provide an alternative.
	]]></description>
	<field name="shared_pixmaps"><![CDATA[
True if the server supports shared pixmaps, otherwise false.
        ]]></field>
	<field name="major_version"><![CDATA[
The major version of the extension supported.
        ]]></field>
	<field name="minor_version"><![CDATA[
The minor version of the extension supported.
        ]]></field>
	<field name="uid">The UID of the server.</field>
	<field name="gid">The GID of the server.</field>
      </doc>
    </reply>
    <doc>
      <brief>Query the version of the MIT-SHM extension.</brief>
      <description><![CDATA[
This is used to determine the version of the MIT-SHM extension supported by the
X server.  Clients MUST NOT make other requests in this extension until a reply
to this requests indicates the X server supports them.
      ]]></description>
    </doc>
  </request>

  <request name="Attach" opcode="1">
    <field type="SEG" name="shmseg" />
    <field type="CARD32" name="shmid" />
    <field type="BOOL" name="read_only" />
    <pad bytes="3" />
    <doc>
      <brief>Attach a System V shared memory segment.</brief>
      <description><![CDATA[
Attach a System V shared memory segment to the server.  This will fail unless
the server has permission to map the segment.  The client may destroy the segment
as soon as it receives a XCB_SHM_COMPLETION event with the shmseg value in this
request and with the appropriate serial number.
      ]]></description>
      <field name="shmseg"><![CDATA[
A shared memory segment ID created with xcb_generate_id().
      ]]></field>
      <field name="shmid"><![CDATA[
The System V shared memory segment the server should map.
      ]]></field>
      <field name="read_only"><![CDATA[
True if the segment shall be mapped read only by the X11 server, otherwise false.
      ]]></field>
    </doc>
  </request>

  <request name="Detach" opcode="2">
    <field type="SEG" name="shmseg" />
    <doc>
      <brief>Destroys the specified shared memory segment.</brief>
      <description><![CDATA[
Destroys the specified shared memory segment.  This will never fail unless the
segment number is incorrect.
      ]]></description>
      <field name="shmseg">The segment to be destroyed.</field>
    </doc>
  </request>

  <request name="PutImage" opcode="3">
    <field type="DRAWABLE" name="drawable" />
    <field type="GCONTEXT" name="gc" />
    <field type="CARD16" name="total_width" />
    <field type="CARD16" name="total_height" />
    <field type="CARD16" name="src_x" />
    <field type="CARD16" name="src_y" />
    <field type="CARD16" name="src_width" />
    <field type="CARD16" name="src_height" />
    <field type="INT16" name="dst_x" />
    <field type="INT16" name="dst_y" />
    <field type="CARD8" name="depth" />
    <field type="CARD8" name="format" />
    <field type="BOOL" name="send_event" />
    <pad bytes="1" />
    <field type="SEG" name="shmseg" />
    <field type="CARD32" name="offset" />
    <doc>
      <brief>Copy data from the shared memory to the specified drawable.</brief>
      <description><![CDATA[
Copy data from the shared memory to the specified drawable.  The amount of bytes
written to the destination image is always equal to the number of bytes read
from the shared memory segment.
      ]]></description>
      <field name="drawable">The drawable to draw to.</field>
      <field name="gc">The graphics context to use.</field>
      <field name="total_width">The total width of the source image.</field>
      <field name="total_height">The total height of the source image.</field>
      <field name="src_x">The source X coordinate of the sub-image to copy.</field>
      <field name="src_y">The source Y coordinate of the sub-image to copy.</field>
      <field name="src_width"><![CDATA[
The width, in source image coordinates, of the data to copy from the source.
The X server will use this to determine the amount of data to copy.  The amount
of the destination image that is overwritten is determined automatically.
      ]]></field>
      <field name="src_height"><![CDATA[
The height, in source image coordinates, of the data to copy from the source.
The X server will use this to determine the amount of data to copy.  The amount
of the destination image that is overwritten is determined automatically.
      ]]></field>
      <field name="dst_x"><![CDATA[
The X coordinate on the destination drawable to copy to.
      ]]></field>
      <field name="dst_y"><![CDATA[
The Y coordinate on the destination drawable to copy to.
      ]]></field>
      <field name="depth">The depth to use.</field>
      <field name="format"><![CDATA[
The format of the image being drawn.  If it is XYBitmap, depth must be 1, or a
"BadMatch" error results.  The foreground pixel in the GC determines the source
for the one bits in the image, and the background pixel determines the source
for the zero bits.  For XYPixmap and ZPixmap, the depth must match the depth of
the drawable, or a "BadMatch" error results.
      ]]></field>
      <field name="send_event"><![CDATA[
True if the server should send an XCB_SHM_COMPLETION event when the blit
completes.
      ]]></field>
      <field name="offset">The offset that the source image starts at.</field>
    </doc>
  </request>

  <request name="GetImage" opcode="4">
    <field type="DRAWABLE" name="drawable" />
    <field type="INT16" name="x" />
    <field type="INT16" name="y" />
    <field type="CARD16" name="width" />
    <field type="CARD16" name="height" />
    <field type="CARD32" name="plane_mask" />
    <field type="CARD8" name="format" />
    <pad bytes="3" />
    <field type="SEG" name="shmseg" />
    <field type="CARD32" name="offset" />
    <reply>
      <field type="CARD8" name="depth" />
      <field type="VISUALID" name="visual" />
      <field type="CARD32" name="size" />
      <doc>
	<brief>Indicates the result of the copy.</brief>
	<description><![CDATA[
The result of the copy.
	]]></description>
	<field name="depth">The depth of the source drawable.</field>
	<field name="visual">The visual ID of the source drawable.</field>
	<field name="size">The number of bytes copied.</field>
      </doc>
    </reply>
    <doc>
      <brief>Copies data from the specified drawable to the shared memory segment.</brief>
      <description><![CDATA[
Copy data from the specified drawable to the shared memory segment.  The amount
of bytes written to the destination image is always equal to the number of bytes
read from the shared memory segment.
      ]]></description>
      <field name="drawable">The drawable to copy the image out of.</field>
      <field name="x">The X coordinate in the drawable to begin copying at.</field>
      <field name="y">The Y coordinate in the drawable to begin copying at.</field>
      <field name="width">The width of the image to copy.</field>
      <field name="height">The height of the image to copy.</field>
      <field name="plane_mask">A mask that determines which planes are used.</field>
      <field name="format">The format to use for the copy (???).</field>
      <field name="shmseg">The destination shared memory segment.</field>
      <field name="offset">The offset in the shared memory segment to copy data to.</field>
    </doc>
  </request>

  <request name="CreatePixmap" opcode="5">
    <field type="PIXMAP" name="pid" />
    <field type="DRAWABLE" name="drawable" />
    <field type="CARD16" name="width" />
    <field type="CARD16" name="height" />
    <field type="CARD8" name="depth" />
    <pad bytes="3" />
    <field type="SEG" name="shmseg" />
    <field type="CARD32" name="offset" />
    <doc>
      <brief>Create a pixmap backed by shared memory.</brief>
      <description>
Create a pixmap backed by shared memory.  Writes to the shared memory will be
reflected in the contents of the pixmap, and writes to the pixmap will be
reflected in the contents of the shared memory.
      </description>
      <field name="pid">A pixmap ID created with xcb_generate_id().</field>
      <field name="drawable">The drawable to create the pixmap in.</field>
      <field name="width"><![CDATA[
The width of the pixmap to create.  Must be nonzero, or a Value error results.
      ]]></field>
      <field name="height"><![CDATA[
The height of the pixmap to create.  Must be nonzero, or a Value error results.
      ]]></field>
      <field name="depth"><![CDATA[
The depth of the pixmap to create.  Must be nonzero, or a Value error results.
      ]]></field>
      <field name="shmseg"><![CDATA[
The shared memory segment to use to create the pixmap.
      ]]></field>
      <field name="offset"><![CDATA[
The offset in the segment to create the pixmap at.
      ]]></field>
    </doc>
  </request>

  <request name="AttachFd" opcode="6">
    <field type="SEG" name="shmseg" />
    <fd name="shm_fd" />
    <field type="BOOL" name="read_only" />
    <pad bytes="3" />
    <doc>
      <brief>Create a shared memory segment</brief>
      <description><![CDATA[
Create a shared memory segment.  The file descriptor will be mapped at offset
zero, and the size will be obtained using fstat().  A zero size will result in a
Value error.
      ]]></description>
      <field name="shmseg"><![CDATA[
A shared memory segment ID created with xcb_generate_id().
      ]]></field>
      <field name="shm_fd">The file descriptor the server should mmap().</field>
      <field name="read_only"><![CDATA[
True if the segment shall be mapped read only by the X11 server, otherwise false.
      ]]></field>
    </doc>
  </request>

  <request name="CreateSegment" opcode="7">
    <field type="SEG" name="shmseg" />
    <field type="CARD32" name="size" />
    <field type="BOOL" name="read_only" />
    <pad bytes="3" />
    <reply>
      <field type="CARD8" name="nfd" />
      <fd name="shm_fd" />
      <pad bytes="24" />
      <doc>
	<brief>The returned file descriptor.</brief>
	<description><![CDATA[
The file descriptor returned by the server.  The client may call mmap() on it to
map the memory allocated by the server.
	]]></description>
	<field name="nfd"><![CDATA[
The number of file descriptors sent by the server.  Will always be 1.
	]]></field>
      </doc>
    </reply>
    <doc>
      <brief>Asks the server to allocate a shared memory segment.</brief>
      <description><![CDATA[
Asks the server to allocate a shared memory segment.  The server’s reply will
include a file descriptor for the client to pass to mmap().
      ]]></description>
      <field name="shmseg"><![CDATA[
A shared memory segment ID created with xcb_generate_id().
      ]]></field>
      <field name="size">The size of the segment to create.</field>
      <field name="read_only"><![CDATA[
True if the server should map the segment read-only; otherwise false.
      ]]></field>
    </doc>
  </request>
</xcb>