path: root/NEWS

Release 1.0 RC2 (2006-10-07)
============================

API changes
-----------

In our announcement of XCB 1.0 RC1, we proposed two API changes for
community feedback:

    We would greatly appreciate API review in this final release
    candidate period. We've had some limited feedback that our attempts
    to impose static type safety on XIDs in C pose more a hindrance than
    a help, so we would appreciate discussion over whether this
    constitutes a "serious issue with the API". Some question also
    remains of whether xcb_poll_for_event should have the out-parameter
    'error', now that XCB has a more uniform mechanism for reporting
    connection errors. Speak now on these points or leave us alone. ;-)

Since we've received feedback agreeing with our proposed changes, and no
objections or requests to keep the existing API, we made both changes
and bumped the soname to libxcb.so.1.0.0 in preparation for the release
of XCB 1.0.

* Remove XID wrapper structures and replace them with uint32_t typedefs.
  XID union types like xcb_drawable_t and xcb_fontable_t also become
  uint32_t typedefs. The API conversion script now replaces xcb_*_new
  with calls directly to xcb_generate_id.  This change makes
  xcb_generate_id part of the client API rather than the extension API,
  so move xcb_generate_id from xcbext.h to xcb.h.

* Remove the 'int *error' out-parameter for xcb_poll_for_event. 
  xcb_poll_for_event now shuts down the xcb_connection_t on fatal
  errors; use xcb_connection_has_error to check.

The Xlib-specific API in libxcb-xlib also changed:

* Stop exposing the XCB IO lock for Xlib's benefit, by removing
  xcb_get_io_lock from the Xlib-specific XCB API; instead, libxcb-xlib
  now provides xcb_xlib_lock and xcb_xlib_unlock.

Code generation changes
-----------------------

* The code generator no longer implicitly imports xproto for extensions.
  xcb-proto 1.0 RC2 includes the corresponding change to explicitly
  import xproto in extensions that need it

* The generated protocol headers now declare "struct foo", "union foo"
  or "enum foo", not just the typedef "foo" of an unnamed
  struct/union/enum type.

Bug Fixes
---------

* Make Plan 7 'checked' requests work correctly.

Documentation improvements
--------------------------

* Document xcb_generate_id.

* Tutorial enhancements.


Release 1.0 RC1 (2006-09-25)
============================

The Great XCB Renaming
----------------------

Rename API to follow a new naming convention:

* XCB_CONSTANTS_UPPERCASE_WITH_UNDERSCORES
* xcb_functions_lowercase_with_underscores
* xcb_types_lowercase_with_underscores_and_suffix_t
* expand all abbreviations like "req", "rep", and "iter"

Word boundaries for the names in the protocol descriptions fall:

* Wherever the protocol descriptions already have an underscore
* Between a lowercase letter and a subsequent uppercase letter
* Before the last uppercase letter in a string of uppercase letters
  followed by a lowercase letter (such as in LSBFirst between LSB and
  First)
* Before and after a string of digits (with exceptions for sized types
  like xcb_char2b_t and xcb_glx_float32_t to match the stdint.h
  convention)

Also fix up some particular naming issues:

* Rename shape_op and shape_kind to drop the "shape_" prefix, since
  otherwise these types end up as xcb_shape_shape_{op,kind}_t.
* Remove leading underscores from enums in the GLX protocol description,
  previously needed to ensure a word separator, but now redundant.

This renaming breaks code written for the previous API naming
convention. The scripts in XCB's tools directory will convert code
written for the old API to use the new API; they work well enough that
we used them to convert the non-program-generated code in XCB, and when
run on the old program-generated code, they almost exactly reproduce the
new program-generated code (modulo whitespace and bugs in the old code
generator).

Authors: Vincent Torri, Thomas Hunger, Josh Triplett

In addition to the API renaming, the library SONAMEs have changed to
libxcb.so and libxcb-extname.so. The library major version remains at 0,
to become version 1 before 1.0 is released; the SONAME lowercasing means
that this will not conflict with XCB 0.9 libraries.

The header files have moved from /usr/include/X11/XCB/ to
/usr/include/xcb/. The XML-XCB protocol descriptions have moved to
/usr/share/xcb, with extension descriptions no longer relegated to an
extensions/ subdirectory. The API conversion script api_conv.pl will fix
references to the header files, and packages using pkg-config will
automatically use the new library names.

Error handling Plan 7
---------------------

All request functions now come in an "unchecked" and "checked" variant.
The checked variant allows callers to handle errors inline where they
obtain the reply, or by calling xcb_request_check for requests with no
reply. The unchecked variant uses the event queue for errors. Requests
with replies default to checked, because the caller must already make a
function call to retrieve the reply and can see the error at that time;
the unchecked variant uses the suffix _unchecked. Requests without
replies default to unchecked, because the caller will not necessarily
expect to handle a response, and the checked variant uses the suffix
_checked.

Connection error handling
-------------------------

Fatal connection errors now put the xcb_connection_t object into an
error state, at which point all further operations on that connection
will fail. Callers can use the new xcb_connection_has_error function to
check for this state in a connection. Functions that return a
connection, such as the xcb_connect function, may instead return an
xcb_connection_t already in an error state.

In the future we expect to add additional API for getting more
information about the error condition that caused the connection to get
into an error state.

Smaller API changes
-------------------

All functions that have been marked 'deprecated' up to now have been
removed for this release. After XCB 1.0 is released, functions marked
'deprecated' will be preserved until the end of time to maintain
compatibility.

XCB no longer provides a sync function. Most callers of this function
should use xcb_flush instead, which usually provides the intended
functionality and does not require a round-trip to the server. If you
really need this functionality, either use xcb_get_input_focus like sync
used to do, or use the xcb_aux_sync function from the xcb-aux library in
xcb-util. However, note that we do not consider the libraries in
xcb-util remotely stable yet.

XCB no longer provides xcb_[extension_name]_init functions for each
extension. These functions previously caused XCB to issue and process a
QueryExtension request. Callers should now directly call
xcb_get_extension_data on the xcb_[extension_name]_id, or use
xcb_prefetch_extension_data if they do not need to force a round-trip
immediately.

The compatibility functions in xcbxlib.h, provided solely for use by
Xlib/XCB, now exist in a separate library libxcb-xlib. We don't want to
have to change the libxcb soname if we later change or remove the Xlib
compatibility functions, and nothing except Xlib/XCB should ever use
them. (Applications which use Xlib/XCB do not need this library either;
Xlib/XCB only uses it internally.)

The descriptions of several extensions have been updated to match the
latest versions implemented in the X.org X server.

GIT Repository split
--------------------

Previously, several XCB-related projects all existed under the umbrella
of a single monolithic GIT repository with per-project subdirectories.
We have split this repository into individual per-project repositories.

Josh Triplett and Jamey Sharp wrote a tool called git-split to
accomplish this repository split. git-split reconstructs the history of
a sub-project previously stored in a subdirectory of a larger
repository. It constructs new commit objects based on the existing tree
objects for the subtree in each commit, and discards commits which do
not affect the history of the sub-project, as well as merges made
unnecessary due to these discarded commits.

We would like to acknowledge the work of the gobby team in creating a
collaborative editor which greatly aided the development of git-split
(as well as these release notes).

Build and implementation fixes
------------------------------

XCB no longer needs proto/x11 from X.org; the XCB header xproto.h
provides the definitions from X.h, named according to XCB conventions.

XCB should now build with non-GNU implementations of Make.

XCB properly handles 32-bit wrap of sequence numbers, and thus now
supports issuing more than 2**32 requests in one connection.

Fixed bugs #7001, #7261.