protocol: double-buffered state for wl_surface

protocol: double-buffered state for wl_surface

This change breaks the protocol.

The current protocol is racy in that updates to surface content and
surface state (e.g. damage, input and opaque regions) are not guaranteed
to happen at the same time. Due to protocol buffering and handling
practices, the issues are very hard to trigger.

Committing damage to a surface at arbitrary times makes it hard to
track when the wl_buffer is being read by the server, and when it is
safe to overwrite (the case of wl_shm with a single buffer reused
constantly).

This protocol change introduces the concept of double-buffered state.
Such state is accumulated and cached in the server, unused, until the
final commit request. The surface will receive its new content and apply
its new state atomically.

A wl_surface.commit request is added to the protocol. This is thought to
be more clear, than having wl_surface.attach committing implicitly, and
then having another request to commit without attaching, as would be
required for a GL app that wants to change e.g. input region without
redrawing.

When these changes are implemented, clients do not have to worry about
ordering damage vs. input region vs. attach vs. ... anymore. Clients set
the state in any order they want, and kick it all in with a commit.

The interactions between wl_surface.attach, (wl_surface.commit,)
wl_buffer.release, and wl_buffer.destroy have been undocumented. Only
careful inspection of the compositor code has told when a wl_buffer is
free for re-use, especially for wl_shm and wrt. wl_surface.damage.
Try to clarify how it all should work, and what happens if the wl_buffer
gets destroyed.

An additional minor fix: allow NULL argument to
wl_surface.set_opaque_region. The wording in the documentation already
implied that a nil region is allowed.

Signed-off-by: Pekka Paalanen <ppaalanen@gmail.com>