vlc | branch: master | Rémi Denis-Courmont <[email protected]> | 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) _______________________________________________ vlc-commits mailing list [email protected] https://mailman.videolan.org/listinfo/vlc-commits
