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