On Wed, 1 Jun 2016 10:49:55 -0500 Yong Bakos <[email protected]> wrote:
> From: Yong Bakos <[email protected]> > > Signed-off-by: Yong Bakos <[email protected]> > --- > protocol/wayland.xml | 334 > ++++++++++++++++++++++++++------------------------- > 1 file changed, 172 insertions(+), 162 deletions(-) > > diff --git a/protocol/wayland.xml b/protocol/wayland.xml > index 700ef03..d0db6cc 100644 > --- a/protocol/wayland.xml > +++ b/protocol/wayland.xml > @@ -48,7 +48,8 @@ > > The callback_data passed in the callback is the event serial. > </description> > - <arg name="callback" type="new_id" interface="wl_callback"/> > + <arg name="callback" type="new_id" interface="wl_callback" > + summary="callback object for the sync request"/> It's a new_id, so summary should probably contain "new". And here it really is a whole new object, but just a handle (see below). > </request> > > <request name="get_registry"> > @@ -57,7 +58,8 @@ > to list and bind the global objects available from the > compositor. > </description> > - <arg name="registry" type="new_id" interface="wl_registry"/> > + <arg name="registry" type="new_id" interface="wl_registry" > + summary="global registry object"/> I was first confused about "global" here, but it does fit. The registry is a global and a singleton for the display. "global" might be confused with globals though (the ones advertised with wl_registry.global event). Maybe call it "a handle to the registry"? All protocol objects are handles in a sense, but I would not call them all handles. wl_surface is a wl_surface, it's not a handle to some other object. wl_registry OTOH is always a handle to the compositor's registry. wl_compositor is always a handle to the compositor, not something a client creates when it creates the protocol object. Does this makes sense? > </request> > > <event name="error"> > @@ -129,8 +131,8 @@ > Binds a new, client-created object to the server using the > specified name as the identifier. > </description> > - <arg name="name" type="uint" summary="unique name for the object"/> > - <arg name="id" type="new_id"/> > + <arg name="name" type="uint" summary="unique numeric name of the > global object"/> > + <arg name="id" type="new_id" summary="global object to bind"/> In the C API, a new_id is actually a return value. I wouldn't say it's the object to bind, rather it is a new object, already bound to the global. > </request> > > <event name="global"> > @@ -187,14 +189,14 @@ > <description summary="create new surface"> > Ask the compositor to create a new surface. > </description> > - <arg name="id" type="new_id" interface="wl_surface"/> > + <arg name="id" type="new_id" interface="wl_surface" summary="surface > to create"/> That's another interesting choice of words. Is the surface already created or to be created? Maybe just punt that difference and say "the new surface"? > </request> > > <request name="create_region"> > <description summary="create new region"> > Ask the compositor to create a new region. > </description> > - <arg name="id" type="new_id" interface="wl_region"/> > + <arg name="id" type="new_id" interface="wl_region" summary="region to > create"/> > </request> > </interface> > > @@ -224,12 +226,12 @@ > a buffer from it. > </description> > > - <arg name="id" type="new_id" interface="wl_buffer"/> > - <arg name="offset" type="int"/> > - <arg name="width" type="int"/> > - <arg name="height" type="int"/> > - <arg name="stride" type="int"/> > - <arg name="format" type="uint" enum="wl_shm.format"/> > + <arg name="id" type="new_id" interface="wl_buffer" summary="buffer to > create"/> > + <arg name="offset" type="int" summary="buffer byte offset within the > pool"/> > + <arg name="width" type="int" summary="buffer width, in bytes"/> > + <arg name="height" type="int" summary="buffer height, in bytes"/> Width and height are in pixels, not bytes. offset is bytes, stride is bytes. Very good to clarify those. :-) > + <arg name="stride" type="int" summary="number of bytes from the > beginning of one row to the beginning of the next row"/> > + <arg name="format" type="uint" enum="wl_shm.format" summary="buffer > pixel format"/> > </request> > > <request name="destroy" type="destructor"> > @@ -250,7 +252,7 @@ > used to make the pool bigger. > </description> > > - <arg name="size" type="int"/> > + <arg name="size" type="int" summary="new size of the pool, in bytes"/> > </request> > </interface> > > @@ -289,62 +291,62 @@ > <!-- The drm format codes match the #defines in drm_fourcc.h. > The formats actually supported by the compositor will be > reported by the format event. --> > - <entry name="c8" value="0x20203843"/> > - <entry name="rgb332" value="0x38424752"/> > - <entry name="bgr233" value="0x38524742"/> > - <entry name="xrgb4444" value="0x32315258"/> > - <entry name="xbgr4444" value="0x32314258"/> > - <entry name="rgbx4444" value="0x32315852"/> > - <entry name="bgrx4444" value="0x32315842"/> > - <entry name="argb4444" value="0x32315241"/> > - <entry name="abgr4444" value="0x32314241"/> > - <entry name="rgba4444" value="0x32314152"/> > - <entry name="bgra4444" value="0x32314142"/> > - <entry name="xrgb1555" value="0x35315258"/> > - <entry name="xbgr1555" value="0x35314258"/> > - <entry name="rgbx5551" value="0x35315852"/> > - <entry name="bgrx5551" value="0x35315842"/> > - <entry name="argb1555" value="0x35315241"/> > - <entry name="abgr1555" value="0x35314241"/> > - <entry name="rgba5551" value="0x35314152"/> > - <entry name="bgra5551" value="0x35314142"/> > - <entry name="rgb565" value="0x36314752"/> > - <entry name="bgr565" value="0x36314742"/> > - <entry name="rgb888" value="0x34324752"/> > - <entry name="bgr888" value="0x34324742"/> > - <entry name="xbgr8888" value="0x34324258"/> > - <entry name="rgbx8888" value="0x34325852"/> > - <entry name="bgrx8888" value="0x34325842"/> > - <entry name="abgr8888" value="0x34324241"/> > - <entry name="rgba8888" value="0x34324152"/> > - <entry name="bgra8888" value="0x34324142"/> > - <entry name="xrgb2101010" value="0x30335258"/> > - <entry name="xbgr2101010" value="0x30334258"/> > - <entry name="rgbx1010102" value="0x30335852"/> > - <entry name="bgrx1010102" value="0x30335842"/> > - <entry name="argb2101010" value="0x30335241"/> > - <entry name="abgr2101010" value="0x30334241"/> > - <entry name="rgba1010102" value="0x30334152"/> > - <entry name="bgra1010102" value="0x30334142"/> > - <entry name="yuyv" value="0x56595559"/> > - <entry name="yvyu" value="0x55595659"/> > - <entry name="uyvy" value="0x59565955"/> > - <entry name="vyuy" value="0x59555956"/> > - <entry name="ayuv" value="0x56555941"/> > - <entry name="nv12" value="0x3231564e"/> > - <entry name="nv21" value="0x3132564e"/> > - <entry name="nv16" value="0x3631564e"/> > - <entry name="nv61" value="0x3136564e"/> > - <entry name="yuv410" value="0x39565559"/> > - <entry name="yvu410" value="0x39555659"/> > - <entry name="yuv411" value="0x31315559"/> > - <entry name="yvu411" value="0x31315659"/> > - <entry name="yuv420" value="0x32315559"/> > - <entry name="yvu420" value="0x32315659"/> > - <entry name="yuv422" value="0x36315559"/> > - <entry name="yvu422" value="0x36315659"/> > - <entry name="yuv444" value="0x34325559"/> > - <entry name="yvu444" value="0x34325659"/> > + <entry name="c8" value="0x20203843" summary="8-bit color index > format"/> > + <entry name="rgb332" value="0x38424752" summary="8-bit RGB format"/> > + <entry name="bgr233" value="0x38524742" summary="8-bit BGR format"/> > + <entry name="xrgb4444" value="0x32315258" summary="16-bit xRGB > format"/> > + <entry name="xbgr4444" value="0x32314258" summary="16-bit xBGR > format"/> > + <entry name="rgbx4444" value="0x32315852" summary="16-bit RGBx > format"/> > + <entry name="bgrx4444" value="0x32315842" summary="16-bit BGRx > format"/> > + <entry name="argb4444" value="0x32315241" summary="16-bit ARGB > format"/> > + <entry name="abgr4444" value="0x32314241" summary="16-bit ABGR > format"/> > + <entry name="rgba4444" value="0x32314152" summary="16-bit RBGA > format"/> > + <entry name="bgra4444" value="0x32314142" summary="16-bit BGRA > format"/> > + <entry name="xrgb1555" value="0x35315258" summary="16-bit xRGB > format"/> > + <entry name="xbgr1555" value="0x35314258" summary="16-bit xBGR 1555 > format"/> > + <entry name="rgbx5551" value="0x35315852" summary="16-bit RGBx 5551 > format"/> > + <entry name="bgrx5551" value="0x35315842" summary="16-bit BGRx 5551 > format"/> > + <entry name="argb1555" value="0x35315241" summary="16-bit ARGB 1555 > format"/> > + <entry name="abgr1555" value="0x35314241" summary="16-bit ABGR 1555 > format"/> > + <entry name="rgba5551" value="0x35314152" summary="16-bit RGBA 5551 > format"/> > + <entry name="bgra5551" value="0x35314142" summary="16-bit BGRA 5551 > format"/> > + <entry name="rgb565" value="0x36314752" summary="16-bit RGB 565 > format"/> > + <entry name="bgr565" value="0x36314742" summary="16-bit BGR 565 > format"/> > + <entry name="rgb888" value="0x34324752" summary="24-bit RGB format"/> > + <entry name="bgr888" value="0x34324742" summary="24-bit BGR format"/> > + <entry name="xbgr8888" value="0x34324258" summary="32-bit xBGR > format"/> > + <entry name="rgbx8888" value="0x34325852" summary="32-bit RGBx > format"/> > + <entry name="bgrx8888" value="0x34325842" summary="32-bit BGRx > format"/> > + <entry name="abgr8888" value="0x34324241" summary="32-bit ABGR > format"/> > + <entry name="rgba8888" value="0x34324152" summary="32-bit RGBA > format"/> > + <entry name="bgra8888" value="0x34324142" summary="32-bit BGRA > format"/> > + <entry name="xrgb2101010" value="0x30335258" summary="32-bit xRGB > 2:10:10:10 format"/> > + <entry name="xbgr2101010" value="0x30334258" summary="32-bit xBGR > 2:10:10:10 format"/> > + <entry name="rgbx1010102" value="0x30335852" summary="32-bit RGBx > 10:10:10:2 format"/> > + <entry name="bgrx1010102" value="0x30335842" summary="32-bit BGRx > 10:10:10:2 format"/> > + <entry name="argb2101010" value="0x30335241" summary="32-bit ARGB > 2:10:10:10 format"/> > + <entry name="abgr2101010" value="0x30334241" summary="32-bit ABGR > 2:10:10:10 format"/> > + <entry name="rgba1010102" value="0x30334152" summary="32-bit RGBA > 10:10:10:2 format"/> > + <entry name="bgra1010102" value="0x30334142" summary="32-bit BGRA > 10:10:10:2 format"/> > + <entry name="yuyv" value="0x56595559" summary="packed YCbCr > Cr0:Y1:Cb0:Y0 format"/> > + <entry name="yvyu" value="0x55595659" summary="packed YCbCr > Cb0:Y1:Cr0:Y0 format"/> > + <entry name="uyvy" value="0x59565955" summary="packed YCbCr > Y1:Cr0:Y0:Cb0 format"/> > + <entry name="vyuy" value="0x59555956" summary="packed YCbCr > Y1:Cb0:Y0:Cr0 format"/> > + <entry name="ayuv" value="0x56555941" summary="packed AYCbCr format"/> > + <entry name="nv12" value="0x3231564e" summary="2 plane YCbCr Cr:Cb > format"/> > + <entry name="nv21" value="0x3132564e" summary="2 plane YCbCr Cb:Cr > format"/> > + <entry name="nv16" value="0x3631564e" summary="2 plane YCbCr Cr:Cb > format"/> > + <entry name="nv61" value="0x3136564e" summary="2 plane YCbCr Cb:Cr > format"/> > + <entry name="yuv410" value="0x39565559" summary="3 plane YCbCr > format"/> > + <entry name="yvu410" value="0x39555659" summary="3 plane YCbCr > format"/> > + <entry name="yuv411" value="0x31315559" summary="3 plane YCbCr > format"/> > + <entry name="yvu411" value="0x31315659" summary="3 plane YCbCr > format"/> > + <entry name="yuv420" value="0x32315559" summary="3 plane YCbCr > format"/> > + <entry name="yvu420" value="0x32315659" summary="3 plane YCbCr > format"/> > + <entry name="yuv422" value="0x36315559" summary="3 plane YCbCr > format"/> > + <entry name="yvu422" value="0x36315659" summary="3 plane YCbCr > format"/> > + <entry name="yuv444" value="0x34325559" summary="3 plane YCbCr > format"/> > + <entry name="yvu444" value="0x34325659" summary="3 plane YCbCr > format"/> That's a good try. Did you look these up from drm_fourcc.h? You may want to explain somewhere what endianess is being used in this notation, and understand the array-of-bytes vs. bits-of-unsigned difference which often causes confusion with 8 bits-per-channel formats. Those are the usual confusions with pixel formats. Even better if you can copy the notation from somewehere like drm_fourcc.h and also explain how it is read. Also the existing summaries for argb8888 and xrgb8888 could use the same treatment, even when the value does not match with drm_fourcc.h. > </enum> > > <request name="create_pool"> > @@ -2279,12 +2289,12 @@ > This enumeration describes how the physical > pixels on an output are laid out. > </description> > - <entry name="unknown" value="0"/> > - <entry name="none" value="1"/> > - <entry name="horizontal_rgb" value="2"/> > - <entry name="horizontal_bgr" value="3"/> > - <entry name="vertical_rgb" value="4"/> > - <entry name="vertical_bgr" value="5"/> > + <entry name="unknown" value="0" summary="unkown geometry"/> > + <entry name="none" value="1" summary="no geometry"/> I suppose "none" would be more like where each pixel changes its color uniformly, without being divided into red, green and blue regions. Maybe it could apply to Pentile, too. > + <entry name="horizontal_rgb" value="2" summary="horizontal RGB"/> > + <entry name="horizontal_bgr" value="3" summary="horizontal BGR"/> > + <entry name="vertical_rgb" value="4" summary="vertical RGB"/> > + <entry name="vertical_bgr" value="5" summary="vertical BGR"/> > </enum> > > <enum name="transform"> > @@ -2302,14 +2312,14 @@ > surfaces. > </description> > > - <entry name="normal" value="0"/> > - <entry name="90" value="1"/> > - <entry name="180" value="2"/> > - <entry name="270" value="3"/> > - <entry name="flipped" value="4"/> > - <entry name="flipped_90" value="5"/> > - <entry name="flipped_180" value="6"/> > - <entry name="flipped_270" value="7"/> > + <entry name="normal" value="0" summary="no transform"/> > + <entry name="90" value="1" summary="90 degrees counter-clockwise"/> > + <entry name="180" value="2" summary="180 degrees counter-clockwise"/> > + <entry name="270" value="3" summary="270 degrees counter-clockwise"/> > + <entry name="flipped" value="4" summary="180 degree flip around a > vertical axis"/> > + <entry name="flipped_90" value="5" summary="flip and rotate 90 degrees > counter-clockwise"/> > + <entry name="flipped_180" value="6" summary="flip and rotate 180 > degrees counter-clockwise"/> > + <entry name="flipped_270" value="7" summary="flip and rotate 270 > degrees counter-clockwise"/> Unfortunately, counter-clockwise still does not say what is being rotated: the framebuffer or the display? This, and also wl_surface.set_buffer_transform could use a rigorous definition on which way the transformation goes, but I can't tell you off-hand what is the right answer. Also flip is problematic: is it always around vertical axis? Before or after the rotation? > </enum> > > <event name="geometry"> > @@ -2423,10 +2433,10 @@ > Add the specified rectangle to the region. > </description> > > - <arg name="x" type="int"/> > - <arg name="y" type="int"/> > - <arg name="width" type="int"/> > - <arg name="height" type="int"/> > + <arg name="x" type="int" summary="TODO"/> > + <arg name="y" type="int" summary="TODO"/> > + <arg name="width" type="int" summary="rectangle width"/> > + <arg name="height" type="int" summary="rectangle height"/> > </request> > > <request name="subtract"> > @@ -2434,10 +2444,10 @@ > Subtract the specified rectangle from the region. > </description> > > - <arg name="x" type="int"/> > - <arg name="y" type="int"/> > - <arg name="width" type="int"/> > - <arg name="height" type="int"/> > + <arg name="x" type="int" summary="TODO"/> > + <arg name="y" type="int" summary="TODO"/> > + <arg name="width" type="int" summary="rectangle width"/> > + <arg name="height" type="int" summary="rectangle height"/> > </request> > </interface> > A region has its own coordinate space. It is completely arbitrary. Only when a region is attached to something, e.g. with wl_surface.set_opaque_region, the coordinate space gets a tangible meaning. Until then its just numbers in unspecified units. Thanks, pq
pgpP5pXlbZEv0.pgp
Description: OpenPGP digital signature
_______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
