2 * Copyright © 2008 Kristian Høgsberg
4 * Permission to use, copy, modify, distribute, and sell this software and its
5 * documentation for any purpose is hereby granted without fee, provided that
6 * the above copyright notice appear in all copies and that both that copyright
7 * notice and this permission notice appear in supporting documentation, and
8 * that the name of the copyright holders not be used in advertising or
9 * publicity pertaining to distribution of the software without specific,
10 * written prior permission. The copyright holders make no representations
11 * about the suitability of this software for any purpose. It is provided "as
12 * is" without express or implied warranty.
14 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
15 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
16 * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
17 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
18 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
19 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
23 #ifndef _WAYLAND_CLIENT_H
24 #define _WAYLAND_CLIENT_H
26 #include "wayland-util.h"
27 #include "wayland-version.h"
35 * \brief Represents a protocol object on the client side.
37 * A wl_proxy acts as a client side proxy to an object existing in the
38 * compositor. The proxy is responsible for converting requests made by the
39 * clients with \ref wl_proxy_marshal() into Wayland's wire format. Events
40 * coming from the compositor are also handled by the proxy, which will in
41 * turn call the handler set with \ref wl_proxy_add_listener().
43 * \note With the exception of function \ref wl_proxy_set_queue(), functions
44 * accessing a \ref wl_proxy are not normally used by client code. Clients
45 * should normally use the higher level interface generated by the scanner to
46 * interact with compositor objects.
53 * \brief Represents a connection to the compositor and acts as a proxy to
54 * the wl_display singleton object.
56 * A \ref wl_display object represents a client connection to a Wayland
57 * compositor. It is created with either \ref wl_display_connect() or
58 * \ref wl_display_connect_to_fd(). A connection is terminated using
59 * \ref wl_display_disconnect().
61 * A \ref wl_display is also used as the \ref wl_proxy for the \ref wl_display
62 * singleton object on the compositor side.
64 * A \ref wl_display object handles all the data sent from and to the
65 * compositor. When a \ref wl_proxy marshals a request, it will write its wire
66 * representation to the display's write buffer. The data is sent to the
67 * compositor when the client calls \ref wl_display_flush().
69 * Incoming data is handled in two steps: queueing and dispatching. In the
70 * queue step, the data coming from the display fd is interpreted and
71 * added to a queue. On the dispatch step, the handler for the incoming
72 * event set by the client on the corresponding \ref wl_proxy is called.
74 * A \ref wl_display has at least one event queue, called the <em>main
75 * queue</em>. Clients can create additional event queues with \ref
76 * wl_display_create_queue() and assign \ref wl_proxy's to it. Events
77 * occurring in a particular proxy are always queued in its assigned queue.
78 * A client can ensure that a certain assumption, such as holding a lock
79 * or running from a given thread, is true when a proxy event handler is
80 * called by assigning that proxy to an event queue and making sure that
81 * this queue is only dispatched when the assumption holds.
83 * The main queue is dispatched by calling \ref wl_display_dispatch().
84 * This will dispatch any events queued on the main queue and attempt
85 * to read from the display fd if its empty. Events read are then queued
86 * on the appropriate queues according to the proxy assignment. Calling
87 * that function makes the calling thread the <em>main thread</em>.
89 * A user created queue is dispatched with \ref wl_display_dispatch_queue().
90 * If there are no events to dispatch this function will block. If this
91 * is called by the main thread, this will attempt to read data from the
92 * display fd and queue any events on the appropriate queues. If calling
93 * from any other thread, the function will block until the main thread
94 * queues an event on the queue being dispatched.
96 * A real world example of event queue usage is Mesa's implementation of
97 * eglSwapBuffers() for the Wayland platform. This function might need
98 * to block until a frame callback is received, but dispatching the main
99 * queue could cause an event handler on the client to start drawing
100 * again. This problem is solved using another event queue, so that only
101 * the events handled by the EGL code are dispatched during the block.
103 * This creates a problem where the main thread dispatches a non-main
104 * queue, reading all the data from the display fd. If the application
105 * would call \em poll(2) after that it would block, even though there
106 * might be events queued on the main queue. Those events should be
107 * dispatched with \ref wl_display_dispatch_pending() before
108 * flushing and blocking.
112 /** \class wl_event_queue
114 * \brief A queue for \ref wl_proxy object events.
116 * Event queues allows the events on a display to be handled in a thread-safe
117 * manner. See \ref wl_display for details.
120 struct wl_event_queue;
122 void wl_event_queue_destroy(struct wl_event_queue *queue);
124 void wl_proxy_marshal(struct wl_proxy *p, uint32_t opcode, ...);
125 struct wl_proxy *wl_proxy_create(struct wl_proxy *factory,
126 const struct wl_interface *interface);
128 void wl_proxy_destroy(struct wl_proxy *proxy);
129 int wl_proxy_add_listener(struct wl_proxy *proxy,
130 void (**implementation)(void), void *data);
131 void wl_proxy_set_user_data(struct wl_proxy *proxy, void *user_data);
132 void *wl_proxy_get_user_data(struct wl_proxy *proxy);
133 uint32_t wl_proxy_get_id(struct wl_proxy *proxy);
134 void wl_proxy_set_queue(struct wl_proxy *proxy, struct wl_event_queue *queue);
136 #include "wayland-client-protocol.h"
138 typedef int (*wl_display_update_func_t)(uint32_t mask, void *data);
139 typedef void (*wl_callback_func_t)(void *data, uint32_t time);
141 struct wl_display *wl_display_connect(const char *name);
142 struct wl_display *wl_display_connect_to_fd(int fd);
143 void wl_display_disconnect(struct wl_display *display);
144 int wl_display_get_fd(struct wl_display *display);
145 int wl_display_dispatch(struct wl_display *display);
146 int wl_display_dispatch_queue(struct wl_display *display,
147 struct wl_event_queue *queue);
148 int wl_display_dispatch_pending(struct wl_display *display);
149 int wl_display_get_error(struct wl_display *display);
151 int wl_display_flush(struct wl_display *display);
152 int wl_display_roundtrip(struct wl_display *display);
153 struct wl_event_queue *wl_display_create_queue(struct wl_display *display);
155 void wl_log_set_handler_client(wl_log_func_t handler);