git.demorecorder.com Git - free-sw/xcb/libxcb/blob - NEWS

   1 Release 1.0 RC2 (2006-10-07)
   2 ============================
   3
   4 API changes
   5 -----------
   6
   7 In our announcement of XCB 1.0 RC1, we proposed two API changes for
   8 community feedback:
   9
  10     We would greatly appreciate API review in this final release
  11     candidate period. We've had some limited feedback that our attempts
  12     to impose static type safety on XIDs in C pose more a hindrance than
  13     a help, so we would appreciate discussion over whether this
  14     constitutes a "serious issue with the API". Some question also
  15     remains of whether xcb_poll_for_event should have the out-parameter
  16     'error', now that XCB has a more uniform mechanism for reporting
  17     connection errors. Speak now on these points or leave us alone. ;-)
  18
  19 Since we've received feedback agreeing with our proposed changes, and no
  20 objections or requests to keep the existing API, we made both changes
  21 and bumped the soname to libxcb.so.1.0.0 in preparation for the release
  22 of XCB 1.0.
  23
  24 * Remove XID wrapper structures and replace them with uint32_t typedefs.
  25   XID union types like xcb_drawable_t and xcb_fontable_t also become
  26   uint32_t typedefs. The API conversion script now replaces xcb_*_new
  27   with calls directly to xcb_generate_id.  This change makes
  28   xcb_generate_id part of the client API rather than the extension API,
  29   so move xcb_generate_id from xcbext.h to xcb.h.
  30
  31 * Remove the 'int *error' out-parameter for xcb_poll_for_event.
  32   xcb_poll_for_event now shuts down the xcb_connection_t on fatal
  33   errors; use xcb_connection_has_error to check.
  34
  35 The Xlib-specific API in libxcb-xlib also changed:
  36
  37 * Stop exposing the XCB IO lock for Xlib's benefit, by removing
  38   xcb_get_io_lock from the Xlib-specific XCB API; instead, libxcb-xlib
  39   now provides xcb_xlib_lock and xcb_xlib_unlock.
  40
  41 Code generation changes
  42 -----------------------
  43
  44 * The code generator no longer implicitly imports xproto for extensions.
  45   xcb-proto 1.0 RC2 includes the corresponding change to explicitly
  46   import xproto in extensions that need it
  47
  48 * The generated protocol headers now declare "struct foo", "union foo"
  49   or "enum foo", not just the typedef "foo" of an unnamed
  50   struct/union/enum type.
  51
  52 Bug Fixes
  53 ---------
  54
  55 * Make Plan 7 'checked' requests work correctly.
  56
  57 Documentation improvements
  58 --------------------------
  59
  60 * Document xcb_generate_id.
  61
  62 * Tutorial enhancements.
  63
  64
  65 Release 1.0 RC1 (2006-09-25)
  66 ============================
  67
  68 The Great XCB Renaming
  69 ----------------------
  70
  71 Rename API to follow a new naming convention:
  72
  73 * XCB_CONSTANTS_UPPERCASE_WITH_UNDERSCORES
  74 * xcb_functions_lowercase_with_underscores
  75 * xcb_types_lowercase_with_underscores_and_suffix_t
  76 * expand all abbreviations like "req", "rep", and "iter"
  77
  78 Word boundaries for the names in the protocol descriptions fall:
  79
  80 * Wherever the protocol descriptions already have an underscore
  81 * Between a lowercase letter and a subsequent uppercase letter
  82 * Before the last uppercase letter in a string of uppercase letters
  83   followed by a lowercase letter (such as in LSBFirst between LSB and
  84   First)
  85 * Before and after a string of digits (with exceptions for sized types
  86   like xcb_char2b_t and xcb_glx_float32_t to match the stdint.h
  87   convention)
  88
  89 Also fix up some particular naming issues:
  90
  91 * Rename shape_op and shape_kind to drop the "shape_" prefix, since
  92   otherwise these types end up as xcb_shape_shape_{op,kind}_t.
  93 * Remove leading underscores from enums in the GLX protocol description,
  94   previously needed to ensure a word separator, but now redundant.
  95
  96 This renaming breaks code written for the previous API naming
  97 convention. The scripts in XCB's tools directory will convert code
  98 written for the old API to use the new API; they work well enough that
  99 we used them to convert the non-program-generated code in XCB, and when
 100 run on the old program-generated code, they almost exactly reproduce the
 101 new program-generated code (modulo whitespace and bugs in the old code
 102 generator).
 103
 104 Authors: Vincent Torri, Thomas Hunger, Josh Triplett
 105
 106 In addition to the API renaming, the library SONAMEs have changed to
 107 libxcb.so and libxcb-extname.so. The library major version remains at 0,
 108 to become version 1 before 1.0 is released; the SONAME lowercasing means
 109 that this will not conflict with XCB 0.9 libraries.
 110
 111 The header files have moved from /usr/include/X11/XCB/ to
 112 /usr/include/xcb/. The XML-XCB protocol descriptions have moved to
 113 /usr/share/xcb, with extension descriptions no longer relegated to an
 114 extensions/ subdirectory. The API conversion script api_conv.pl will fix
 115 references to the header files, and packages using pkg-config will
 116 automatically use the new library names.
 117
 118 Error handling Plan 7
 119 ---------------------
 120
 121 All request functions now come in an "unchecked" and "checked" variant.
 122 The checked variant allows callers to handle errors inline where they
 123 obtain the reply, or by calling xcb_request_check for requests with no
 124 reply. The unchecked variant uses the event queue for errors. Requests
 125 with replies default to checked, because the caller must already make a
 126 function call to retrieve the reply and can see the error at that time;
 127 the unchecked variant uses the suffix _unchecked. Requests without
 128 replies default to unchecked, because the caller will not necessarily
 129 expect to handle a response, and the checked variant uses the suffix
 130 _checked.
 131
 132 Connection error handling
 133 -------------------------
 134
 135 Fatal connection errors now put the xcb_connection_t object into an
 136 error state, at which point all further operations on that connection
 137 will fail. Callers can use the new xcb_connection_has_error function to
 138 check for this state in a connection. Functions that return a
 139 connection, such as the xcb_connect function, may instead return an
 140 xcb_connection_t already in an error state.
 141
 142 In the future we expect to add additional API for getting more
 143 information about the error condition that caused the connection to get
 144 into an error state.
 145
 146 Smaller API changes
 147 -------------------
 148
 149 All functions that have been marked 'deprecated' up to now have been
 150 removed for this release. After XCB 1.0 is released, functions marked
 151 'deprecated' will be preserved until the end of time to maintain
 152 compatibility.
 153
 154 XCB no longer provides a sync function. Most callers of this function
 155 should use xcb_flush instead, which usually provides the intended
 156 functionality and does not require a round-trip to the server. If you
 157 really need this functionality, either use xcb_get_input_focus like sync
 158 used to do, or use the xcb_aux_sync function from the xcb-aux library in
 159 xcb-util. However, note that we do not consider the libraries in
 160 xcb-util remotely stable yet.
 161
 162 XCB no longer provides xcb_[extension_name]_init functions for each
 163 extension. These functions previously caused XCB to issue and process a
 164 QueryExtension request. Callers should now directly call
 165 xcb_get_extension_data on the xcb_[extension_name]_id, or use
 166 xcb_prefetch_extension_data if they do not need to force a round-trip
 167 immediately.
 168
 169 The compatibility functions in xcbxlib.h, provided solely for use by
 170 Xlib/XCB, now exist in a separate library libxcb-xlib. We don't want to
 171 have to change the libxcb soname if we later change or remove the Xlib
 172 compatibility functions, and nothing except Xlib/XCB should ever use
 173 them. (Applications which use Xlib/XCB do not need this library either;
 174 Xlib/XCB only uses it internally.)
 175
 176 The descriptions of several extensions have been updated to match the
 177 latest versions implemented in the X.org X server.
 178
 179 GIT Repository split
 180 --------------------
 181
 182 Previously, several XCB-related projects all existed under the umbrella
 183 of a single monolithic GIT repository with per-project subdirectories.
 184 We have split this repository into individual per-project repositories.
 185
 186 Josh Triplett and Jamey Sharp wrote a tool called git-split to
 187 accomplish this repository split. git-split reconstructs the history of
 188 a sub-project previously stored in a subdirectory of a larger
 189 repository. It constructs new commit objects based on the existing tree
 190 objects for the subtree in each commit, and discards commits which do
 191 not affect the history of the sub-project, as well as merges made
 192 unnecessary due to these discarded commits.
 193
 194 We would like to acknowledge the work of the gobby team in creating a
 195 collaborative editor which greatly aided the development of git-split
 196 (as well as these release notes).
 197
 198 Build and implementation fixes
 199 ------------------------------
 200
 201 XCB no longer needs proto/x11 from X.org; the XCB header xproto.h
 202 provides the definitions from X.h, named according to XCB conventions.
 203
 204 XCB should now build with non-GNU implementations of Make.
 205
 206 XCB properly handles 32-bit wrap of sequence numbers, and thus now
 207 supports issuing more than 2**32 requests in one connection.
 208
 209 Fixed bugs #7001, #7261.