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