include/vlc_vout_window.h

   1 /*****************************************************************************
   2  * vlc_vout_window.h: vout_window_t definitions
   3  *****************************************************************************
   4  * Copyright (C) 2008 Rémi Denis-Courmont
   5  * Copyright (C) 2009 Laurent Aimar
   6  * $Id$
   7  *
   8  * Authors: Laurent Aimar <fenrir _AT_ videolan _DOT_ org>
   9  *
  10  * This program is free software; you can redistribute it and/or modify it
  11  * under the terms of the GNU Lesser General Public License as published by
  12  * the Free Software Foundation; either version 2.1 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public License
  21  * along with this program; if not, write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  23  *****************************************************************************/
  24
  25 #ifndef VLC_VOUT_WINDOW_H
  26 #define VLC_VOUT_WINDOW_H 1
  27
  28 #include <stdarg.h>
  29 #include <vlc_common.h>
  30
  31 /**
  32  * \defgroup video_window Video window
  33  * \ingroup video_output
  34  * Video output window management
  35  * @{
  36  * \file
  37  * Video output window modules interface
  38  */
  39
  40 typedef struct vout_window_t vout_window_t;
  41
  42 struct wl_display;
  43 struct wl_surface;
  44
  45 /**
  46  * Window handle type
  47  */
  48 enum vout_window_type {
  49     VOUT_WINDOW_TYPE_DUMMY /**< Dummy window (not an actual window) */,
  50     VOUT_WINDOW_TYPE_XID /**< X11 window */,
  51     VOUT_WINDOW_TYPE_HWND /**< Win32 or OS/2 window */,
  52     VOUT_WINDOW_TYPE_NSOBJECT /**< MacOS X view */,
  53     VOUT_WINDOW_TYPE_ANDROID_NATIVE /**< Android native window */,
  54     VOUT_WINDOW_TYPE_WAYLAND /**< Wayland surface */,
  55 };
  56
  57 /**
  58  * Window management state.
  59  */
  60 enum vout_window_state {
  61     VOUT_WINDOW_STATE_NORMAL,
  62     VOUT_WINDOW_STATE_ABOVE,
  63     VOUT_WINDOW_STATE_BELOW,
  64 };
  65
  66 /**
  67  * Window mouse event type for vout_window_mouse_event_t
  68  */
  69 enum vout_window_mouse_event_type {
  70     VOUT_WINDOW_MOUSE_MOVED,
  71     VOUT_WINDOW_MOUSE_PRESSED,
  72     VOUT_WINDOW_MOUSE_RELEASED,
  73     VOUT_WINDOW_MOUSE_DOUBLE_CLICK,
  74 };
  75
  76 /**
  77  * Window mouse event
  78  */
  79 typedef struct vout_window_mouse_event_t
  80 {
  81     enum vout_window_mouse_event_type type;
  82     int x;
  83     int y;
  84     int button_mask;
  85 } vout_window_mouse_event_t;
  86
  87 /**
  88  * Window (desired) configuration.
  89  *
  90  * This structure describes the intended initial configuration
  91  * of a \ref vout_window_t.
  92  */
  93 typedef struct vout_window_cfg_t {
  94     /**
  95      * Whether the window should be in full screen mode or not.
  96      */
  97     bool is_fullscreen;
  98
  99     /**
 100      * Whether the window should have decorations or not.
 101      */
 102     bool is_decorated;
 103
 104 #ifdef __APPLE__
 105     /* Window position hint */
 106     int x;
 107     int y;
 108 #endif
 109
 110     /**
 111      * Intended pixel width of the window.
 112      */
 113     unsigned width;
 114
 115     /**
 116      * Intended pixel height of the window.
 117      */
 118     unsigned height;
 119
 120 } vout_window_cfg_t;
 121
 122 struct vout_window_callbacks {
 123     void (*resized)(vout_window_t *, unsigned width, unsigned height);
 124     void (*closed)(vout_window_t *);
 125     void (*state_changed)(vout_window_t *, unsigned state);
 126     void (*windowed)(vout_window_t *);
 127     void (*fullscreened)(vout_window_t *, const char *id);
 128
 129     void (*mouse_event)(vout_window_t *,
 130                         const vout_window_mouse_event_t *mouse);
 131     void (*keyboard_event)(vout_window_t *, unsigned key);
 132
 133     void (*output_event)(vout_window_t *, const char *id, const char *desc);
 134 };
 135
 136 struct vout_window_operations {
 137     int (*enable)(vout_window_t *, const vout_window_cfg_t *);
 138     void (*disable)(vout_window_t *);
 139     void (*resize)(vout_window_t *, unsigned width, unsigned height);
 140
 141     /**
 142      * Destroy the window.
 143      *
 144      * Destroys the window and releases all associated resources.
 145      */
 146     void (*destroy)(vout_window_t *);
 147
 148     void (*set_state)(vout_window_t *, unsigned state);
 149     void (*unset_fullscreen)(vout_window_t *);
 150     void (*set_fullscreen)(vout_window_t *, const char *id);
 151 };
 152
 153 typedef struct vout_window_owner {
 154     const struct vout_window_callbacks *cbs;
 155     void *sys;
 156 } vout_window_owner_t;
 157
 158 /**
 159  * Graphical window
 160  *
 161  * This structure is an abstract interface to the windowing system.
 162  * The window is normally used to draw video (and subpictures) into, but it
 163  * can also be used for other purpose (e.g. OpenGL visualization).
 164  *
 165  * The window is responsible for providing a window handle, whose exact
 166  * meaning depends on the windowing system. It also must report some events
 167  * such as user input (keyboard, mouse) and window resize.
 168  *
 169  * Finally, it must support some control requests such as for fullscreen mode.
 170  */
 171 struct vout_window_t {
 172     struct vlc_common_members obj;
 173
 174      /**
 175       * Window handle type
 176       *
 177       * This identified the windowing system and protocol that the window
 178       * needs to use. This also selects which member of the \ref handle union
 179       * and the \ref display union are to be set.
 180       *
 181       * The possible values are defined in \ref vout_window_type.
 182       */
 183     unsigned type;
 184
 185     /**
 186      * Window handle (mandatory)
 187      *
 188      * This must be filled by the plugin upon activation.
 189      *
 190      * Depending on the \ref type above, a different member of this union is
 191      * used.
 192      */
 193     union {
 194         void     *hwnd;          /**< Win32 window handle */
 195         uint32_t xid;            /**< X11 windows ID */
 196         void     *nsobject;      /**< Mac OSX view object */
 197         void     *anativewindow; /**< Android native window */
 198         struct wl_surface *wl;   /**< Wayland surface (client pointer) */
 199     } handle;
 200
 201     /** Display server (mandatory)
 202      *
 203      * This must be filled by the plugin upon activation.
 204      *
 205      * The window handle is relative to the display server. The exact meaning
 206      * of the display server depends on the window handle type. Not all window
 207      * handle type provide a display server field.
 208      */
 209     union {
 210         char     *x11; /**< X11 display string (NULL = use default) */
 211         struct wl_display *wl; /**< Wayland display (client pointer) */
 212     } display;
 213
 214     const struct vout_window_operations *ops;
 215
 216     struct {
 217         bool has_double_click; /**< Whether double click events are sent,
 218                                     or need to be emulated */
 219     } info;
 220
 221     /* Private place holder for the vout_window_t module (optional)
 222      *
 223      * A module is free to use it as it wishes.
 224      */
 225     void *sys;
 226
 227     vout_window_owner_t owner;
 228 };
 229
 230 /**
 231  * Creates a new window.
 232  *
 233  * @param module plugin name (usually "$window")
 234  * @note don't use it inside a "vout display" module
 235  */
 236 VLC_API vout_window_t * vout_window_New(vlc_object_t *, const char *module, const vout_window_owner_t *);
 237
 238 /**
 239  * Deletes a window created by vout_window_New().
 240  *
 241  * @note See vout_window_New() about window recycling.
 242  */
 243 VLC_API void vout_window_Delete(vout_window_t *);
 244
 245 void vout_window_SetInhibition(vout_window_t *window, bool enabled);
 246
 247 /**
 248  * Configures the window manager state for this window.
 249  */
 250 static inline void vout_window_SetState(vout_window_t *window, unsigned state)
 251 {
 252     if (window->ops->set_state != NULL)
 253         window->ops->set_state(window, state);
 254 }
 255
 256 /**
 257  * Requests a new window size.
 258  *
 259  * This requests a change of the window size.
 260  *
 261  * \warning  The windowing system may or may not actually resize the window
 262  * to the requested size. Track the resized event to determine the actual size.
 263  *
 264  * \note The size is expressed in terms of the "useful" area,
 265  * i.e. it excludes any side decoration added by the windowing system.
 266  *
 267  * \param width pixel width
 268  * \param height height width
 269  */
 270 static inline void vout_window_SetSize(vout_window_t *window,
 271                                       unsigned width, unsigned height)
 272 {
 273     if (window->ops->resize != NULL)
 274         window->ops->resize(window, width, height);
 275 }
 276
 277 /**
 278  * Requests fullscreen mode.
 279  *
 280  * \param id nul-terminated output identifier, NULL for default
 281  */
 282 static inline void vout_window_SetFullScreen(vout_window_t *window,
 283                                             const char *id)
 284 {
 285     if (window->ops->set_fullscreen != NULL)
 286         window->ops->set_fullscreen(window, id);
 287 }
 288
 289 /**
 290  * Requests windowed mode.
 291  */
 292 static inline void vout_window_UnsetFullScreen(vout_window_t *window)
 293 {
 294     if (window->ops->unset_fullscreen != NULL)
 295         window->ops->unset_fullscreen(window);
 296 }
 297
 298 /**
 299  * Enables a window.
 300  *
 301  * This informs the window provider that the window is about to be taken into
 302  * active use. A window is always initially disabled. This is so that the
 303  * window provider can provide a persistent connection to the display server,
 304  * and track any useful events, such as monitors hotplug.
 305  *
 306  * The window handle (vout_window_t.handle) and display (vout_window_t.display)
 307  * must remain valid and constant while the window is enabled.
 308  */
 309 int vout_window_Enable(vout_window_t *window, const vout_window_cfg_t *cfg);
 310
 311 /**
 312  * Disables a window.
 313  *
 314  * This informs the window provider that the window is no longer needed.
 315  *
 316  * Note that the window may be re-enabled later by a call to
 317  * vout_window_Enable().
 318  */
 319 void vout_window_Disable(vout_window_t *window);
 320
 321 /**
 322  * Report current window size
 323  *
 324  * This notifies the user of the window what the pixel dimensions of the
 325  * window are (or should be, depending on the windowing system).
 326  *
 327  * \note This function is thread-safe. In case of concurrent call, it is
 328  * undefined which one is taken into account (but at least one is).
 329  */
 330 static inline void vout_window_ReportSize(vout_window_t *window,
 331                                           unsigned width, unsigned height)
 332 {
 333     window->owner.cbs->resized(window, width, height);
 334 }
 335
 336 static inline void vout_window_ReportClose(vout_window_t *window)
 337 {
 338     if (window->owner.cbs->closed != NULL)
 339         window->owner.cbs->closed(window);
 340 }
 341
 342 /**
 343  * Reports the current window state.
 344  *
 345  * This notifies the owner of the window that the state of the window changed.
 346  * \param state \see vout_window_state
 347  */
 348 static inline void vout_window_ReportState(vout_window_t *window,
 349                                            unsigned state)
 350 {
 351     if (window->owner.cbs->state_changed != NULL)
 352         window->owner.cbs->state_changed(window, state);
 353 }
 354
 355 /**
 356  * Reports that the window is not in full screen.
 357  *
 358  * This notifies the owner of the window that the window is windowed, i.e. not
 359  * in full screen mode.
 360  */
 361 static inline void vout_window_ReportWindowed(vout_window_t *window)
 362 {
 363     if (window->owner.cbs->windowed != NULL)
 364         window->owner.cbs->windowed(window);
 365 }
 366
 367 /**
 368  * Reports that the window is in full screen.
 369  *
 370  * \param id fullscreen output nul-terminated identifier, NULL for default
 371  */
 372 static inline void vout_window_ReportFullscreen(vout_window_t *window,
 373                                                 const char *id)
 374 {
 375     if (window->owner.cbs->fullscreened != NULL)
 376         window->owner.cbs->fullscreened(window, id);
 377 }
 378
 379 static inline void vout_window_SendMouseEvent(vout_window_t *window,
 380                                               const vout_window_mouse_event_t *mouse)
 381 {
 382     if (window->owner.cbs->mouse_event != NULL)
 383         window->owner.cbs->mouse_event(window, mouse);
 384 }
 385
 386 /**
 387  * Send a mouse movement
 388  *
 389  * The mouse position must be expressed against window unit.
 390  */
 391 static inline void vout_window_ReportMouseMoved(vout_window_t *window,
 392                                                 int x, int y)
 393 {
 394     const vout_window_mouse_event_t mouse = {
 395         VOUT_WINDOW_MOUSE_MOVED, x, y, 0
 396     };
 397     vout_window_SendMouseEvent(window, &mouse);
 398 }
 399
 400 /**
 401  * Send a mouse pressed event
 402  */
 403 static inline void vout_window_ReportMousePressed(vout_window_t *window,
 404                                                   int button)
 405 {
 406     const vout_window_mouse_event_t mouse = {
 407         VOUT_WINDOW_MOUSE_PRESSED, 0, 0, button,
 408     };
 409     vout_window_SendMouseEvent(window, &mouse);
 410 }
 411
 412 /**
 413  * Send a mouse released event
 414  */
 415 static inline void vout_window_ReportMouseReleased(vout_window_t *window,
 416                                                   int button)
 417 {
 418     const vout_window_mouse_event_t mouse = {
 419         VOUT_WINDOW_MOUSE_RELEASED, 0, 0, button,
 420     };
 421     vout_window_SendMouseEvent(window, &mouse);
 422 }
 423
 424 /**
 425  * Send a mouse double click event
 426  */
 427 static inline void vout_window_ReportMouseDoubleClick(vout_window_t *window,
 428                                                       int button)
 429 {
 430     const vout_window_mouse_event_t mouse = {
 431         VOUT_WINDOW_MOUSE_DOUBLE_CLICK, 0, 0, button,
 432     };
 433     vout_window_SendMouseEvent(window, &mouse);
 434 }
 435
 436 static inline void vout_window_ReportKeyPress(vout_window_t *window, int key)
 437 {
 438     if (window->owner.cbs->keyboard_event != NULL)
 439         window->owner.cbs->keyboard_event(window, key);
 440 }
 441
 442 /**
 443  * Adds/removes a fullscreen output.
 444  *
 445  * This notifies the owner of the window that a usable fullscreen output has
 446  * been added, changed or removed.
 447  *
 448  * If an output with the same identifier is already known, its name will be
 449  * updated. Otherwise it will be added.
 450  * If the name parameter is NULL, the output will be removed.
 451  *
 452  * \param id unique nul-terminated identifier for the output
 453  * \param name human-readable name
 454  */
 455 static inline void vout_window_ReportOutputDevice(vout_window_t *window,
 456                                                   const char *id,
 457                                                   const char *name)
 458 {
 459     if (window->owner.cbs->output_event != NULL)
 460         window->owner.cbs->output_event(window, id, name);
 461 }
 462
 463 /** @} */
 464 #endif /* VLC_VOUT_WINDOW_H */