Provided by: libwayland-dev_1.4.0-1ubuntu1_amd64 bug

NAME

       wl_display -

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

SYNOPSIS

       #include <wayland-client.h>

   Public Member Functions
       struct wl_event_queue * wl_display_create_queue (struct wl_display *display)
       struct wl_display * wl_display_connect_to_fd (int fd)
       struct wl_display * wl_display_connect (const char *name)
       void wl_display_disconnect (struct wl_display *display)
       int wl_display_get_fd (struct wl_display *display)
       int wl_display_roundtrip (struct wl_display *display)
       int wl_display_read_events (struct wl_display *display)
       int wl_display_prepare_read (struct wl_display *display)
       void wl_display_cancel_read (struct wl_display *display)
       int wl_display_dispatch_queue (struct wl_display *display, struct wl_event_queue *queue)
       int wl_display_dispatch_queue_pending (struct wl_display *display, struct wl_event_queue
           *queue)
       int wl_display_dispatch (struct wl_display *display)
       int wl_display_dispatch_pending (struct wl_display *display)
       int wl_display_get_error (struct wl_display *display)
       int wl_display_flush (struct wl_display *display)
       struct wl_client * wl_client_create (struct wl_display *display, int fd)
       uint32_t wl_display_get_serial (struct wl_display *display)
       uint32_t wl_display_next_serial (struct wl_display *display)
       uint32_t * wl_display_add_shm_format (struct wl_display *display, uint32_t format)
       struct wl_array * wl_display_get_additional_shm_formats (struct wl_display *display)

   Public Attributes
       struct wl_event_loop * loop
       int run
       uint32_t id
       uint32_t serial
       struct wl_list registry_resource_list
       struct wl_list global_list
       struct wl_list socket_list
       struct wl_list client_list
       struct wl_signal destroy_signal
       struct wl_array additional_shm_formats

Detailed Description

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

       A wl_display object represents a client connection to a Wayland compositor. It is created
       with either wl_display_connect() or wl_display_connect_to_fd(). A connection is terminated
       using wl_display_disconnect().

       A wl_display is also used as the wl_proxy for the wl_display singleton object on the
       compositor side.

       A wl_display object handles all the data sent from and to the compositor. When a wl_proxy
       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 wl_display_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 wl_proxy is
       called.

       A wl_display has at least one event queue, called the main queue. Clients can create
       additional event queues with wl_display_create_queue() and assign wl_proxy'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 wl_display_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 wl_display_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 wl_display_dispatch_pending() before flushing and blocking.

