From 8d490fdb34ad4374b3ab144f1b46296eb81ad316 Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Mon, 19 Mar 2018 15:46:28 -0400 Subject: [PATCH] Write some more docs --- include/wlr/backend.h | 23 +++++++++++++++++++++++ include/wlr/backend/drm.h | 7 +++++++ include/wlr/backend/headless.h | 14 ++++++++++++++ include/wlr/backend/interface.h | 4 ++++ include/wlr/backend/libinput.h | 4 +++- include/wlr/backend/multi.h | 10 ++++++++++ 6 files changed, 61 insertions(+), 1 deletion(-) diff --git a/include/wlr/backend.h b/include/wlr/backend.h index 00dc9fdc..e3b14add 100644 --- a/include/wlr/backend.h +++ b/include/wlr/backend.h @@ -11,16 +11,39 @@ struct wlr_backend { const struct wlr_backend_impl *impl; struct { + /** Raised when destroyed, passed the wlr_backend reference */ struct wl_signal destroy; + /** Raised when new inputs are added, passed the wlr_input_device */ struct wl_signal new_input; + /** Raised when new outputs are added, passed the wlr_output */ struct wl_signal new_output; } events; }; +/** + * Automatically initializes the most suitable backend given the environment. + * Will always return a multibackend. The backend is created but not started. + * Returns NULL on failure. + */ struct wlr_backend *wlr_backend_autocreate(struct wl_display *display); +/** + * Start the backend. This may signal new_input or new_output immediately, but + * may also wait until the display's event loop begins. Returns false on + * failure. + */ bool wlr_backend_start(struct wlr_backend *backend); +/** + * Destroy the backend and clean up all of its resources. Normally called + * automatically when the wl_display is destroyed. + */ void wlr_backend_destroy(struct wlr_backend *backend); +/** + * Obtains the wlr_egl reference this backend is using. + */ struct wlr_egl *wlr_backend_get_egl(struct wlr_backend *backend); +/** + * Obtains the wlr_renderer reference this backend is using. + */ struct wlr_renderer *wlr_backend_get_renderer(struct wlr_backend *backend); uint32_t usec_to_msec(uint64_t usec); diff --git a/include/wlr/backend/drm.h b/include/wlr/backend/drm.h index 90460647..0c9e5c8b 100644 --- a/include/wlr/backend/drm.h +++ b/include/wlr/backend/drm.h @@ -6,6 +6,13 @@ #include #include +/** + * Creates a DRM backend using the specified GPU file descriptor (typically from + * a device node in /dev/dri). + * + * To slave this to another DRM backend, pass it as the parent (which _must_ be + * a DRM backend, other kinds of backends raise SIGABRT). + */ struct wlr_backend *wlr_drm_backend_create(struct wl_display *display, struct wlr_session *session, int gpu_fd, struct wlr_backend *parent); diff --git a/include/wlr/backend/headless.h b/include/wlr/backend/headless.h index 8995f7cb..ee784a0d 100644 --- a/include/wlr/backend/headless.h +++ b/include/wlr/backend/headless.h @@ -5,9 +5,23 @@ #include #include +/** + * Creates a headless backend. A headless backend has no outputs or inputs by + * default. + */ struct wlr_backend *wlr_headless_backend_create(struct wl_display *display); +/** + * Create a new headless output backed by an in-memory EGL framebuffer. You can + * read pixels from this framebuffer via wlr_renderer_read_pixels but it is + * otherwise not displayed. + */ struct wlr_output *wlr_headless_add_output(struct wlr_backend *backend, unsigned int width, unsigned int height); +/** + * Creates a new input device. The caller is responsible for manually raising + * any event signals on the new input device if it wants to simulate input + * events. + */ struct wlr_input_device *wlr_headless_add_input_device( struct wlr_backend *backend, enum wlr_input_device_type type); bool wlr_backend_is_headless(struct wlr_backend *backend); diff --git a/include/wlr/backend/interface.h b/include/wlr/backend/interface.h index d9212795..f03e95d9 100644 --- a/include/wlr/backend/interface.h +++ b/include/wlr/backend/interface.h @@ -12,6 +12,10 @@ struct wlr_backend_impl { struct wlr_renderer *(*get_renderer)(struct wlr_backend *backend); }; +/** + * Initializes common state on a wlr_backend and sets the implementation to the + * provided wlr_backend_impl reference. + */ void wlr_backend_init(struct wlr_backend *backend, const struct wlr_backend_impl *impl); diff --git a/include/wlr/backend/libinput.h b/include/wlr/backend/libinput.h index c7cfe894..92d31415 100644 --- a/include/wlr/backend/libinput.h +++ b/include/wlr/backend/libinput.h @@ -9,7 +9,9 @@ struct wlr_backend *wlr_libinput_backend_create(struct wl_display *display, struct wlr_session *session); -struct libinput_device *wlr_libinput_get_device_handle(struct wlr_input_device *dev); +/** Gets the underlying libinput_device handle for the given wlr_input_device */ +struct libinput_device *wlr_libinput_get_device_handle( + struct wlr_input_device *dev); bool wlr_backend_is_libinput(struct wlr_backend *backend); bool wlr_input_device_is_libinput(struct wlr_input_device *device); diff --git a/include/wlr/backend/multi.h b/include/wlr/backend/multi.h index 2dee7403..842eed67 100644 --- a/include/wlr/backend/multi.h +++ b/include/wlr/backend/multi.h @@ -4,11 +4,21 @@ #include #include +/** + * Creates a multi-backend. Multi-backends wrap an arbitrary number of backends + * and aggregate their new_output/new_input signals. + */ struct wlr_backend *wlr_multi_backend_create(struct wl_display *display); +/** + * Adds the given backend to the multi backend. This should be done before the + * new backend is started. + */ void wlr_multi_backend_add(struct wlr_backend *multi, struct wlr_backend *backend); + void wlr_multi_backend_remove(struct wlr_backend *multi, struct wlr_backend *backend); + bool wlr_backend_is_multi(struct wlr_backend *backend); struct wlr_session *wlr_multi_get_session(struct wlr_backend *base); bool wlr_multi_is_empty(struct wlr_backend *backend);