NAME

       wayland::display_t - Represents a connection to the compositor and acts as a proxy to the
       display singleton object.

SYNOPSIS

       #include <wayland-client.hpp>

       Inherits wayland::proxy_t.

   Public Types
       enum class wrapper_type { standard, display, foreign, proxy_wrapper }

   Public Member Functions
       display_t (int fd)
           Connect to Wayland display on an already open fd.
       display_t (const std::string &name={})
           Connect to a Wayland display.
       display_t (wl_display *display)
           Use an existing connection to a Wayland display to construct a waylandpp display_t.
       ~display_t () noexcept=default
           Close a connection to a Wayland display.
       event_queue_t create_queue () const
           Create a new event queue for this display.
       int get_fd () const
           Get a display context's file descriptor.
       int roundtrip () const
           Block until all pending request are processed by the server.
       int roundtrip_queue (const event_queue_t &queue) const
           Block until all pending request are processed by the server.
       read_intent obtain_read_intent () const
           Announce calling thread's intention to read events from the Wayland display file
           descriptor.
       read_intent obtain_queue_read_intent (const event_queue_t &queue) const
           Announce calling thread's intention to read events from the Wayland display file
           descriptor.
       int dispatch_queue (const event_queue_t &queue) const
           Dispatch events in an event queue.
       int dispatch_queue_pending (const event_queue_t &queue) const
           Dispatch pending events in an event queue.
       int dispatch () const
           Process incoming events.
       int dispatch_pending () const
           Dispatch main queue events without reading from the display fd.
       int get_error () const
           Retrieve the last error that occurred on a display.
       std::tuple< int, bool > flush () const
           Send all buffered requests on the display to the server.
       callback_t sync ()
           asynchronous roundtrip
       registry_t get_registry ()
           get global registry object
       display_t proxy_create_wrapper ()
           create proxy wrapper for this display
       uint32_t get_id () const
           Get the id of a proxy object.
       std::string get_class () const
           Get the interface name (class) of a proxy object.
       uint32_t get_version () const
           Get the protocol object version of a proxy object.
       wrapper_type get_wrapper_type () const
           Get the type of a proxy object.
       void set_queue (event_queue_t queue)
           Assign a proxy to an event queue.
       wl_proxy * c_ptr () const
           Get a pointer to the underlying C struct.
       bool proxy_has_object () const
           Check whether this wrapper actually wraps an object.
       operator bool () const
           Check whether this wrapper actually wraps an object.
       bool operator== (const proxy_t &right) const
           Check whether two wrappers refer to the same object.
       bool operator!= (const proxy_t &right) const
           Check whether two wrappers refer to different objects.
       void proxy_release ()
           Release the wrapped object (if any), making this an empty wrapper.

Detailed Description

       Represents a connection to the compositor and acts as a proxy to the display singleton
       object.

       A display_t object represents a client connection to a Wayland compositor. It is created
       with display_t::display_t(). A connection is terminated using display_t::~display_t().

       A display_t is also used as the proxy for the display singleton object on the compositor
       side. A display_t object handles all the data sent from and to the compositor. When a
       proxy_t marshals a request, it will write its wire representation to the display's write
       buffer. The data is sent to the compositor when the client calls display_t::flush().

       Incoming data is handled in two steps: queueing and dispatching. In the queue step, the
       data coming from the display fd is interpreted and added to a queue. On the dispatch step,
       the handler for the incoming event set by the client on the corresponding proxy_t is
       called.

       A display has at least one event queue, called the main queue. Clients can create
       additional event queues with display_t::create_queue() and assign proxy_t's to it. Events
       occurring in a particular proxy are always queued in its assigned queue. A client can
       ensure that a certain assumption, such as holding a lock or running from a given thread,
       is true when a proxy event handler is called by assigning that proxy to an event queue and
       making sure that this queue is only dispatched when the assumption holds.

       The main queue is dispatched by calling display_t::dispatch(). This will dispatch any
       events queued on the main queue and attempt to read from the display fd if its empty.
       Events read are then queued on the appropriate queues according to the proxy assignment.
       Calling that function makes the calling thread the main thread.

       A user created queue is dispatched with display_t::dispatch_queue(). If there are no
       events to dispatch this function will block. If this is called by the main thread, this
       will attempt to read data from the display fd and queue any events on the appropriate
       queues. If calling from any other thread, the function will block until the main thread
       queues an event on the queue being dispatched.

       A real world example of event queue usage is Mesa's implementation of eglSwapBuffers() for
       the Wayland platform. This function might need to block until a frame callback is
       received, but dispatching the main queue could cause an event handler on the client to
       start drawing again. This problem is solved using another event queue, so that only the
       events handled by the EGL code are dispatched during the block.

       This creates a problem where the main thread dispatches a non-main queue, reading all the
       data from the display fd. If the application would call poll(2) after that it would block,
       even though there might be events queued on the main queue. Those events should be
       dispatched with display_t::dispatch_pending() before flushing and blocking.

       Examples
           dump.cpp, egl.cpp, foreign_display.cpp, proxy_wrapper.cpp, and shm.cpp.

       Definition at line 478 of file wayland-client.hpp.

