[Xcb] [tutorial] add of an extension section

[Vincent Torri]

Hey,

I have added a small section about the extensions. The diff is attached.

could you please tell me what to fix/add. I wonder, for example, if it is
a good Idea to add a small description of all the extensions (in the list
that is in the section) or if it is useless.

I would also like to know if the example code (shm one) is good enough.

Vincent
-------------- next part --------------
--- xcb_doc_tutorial_index.html	2006-03-17 12:07:37.000000000 +0000
+++ tutorial_new.html	2006-03-17 12:08:31.000000000 +0000
@@ -153,6 +153,7 @@
             <li><a class="subsection" href="#DisplayCells">DisplayCells / CellsOfScreen</a>
           </ol>
       </ol>
+    <li><a class="subsection" href="#extensions">X extensions</a>
   </ol>
   </div>
   <div class="section">
@@ -3769,6 +3770,122 @@
 </pre>
         </ol>
       </ol>
+      <li class="title"><a name="extensions">X extensions</a>
+      <p>
+      The X extensions allow to use extra features like compositing
+      images, use of shared memory, multiple screens,... The
+      current avalaible extensions in XCB (when this section has
+      been written) are
+      </p>
+      <ol>
+        <li>bigreq
+        <li>composite
+        <li>damage
+        <li>dpms
+        <li>glx
+        <li>randr
+        <li>record
+        <li>render
+        <li>res
+        <li>screensaver
+        <li>shape
+        <li>shm
+        <li>sync
+        <li>xc_misc
+        <li>xevie
+        <li>xf86dri
+        <li>xfixies
+        <li>xprint
+        <li>xv
+        <li>xvmc
+      </ol>
+      <p>
+      To initialize an extension, you need to use that function:
+      </p>
+      <pre class="code">
+const XCBQueryExtensionRep *XCBGetExtensionData(XCBConnection *c, XCBExtension *ext);
+</pre>
+      <p>
+      It require a connection and a variable used as a key for the
+      extension (<span class="code">XCBExtension *ext</span>. This
+      key is found in the header file of the extension. The returned
+      value is a reply that is used with all the extension
+      functions.
+      </p>
+      <p>
+      <b>One important note should be made</b>: the returned reply
+      must not be freed (unlike most of the other replies).
+      </p>
+      <p>
+      If you use several extensions, you might want to use the function
+      </p>
+      <pre class="code">
+void XCBPrefetchExtensionData(XCBConnection *c, XCBExtension *ext);
+</pre>
+      <p>
+      This function allows a "prefetch" of extension data into the
+      extension cache, and speed up the load of the extensions. You
+      have to call this function for all the extensions, then you have
+      to call <span class="code">XCBGetExtensionData</span> for all the
+      extensions too.
+      </p>
+      <p>
+      Here is an example with the shm extension:
+      </p>
+      <pre class="code">
+#include &lt;sys/ipc.h&gt;
+#include &lt;sys/shm.h&gt;
+
+#include &lt;X11/XCB/xcb.h&gt;
+#include &lt;X11/XCB/shm.h&gt;
+#include &lt;X11/XCB/xcb_image.h&gt;
+
+int can_do_shm (XCBConnection *c, XCBImage **image)
+{
+  const XCBQueryExtensionRep *rep;
+  int                         res = 0;
+  CARD8                       format;
+
+  if (!image) return res;
+
+  rep = XCBGetExtensionData (c, );
+  if (!rep) return res;
+
+  if (rep-&gt;shared_pixmaps &&
+      (rep-&gt;major_version &gt; 1 || rep-&gt;minor_version &gt; 0))
+    format = rep-&gt;pixmap_format;
+  else
+    format = 0;
+
+  *image = XCBImageSHMCreate (c, depth, format, NULL, width, height);
+  if (!*image) return res;
+
+  shminfo.shmid = shmget (IPC_PRIVATE,
+                          *image-&gt;bytes_per_line * *image-&gt;height,
+                          IPC_CREAT | 0777);
+  if (shminfo.shmid == -1) return res;
+ 
+  shminfo.shmaddr = shmat (shminfo.shmid, 0, 0);
+  if (!shminfo.shmaddr) return res;
+
+  *image-&gt;data = shminfo.shmaddr;
+
+  shminfo.shmseg = XCBShmSEGNew (c);
+  XCBShmAttach (c, shminfo.shmseg, shminfo.shmid, 0);
+  shmctl_status = shmctl(shminfo.shmid, IPC_RMID, 0);
+  if (shmctl_status == -1) return res;
+
+  if (*image)
+    res = 1;
+  else {
+    shmdt (shminfo.shmaddr);
+    shmctl (shminfo.shmid, IPC_RMID, 0);
+    *image = NULL;
+  }
+
+  return res;
+}
+</pre>
     </ol>
   </div>
 </body>