[Wayland] Wayland agreement description

Wayland Agreement that

Wayland Basic concepts

What is? wayland？

• It is a window management protocol . Simple understanding ,wayland It's a set Display Server And Display Client Protocol for inter communication .Wayland Defines a set of standard protocols , And stipulate the core objects in this set of agreements （https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Interfaces）.

Weston What is it? ？‘

• Wayland Just a set of agreements , A set of norms .Weston yes wayland On the official website Wayland Compositor A set of reference implementations for .

If you don't go into the details , You can simply put Weston Directly understood as ,wayland Official , follow Wayland Agreed , A set of window management components .

Several concepts

• Asynchronous object-oriented protocol ：wayland All requests in , All right. ” object “ Method call for . Here's the request , It can be understood as Client Yes Server End function request .
  
• Message based protocols ：wayland Is a message based protocol .Server and Client Between two ends , Through message interaction .Wayland The protocol specifies a fixed format for messages . Please refer to the official website for details (https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Wire-Format)
  
  scanner Code generation
• In general , If a set of protocol specifications is defined . Basically, there will be a set , The corresponding code generation method .Wayland Protocol code generation , Be similar to AIDL、FIDL Equal interface protocol . Here's the picture , Following the protocol specification xml file ( The contents of the document , according to wayland Protocol interface specification preparation ), utilize wayland Tools provided , Generate the corresponding source file .
  

Wayland agreement

• wayland The performance of the agreement is , A series of Interface The combination of .Interface Include Request and Event.
• A series of Interface In two parts ,Core And extension , among Core by wayland Provisions of the agreement , Must be realized Interface.
  

Protocol semantic syntax

Code generation

• Be careful , The following generated source files , Just related Interface The definition of . Just the definition of the interface , About the implementation of interface definition , In another part （ for example weston）.Interface Function realization , Not here .

#  Generate Client End file 
./scanner client-header wayland.xml wayland-client-protocol.h
#  Generate Server Header file 
./scanner server-header wayland.xml wayland-server-protocol.h
#  Generate common code 
./scanner code  wayland.xml wayland-protocol.c

The generated code is partially intercepted

• wayland-server-protocol.h

@ingroup iface_wl_display										
@struct wl_display_interface										
/										
struct wl_display_interface {
    		// wl_display +interface 
/** asynchronous roundtrip //  This comment follows the above xml It's the same  The sync request asks the server to emit the ‘done’ event on the returned wl_callback object. Since requests are handled in-order and events are delivered in-order, this can be used as a barrier to ensure all previous requests and the resulting events have been handled. The object returned by this request will be destroyed by the compositor after the callback is fired and as such the client must not attempt to use it after that point. The callback_data passed in the callback is the event serial. / void (*sync)(struct wl_client *client, // Server The interface of the end , Define as a function pointer  struct wl_resource *resource, // client +resource yes wayland The protocol is automatically completed  uint32_t callback); //  In fact, it is similar to C++ Member function , There is an implicit this Pointer parameters are the same  /** get global registry object This request creates a registry object that allows the client to list and bind the global objects available from the compositor. / void (*get_registry)(struct wl_client *client, struct wl_resource *resource, uint32_t registry); }; #define WL_DISPLAY_ERROR 0 // Event(Error) The macro definition of  #define WL_DISPLAY_ERROR_SINCE_VERSION 1 #ifndef WL_DISPLAY_ERROR_ENUM // Enmu The definition of  #define WL_DISPLAY_ERROR_ENUM /** @ingroup iface_wl_display global error values These errors are global and can be emitted in response to any server request. / enum wl_display_error { /** server couldn’t find object / WL_DISPLAY_ERROR_INVALID_OBJECT = 0, /** method doesn’t exist on the specified interface / WL_DISPLAY_ERROR_INVALID_METHOD = 1, /** server is out of memory / WL_DISPLAY_ERROR_NO_MEMORY = 2, }; #endif /* WL_DISPLAY_ERROR_ENUM */										
										

• wayland-client-protocol.h

// define WL_DISPLAY_SYNC 0 //  Method defined macro (OpeID) 
										
										
/** @ingroup iface_wl_display The sync request asks the server to emit the ‘done’ event on the returned wl_callback object. Since requests are handled in-order and events are delivered in-order, this can be used as a barrier to ensure all previous requests and the resulting events have been handled. The object returned by this request will be destroyed by the compositor after the callback is fired and as such the client must not attempt to use it after that point. The callback_data passed in the callback is the event serial. / static inline struct wl_callback * wl_display_sync(struct wl_display *wl_display) // Client End   Corresponding interface  { struct wl_proxy *callback; callback = wl_proxy_marshal_constructor((struct wl_proxy *) wl_display, WL_DISPLAY_SYNC, &wl_callback_interface, NULL); return (struct wl_callback *) callback; } /** @ingroup iface_wl_display @struct wl_display_listener / struct wl_display_listener { // Client End  Event Interface  /** fatal error event The error event is sent out when a fatal (non-recoverable) error has occurred. The object_id argument is the object where the error occurred, most often in response to a request to that object. The code identifies the error and is defined by the object interface. As such, each interface defines its own set of error codes. The message is an brief description of the error, for (debugging) convenience. / void (*error)(void *data, struct wl_display *wl_display, void *object_id, uint32_t code, const char *message); /** acknowledge object ID deletion This event is used internally by the object ID management logic. When a client deletes an object, the server will send this event to acknowledge that it has seen the delete request. When the client receive this event, it will know that it can safely reuse the object ID. / void (*delete_id)(void *data, struct wl_display *wl_display, uint32_t id); }; 

• wayland-protocol.c

”static const struct wl_message wl_display_requests[] = {
     // request 
{
     “sync”, “n”, types + 8 },							
{
     “get_registry”, “n”, types + 9 },								
};								
								
static const struct wl_message wl_display_events[] = {
    	 // event 
{
     “error”, “ous”, types + 0 },								
{
     “delete_id”, “u”, types + 0 },								
};								
								
WL_EXPORT const struct wl_interface wl_display_interface = {
     // interface 
“wl_display”, 1,								
2, wl_display_requests,								
2, wl_display_events,								
};