Wayland agreement description
Wayland basic concepts
What is wayland?
- It is a window management protocol. Simply understand, Wayland is a set of communication protocol between Display Server and Display Client. Wayland defines a set of standard protocols and specifies the core objects in this set of protocols( https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Interfaces).
What is Weston‘
- Wayland is just a set of agreements, a set of specifications. Weston is a set of reference implementations of Wayland composer on the official website of Wayland.
Without going into the details, Weston can be simply understood as a set of window management components officially given by Wayland and following the Wayland agreement.
Several concepts
- Asynchronous object-oriented protocol: all requests in wayland are method calls to "objects". The requests here can be understood as function requests from the Client to the Server.
- Message based protocol: Wayland is a message based protocol. The Server and Client interact through messages. Wayland protocol specifies the fixed format of messages. Please refer to the official website for details( https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Wire-Format)
scanner code generation - Generally speaking, if a set of protocol specifications is defined, there will basically be a set of corresponding code generation methods. Wayland protocol code generation is similar to AIDL, FIDL and other interface protocols. As shown in the figure below, follow the xml file of the protocol specification (the file content is written according to Wayland protocol interface specification) and use the tools provided by Wayland to generate the corresponding source file.
Wayland agreement
- wayland protocol is a combination of a series of interfaces, including Request and Event.
- A series of interfaces are divided into two parts: core and extension. Core is the Interface that must be implemented according to wayland protocol.
Protocol semantic syntax
code generation
- Note that the following generated source file is only the definition of the relevant Interface. It is only the definition of the Interface. The implementation of the Interface definition is in another part (e.g. weston). The implementation of the Interface function is not introduced here.
# Generate Client side 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
Partial interception of generated code
- wayland-server-protocol.h
@ingroup iface_wl_display
@struct wl_display_interface
/
struct wl_display_interface { // wl_display +interface
/**
asynchronous roundtrip // This comment is the same as the xml above
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 is defined in the form of function pointer
struct wl_resource *resource, // client +resource It is automatically completed by wayland protocol
uint32_t callback); // In fact, it is similar to the implicit this pointer parameter in C + + member functions
/**
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)Macro definition for
#define WL_DISPLAY_ERROR_SINCE_VERSION 1
#ifndef WL_DISPLAY_ERROR_ENUM // Enmu 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) // Corresponding interface of Client side
{
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 side 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,
};