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  *
   7  * Authors: Laurent Aimar <fenrir _AT_ videolan _DOT_ org>
   8  *
   9  * This program is free software; you can redistribute it and/or modify it
  10  * under the terms of the GNU Lesser General Public License as published by
  11  * the Free Software Foundation; either version 2.1 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this program; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  22  *****************************************************************************/
  23
  24 #ifndef VLC_VOUT_WINDOW_H
  25 #define VLC_VOUT_WINDOW_H 1
  26
  27 #include <stdarg.h>
  28 #include <vlc_common.h>
  29
  30 /**
  31  * \defgroup video_window Video window
  32  * \ingroup video_output
  33  * Window management
  34  *
  35  * Window management provides a partial abstraction for windowing systems and
  36  * rendering targets (i.e. "windows"). See \ref vout_window_t.
  37  *
  38  * @{
  39  * \file
  40  * Window modules interface
  41  */
  42
  43 struct vout_window_t;
  44 struct wl_display;
  45 struct wl_surface;
  46
  47 /**
  48  * Window handle type.
  49  *
  50  * The window handle type specifies the window system protocol that the
  51  * window was created with. It determines which members of the
  52  * vout_window_t::handle and vout_window_t::display unions are defined
  53  * for the given window.
  54  *
  55  * It also establishes some protocol-dependent semantics such as the exact
  56  * interpretation of the window state (\ref vout_window_state)
  57  * and the window size.
  58  */
  59 enum vout_window_type {
  60     VOUT_WINDOW_TYPE_DUMMY /**< Dummy window (not an actual window) */,
  61     VOUT_WINDOW_TYPE_XID /**< X11 window */,
  62     VOUT_WINDOW_TYPE_HWND /**< Win32 or OS/2 window */,
  63     VOUT_WINDOW_TYPE_NSOBJECT /**< macOS/iOS view */,
  64     VOUT_WINDOW_TYPE_ANDROID_NATIVE /**< Android native window */,
  65     VOUT_WINDOW_TYPE_WAYLAND /**< Wayland surface */,
  66     VOUT_WINDOW_TYPE_DCOMP /**< Win32 DirectComposition */,
  67 };
  68
  69 /**
  70  * Window states.
  71  *
  72  * Currently, this only handles different window stacking orders.
  73  * See also \ref vout_window_SetState().
  74  */
  75 enum vout_window_state {
  76     VOUT_WINDOW_STATE_NORMAL /**< Normal stacking */,
  77     VOUT_WINDOW_STATE_ABOVE /**< Stacking above (a.k.a. always on top) */,
  78     VOUT_WINDOW_STATE_BELOW /**< Stacking below (a.k.a. wall paper mode) */,
  79 };
  80
  81 /**
  82  * Window mouse event types.
  83  *
  84  * This enumeration defines the possible event types
  85  * vout_window_mouse_event_t::type.
  86  */
  87 enum vout_window_mouse_event_type {
  88     VOUT_WINDOW_MOUSE_MOVED /**< Pointer position change */,
  89     VOUT_WINDOW_MOUSE_PRESSED /**< Pointer button press or single click */,
  90     VOUT_WINDOW_MOUSE_RELEASED /**< Pointer button release */,
  91     VOUT_WINDOW_MOUSE_DOUBLE_CLICK /**< Double click */,
  92 };
  93
  94 /**
  95  * Window mouse event.
  96  *
  97  * This structure describes a pointer input event on a window.
  98  */
  99 typedef struct vout_window_mouse_event_t
 100 {
 101     enum vout_window_mouse_event_type type; /**< Event type. */
 102
 103     /**
 104      * Pointer abscissa.
 105      *
 106      * The pointer abscissa is relative to the window and expressed in pixels.
 107      * Abscissa goes from left to right, such that the left-most column is at 0
 108      * and the right-most column is at width minus one.
 109      *
 110      * A negative abscissa refers to pixels to the left of the window, and
 111      * an abscissa of width or larger refers to pixels to the right.
 112      *
 113      * This is only set if @c event equals \ref VOUT_WINDOW_MOUSE_MOVED.
 114      */
 115     int x;
 116
 117     /**
 118      * Pointer ordinate.
 119      *
 120      * The pointer ordinate is relative to the window and expressed in pixels.
 121      * Ordinate goes from top to bottom, such that the top-most row is at 0
 122      * and the bottom-most column is at height minus one.
 123      *
 124      * A negative ordinate refers to pixels above the window, and
 125      * an ordinate of height or larger refers to pixels below the window.
 126      *
 127      * This is only set if @c event equals \ref VOUT_WINDOW_MOUSE_MOVED.
 128      */
 129     int y;
 130
 131     /**
 132      * Pressed button.
 133      *
 134      * See \ref vlc_mouse_button for possible vaules.
 135      *
 136      * This is set if @c event does not equal \ref VOUT_WINDOW_MOUSE_MOVED.
 137      */
 138     int button_mask;
 139 } vout_window_mouse_event_t;
 140
 141 /**
 142  * Window (desired) configuration.
 143  *
 144  * This structure describes the intended initial configuration
 145  * of a \ref vout_window_t.
 146  */
 147 typedef struct vout_window_cfg_t {
 148     /**
 149      * Whether the window should be in full screen mode or not.
 150      */
 151     bool is_fullscreen;
 152
 153     /**
 154      * Whether the window should have decorations or not.
 155      */
 156     bool is_decorated;
 157
 158 #if defined(__APPLE__) || defined(_WIN32)
 159     /* Window position hint */
 160     int x;
 161     int y;
 162 #endif
 163
 164     /**
 165      * Intended pixel width of the window.
 166      */
 167     unsigned width;
 168
 169     /**
 170      * Intended pixel height of the window.
 171      */
 172     unsigned height;
 173
 174 } vout_window_cfg_t;
 175
 176 /**
 177  * Window event callbacks structure.
 178  *
 179  * This structure provided to vout_window_New() conveys callbacks to handle
 180  * window events.
 181  *
 182  * As a general rule, the events can occur synchronously or asynchronously from
 183  * the time that the window is (succesfully) being created by vout_window_New()
 184  * until the time that the window has been deleted by vout_window_Delete().
 185  *
 186  * \warning
 187  * Also, a window object functions are not reentrant, so the callbacks must not
 188  * invoke the window object functions.
 189  * Otherwise a deadlock or infinite recursion may occur.
 190  */
 191 struct vout_window_callbacks {
 192     /**
 193      * Callback for window size changes.
 194      *
 195      * This callback function is invoked when the windowing
 196      * system changes the window size.
 197      *
 198      * This event may occur synchronously when the window is created or a size
 199      * change is requested. It may also occur asynchronously as a consequence
 200      * of external events from the windowing system, or deferred processing of
 201      * a size change request.
 202      */
 203     void (*resized)(struct vout_window_t *, unsigned width, unsigned height);
 204
 205     /**
 206      * Callback for window closing.
 207      *
 208      * This callback function (if non-NULL) is invoked upon an external request
 209      * to close the window. Not all windowing systems support this.
 210      *
 211      * Soon after this callback, the window should be disabled with
 212      * vout_window_Disable().
 213      *
 214      * \warning Do not disable the window within the callback.
 215      * That could lead to a dead lock.
 216      */
 217     void (*closed)(struct vout_window_t *);
 218
 219     /**
 220      * Callback for window state change.
 221      *
 222      * This callback function (if non-NULL) is invoked when the window state
 223      * as changed, either as a consequence of vout_window_SetSate() or external
 224      * events.
 225      *
 226      * \bug Many window back-ends fail to invoke this callback when due.
 227      *
 228      * \param state new window state (see \ref vout_window_state).
 229      */
 230     void (*state_changed)(struct vout_window_t *, unsigned state);
 231
 232     /**
 233      * Callback for windowed mode.
 234      *
 235      * This callback function (if non-NULL) is invoked when the window becomes
 236      * windowed. It might also occur spuriously if the window remains windowed.
 237      *
 238      * \bug Many window back-ends fail to invoke this callback when due.
 239      */
 240     void (*windowed)(struct vout_window_t *);
 241
 242     /**
 243      * Callback for fullscreen mode.
 244      *
 245      * This callback function (if non-NULL) is invoked when the window becomes
 246      * fullscreen, when it changes to a different fullscreen output, or
 247      * spuriously when the window remains in fullscreen mode.
 248      *
 249      * \bug Many window back-ends fail to invoke this callback when due.
 250      *
 251      * \param id fullscreen output identifier (NULL if unspecified)
 252      */
 253     void (*fullscreened)(struct vout_window_t *, const char *id);
 254
 255     /**
 256      * Callback for pointer input events.
 257      *
 258      * This callback function (if non-NULL) is invoked upon any pointer input
 259      * event on the window. See \ref vout_window_mouse_event_t.
 260      *
 261      * \param mouse pointer to the input event.
 262      */
 263     void (*mouse_event)(struct vout_window_t *,
 264                         const vout_window_mouse_event_t *mouse);
 265
 266     /**
 267      * Callback for keyboard input events.
 268      *
 269      * This callback function (if non-NULL) is invoked upon any keyboard key
 270      * press event, or repetition event, on the window.
 271      *
 272      * \note No events are delivered for keyboard key releases.
 273      *
 274      * \param key VLC key code
 275      */
 276     void (*keyboard_event)(struct vout_window_t *, unsigned key);
 277
 278     /**
 279      * Callback for fullscreen output enumeration.
 280      *
 281      * This callback function (if non-NULL) indicates that a fullscreen output
 282      * becomes available, changes human-readable description, or becomes
 283      * unavailable.
 284      *
 285      * \param id nul-terminated id fullscreen output identifier
 286      *           (cannot be NULL)
 287      * \param desc nul-terminated human-readable description,
 288      *             or NULL if the output has become unavailable
 289      */
 290     void (*output_event)(struct vout_window_t *,
 291                          const char *id, const char *desc);
 292 };
 293
 294 /**
 295  * Window callbacks and opaque data.
 296  */
 297 typedef struct vout_window_owner {
 298     const struct vout_window_callbacks *cbs; /**< Callbacks */
 299     void *sys; /**< Opaque data / private pointer for callbacks */
 300 } vout_window_owner_t;
 301
 302 /**
 303  * Window implementation callbacks.
 304  */
 305 struct vout_window_operations {
 306     int (*enable)(struct vout_window_t *, const vout_window_cfg_t *);
 307     void (*disable)(struct vout_window_t *);
 308     void (*resize)(struct vout_window_t *, unsigned width, unsigned height);
 309
 310     /**
 311      * Destroy the window.
 312      *
 313      * Destroys the window and releases all associated resources.
 314      */
 315     void (*destroy)(struct vout_window_t *);
 316
 317     void (*set_state)(struct vout_window_t *, unsigned state);
 318     void (*unset_fullscreen)(struct vout_window_t *);
 319     void (*set_fullscreen)(struct vout_window_t *, const char *id);
 320     void (*set_title)(struct vout_window_t *, const char *id);
 321 };
 322
 323 /**
 324  * Window object.
 325  *
 326  * This structure is an abstract interface to the windowing system.
 327  * The window is normally used to draw video (and subpictures) into, but it
 328  * can also be used for other purpose (e.g. OpenGL visualization).
 329  *
 330  * The window is responsible for providing a window handle, whose exact
 331  * meaning depends on the windowing system. It also must report some events
 332  * such as user input (keyboard, mouse) and window resize.
 333  *
 334  * Finally, it must support some control requests such as for fullscreen mode.
 335  */
 336 typedef struct vout_window_t {
 337     struct vlc_object_t obj;
 338
 339      /**
 340       * Window handle type
 341       *
 342       * This identified the windowing system and protocol that the window
 343       * needs to use. This also selects which member of the \ref handle union
 344       * and the \ref display union are to be set.
 345       *
 346       * The possible values are defined in \ref vout_window_type.
 347       */
 348     unsigned type;
 349
 350     /**
 351      * Window handle (mandatory)
 352      *
 353      * This must be filled by the plugin upon succesful vout_window_Enable().
 354      *
 355      * Depending on the \ref type above, a different member of this union is
 356      * used.
 357      */
 358     union {
 359         void     *hwnd;          /**< Win32 window handle */
 360         uint32_t xid;            /**< X11 windows ID */
 361         void     *nsobject;      /**< macOS/iOS view object */
 362         void     *anativewindow; /**< Android native window */
 363         struct wl_surface *wl;   /**< Wayland surface (client pointer) */
 364         void     *dcomp_visual;  /**<  Win32 direct composition visual */
 365     } handle;
 366
 367     /** Display server (mandatory)
 368      *
 369      * This must be filled by the plugin upon activation.
 370      *
 371      * The window handle is relative to the display server. The exact meaning
 372      * of the display server depends on the window handle type. Not all window
 373      * handle type provide a display server field.
 374      */
 375     union {
 376         char     *x11; /**< X11 display string (NULL = use default) */
 377         struct wl_display *wl; /**< Wayland display (client pointer) */
 378         void* dcomp_device; /**< DirectComposition device */
 379     } display;
 380
 381     const struct vout_window_operations *ops; /**< operations handled by the
 382                              window. Once this is set it MUST NOT be changed */
 383
 384     struct {
 385         bool has_double_click; /**< Whether double click events are sent,
 386                                     or need to be emulated */
 387     } info;
 388
 389     /* Private place holder for the vout_window_t module (optional)
 390      *
 391      * A module is free to use it as it wishes.
 392      */
 393     void *sys;
 394
 395     vout_window_owner_t owner;
 396 } vout_window_t;
 397
 398 /**
 399  * Creates a new window.
 400  *
 401  * This function creates a window, or some other kind of rectangle render
 402  * target.
 403  *
 404  * \param obj parent VLC object
 405  * \param module plugin name, NULL for default
 406  * \param owner callbacks and private data
 407  * \return a new window, or NULL on error.
 408  */
 409 VLC_API vout_window_t *vout_window_New(vlc_object_t *obj,
 410                                        const char *module,
 411                                        const vout_window_owner_t *owner);
 412
 413 /**
 414  * Deletes a window.
 415  *
 416  * This deletes a window created by vout_window_New().
 417  *
 418  * \param window window object to delete
 419  */
 420 VLC_API void vout_window_Delete(vout_window_t *window);
 421
 422 /**
 423  * Inhibits or deinhibits the screensaver.
 424  *
 425  * \param window window in respect to which the screensaver should be inhibited
 426  *               or deinhibited
 427  * \param true to inhibit, false to deinhibit
 428  */
 429 void vout_window_SetInhibition(vout_window_t *window, bool enabled);
 430
 431 /**
 432  * Requests a new window state.
 433  *
 434  * This requests a change of the state of a window from the windowing system.
 435  * See \ref vout_window_state for possible states.
 436  *
 437  * @param window window whose state to change
 438  * @param state requested state
 439  */
 440 static inline void vout_window_SetState(vout_window_t *window, unsigned state)
 441 {
 442     if (window->ops->set_state != NULL)
 443         window->ops->set_state(window, state);
 444 }
 445
 446 /**
 447  * Requests a new window size.
 448  *
 449  * This requests a change of the window size. In general and unless otherwise
 450  * stated, the size is expressed in pixels. However, the exact interpretation
 451  * of the window size depends on the windowing system.
 452  *
 453  * There is no return value as the request may be processed asynchronously,
 454  * ignored and/or modified by the window system. The actual size of the window
 455  * is determined by the vout_window_callbacks::resized callback function that
 456  * was supplied to vout_window_New().
 457  *
 458  * \note The size is expressed in terms of the "useful" area,
 459  * i.e. it excludes any side decoration added by the windowing system.
 460  *
 461  * \param window window whom a size change is requested for
 462  * \param width pixel width
 463  * \param height height width
 464  */
 465 static inline void vout_window_SetSize(vout_window_t *window,
 466                                       unsigned width, unsigned height)
 467 {
 468     if (window->ops->resize != NULL)
 469         window->ops->resize(window, width, height);
 470 }
 471
 472 /**
 473  * Requests fullscreen mode.
 474  *
 475  * \param window window to be brought to fullscreen mode.
 476  * \param id nul-terminated output identifier, NULL for default
 477  */
 478 static inline void vout_window_SetFullScreen(vout_window_t *window,
 479                                             const char *id)
 480 {
 481     if (window->ops->set_fullscreen != NULL)
 482         window->ops->set_fullscreen(window, id);
 483 }
 484
 485 /**
 486  * Requests windowed mode.
 487  *
 488  * \param window window to be brought into windowed mode.
 489  */
 490 static inline void vout_window_UnsetFullScreen(vout_window_t *window)
 491 {
 492     if (window->ops->unset_fullscreen != NULL)
 493         window->ops->unset_fullscreen(window);
 494 }
 495
 496 /**
 497  * Request a new window title.
 498  *
 499  * \param window window to change the title.
 500  * \param title window title to use.
 501  */
 502 static inline void vout_window_SetTitle(vout_window_t *window, const char *title)
 503 {
 504     if (window->ops->set_title != NULL)
 505         window->ops->set_title(window, title);
 506 }
 507
 508 /**
 509  * Enables a window.
 510  *
 511  * This informs the window provider that the window is about to be taken into
 512  * active use. A window is always initially disabled. This is so that the
 513  * window provider can provide a persistent connection to the display server,
 514  * and track any useful events, such as monitors hotplug.
 515  *
 516  * The window handle (vout_window_t.handle) must remain valid and constant
 517  * while the window is enabled.
 518  */
 519 VLC_API
 520 int vout_window_Enable(vout_window_t *window, const vout_window_cfg_t *cfg);
 521
 522 /**
 523  * Disables a window.
 524  *
 525  * This informs the window provider that the window is no longer needed.
 526  *
 527  * \note
 528  * The window may be re-enabled later by a call to vout_window_Enable().
 529  */
 530 VLC_API
 531 void vout_window_Disable(vout_window_t *window);
 532
 533 /**
 534  * Reports the current window size.
 535  *
 536  * This function is called by the window implementation and notifies the owner
 537  * of the window what the pixel dimensions of the window are (or should be,
 538  * depending on the windowing system).
 539  *
 540  * \note This function is thread-safe. In case of concurrent call, it is
 541  * undefined which one is taken into account (but at least one is).
 542  */
 543 static inline void vout_window_ReportSize(vout_window_t *window,
 544                                           unsigned width, unsigned height)
 545 {
 546     window->owner.cbs->resized(window, width, height);
 547 }
 548
 549 /**
 550  * Reports a request to close the window.
 551  *
 552  * This function is called by the window implementation to advise that the
 553  * window is being closed externally, and should be disabled by the owner.
 554  */
 555 static inline void vout_window_ReportClose(vout_window_t *window)
 556 {
 557     if (window->owner.cbs->closed != NULL)
 558         window->owner.cbs->closed(window);
 559 }
 560
 561 /**
 562  * Reports the current window state.
 563  *
 564  * This function is called by the window implementation to notify the owner of
 565  * the window that the state of the window changed.
 566  *
 567  * \param state \see vout_window_state
 568  */
 569 static inline void vout_window_ReportState(vout_window_t *window,
 570                                            unsigned state)
 571 {
 572     if (window->owner.cbs->state_changed != NULL)
 573         window->owner.cbs->state_changed(window, state);
 574 }
 575
 576 /**
 577  * Reports that the window is not in full screen.
 578  *
 579  * This notifies the owner of the window that the window is windowed, i.e. not
 580  * in full screen mode.
 581  */
 582 VLC_API void vout_window_ReportWindowed(vout_window_t *wnd);
 583
 584 /**
 585  * Reports that the window is in full screen.
 586  *
 587  * \param id fullscreen output nul-terminated identifier, NULL for default
 588  */
 589 VLC_API void vout_window_ReportFullscreen(vout_window_t *wnd, const char *id);
 590
 591 static inline void vout_window_SendMouseEvent(vout_window_t *window,
 592                                               const vout_window_mouse_event_t *mouse)
 593 {
 594     if (window->owner.cbs->mouse_event != NULL)
 595         window->owner.cbs->mouse_event(window, mouse);
 596 }
 597
 598 /**
 599  * Reports a pointer movement.
 600  *
 601  * The mouse position must be expressed in window pixel units.
 602  * See also \ref vout_window_mouse_event_t.
 603  *
 604  * \param window window in focus
 605  * \param x abscissa
 606  * \param y ordinate
 607  */
 608 static inline void vout_window_ReportMouseMoved(vout_window_t *window,
 609                                                 int x, int y)
 610 {
 611     const vout_window_mouse_event_t mouse = {
 612         VOUT_WINDOW_MOUSE_MOVED, x, y, 0
 613     };
 614     vout_window_SendMouseEvent(window, &mouse);
 615 }
 616
 617 /**
 618  * Reports a mouse button press.
 619  *
 620  * \param window window in focus
 621  * \param button pressed button (see \ref vlc_mouse_button)
 622  */
 623 static inline void vout_window_ReportMousePressed(vout_window_t *window,
 624                                                   int button)
 625 {
 626     const vout_window_mouse_event_t mouse = {
 627         VOUT_WINDOW_MOUSE_PRESSED, 0, 0, button,
 628     };
 629     vout_window_SendMouseEvent(window, &mouse);
 630 }
 631
 632 /**
 633  * Reports a mouse button release.
 634  *
 635  * \param window window in focus
 636  * \param button released button (see \ref vlc_mouse_button)
 637  */
 638 static inline void vout_window_ReportMouseReleased(vout_window_t *window,
 639                                                    int button)
 640 {
 641     const vout_window_mouse_event_t mouse = {
 642         VOUT_WINDOW_MOUSE_RELEASED, 0, 0, button,
 643     };
 644     vout_window_SendMouseEvent(window, &mouse);
 645 }
 646
 647 /**
 648  * Reports a mouse double-click.
 649  *
 650  * \param window window in focus
 651  * \param button double-clicked button (see \ref vlc_mouse_button)
 652  */
 653 static inline void vout_window_ReportMouseDoubleClick(vout_window_t *window,
 654                                                       int button)
 655 {
 656     const vout_window_mouse_event_t mouse = {
 657         VOUT_WINDOW_MOUSE_DOUBLE_CLICK, 0, 0, button,
 658     };
 659     vout_window_SendMouseEvent(window, &mouse);
 660 }
 661
 662 /**
 663  * Reports a keyboard key press.
 664  *
 665  * \param window window in focus
 666  * \param key VLC key code
 667  */
 668 static inline void vout_window_ReportKeyPress(vout_window_t *window, int key)
 669 {
 670     if (window->owner.cbs->keyboard_event != NULL)
 671         window->owner.cbs->keyboard_event(window, key);
 672 }
 673
 674 /**
 675  * Adds/removes a fullscreen output.
 676  *
 677  * This notifies the owner of the window that a usable fullscreen output has
 678  * been added, changed or removed.
 679  *
 680  * If an output with the same identifier is already known, its name will be
 681  * updated. Otherwise it will be added.
 682  * If the name parameter is NULL, the output will be removed.
 683  *
 684  * \param id unique nul-terminated identifier for the output
 685  * \param name human-readable name
 686  */
 687 static inline void vout_window_ReportOutputDevice(vout_window_t *window,
 688                                                   const char *id,
 689                                                   const char *name)
 690 {
 691     if (window->owner.cbs->output_event != NULL)
 692         window->owner.cbs->output_event(window, id, name);
 693 }
 694
 695 /** @} */
 696 #endif /* VLC_VOUT_WINDOW_H */