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_INVALID=0 /**< Invalid or unspecified window type */,
  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, /* int b_fullscreen */
  65     VOUT_WINDOW_HIDE_MOUSE, /* int b_hide */
  66 };
  67
  68 /**
  69  * Window mouse event type for vout_window_mouse_event_t
  70  */
  71 enum vout_window_mouse_event_type {
  72     VOUT_WINDOW_MOUSE_STATE,
  73     VOUT_WINDOW_MOUSE_MOVED,
  74     VOUT_WINDOW_MOUSE_PRESSED,
  75     VOUT_WINDOW_MOUSE_RELEASED,
  76     VOUT_WINDOW_MOUSE_DOUBLE_CLICK,
  77 };
  78
  79 /**
  80  * Window mouse event
  81  */
  82 typedef struct vout_window_mouse_event_t
  83 {
  84     enum vout_window_mouse_event_type type;
  85     int x;
  86     int y;
  87     int button_mask;
  88 } vout_window_mouse_event_t;
  89
  90 typedef struct vout_window_cfg_t {
  91     /* Window handle type */
  92     unsigned type;
  93
  94     /* If true, a standalone window is requested */
  95     bool is_standalone;
  96     bool is_fullscreen;
  97
  98 #ifdef __APPLE__
  99     /* Window position hint */
 100     int x;
 101     int y;
 102 #endif
 103
 104     /* Windows size hint */
 105     unsigned width;
 106     unsigned height;
 107
 108 } vout_window_cfg_t;
 109
 110 typedef struct vout_window_owner {
 111     void *sys;
 112     void (*resized)(vout_window_t *, unsigned width, unsigned height);
 113     void (*closed)(vout_window_t *);
 114     void (*mouse_event)(vout_window_t *, const vout_window_mouse_event_t *mouse);
 115 } vout_window_owner_t;
 116
 117 /**
 118  * Graphical window
 119  *
 120  * This structure is an abstract interface to the windowing system.
 121  * The window is normally used to draw video (and subpictures) into, but it
 122  * can also be used for other purpose (e.g. OpenGL visualization).
 123  *
 124  * The window is responsible for providing a window handle, whose exact
 125  * meaning depends on the windowing system. It also must report some events
 126  * such as user input (keyboard, mouse) and window resize.
 127  *
 128  * Finally, it must support some control requests such as for fullscreen mode.
 129  */
 130 struct vout_window_t {
 131     VLC_COMMON_MEMBERS
 132
 133      /**
 134       * Window handle type
 135       *
 136       * This identified the windowing system and protocol that the window
 137       * needs to use. This also selects which member of the \ref handle union
 138       * and the \ref display union are to be set.
 139       *
 140       * The possible values are defined in \ref vout_window_type.
 141       *
 142       * VOUT_WINDOW_TYPE_INVALID is a special placeholder type. It means that
 143       * any windowing system is acceptable. In that case, the plugin must set
 144       * its actual type during activation.
 145       */
 146     unsigned type;
 147
 148     /**
 149      * Window handle (mandatory)
 150      *
 151      * This must be filled by the plugin upon activation.
 152      *
 153      * Depending on the \ref type above, a different member of this union is
 154      * used.
 155      */
 156     union {
 157         void     *hwnd;          /**< Win32 window handle */
 158         uint32_t xid;            /**< X11 windows ID */
 159         void     *nsobject;      /**< Mac OSX view object */
 160         void     *anativewindow; /**< Android native window */
 161         struct wl_surface *wl;   /**< Wayland surface (client pointer) */
 162     } handle;
 163
 164     /** Display server (mandatory)
 165      *
 166      * This must be filled by the plugin upon activation.
 167      *
 168      * The window handle is relative to the display server. The exact meaning
 169      * of the display server depends on the window handle type. Not all window
 170      * handle type provide a display server field.
 171      */
 172     union {
 173         char     *x11; /**< X11 display string (NULL = use default) */
 174         struct wl_display *wl; /**< Wayland display (client pointer) */
 175     } display;
 176
 177     /**
 178      * Control callback (mandatory)
 179      *
 180      * This callback handles some control request regarding the window.
 181      * See \ref vout_window_control.
 182      *
 183      * This field should not be used directly when manipulating a window.
 184      * vout_window_Control() should be used instead.
 185      */
 186     int (*control)(vout_window_t *, int query, va_list);
 187
 188     struct {
 189         bool has_double_click; /**< Whether double click events are sent,
 190                                     or need to be emulated */
 191     } info;
 192
 193     /* Private place holder for the vout_window_t module (optional)
 194      *
 195      * A module is free to use it as it wishes.
 196      */
 197     vout_window_sys_t *sys;
 198
 199     vout_window_owner_t owner;
 200 };
 201
 202 /**
 203  * Creates a new window.
 204  *
 205  * @param module plugin name (usually "$window")
 206  * @note If you are inside a "vout display", you must use
 207  / vout_display_NewWindow() and vout_display_DeleteWindow() instead.
 208  * This enables recycling windows.
 209  */
 210 VLC_API vout_window_t * vout_window_New(vlc_object_t *, const char *module, const vout_window_cfg_t *, const vout_window_owner_t *);
 211
 212 /**
 213  * Deletes a window created by vout_window_New().
 214  *
 215  * @note See vout_window_New() about window recycling.
 216  */
 217 VLC_API void vout_window_Delete(vout_window_t *);
 218
 219 void vout_window_SetInhibition(vout_window_t *window, bool enabled);
 220
 221 static inline int vout_window_vaControl(vout_window_t *window, int query,
 222                                         va_list ap)
 223 {
 224     return window->control(window, query, ap);
 225 }
 226
 227 /**
 228  * Reconfigures a window.
 229  *
 230  * @note The vout_window_* wrappers should be used instead of this function.
 231  *
 232  * @warning The caller must own the window, as vout_window_t is not thread safe.
 233  */
 234 static inline int vout_window_Control(vout_window_t *window, int query, ...)
 235 {
 236     va_list ap;
 237     int ret;
 238
 239     va_start(ap, query);
 240     ret = vout_window_vaControl(window, query, ap);
 241     va_end(ap);
 242     return ret;
 243 }
 244
 245 /**
 246  * Configures the window manager state for this window.
 247  */
 248 static inline int vout_window_SetState(vout_window_t *window, unsigned state)
 249 {
 250     return vout_window_Control(window, VOUT_WINDOW_SET_STATE, state);
 251 }
 252
 253 /**
 254  * Configures the window display (i.e. inner/useful) size.
 255  */
 256 static inline int vout_window_SetSize(vout_window_t *window,
 257                                       unsigned width, unsigned height)
 258 {
 259     return vout_window_Control(window, VOUT_WINDOW_SET_SIZE, width, height);
 260 }
 261
 262 /**
 263  * Sets fullscreen mode.
 264  */
 265 static inline int vout_window_SetFullScreen(vout_window_t *window, bool full)
 266 {
 267     return vout_window_Control(window, VOUT_WINDOW_SET_FULLSCREEN, full);
 268 }
 269
 270 /**
 271  * Hide the mouse cursor
 272  */
 273 static inline int vout_window_HideMouse(vout_window_t *window, bool hide)
 274 {
 275     return vout_window_Control(window, VOUT_WINDOW_HIDE_MOUSE, hide);
 276 }
 277
 278 /**
 279  * Report current window size
 280  *
 281  * This notifies the user of the window what the pixel dimensions of the
 282  * window are (or should be, depending on the windowing system).
 283  *
 284  * \note This function is thread-safe. In case of concurrent call, it is
 285  * undefined which one is taken into account (but at least one is).
 286  */
 287 static inline void vout_window_ReportSize(vout_window_t *window,
 288                                           unsigned width, unsigned height)
 289 {
 290     if (window->owner.resized != NULL)
 291         window->owner.resized(window, width, height);
 292 }
 293
 294 static inline void vout_window_ReportClose(vout_window_t *window)
 295 {
 296     if (window->owner.closed != NULL)
 297         window->owner.closed(window);
 298 }
 299
 300 static inline void vout_window_SendMouseEvent(vout_window_t *window,
 301                                               const vout_window_mouse_event_t *mouse)
 302 {
 303     if (window->owner.mouse_event != NULL)
 304         window->owner.mouse_event(window, mouse);
 305 }
 306
 307 /**
 308  * Send a full mouse state
 309  *
 310  * The mouse position must be expressed against window unit. You can use this
 311  * function of others vout_window_ReportMouse*() functions.
 312  */
 313 static inline void vout_window_ReportMouseState(vout_window_t *window,
 314                                                 int x, int y, int button_mask)
 315 {
 316     const vout_window_mouse_event_t mouse = {
 317         VOUT_WINDOW_MOUSE_STATE, x, y, button_mask
 318     };
 319     vout_window_SendMouseEvent(window, &mouse);
 320 }
 321
 322 /**
 323  * Send a mouse movement
 324  *
 325  * The mouse position must be expressed against window unit.
 326  */
 327 static inline void vout_window_ReportMouseMoved(vout_window_t *window,
 328                                                 int x, int y)
 329 {
 330     const vout_window_mouse_event_t mouse = {
 331         VOUT_WINDOW_MOUSE_MOVED, x, y, 0
 332     };
 333     vout_window_SendMouseEvent(window, &mouse);
 334 }
 335
 336 /**
 337  * Send a mouse pressed event
 338  */
 339 static inline void vout_window_ReportMousePressed(vout_window_t *window,
 340                                                   int button)
 341 {
 342     const vout_window_mouse_event_t mouse = {
 343         VOUT_WINDOW_MOUSE_PRESSED, 0, 0, button,
 344     };
 345     vout_window_SendMouseEvent(window, &mouse);
 346 }
 347
 348 /**
 349  * Send a mouse released event
 350  */
 351 static inline void vout_window_ReportMouseReleased(vout_window_t *window,
 352                                                   int button)
 353 {
 354     const vout_window_mouse_event_t mouse = {
 355         VOUT_WINDOW_MOUSE_RELEASED, 0, 0, button,
 356     };
 357     vout_window_SendMouseEvent(window, &mouse);
 358 }
 359
 360 /**
 361  * Send a mouse double click event
 362  */
 363 static inline void vout_window_ReportMouseDoubleClick(vout_window_t *window,
 364                                                       int button)
 365 {
 366     const vout_window_mouse_event_t mouse = {
 367         VOUT_WINDOW_MOUSE_DOUBLE_CLICK, 0, 0, button,
 368     };
 369     vout_window_SendMouseEvent(window, &mouse);
 370 }
 371
 372 /** @} */
 373 #endif /* VLC_VOUT_WINDOW_H */