[vlc-commits] window: improve documentation
Rémi Denis-Courmont
git at videolan.org
Mon Feb 18 19:38:24 CET 2019
vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Mon Feb 18 20:37:13 2019 +0200| [6fe6c26258bf71faaa77e36fc4f6dd121f662e7a] | committer: Rémi Denis-Courmont
window: improve documentation
> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=6fe6c26258bf71faaa77e36fc4f6dd121f662e7a
---
include/vlc_mouse.h | 2 +-
include/vlc_vout_window.h | 345 ++++++++++++++++++++++++++++++++++++++--------
2 files changed, 285 insertions(+), 62 deletions(-)
diff --git a/include/vlc_mouse.h b/include/vlc_mouse.h
index 4e1b813934..870f27ffb5 100644
--- a/include/vlc_mouse.h
+++ b/include/vlc_mouse.h
@@ -26,7 +26,7 @@
/**
* Mouse buttons
*/
-enum
+enum vlc_mouse_button
{
MOUSE_BUTTON_LEFT=0,
MOUSE_BUTTON_CENTER,
diff --git a/include/vlc_vout_window.h b/include/vlc_vout_window.h
index d0fc2a7294..3c29f6b2d2 100644
--- a/include/vlc_vout_window.h
+++ b/include/vlc_vout_window.h
@@ -30,19 +30,31 @@
/**
* \defgroup video_window Video window
* \ingroup video_output
- * Video output window management
+ * Window management
+ *
+ * Window management provides a partial abstraction for windowing systems and
+ * rendering targets (i.e. "windows"). See \ref vout_window_t.
+ *
* @{
* \file
- * Video output window modules interface
+ * Window modules interface
*/
-typedef struct vout_window_t vout_window_t;
-
+struct vout_window_t;
struct wl_display;
struct wl_surface;
/**
- * Window handle type
+ * Window handle type.
+ *
+ * The window handle type specifies the window system protocol that the
+ * window was created with. It determines which members of the
+ * vout_window_t::handle and vout_window_t::display unions are defined
+ * for the given window.
+ *
+ * It also establishes some protocol-dependent semantics such as the exact
+ * interpretation of the window state (\ref vout_window_state)
+ * and the window size.
*/
enum vout_window_type {
VOUT_WINDOW_TYPE_DUMMY /**< Dummy window (not an actual window) */,
@@ -54,32 +66,74 @@ enum vout_window_type {
};
/**
- * Window management state.
+ * Window states.
+ *
+ * Currently, this only handles different window stacking orders.
+ * See also \ref vout_window_SetState().
*/
enum vout_window_state {
- VOUT_WINDOW_STATE_NORMAL,
- VOUT_WINDOW_STATE_ABOVE,
- VOUT_WINDOW_STATE_BELOW,
+ VOUT_WINDOW_STATE_NORMAL /**< Normal stacking */,
+ VOUT_WINDOW_STATE_ABOVE /**< Stacking above (a.k.a. always on top) */,
+ VOUT_WINDOW_STATE_BELOW /**< Stacking below (a.k.a. wall paper mode) */,
};
/**
- * Window mouse event type for vout_window_mouse_event_t
+ * Window mouse event types.
+ *
+ * This enumeration defines the possible event types
+ * vout_window_mouse_event_t::type.
*/
enum vout_window_mouse_event_type {
- VOUT_WINDOW_MOUSE_MOVED,
- VOUT_WINDOW_MOUSE_PRESSED,
- VOUT_WINDOW_MOUSE_RELEASED,
- VOUT_WINDOW_MOUSE_DOUBLE_CLICK,
+ VOUT_WINDOW_MOUSE_MOVED /**< Pointer position change */,
+ VOUT_WINDOW_MOUSE_PRESSED /**< Pointer button press or single click */,
+ VOUT_WINDOW_MOUSE_RELEASED /**< Pointer button release */,
+ VOUT_WINDOW_MOUSE_DOUBLE_CLICK /**< Double click */,
};
/**
- * Window mouse event
+ * Window mouse event.
+ *
+ * This structure describes a pointer input event on a window.
*/
typedef struct vout_window_mouse_event_t
{
- enum vout_window_mouse_event_type type;
+ enum vout_window_mouse_event_type type; /**< Event type. */
+
+ /**
+ * Pointer abscissa.
+ *
+ * The pointer abscissa is relative to the window and expressed in pixels.
+ * Abscissa goes from left to right, such that the left-most column is at 0
+ * and the right-most column is at width minus one.
+ *
+ * A negative abscissa refers to pixels to the left of the window, and
+ * an abscissa of width or larger refers to pixels to the right.
+ *
+ * This is only set if @c event equals \ref VOUT_WINDOW_MOUSE_MOVED.
+ */
int x;
+
+ /**
+ * Pointer ordinate.
+ *
+ * The pointer ordinate is relative to the window and expressed in pixels.
+ * Ordinate goes from top to bottom, such that the top-most row is at 0
+ * and the bottom-most column is at height minus one.
+ *
+ * A negative ordinate refers to pixels above the window, and
+ * an ordinate of height or larger refers to pixels below the window.
+ *
+ * This is only set if @c event equals \ref VOUT_WINDOW_MOUSE_MOVED.
+ */
int y;
+
+ /**
+ * Pressed button.
+ *
+ * See \ref vlc_mouse_button for possible vaules.
+ *
+ * This is set if @c event does not equal \ref VOUT_WINDOW_MOUSE_MOVED.
+ */
int button_mask;
} vout_window_mouse_event_t;
@@ -118,44 +172,154 @@ typedef struct vout_window_cfg_t {
} vout_window_cfg_t;
+/**
+ * Window event callbacks structure.
+ *
+ * This structure provided to vout_window_New() conveys callbacks to handle
+ * window events.
+ *
+ * As a general rule, the events can occur synchronously or asynchronously from
+ * the time that the window is (succesfully) being created by vout_window_New()
+ * until the time that the window has been deleted by vout_window_Delete().
+ *
+ * \warning
+ * Also, a window object functions are not reentrant, so the callbacks must not
+ * invoke the window object functions.
+ * Otherwise a deadlock or infinite recursion may occur.
+ */
struct vout_window_callbacks {
- void (*resized)(vout_window_t *, unsigned width, unsigned height);
- void (*closed)(vout_window_t *);
- void (*state_changed)(vout_window_t *, unsigned state);
- void (*windowed)(vout_window_t *);
- void (*fullscreened)(vout_window_t *, const char *id);
+ /**
+ * Callback for window size changes.
+ *
+ * This callback function (if non-NULL) is invoked when the windowing
+ * system changes the window size.
+ *
+ * This event may occur synchronously when the window is created or a size
+ * change is requested. It may also occur asynchronously as a consequence
+ * of external events from the windowing system, or deferred processing of
+ * a size change request.
+ */
+ void (*resized)(struct vout_window_t *, unsigned width, unsigned height);
+
+ /**
+ * Callback for window closing.
+ *
+ * This callback function (if non-NULL) is invoked upon an external request
+ * to close the window. Not all windowing systems support this.
+ *
+ * Soon after this callback, the window should be disabled with
+ * vout_window_Disable().
+ *
+ * \warning Do not disable the window within the callback.
+ * That could lead to a dead lock.
+ */
+ void (*closed)(struct vout_window_t *);
+
+ /**
+ * Callback for window state change.
+ *
+ * This callback function (if non-NULL) is invoked when the window state
+ * as changed, either as a consequence of vout_window_SetSate() or external
+ * events.
+ *
+ * \bug Many window back-ends fail to invoke this callback when due.
+ *
+ * \param state new window state (see \ref vout_window_state).
+ */
+ void (*state_changed)(struct vout_window_t *, unsigned state);
- void (*mouse_event)(vout_window_t *,
+ /**
+ * Callback for windowed mode.
+ *
+ * This callback function (if non-NULL) is invoked when the window becomes
+ * windowed. It might also occur spuriously if the window remains windowed.
+ *
+ * \bug Many window back-ends fail to invoke this callback when due.
+ */
+ void (*windowed)(struct vout_window_t *);
+
+ /**
+ * Callback for fullscreen mode.
+ *
+ * This callback function (if non-NULL) is invoked when the window becomes
+ * fullscreen, when it changes to a different fullscreen output, or
+ * spuriously when the window remains in fullscreen mode.
+ *
+ * \bug Many window back-ends fail to invoke this callback when due.
+ *
+ * \param id fullscreen output identifier (NULL if unspecified)
+ */
+ void (*fullscreened)(struct vout_window_t *, const char *id);
+
+ /**
+ * Callback for pointer input events.
+ *
+ * This callback function (if non-NULL) is invoked upon any pointer input
+ * event on the window. See \ref vout_window_mouse_event_t.
+ *
+ * \param mouse pointer to the input event.
+ */
+ void (*mouse_event)(struct vout_window_t *,
const vout_window_mouse_event_t *mouse);
- void (*keyboard_event)(vout_window_t *, unsigned key);
- void (*output_event)(vout_window_t *, const char *id, const char *desc);
+ /**
+ * Callback for keyboard input events.
+ *
+ * This callback function (if non-NULL) is invoked upon any keyboard key
+ * press event, or repetition event, on the window.
+ *
+ * \note No events are delivered for keyboard key releases.
+ *
+ * \param key VLC key code
+ */
+ void (*keyboard_event)(struct vout_window_t *, unsigned key);
+
+ /**
+ * Callback for fullscreen output enumeration.
+ *
+ * This callback function (if non-NULL) indicates that a fullscreen output
+ * becomes available, changes human-readable description, or becomes
+ * unavailable.
+ *
+ * \param id nul-terminated id fullscreen output identifier
+ * (cannot be NULL)
+ * \param desc nul-terminated human-readable description,
+ * or NULL if the output has become unavailable
+ */
+ void (*output_event)(struct vout_window_t *,
+ const char *id, const char *desc);
};
+/**
+ * Window callbacks and opaque data.
+ */
+typedef struct vout_window_owner {
+ const struct vout_window_callbacks *cbs; /**< Callbacks */
+ void *sys; /**< Opaque data / private pointer for callbacks */
+} vout_window_owner_t;
+
+/**
+ * Window implementation callbacks.
+ */
struct vout_window_operations {
- int (*enable)(vout_window_t *, const vout_window_cfg_t *);
- void (*disable)(vout_window_t *);
- void (*resize)(vout_window_t *, unsigned width, unsigned height);
+ int (*enable)(struct vout_window_t *, const vout_window_cfg_t *);
+ void (*disable)(struct vout_window_t *);
+ void (*resize)(struct vout_window_t *, unsigned width, unsigned height);
/**
* Destroy the window.
*
* Destroys the window and releases all associated resources.
*/
- void (*destroy)(vout_window_t *);
+ void (*destroy)(struct vout_window_t *);
- void (*set_state)(vout_window_t *, unsigned state);
- void (*unset_fullscreen)(vout_window_t *);
- void (*set_fullscreen)(vout_window_t *, const char *id);
+ void (*set_state)(struct vout_window_t *, unsigned state);
+ void (*unset_fullscreen)(struct vout_window_t *);
+ void (*set_fullscreen)(struct vout_window_t *, const char *id);
};
-typedef struct vout_window_owner {
- const struct vout_window_callbacks *cbs;
- void *sys;
-} vout_window_owner_t;
-
/**
- * Graphical window
+ * Window object.
*
* This structure is an abstract interface to the windowing system.
* The window is normally used to draw video (and subpictures) into, but it
@@ -167,7 +331,7 @@ typedef struct vout_window_owner {
*
* Finally, it must support some control requests such as for fullscreen mode.
*/
-struct vout_window_t {
+typedef struct vout_window_t {
struct vlc_common_members obj;
/**
@@ -224,27 +388,49 @@ struct vout_window_t {
void *sys;
vout_window_owner_t owner;
-};
+} vout_window_t;
/**
* Creates a new window.
*
- * @param module plugin name (usually "$window")
- * @note don't use it inside a "vout display" module
+ * This function creates a window, or some other kind of rectangle render
+ * target.
+ *
+ * \param obj parent VLC object
+ * \param module plugin name, NULL for default
+ * \param owner callbacks and private data
+ * \return a new window, or NULL on error.
*/
-VLC_API vout_window_t * vout_window_New(vlc_object_t *, const char *module, const vout_window_owner_t *);
+VLC_API vout_window_t *vout_window_New(vlc_object_t *obj,
+ const char *module,
+ const vout_window_owner_t *owner);
/**
- * Deletes a window created by vout_window_New().
+ * Deletes a window.
+ *
+ * This deletes a window created by vout_window_New().
*
- * @note See vout_window_New() about window recycling.
+ * \param window window object to delete
*/
-VLC_API void vout_window_Delete(vout_window_t *);
+VLC_API void vout_window_Delete(vout_window_t *window);
+/**
+ * Inhibits or deinhibits the screensaver.
+ *
+ * \param window window in respect to which the screensaver should be inhibited
+ * or deinhibited
+ * \param true to inhibit, false to deinhibit
+ */
void vout_window_SetInhibition(vout_window_t *window, bool enabled);
/**
- * Configures the window manager state for this window.
+ * Requests a new window state.
+ *
+ * This requests a change of the state of a window from the windowing system.
+ * See \ref vout_window_state for possible states.
+ *
+ * @param window window whose state to change
+ * @param state requested state
*/
static inline void vout_window_SetState(vout_window_t *window, unsigned state)
{
@@ -255,14 +441,19 @@ static inline void vout_window_SetState(vout_window_t *window, unsigned state)
/**
* Requests a new window size.
*
- * This requests a change of the window size.
+ * This requests a change of the window size. In general and unless otherwise
+ * stated, the size is expressed in pixels. However, the exact interpretation
+ * of the window size depends on the windowing system.
*
- * \warning The windowing system may or may not actually resize the window
- * to the requested size. Track the resized event to determine the actual size.
+ * There is no return value as the request may be processed asynchronously,
+ * ignored and/or modified by the window system. The actual size of the window
+ * is determined by the vout_window_callbacks::resized callback function that
+ * was supplied to vout_window_New().
*
* \note The size is expressed in terms of the "useful" area,
* i.e. it excludes any side decoration added by the windowing system.
*
+ * \param window window whom a size change is requested for
* \param width pixel width
* \param height height width
*/
@@ -276,6 +467,7 @@ static inline void vout_window_SetSize(vout_window_t *window,
/**
* Requests fullscreen mode.
*
+ * \param window window to be brought to fullscreen mode.
* \param id nul-terminated output identifier, NULL for default
*/
static inline void vout_window_SetFullScreen(vout_window_t *window,
@@ -287,6 +479,8 @@ static inline void vout_window_SetFullScreen(vout_window_t *window,
/**
* Requests windowed mode.
+ *
+ * \param window window to be brought into windowed mode.
*/
static inline void vout_window_UnsetFullScreen(vout_window_t *window)
{
@@ -313,17 +507,18 @@ int vout_window_Enable(vout_window_t *window, const vout_window_cfg_t *cfg);
*
* This informs the window provider that the window is no longer needed.
*
- * Note that the window may be re-enabled later by a call to
- * vout_window_Enable().
+ * \note
+ * The window may be re-enabled later by a call to vout_window_Enable().
*/
VLC_API
void vout_window_Disable(vout_window_t *window);
/**
- * Report current window size
+ * Reports the current window size.
*
- * This notifies the user of the window what the pixel dimensions of the
- * window are (or should be, depending on the windowing system).
+ * This function is called by the window implementation and notifies the owner
+ * of the window what the pixel dimensions of the window are (or should be,
+ * depending on the windowing system).
*
* \note This function is thread-safe. In case of concurrent call, it is
* undefined which one is taken into account (but at least one is).
@@ -334,6 +529,12 @@ static inline void vout_window_ReportSize(vout_window_t *window,
window->owner.cbs->resized(window, width, height);
}
+/**
+ * Reports a request to close the window.
+ *
+ * This function is called by the window implementation to advise that the
+ * window is being closed externally, and should be disabled by the owner.
+ */
static inline void vout_window_ReportClose(vout_window_t *window)
{
if (window->owner.cbs->closed != NULL)
@@ -343,7 +544,9 @@ static inline void vout_window_ReportClose(vout_window_t *window)
/**
* Reports the current window state.
*
- * This notifies the owner of the window that the state of the window changed.
+ * This function is called by the window implementation to notify the owner of
+ * the window that the state of the window changed.
+ *
* \param state \see vout_window_state
*/
static inline void vout_window_ReportState(vout_window_t *window,
@@ -385,9 +588,14 @@ static inline void vout_window_SendMouseEvent(vout_window_t *window,
}
/**
- * Send a mouse movement
+ * Reports a pointer movement.
+ *
+ * The mouse position must be expressed in window pixel units.
+ * See also \ref vout_window_mouse_event_t.
*
- * The mouse position must be expressed against window unit.
+ * \param window window in focus
+ * \param x abscissa
+ * \param y ordinate
*/
static inline void vout_window_ReportMouseMoved(vout_window_t *window,
int x, int y)
@@ -399,7 +607,10 @@ static inline void vout_window_ReportMouseMoved(vout_window_t *window,
}
/**
- * Send a mouse pressed event
+ * Reports a mouse button press.
+ *
+ * \param window window in focus
+ * \param button pressed button (see \ref vlc_mouse_button)
*/
static inline void vout_window_ReportMousePressed(vout_window_t *window,
int button)
@@ -411,10 +622,13 @@ static inline void vout_window_ReportMousePressed(vout_window_t *window,
}
/**
- * Send a mouse released event
+ * Reports a mouse button release.
+ *
+ * \param window window in focus
+ * \param button released button (see \ref vlc_mouse_button)
*/
static inline void vout_window_ReportMouseReleased(vout_window_t *window,
- int button)
+ int button)
{
const vout_window_mouse_event_t mouse = {
VOUT_WINDOW_MOUSE_RELEASED, 0, 0, button,
@@ -423,7 +637,10 @@ static inline void vout_window_ReportMouseReleased(vout_window_t *window,
}
/**
- * Send a mouse double click event
+ * Reports a mouse double-click.
+ *
+ * \param window window in focus
+ * \param button double-clicked button (see \ref vlc_mouse_button)
*/
static inline void vout_window_ReportMouseDoubleClick(vout_window_t *window,
int button)
@@ -434,6 +651,12 @@ static inline void vout_window_ReportMouseDoubleClick(vout_window_t *window,
vout_window_SendMouseEvent(window, &mouse);
}
+/**
+ * Reports a keyboard key press.
+ *
+ * \param window window in focus
+ * \param key VLC key code
+ */
static inline void vout_window_ReportKeyPress(vout_window_t *window, int key)
{
if (window->owner.cbs->keyboard_event != NULL)
More information about the vlc-commits
mailing list