Member Enumeration Documentation

   enum class wayland::proxy_t::wrapper_type [strong],  [inherited]
       Underlying wl_proxy type and properties of a proxy_t that affect construction,
       destruction, and event handling

       Enumerator

       standard
              C pointer is a standard type compatible with wl_proxy*. Events are dispatched and
              it is destructed when the proxy_t is destructed. User data is set.

       display
              C pointer is a wl_display*. No events are dispatched, wl_display_disconnect is
              called when the proxy_t is destructed. User data is set.

       foreign
              C pointer is a standard type compatible with wl_proxy*, but another library owns it
              and it should not be touched in a way that could affect the operation of the other
              library. No events are dispatched, wl_proxy_destroy is not called when the proxy_t
              is destructed, user data is not touched. Consequently, there is no reference
              counting for the proxy_t. Lifetime of such wrappers should preferably be short to
              minimize the chance that the owning library decides to destroy the wl_proxy.

       proxy_wrapper
              C pointer is a wl_proxy* that was constructed with wl_proxy_create_wrapper. No
              events are dispatched, wl_proxy_wrapper_destroy is called when the proxy_t is
              destroyed. Reference counting is active. A reference to the proxy_t creating this
              proxy wrapper is held to extend its lifetime until after the proxy wrapper is
              destroyed.

       Definition at line 116 of file wayland-client.hpp.

Constructor & Destructor Documentation

   wayland::display_t::display_t (int fd)
       Connect to Wayland display on an already open fd.

       Parameters
           fd The fd to use for the connection

       The display_t takes ownership of the fd and will close it when the display is destroyed.
       The fd will also be closed in case of failure.

   wayland::display_t::display_t (const std::string & name = {})
       Connect to a Wayland display.

       Parameters
           name Optional name of the Wayland display to connect to

       Connect to the Wayland display named name. If name is empty, its value will be replaced
       with the WAYLAND_DISPLAY environment variable if it is set, otherwise display 'wayland-0'
       will be used.

   wayland::display_t::display_t (wl_display * display) [explicit]
       Use an existing connection to a Wayland display to construct a waylandpp display_t.

       Parameters
           display C wl_display pointer to use; must not be nullptr

       A wl_display* that was already established using the C wayland-client API is wrapped in an
       waylandpp display_t instance so it can be used easily from C++. Ownership of the display
       is not taken, so this may be used for wrapping a wl_display connection established by
       another library.

       On destruction of the display_t, wl_display_disconnect is not called and no resources are
       freed. It is the responsibility of the caller to make sure that the wl_display and the
       display_t are not used simultaneously in incompatible ways. It is especially problematic
       if the wl_display is destroyed while the display_t wrapper is still being used.

       Whether the wl_display or the display_t is destructed first ultimately does not matter,
       but any waylandpp proxy_t instances must be destructed or have their owned objects
       released before the wl_display is destroyed. Otherwise, the proxy_t destructor will try to
       free the underlying wl_proxy that was already destroyed together with the wl_display.

   wayland::display_t::~display_t () [default],  [noexcept]
       Close a connection to a Wayland display. Close the connection to display and free all
       resources associated with it. This does not apply to display_t instances that are wrappers
       for a pre-established C wl_display.