Member Function Documentation

   struct wl_client * wl_client_create (struct wl_display *display, intfd)
       Create a client for the given file descriptor

       Parameters:
           display The display object
           fd The file descriptor for the socket to the client

       Returns:
           The new client object or NULL on failure.

       Given a file descriptor corresponding to one end of a socket, this function will create a
       wl_client struct and add the new client to the compositors client list. At that point, the
       client is initialized and ready to run, as if the client had connected to the servers
       listening socket. When the client eventually sends requests to the compositor, the
       wl_client argument to the request handler will be the wl_client returned from this
       function.

       The other end of the socket can be passed to wl_display_connect_to_fd() on the client side
       or used with the WAYLAND_SOCKET environment variable on the client side.

       On failure this function sets errno accordingly and returns NULL.

   uint32_t * wl_display_add_shm_format (struct wl_display *display, uint32_tformat)
       Add support for a wl_shm pixel format

       Parameters:
           display The display object
           format The wl_shm pixel format to advertise

       Returns:
           A pointer to the wl_shm format that was added to the list or NULL if adding it to the
           list failed.

       Add the specified wl_shm format to the list of formats the wl_shm object advertises when a
       client binds to it. Adding a format to the list means that clients will know that the
       compositor supports this format and may use it for creating wl_shm buffers. The compositor
       must be able to handle the pixel format when a client requests it.

       The compositor by default supports WL_SHM_FORMAT_ARGB8888 and WL_SHM_FORMAT_XRGB8888.

   void wl_display_cancel_read (struct wl_display *display)
       Release exclusive access to display file descriptor

       Parameters:
           display The display context object

       This releases the exclusive access. Useful for canceling the lock when a timed out poll
       returns fd not readable and we're not going to read from the fd anytime soon.

   struct wl_display * wl_display_connect (const char *name)
       Connect to a Wayland display

       Parameters:
           name Name of the Wayland display to connect to

       Returns:
           A wl_display object or NULL on failure

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

   struct wl_display * wl_display_connect_to_fd (intfd)
       Connect to Wayland display on an already open fd

       Parameters:
           fd The fd to use for the connection

       Returns:
           A wl_display object or NULL on failure

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

   struct wl_event_queue * wl_display_create_queue (struct wl_display *display)
       Create a new event queue for this display

       Parameters:
           display The display context object

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

   void wl_display_disconnect (struct wl_display *display)
       Close a connection to a Wayland display

       Parameters:
           display The display context object

       Close the connection to display and free all resources associated with it.

   int wl_display_dispatch (struct wl_display *display)
       Process incoming events

       Parameters:
           display The display context object

       Returns:
           The number of dispatched events on success or -1 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 wl_display_dispatch_pending().

           Calling this will release the display file descriptor if this thread acquired it using
           wl_display_acquire_fd().

       See Also:
           wl_display_dispatch_pending(), wl_display_dispatch_queue()

   int wl_display_dispatch_pending (struct wl_display *display)
       Dispatch main queue events without reading from the display fd

       Parameters:
           display The display context object

       Returns:
           The number of dispatched events or -1 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
       wl_display_dispatch_pending() and then wl_display_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 wl_display_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:
           wl_display_dispatch(), wl_display_dispatch_queue(), wl_display_flush()

   int wl_display_dispatch_queue (struct wl_display *display, struct wl_event_queue *queue)
       Dispatch events in an event queue

       Parameters:
           display The display context object
           queue The event queue to dispatch

       Returns:
           The number of dispatched events on success or -1 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 wl_display_dispatch_queue_pending (struct wl_display *display, struct wl_event_queue
       *queue)
       Dispatch pending events in an event queue

       Parameters:
           display The display context object
           queue The event queue to dispatch

       Returns:
           The number of dispatched events on success or -1 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.

       Since:
           1.0.2

   int wl_display_flush (struct wl_display *display)
       Send all buffered requests on the display to the server

       Parameters:
           display The display context object

       Returns:
           The number of bytes sent on success or -1 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. On
       failure, this function returns -1 and errno is set appropriately.

       wl_display_flush() never blocks. It will write as much data as possible, but if all data
       could not be written, errno will be set to EAGAIN and -1 returned. In that case, use poll
       on the display file descriptor to wait for it to become writable again.

   struct wl_array * wl_display_get_additional_shm_formats (struct wl_display *display)
       Get list of additional wl_shm pixel formats

       Parameters:
           display The display object

       This function returns the list of addition wl_shm pixel formats that the compositor
       supports. WL_SHM_FORMAT_ARGB8888 and WL_SHM_FORMAT_XRGB8888 are always supported and not
       included in the array, but all formats added through wl_display_add_shm_format() will be
       in the array.

       See Also:
           wl_display_add_shm_format()

   int wl_display_get_error (struct wl_display *display)
       Retrieve the last error that occurred on a display

       Parameters:
           display The display context object

       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 wl_display_get_fd (struct wl_display *display)
       Get a display context's file descriptor

       Parameters:
           display The display context object

       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 wl_display_get_serial (struct wl_display *display)
       Get the current serial number

       Parameters:
           display The display object

       This function returns the most recent serial number, but does not increment it.

   uint32_t wl_display_next_serial (struct wl_display *display)
       Get the next serial number

       Parameters:
           display The display object

       This function increments the display serial number and returns the new value.

   int wl_display_prepare_read (struct wl_display *display)
       Prepare to read events after polling file descriptor

       Parameters:
           display The display context object

       Returns:
           0 on success or -1 if event queue was not empty

       This function must be called before reading from the file descriptor using
       wl_display_read_events(). Calling wl_display_prepare_read() announces the calling threads
       intention to read and ensures that until the thread is ready to read and calls
       wl_display_read_events(), no other thread will read from the file descriptor. This only
       succeeds if the event queue is empty though, and if there are undispatched events in the
       queue, -1 is returned and errno set to EAGAIN.

       If a thread successfully calls wl_display_prepare_read(), it must either call
       wl_display_read_events() when it's ready or cancel the read intention by calling
       wl_display_cancel_read().

       Use this function before polling on the display fd or to integrate the fd into a toolkit
       event loop in a race-free way. Typically, a toolkit will call
       wl_display_dispatch_pending() before sleeping, to make sure it doesn't block with
       unhandled events. Upon waking up, it will assume the file descriptor is readable and read
       events from the fd by calling wl_display_dispatch(). Simplified, we have:

       wl_display_dispatch_pending(display); wl_display_flush(display); poll(fds, nfds, -1);
       wl_display_dispatch(display);

       There are two races here: first, before blocking in poll(), the fd could become readable
       and another thread reads the events. Some of these events may be for the main queue and
       the other thread will queue them there and then the main thread will go to sleep in
       poll(). This will stall the application, which could be waiting for a event to kick of the
       next animation frame, for example.

       The other race is immediately after poll(), where another thread could preempt and read
       events before the main thread calls wl_display_dispatch(). This call now blocks and
       starves the other fds in the event loop.

       A correct sequence would be:

       while (wl_display_prepare_read(display) != 0) wl_display_dispatch_pending(display);
       wl_display_flush(display); poll(fds, nfds, -1); wl_display_read_events(display);
       wl_display_dispatch_pending(display);

       Here we call wl_display_prepare_read(), which ensures that between returning from that
       call and eventually calling wl_display_read_events(), no other thread will read from the
       fd and queue events in our queue. If the call to wl_display_prepare_read() fails, we
       dispatch the pending events and try again until we're successful.

   int wl_display_read_events (struct wl_display *display)
       Read events from display file descriptor

       Parameters:
           display The display context object

       Returns:
           0 on success or -1 on error. In case of error errno will be set accordingly

       This will read events from the file descriptor for the display. This function does not
       dispatch events, it only reads and queues events into their corresponding event queues. If
       no data is avilable on the file descriptor, wl_display_read_events() returns immediately.
       To dispatch events that may have been queued, call wl_display_dispatch_pending() or
       wl_display_dispatch_queue_pending().

       Before calling this function, wl_display_prepare_read() must be called first.

   int wl_display_roundtrip (struct wl_display *display)
       Block until all pending request are processed by the server

       Parameters:
           display The display context object

       Returns:
           The number of dispatched events on success or -1 on failure

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

Author

       Generated automatically by Doxygen for Wayland from the source code.