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