Member Function Documentation

   wl_proxy * wayland::proxy_t::c_ptr () const [inherited]
       Get a pointer to the underlying C struct.

       Returns
           The underlying wl_proxy wrapped by this proxy_t if it exists, otherwise an exception
           is thrown

   event_queue_t wayland::display_t::create_queue () const
       Create a new event queue for this display.

       Returns
           A new event queue associated with this display or NULL on failure.

       Examples
           proxy_wrapper.cpp.

   int wayland::display_t::dispatch () const
       Process incoming events.

       Returns
           The number of dispatched events

       Exceptions
           std::system_error on failure

       Dispatch the display's main event queue.

       If the main event queue is empty, this function blocks until there are events to be read
       from the display fd. Events are read and queued on the appropriate event queues. Finally,
       events on the main event queue are dispatched.

       Note: It is not possible to check if there are events on the main queue or not. For
       dispatching main queue events without blocking, see display_t::dispatch_pending(). Calling
       this will release the display file descriptor if this thread acquired it using
       display_t::acquire_fd().

       See also: display_t::dispatch_pending(), display_t::dispatch_queue()

       Examples
           egl.cpp, and shm.cpp.

   int wayland::display_t::dispatch_pending () const
       Dispatch main queue events without reading from the display fd.

       Returns
           The number of dispatched events

       Exceptions
           std::system_error on failure

       This function dispatches events on the main event queue. It does not attempt to read the
       display fd and simply returns zero if the main queue is empty, i.e., it doesn't block.

       This is necessary when a client's main loop wakes up on some fd other than the display fd
       (network socket, timer fd, etc) and calls wl_display_dispatch_queue() from that callback.
       This may queue up events in the main queue while reading all data from the display fd.
       When the main thread returns to the main loop to block, the display fd no longer has data,
       causing a call to poll(2) (or similar functions) to block indefinitely, even though there
       are events ready to dispatch.

       To proper integrate the wayland display fd into a main loop, the client should always call
       display_t::dispatch_pending() and then display_t::flush() prior to going back to sleep. At
       that point, the fd typically doesn't have data so attempting I/O could block, but events
       queued up on the main queue should be dispatched.

       A real-world example is a main loop that wakes up on a timerfd (or a sound card fd
       becoming writable, for example in a video player), which then triggers GL rendering and
       eventually eglSwapBuffers(). eglSwapBuffers() may call display_t::dispatch_queue() if it
       didn't receive the frame event for the previous frame, and as such queue events in the
       main queue. Note: Calling this makes the current thread the main one.

       See also: display_t::dispatch(), display_t::dispatch_queue(), display_t::flush()

   int wayland::display_t::dispatch_queue (const event_queue_t & queue) const
       Dispatch events in an event queue.

       Parameters
           queue The event queue to dispatch

       Returns
           The number of dispatched events

       Exceptions
           std::system_error on failure

       Dispatch all incoming events for objects assigned to the given event queue. On failure -1
       is returned and errno set appropriately.

       This function blocks if there are no events to dispatch. If calling from the main thread,
       it will block reading data from the display fd. For other threads this will block until
       the main thread queues events on the queue passed as argument.

   int wayland::display_t::dispatch_queue_pending (const event_queue_t & queue) const
       Dispatch pending events in an event queue.

       Parameters
           queue The event queue to dispatch

       Returns
           The number of dispatched events

       Exceptions
           std::system_error on failure

       Dispatch all incoming events for objects assigned to the given event queue. On failure -1
       is returned and errno set appropriately. If there are no events queued, this function
       returns immediately.

   std::tuple< int, bool > wayland::display_t::flush () const
       Send all buffered requests on the display to the server.

       Returns
           Tuple of the number of bytes sent and whether all data was sent.

       Exceptions
           std::system_error on failure

       Send all buffered data on the client side to the server. Clients should call this function
       before blocking. On success, the number of bytes sent to the server is returned.

       display_t::flush() never blocks. It will write as much data as possible, but if all data
       could not be written, the second element in the returned tuple will be set to false. In
       that case, use poll on the display file descriptor to wait for it to become writable
       again.

   std::string wayland::proxy_t::get_class () const [inherited]
       Get the interface name (class) of a proxy object.

       Returns
           The interface name of the object associated with the proxy

   int wayland::display_t::get_error () const
       Retrieve the last error that occurred on a display.

       Returns
           The last error that occurred on display or 0 if no error occurred

       Return the last error that occurred on the display. This may be an error sent by the
       server or caused by the local client.

       Note: Errors are fatal. If this function returns non-zero the display can no longer be
       used.

   int wayland::display_t::get_fd () const
       Get a display context's file descriptor.

       Returns
           Display object file descriptor

       Return the file descriptor associated with a display so it can be integrated into the
       client's main loop.

   uint32_t wayland::proxy_t::get_id () const [inherited]
       Get the id of a proxy object.

       Returns
           The id the object associated with the proxy

   registry_t wayland::display_t::get_registry ()
       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.

       Examples
           dump.cpp, egl.cpp, proxy_wrapper.cpp, and shm.cpp.

   uint32_t wayland::proxy_t::get_version () const [inherited]
       Get the protocol object version of a proxy object. Gets the protocol object version of a
       proxy object, or 0 if the proxy was created with unversioned API.

       A returned value of 0 means that no version information is available, so the caller must
       make safe assumptions about the object's real version.

       display_t will always return version 0.

       Returns
           The protocol object version of the proxy or 0

   wrapper_type wayland::proxy_t::get_wrapper_type () const [inline],  [inherited]
       Get the type of a proxy object.

       Definition at line 302 of file wayland-client.hpp.

   read_intent wayland::display_t::obtain_queue_read_intent (const event_queue_t & queue) const
       Announce calling thread's intention to read events from the Wayland display file
       descriptor.

       Parameters
           queue event queue for which the read event will be valid

       Returns
           New read_intent for this display and the specified event queue

       Exceptions
           std::system_error on failure

       See obtain_read_intent for details.

   read_intent wayland::display_t::obtain_read_intent () const
       Announce calling thread's intention to read events from the Wayland display file
       descriptor. This ensures that until the thread is ready to read and calls
       read_intent::read, no other thread will read from the file descriptor. During preparation,
       all undispatched events in the event queue are dispatched until the queue is empty.

       Use this function before polling on the display fd or to integrate the fd into a toolkit
       event loop in a race-free way.

       Typical usage is:

       auto read_intent = display.obtain_read_intent();
       display.flush();
       poll(fds, nfds, -1); // Custom poll() handling is possible here
       if(fd.revents & POLLIN)
         read_intent.read();
       display.dispatch_pending();

       The read_intent ensures that if the above code e.g. throws an exception before actually
       reading from the file descriptor or times out in poll(), the read intent is always
       cancelled so other threads can proceed.

       In one thread, do not hold more than one read intent for the same display at the same
       time, irrespective of the event queue.

       Returns
           New read_intent for this display and the default event queue

       Exceptions
           std::system_error on failure

   wayland::proxy_t::operator bool () const [inherited]
       Check whether this wrapper actually wraps an object.

       Returns
           true if there is an underlying object, false if this wrapper is empty

   bool wayland::proxy_t::operator!= (const proxy_t & right) const [inherited]
       Check whether two wrappers refer to different objects.

   bool wayland::proxy_t::operator== (const proxy_t & right) const [inherited]
       Check whether two wrappers refer to the same object.

   display_t wayland::display_t::proxy_create_wrapper ()
       create proxy wrapper for this display

       Examples
           proxy_wrapper.cpp.

   bool wayland::proxy_t::proxy_has_object () const [inherited]
       Check whether this wrapper actually wraps an object.

       Returns
           true if there is an underlying object, false if this wrapper is empty

   void wayland::proxy_t::proxy_release () [inherited]
       Release the wrapped object (if any), making this an empty wrapper. Note that display_t
       instances cannot be released this way. Attempts to do so are ignored.

       Examples
           foreign_display.cpp.

   int wayland::display_t::roundtrip () const
       Block until all pending request are processed by the server.

       Returns
           The number of dispatched events

       Exceptions
           std::system_error on failure

       Blocks until the server process all currently issued requests and sends out pending events
       on all event queues.

       Examples
           dump.cpp, egl.cpp, and shm.cpp.

   int wayland::display_t::roundtrip_queue (const event_queue_t & queue) const
       Block until all pending request are processed by the server.

       Returns
           The number of dispatched events

       Exceptions
           std::system_error on failure

       Blocks until the server processes all currently issued requests and sends out pending
       events on the event queue.

       Note: This function uses dispatch_queue() internally. If you are using read_events() from
       more threads, don't use this function (or make sure that calling roundtrip_queue() doesn't
       interfere with calling prepare_read() and read_events())

       Examples
           proxy_wrapper.cpp.

   void wayland::proxy_t::set_queue (event_queue_t queue) [inherited]
       Assign a proxy to an event queue.

       Parameters
           queue The event queue that will handle this proxy

       Assign proxy to event queue. Events coming from proxy will be queued in queue instead of
       the display's main queue.

       See also: display_t::dispatch_queue().

       Examples
           proxy_wrapper.cpp.

   callback_t wayland::display_t::sync ()
       asynchronous roundtrip The sync request asks the server to emit the 'done' event on the
       returned callback_t 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.

Author

       Generated automatically by Doxygen for Wayland++ from the source code.