[Xcb-commit] MixingCalls.mdwn XCBConnectionOfDisplay.mdwn XcbPortingCreateCursor.mdwn XcbPorting.mdwn XCBToDo.mdwn XCLATOM.mdwn XCLCOLORMAP.mdwn
Alan Coopersmith
alanc at freedesktop.org
Mon Oct 4 08:04:13 PDT 2010
MixingCalls.mdwn | 78 ++++++++++++++++++++++++++++++++++++++++++--
XCBConnectionOfDisplay.mdwn | 76 ------------------------------------------
XCBToDo.mdwn | 4 +-
XCLATOM.mdwn | 29 ----------------
XCLCOLORMAP.mdwn | 67 -------------------------------------
XcbPorting.mdwn | 41 ++++++-----------------
XcbPortingCreateCursor.mdwn | 47 ++++++++++++--------------
7 files changed, 114 insertions(+), 228 deletions(-)
New commits:
commit 1c8f85a5893946288fb06aa20db19fd6442a520e
Author: Alan Coopersmith <alan.coopersmith at oracle.com>
Date: Sun Oct 3 13:53:50 2010 -0700
Update old XCL references/examples to XlibXcb
Signed-off-by: Alan Coopersmith <alan.coopersmith at oracle.com>
Reviewed-by: Josh Triplett <josh at joshtriplett.org>
diff --git a/MixingCalls.mdwn b/MixingCalls.mdwn
index 0e3875d..d9b8540 100644
--- a/MixingCalls.mdwn
+++ b/MixingCalls.mdwn
@@ -1,9 +1,83 @@
-### Xlib/XCB: Mixing Xlib and XCB Calls
+## Xlib/XCB: Mixing Xlib and XCB Calls
-One of the nice features of Xlib/XCB is that it supports a gradual transition from Xlib to XCB, by permitting mixing Xlib and XCB calls in programs. Of course, you need to be running a new enough version of Xlib to get Xlib/XCB, and not have turned the XCB support off.
+One of the nice features of Xlib/XCB is that it supports a gradual transition from Xlib to XCB, by permitting mixing Xlib and XCB calls in programs. Of course, you need to be running a new enough version of Xlib to get Xlib/XCB, and not have turned the XCB support off. This API is available in libX11 1.2.0 and later, and guaranteed to be present in libX11 1.4.0 and later. (It was possible to disable at build time in libX11 1.2.x and 1.3.x.)
To mix calls, you'll need both an XCB connection and Xlib display. Get this by using XOpenDisplay() to get an Xlib Display, then calling XGetXCBConnection() (from "Xlib-xcb.h") on the Xlib Display to get an XCBConnection.
You can now mix calls to XCB and Xlib. The datatypes of the two systems are somewhat interoperable; for example, you can use an Xlib Window anywhere an xcb\_window\_t is required. In general, XID types like Window (X.h:typedef XID) are synonymous with their XCB equivalents.
Only one of Xlib and XCB can manage the event queue. By default, Xlib does. To change this, call XSetEventQueueOwner() (from "Xlib-xcb.h") before making other calls.
+
+## Example
+
+ #include <X11/Xlib-xcb.h>
+ #include <stdlib.h>
+ #include <stdio.h>
+ #include <unistd.h>
+
+ int main()
+ {
+ Display *dpy = XOpenDisplay(NULL);
+ xcb_connection_t *c;
+ const xcb_setup_t *setup;
+ xcb_screen_t *screen;
+ xcb_window_t window;
+
+ const int depth = 0, x = 0, y = 0, width = 150, height = 150,
+ border_width = 1;
+
+ if (! dpy)
+ {
+ fprintf(stderr, "Could not open display.\n");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Now that we have an open Display object, cast it to an
+ * XCBConnection object so it can be used with native XCB
+ * functions.
+ */
+ c = XGetXCBConnection(dpy);
+
+ if (! c)
+ {
+ fprintf(stderr, "Could not cast the Display object to an "
+ "XCBConnection object.\n");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Do something meaningful, fun, and interesting with the new
+ * XCBConnection object.
+ */
+ setup = xcb_get_setup (c);
+ screen = (xcb_setup_roots_iterator (setup)).data;
+ window = xcb_generate_id (c);
+
+ xcb_create_window (c, depth, window, screen->root, x, y, width, height,
+ border_width, InputOutput, screen->root_visual, 0, NULL);
+ xcb_map_window (c, window);
+ xcb_flush (c);
+
+ pause();
+
+ return EXIT_SUCCESS;
+ }
+
+Some salient points in this example include the following:
+
+- The only header that is included is `Xlib-xcb.h`. Neither of the headers `Xlib.h` nor `xcb.h` are included, yet Xlib and XCB functions are used. This is because `Xlib-xcb.h` includes `xcb.h` and `Xlib.h`.
+- The standard Xlib function `XOpenDisplay` is used to create a Display object.
+- The `Display` object is cast to an `xcb_connection_t` object using `XGetXCBConnection`.
+- After the cast, the connection is passed to various other XCB functions.
+
+Though this example is contrived, `XGetXCBConnection` is an essential part of the porting process. For example, say you have some function that takes a `Display` object. You can leave the prototype unchanged, in the body of the function cast it to an `xcb_connection_t`, and port only that function. The rest of the code can remain unchanged. In this way, the process of converting the application to use XCB is staggered as necessary, time, knowledge, and knowledge permit.
+
+## Casting the Other Way
+
+How do you get a `Display` object given an `xcb_connection_t` object? You can't. So, if you find yourself needing to cast an `xcb_connection_t` to a `Display`, stop, rethink, and find another way to structure your code to work without the cast.
+
+## See Also
+
+- [[XcbPorting]]
+- [[XcbApi]]
+- [Mailing list posts](http://www.google.com/search?q=site%3Alists.freedesktop.org+XGetXCBConnection) related to XGetXCBConnection.
+
diff --git a/XCBConnectionOfDisplay.mdwn b/XCBConnectionOfDisplay.mdwn
index 9ba8c3f..59d5835 100644
--- a/XCBConnectionOfDisplay.mdwn
+++ b/XCBConnectionOfDisplay.mdwn
@@ -1,76 +1,2 @@
-The `XCBConnectionOfDisplay` function casts an Xlib `Display` object to an `XCBConnection` object.
+The `XCBConnectionOfDisplay` function was replaced by the `XGetXCBConnection` API described in [[MixingCalls]].
-# Function Prototype
-
- XCBConnection *XCBConnectionOfDisplay(Display *dpy);
-
-# Example
-
- #include <X11/xcl.h>
- #include <stdlib.h>
- #include <stdio.h>
-
- int main()
- {
- Display *dpy = XOpenDisplay(NULL);
- XCBConnection *c;
- XCBSCREEN *screen;
- XCBWINDOW window;
-
- const int depth = 0, x = 0, y = 0, width = 150, height = 150,
- border_width = 1;
-
- if (! dpy)
- {
- fprintf(stderr, "Could not open display.\n");
- exit(EXIT_FAILURE);
- }
-
- /* Now that we have an open Display object, cast it to an
- * XCBConnection object so it can be used with native XCB
- * functions.
- */
- c = XCBConnectionOfDisplay(dpy);
-
- if (! c)
- {
- fprintf(stderr, "Could not cast the Display object to an "
- "XCBConnection object.\n");
- exit(EXIT_FAILURE);
- }
-
- /* Do something meaningful, fun, and interesting with the new
- * XCBConnection object.
- */
- window = XCBWINDOWNew(c);
- screen = XCBConnSetupSuccessRepRootsIter(XCBGetSetup(c)).data;
-
- XCBCreateWindow(c, depth, window, screen->root, x, y, width, height,
- border_width, InputOutput, screen->root_visual, 0, NULL);
- XCBMapWindow(c, window);
- XCBSync(c, 0);
-
- for (;;) /* Loop forever */ ;
-
- return EXIT_SUCCESS;
- }
-
-Some salient points in this example include the following:
-
-- The only header that is included is `xcl.h`. The headers `Xlib.h` nor `xcb.h` are included, yet Xlib and XCB functions are used. This is because `xcl.h` includes `xcb.h` and `Xlib.h`.
-- The standard Xlib function `XOpenDisplay` is used to create a Display object.
-- The `Display` object is cast to an `XCBConnection` object using `XCBConnectionOfDisplay`.
-- After the cast, the connection is passed to various other XCB functions.
-
-Though this example is contrived, `XCBConnectionOfDisplay` is an essential part of the porting process. For example, say you have some function that takes a `Display` object. You can leave the prototype unchanged, in the body of the function cast it to an `XCBConnection`, and port only that function. The rest of the code can remain unchanged. In this way, the process of converting the application to use XCB is staggered as necessary, time, knowledge, and knowledge permit.
-
-# Casting the Other Way
-
-How do you get a `Display` object given an `XCBConnection` object? You can't. So, if you find yourself needing to cast an `XCBConnection` to a `Display`, stop, rethink, and find another way to structure your code to work without the cast.
-
-# See Also
-
-- [[XcbPorting]]
-- [[XCBConnection|XcbApi]]
-- [[XCBSync|XcbApi]]
-- [Mailing list posts](http://www.google.com/search?q=site%3Alists.freedesktop.org+XCBConnectionOfDisplay) related to XCBConnectionOfDisplay.
diff --git a/XCBToDo.mdwn b/XCBToDo.mdwn
index 361f2ba..aa22d22 100644
--- a/XCBToDo.mdwn
+++ b/XCBToDo.mdwn
@@ -10,10 +10,10 @@ Don't forget to ask for help on the mailing list if you get stuck.
# Getting started
-If you're not sure where to start in learning about XCB and XCL, you might try these steps. Documenting your progress for others coming this way would be a great contribution too.
+If you're not sure where to start in learning about XCB, you might try these steps. Documenting your progress for others coming this way would be a great contribution too.
- Check out and build the [Xlib](http://freedesktop.org/wiki/Software/X11) source.
-- Check out and build the [[XCB/XCL|index]] sources.
+- Check out and build the [[XCB|index]] sources.
- Understand and document the DPMS extension implementation. Re-implementing it straight from the original extension documentation would be a good way to accomplish this. The [[XmlXcb]] documentation should be sufficient to do this.
With that experience, the easiest thing you can do to help our efforts is to implement some extension that's currently unsupported by XCB.
diff --git a/XCLATOM.mdwn b/XCLATOM.mdwn
deleted file mode 100644
index c4ae8db..0000000
--- a/XCLATOM.mdwn
+++ /dev/null
@@ -1,29 +0,0 @@
-The `XCLATOM` function casts an `Atom` object to an `XCBATOM` object.
-
-# Function Prototype
-
- static inline XCBATOM XCLATOM(Atom src);
-
-# Example
-
- #include <X11/xcl.h>
- #include <stdlib.h>
- #include <assert.h>
-
- int main(int argc, char* argv[])
- {
- Atom src, result;
- XCBATOM dest = XCLATOM(src);
-
- /* To cast back to an `Atom' from an `XCBATOM', just use the XCB
- type's `xid' field. */
- result = dest.xid;
- assert(result == src);
-
- return EXIT_SUCCESS;
- }
-
-# See Also
-
-- [[XcbPorting]]
-- [Mailing list posts](http://www.google.com/search?q=site%3Alists.freedesktop.org+xclatom) related to XCLATOM.
diff --git a/XCLCOLORMAP.mdwn b/XCLCOLORMAP.mdwn
deleted file mode 100644
index d3f48ad..0000000
--- a/XCLCOLORMAP.mdwn
+++ /dev/null
@@ -1,67 +0,0 @@
-The `XCLCOLORMAP` functions casts a `Colormap` object to an `XCBCOLORMAP`.
-
-# Function Prototype
-
- static inline XCBCOLORMAP XCLCOLORMAP(Colormap src);
-
-# Example
-
- #include <X11/xcl.h>
- #include <stdlib.h>
- #include <stdio.h>
- #include <assert.h>
-
- static const int red = 0xFFFF, green = 0x0, blue = 0x0; /* Test values. */
-
- int main(void)
- {
- Display *dpy = XOpenDisplay(NULL);
- int screen_num = DefaultScreen(dpy);
- XColor color;
-
- superduperColorAllocator(dpy, screen_num, &color);
-
- assert(color.red == red);
- assert(color.green == green);
- assert(color.blue == blue);
-
- printf("Closest supported color value = 0x%X\n"
- "Actual colors used:\n"
- " red = 0x%X\n"
- " green = 0x%X\n"
- " blue = 0x%X\n", color.pixel, color.red, color.green, color.blue);
-
- return EXIT_SUCCESS;
- }
-
- Status superduperColorAllocator(Display* dpy, int screen_num, XColor *color)
- {
- Status result;
- XCBConnection *c = XCBConnectionOfDisplay(dpy);
- XCBCOLORMAP cmap = XCLCOLORMAP(DefaultColormap(dpy, screen_num));
- XCBAllocColorCookie cookie = XCBAllocColor(c, cmap, red, green, blue);
- XCBAllocColorRep *color_rep = XCBAllocColorReply(c, cookie, 0);
-
- if (! color_rep)
- result = 0;
- else
- {
- result = 1;
-
- color->pixel = color_rep->pixel;
- color->red = color_rep->red;
- color->blue = color_rep->blue;
- color->green = color_rep->green;
-
- free(color_rep);
- }
-
- return result;
- }
-
-In this example, imagine the interface of `superduperColorAllocator` has been publicly released and can't be changed; however, since the XCL is binary compatible with Xlib, the internal implementation of this function can be ported to take advantage of XCB. Specifically, in this example, the result of `DefaultColormap` is cast from a `Colormap` to an `XCBCOLORMAP` using `XCLCOLORMAP`. After which, it allocates a new `XCBAllocColorRep` object using `XCBAllocColor` and `XCBAllocColorReply` in a way that is analogous to `XAllocColor`. This newly created `XCBAllocColorRep` object's data is then copied into the caller's `XColor` structure. Finally, like the Xlib's `XAllocColor` function, the new color must be freed because it is no longer needed. After returning to the client, the results are verified and printed.
-
-# See Also
-
-- [[XcbPorting]]
-- [Mailing list posts](http://www.google.com/search?q=site%3Alists.freedesktop.org+XCLCOLORMAP) related to XCLCOLORMAP.
diff --git a/XcbPorting.mdwn b/XcbPorting.mdwn
index c3e731f..2fd8d37 100644
--- a/XcbPorting.mdwn
+++ b/XcbPorting.mdwn
@@ -1,42 +1,25 @@
-This page provides information and resources about porting applications from Xlib to XCB. It discusses the Xlib Compatibility Layer, provides various examples, conglomerates past mailing list posts related to poring, and hopefully will become an important reference for developers who wish to utilize the power and simplicity of XCB by reprogramming their applications to it.
+This page provides information and resources about porting applications from Xlib to XCB. It discusses the Xlib compatibility layer, provides various examples, conglomerates past mailing list posts related to poring, and hopefully will become an important reference for developers who wish to utilize the power and simplicity of XCB by reprogramming their applications to it.
# The Big Picture
-The recommended way to port an application from Xlib to XCB is to begin by converting the internal interfaces and structures from Xlib types to XCB. For libraries, a two step strategy is recommended. First, begin by porting the public interfaces to use XCB types. Then, provide a thin wrapper library that provides the old interface, so legacy applications can use the newly ported library without any alterations. To help with this process, a small abstraction layer called the XCL is available.
+The recommended way to port an application from Xlib to XCB is to begin by converting the internal interfaces and structures from Xlib types to XCB. For libraries, a two step strategy is recommended. First, begin by porting the public interfaces to use XCB types. Then, provide a thin wrapper library that provides the old interface, so legacy applications can use the newly ported library without any alterations.
-# The XCL
+# Xlib compatibility
-As mentioned [[elsewhere|XlibXcb]], the Xlib Compatibility Layer or XCL for short emulates Xlib but is built on XCB. This allows current applications built with Xlib to begin leveraging XCB's capabilities slowly over time; the entire program doesn't have to be ported immediately. Rather, it can continue to use various Xlib functions, data types, etc. while also using XCB's facilities, structures, and other resources simultaneously.
+As mentioned [[elsewhere|XlibXcb]], the Xlib compatibility layer is found in versions of Xlib built with support for XCB. This allows current applications built with Xlib to begin leveraging XCB's capabilities slowly over time; the entire program doesn't have to be ported immediately. Rather, it can continue to use various Xlib functions, data types, etc. while also using XCB's facilities, structures, and other resources simultaneously.
-Before beginning to use the XCL, it is highly recommended that you read [[JameySharp]] and [[BartMassey]]'s paper _[XCL: An Xlib Compatibility Layer for XCB](http://www.usenix.org/events/usenix02/tech/freenix/sharp.html)_. (There are also other formats and sources where this document can be found; see the [[Publications]] page.)
+This replaced the previous XCL library, which is described in the [[History]] section.
-## Using the XCL
-
-To begin using the XCL just include the header file `xcl.h` rather than `Xlib.h`. After doing so, you will be able to a large majority of Xlib functions and types; XCB's functions, macros, data types, etc; and some convenient macros for converting Xlib types to XCB types.
-
-### Functions and Macros Available in xcl.h
-
-The following functions provided by `xcl.h` can be used to cast from Xlib types to XCB types:
-
-[[XCBConnectionOfDisplay]], [[XCLATOM]], [[XCLBUTTON]], [[XCLCOLORMAP]], [[XCLCURSOR]], [[XCLDRAWABLE]], [[XCLFONT]], [[XCLFONTABLE]], [[XCLGCONTEXT]], [[XCLKEYCODE]], [[XCLKEYSYM]], [[XCLPIXMAP]], [[XCLTIMESTAMP]], [[XCLVISUALID]], [[XCLWINDOW]], [[XSetEventQueueOwner]]
-
-Follow the function's link to see its prototype and an example of how to use it.
+Once you use the Xlib functions to open a Display, you can then obtain a
+matching `xcb_connection_t` and begin [[mixing calls|MixingCalls]] using
+whichever API is most convenient.
# Past Posts
-<dl>
- <dd>
- <p><a href="http://lists.freedesktop.org/pipermail/xcb/2005-June/000825.html">XNextEvent</a> How to write the usual Xlib non-blocking event loop in XCB.</p>
- </dd>
-</dl>
+- [XNextEvent: How to write the usual Xlib non-blocking event loop in XCB](http://lists.freedesktop.org/pipermail/xcb/2005-June/000825.html).
# Examples
-<dl>
- <dd>
- <p>[[XcbPortingCreateCursor]] Creating a cursor from a standard font.</p>
- </dd>
- <dd>
- <p><a href="http://xcb.freedesktop.org/tutorial/events/">The Events section of the XCB Tutorial</a> explains how to set up the event loop in XCB and compares the process with Xlib's <tt>XNextEvent</tt> and <tt>XPending</tt>.</p>
- </dd>
-</dl>
+- [[MixingCalls]] Using Xlib and xcb calls in the same program.
+- [[XcbPortingCreateCursor]] Creating a cursor from a standard font.
+- [[The Events section of the XCB Tutorial|tutorial/events]] explains how to set up the event loop in XCB and compares the process with Xlib's <tt>XNextEvent</tt> and <tt>XPending</tt>.
diff --git a/XcbPortingCreateCursor.mdwn b/XcbPortingCreateCursor.mdwn
index 1ca50fb..76248e9 100644
--- a/XcbPortingCreateCursor.mdwn
+++ b/XcbPortingCreateCursor.mdwn
@@ -1,59 +1,58 @@
This example creates a new `Display` and `Window` using the common Xlib functions `XOpenDisplay` and `XCreateSimpleWindow`. It then calls a helper function `attach_cursor` that uses both XCB and Xlib facilities to set the cursor of the provided `Window` to whatever shape the client provides (in this case a question mark with an arrow as defined by `XC_question_arrow`).
- #include <X11/xcl.h>
+ #include <X11/Xlib-xcb.h>
#include <X11/cursorfont.h>
-
+ #include <unistd.h>
+
void attach_cursor(Display *dpy, Window w, int shape)
{
static const int fgred = 0, fggreen = 0, fgblue = 0,
bgred = 0xFFFF, bggreen = 0xFFFF, bgblue = 0xFFFF;
-
- XCBConnection *c = XCBConnectionOfDisplay(dpy);
- XCBCURSOR cursor = XCBCURSORNew(c);
- XCBWINDOW window = XCLWINDOW(w);
- XCBFONT font = XCBFONTNew(c),
+
+ xcb_connection_t *c = XGetXCBConnection(dpy);
+ xcb_cursor_t cursor = xcb_generate_id(c);
+ xcb_window_t window = (xcb_window_t) w;
+ xcb_font_t font = xcb_generate_id(c),
*mask_font = &font; /* An alias to clarify what is being passed
to XCBCreateGlyphCursor. */
-
- XCBOpenFont(c, font, sizeof("cursor"), "cursor");
- XCBCreateGlyphCursor(c, cursor, font, *mask_font, shape, shape + 1,
+
+ xcb_open_font(c, font, sizeof("cursor"), "cursor");
+ xcb_create_glyph_cursor (c, cursor, font, *mask_font, shape, shape + 1,
fgred, fggreen, fgblue, bgred, bggreen, bgblue);
- XDefineCursor(dpy, window.xid, cursor.xid);
- XCBFreeCursor(c, cursor);
- XCBCloseFont(c, font);
+ XDefineCursor(dpy, window, cursor);
+ xcb_free_cursor(c, cursor);
+ xcb_close_font(c, font);
}
-
+
int main(void)
{
static const int DEPTH = 0, X = 0, Y = 0, BORDER_WIDTH = 1;
static const size_t WIDTH = 150, HEIGHT = 150;
-
+
Display *dpy;
int screen_num;
unsigned int bordercolor, bgcolor;
Window window;
-
+
dpy = XOpenDisplay(NULL);
screen_num = DefaultScreen(dpy);
bordercolor = BlackPixel(dpy, screen_num);
bgcolor = WhitePixel(dpy, screen_num);
window = XCreateSimpleWindow(dpy, RootWindow(dpy, screen_num), X, Y, WIDTH,
HEIGHT, BORDER_WIDTH, bordercolor, bgcolor);
-
+
attach_cursor(dpy, window, XC_question_arrow);
XMapWindow(dpy, window);
XSync(dpy, 0);
-
- while (1)
- ; /* Hit C-c to break out of this loop. */
-
+
+ pause(); /* Hit C-c to break out of this loop. */
+
return 0;
}
-
+
Suppose that the `attach_cursor` function was to be ported entirely to use XCB's functionality. How could the pointer's cursor be set to the specified symbol without using `XDefineCursor`?
# See Also
- [[XcbPorting]]
-- [[XCLWINDOW]]
-- [[XCBConnectionOfDisplay]]
+- [[MixingCalls]]
More information about the xcb-commit
mailing list