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: 3a613d4e4701783a43cefd299e171f95164e30e9 $
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
vout_window_vaControl(vout_window_t * window,int query,va_list ap)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 */
vout_window_Control(vout_window_t * window,int query,...)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 */
vout_window_SetState(vout_window_t * window,unsigned state)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 */
vout_window_SetSize(vout_window_t * window,unsigned width,unsigned height)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 */
vout_window_SetFullScreen(vout_window_t * window,bool full)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 */
vout_window_HideMouse(vout_window_t * window,bool hide)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 */
vout_window_ReportSize(vout_window_t * window,unsigned width,unsigned height)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
vout_window_ReportClose(vout_window_t * window)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
vout_window_SendMouseEvent(vout_window_t * window,const vout_window_mouse_event_t * mouse)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 */
vout_window_ReportMouseState(vout_window_t * window,int x,int y,int button_mask)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 */
vout_window_ReportMouseMoved(vout_window_t * window,int x,int y)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 */
vout_window_ReportMousePressed(vout_window_t * window,int button)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 */
vout_window_ReportMouseReleased(vout_window_t * window,int button)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 */
vout_window_ReportMouseDoubleClick(vout_window_t * window,int button)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 */
374