wayland.client.opaque_types source code

1 /+
2  +  Wayland copyright:
3  +  Copyright © 2008 Kristian Høgsberg
4  +
5  +  Permission is hereby granted, free of charge, to any person
6  +  obtaining a copy of this software and associated documentation files
7  +  (the "Software"), to deal in the Software without restriction,
8  +  including without limitation the rights to use, copy, modify, merge,
9  +  publish, distribute, sublicense, and/or sell copies of the Software,
10  +  and to permit persons to whom the Software is furnished to do so,
11  +  subject to the following conditions:
12  +
13  +  The above copyright notice and this permission notice (including the
14  +  next paragraph) shall be included in all copies or substantial
15  +  portions of the Software.
16  +
17  +  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18  +  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19  +  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20  +  NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
21  +  BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
22  +  ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
23  +  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24  +  SOFTWARE.
25  +/
26 /+
27  +  D bindings copyright:
28  +  Copyright © 2015 Rémi Thebault
29  +/
30 
31 module wayland.client.opaque_types;
32 
33 extern (C):
34 
35 struct wl_object;
36 
37 struct wl_client;
38 /** \class wl_proxy
39  *
40  * \brief Represents a protocol object on the client side.
41  *
42  * A wl_proxy acts as a client side proxy to an object existing in the
43  * compositor. The proxy is responsible for converting requests made by the
44  * clients with \ref wl_proxy_marshal() into Wayland's wire format. Events
45  * coming from the compositor are also handled by the proxy, which will in
46  * turn call the handler set with \ref wl_proxy_add_listener().
47  *
48  * \note With the exception of function \ref wl_proxy_set_queue(), functions
49  * accessing a wl_proxy are not normally used by client code. Clients
50  * should normally use the higher level interface generated by the scanner to
51  * interact with compositor objects.
52  *
53  */
54 struct wl_proxy;
55 
56 /** \class wl_display
57  *
58  * \brief Represents a connection to the compositor and acts as a proxy to
59  * the wl_display singleton object.
60  *
61  * A wl_display object represents a client connection to a Wayland
62  * compositor. It is created with either \ref wl_display_connect() or
63  * \ref wl_display_connect_to_fd(). A connection is terminated using
64  * \ref wl_display_disconnect().
65  *
66  * A wl_display is also used as the \ref wl_proxy for the wl_display
67  * singleton object on the compositor side.
68  *
69  * A wl_display object handles all the data sent from and to the
70  * compositor. When a \ref wl_proxy marshals a request, it will write its wire
71  * representation to the display's write buffer. The data is sent to the
72  * compositor when the client calls \ref wl_display_flush().
73  *
74  * Incoming data is handled in two steps: queueing and dispatching. In the
75  * queue step, the data coming from the display fd is interpreted and
76  * added to a queue. On the dispatch step, the handler for the incoming
77  * event set by the client on the corresponding \ref wl_proxy is called.
78  *
79  * A wl_display has at least one event queue, called the <em>default
80  * queue</em>. Clients can create additional event queues with \ref
81  * wl_display_create_queue() and assign \ref wl_proxy's to it. Events
82  * occurring in a particular proxy are always queued in its assigned queue.
83  * A client can ensure that a certain assumption, such as holding a lock
84  * or running from a given thread, is true when a proxy event handler is
85  * called by assigning that proxy to an event queue and making sure that
86  * this queue is only dispatched when the assumption holds.
87  *
88  * The default queue is dispatched by calling \ref wl_display_dispatch().
89  * This will dispatch any events queued on the default queue and attempt
90  * to read from the display fd if it's empty. Events read are then queued
91  * on the appropriate queues according to the proxy assignment.
92  *
93  * A user created queue is dispatched with \ref wl_display_dispatch_queue().
94  * This function behaves exactly the same as wl_display_dispatch()
95  * but it dispatches given queue instead of the default queue.
96  *
97  * A real world example of event queue usage is Mesa's implementation of
98  * eglSwapBuffers() for the Wayland platform. This function might need
99  * to block until a frame callback is received, but dispatching the default
100  * queue could cause an event handler on the client to start drawing
101  * again. This problem is solved using another event queue, so that only
102  * the events handled by the EGL code are dispatched during the block.
103  *
104  * This creates a problem where a thread dispatches a non-default
105  * queue, reading all the data from the display fd. If the application
106  * would call \em poll(2) after that it would block, even though there
107  * might be events queued on the default queue. Those events should be
108  * dispatched with \ref wl_display_dispatch_(queue_)pending() before
109  * flushing and blocking.
110  */
111 struct wl_display;
112 
113 /** \class wl_event_queue
114  *
115  * \brief A queue for \ref wl_proxy object events.
116  *
117  * Event queues allows the events on a display to be handled in a thread-safe
118  * manner. See \ref wl_display for details.
119  *
120  */
121 struct wl_event_queue;
122 struct wl_global;
123