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
8 * Authors: Laurent Aimar <fenrir _AT_ videolan _DOT_ org>
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.
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.
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 *****************************************************************************/
25 #ifndef VLC_VOUT_WINDOW_H
26 #define VLC_VOUT_WINDOW_H 1
29 #include <vlc_common.h>
32 * \defgroup video_window Video window
33 * \ingroup video_output
34 * Video output window management
37 * Video output window modules interface
40 typedef struct vout_window_t vout_window_t
;
41 typedef struct vout_window_sys_t vout_window_sys_t
;
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 */,
59 * Control query for vout_window_t
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
,
70 * Window management state.
72 enum vout_window_state
{
73 VOUT_WINDOW_STATE_NORMAL
,
74 VOUT_WINDOW_STATE_ABOVE
,
75 VOUT_WINDOW_STATE_BELOW
,
79 * Window mouse event type for vout_window_mouse_event_t
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
,
91 typedef struct vout_window_mouse_event_t
93 enum vout_window_mouse_event_type type
;
97 } vout_window_mouse_event_t
;
99 typedef struct vout_window_cfg_t
{
100 /* If true, a standalone window is requested */
106 /* Window position hint */
111 /* Windows size hint */
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
);
124 void (*mouse_event
)(vout_window_t
*,
125 const vout_window_mouse_event_t
*mouse
);
126 void (*keyboard_event
)(vout_window_t
*, unsigned key
);
128 void (*output_event
)(vout_window_t
*, const char *id
, const char *desc
);
131 typedef struct vout_window_owner
{
132 const struct vout_window_callbacks
*cbs
;
134 } vout_window_owner_t
;
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).
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.
147 * Finally, it must support some control requests such as for fullscreen mode.
149 struct vout_window_t
{
150 struct vlc_common_members obj
;
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.
159 * The possible values are defined in \ref vout_window_type.
164 * Window handle (mandatory)
166 * This must be filled by the plugin upon activation.
168 * Depending on the \ref type above, a different member of this union is
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) */
179 /** Display server (mandatory)
181 * This must be filled by the plugin upon activation.
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.
188 char *x11
; /**< X11 display string (NULL = use default) */
189 struct wl_display
*wl
; /**< Wayland display (client pointer) */
193 * Control callback (mandatory)
195 * This callback handles some control request regarding the window.
196 * See \ref vout_window_control.
198 * This field should not be used directly when manipulating a window.
199 * vout_window_Control() should be used instead.
201 int (*control
)(vout_window_t
*, int query
, va_list);
204 bool has_double_click
; /**< Whether double click events are sent,
205 or need to be emulated */
208 /* Private place holder for the vout_window_t module (optional)
210 * A module is free to use it as it wishes.
212 vout_window_sys_t
*sys
;
214 vout_window_owner_t owner
;
218 * Creates a new window.
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.
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
*);
227 * Deletes a window created by vout_window_New().
229 * @note See vout_window_New() about window recycling.
231 VLC_API
void vout_window_Delete(vout_window_t
*);
233 void vout_window_SetInhibition(vout_window_t
*window
, bool enabled
);
235 static inline int vout_window_vaControl(vout_window_t
*window
, int query
,
238 return window
->control(window
, query
, ap
);
242 * Reconfigures a window.
244 * @note The vout_window_* wrappers should be used instead of this function.
246 * @warning The caller must own the window, as vout_window_t is not thread safe.
248 static inline int vout_window_Control(vout_window_t
*window
, int query
, ...)
254 ret
= vout_window_vaControl(window
, query
, ap
);
260 * Configures the window manager state for this window.
262 static inline int vout_window_SetState(vout_window_t
*window
, unsigned state
)
264 return vout_window_Control(window
, VOUT_WINDOW_SET_STATE
, state
);
268 * Configures the window display (i.e. inner/useful) size.
270 static inline int vout_window_SetSize(vout_window_t
*window
,
271 unsigned width
, unsigned height
)
273 return vout_window_Control(window
, VOUT_WINDOW_SET_SIZE
, width
, height
);
277 * Requests fullscreen mode.
279 * \param id nul-terminated output identifier, NULL for default
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.
286 static inline int vout_window_SetFullScreen(vout_window_t
*window
,
289 return vout_window_Control(window
, VOUT_WINDOW_SET_FULLSCREEN
, id
);
293 * Requests windowed mode.
295 * \return \see vout_window_SetFullScreen()
297 static inline int vout_window_UnsetFullScreen(vout_window_t
*window
)
299 return vout_window_Control(window
, VOUT_WINDOW_UNSET_FULLSCREEN
);
303 * Report current window size
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).
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).
311 static inline void vout_window_ReportSize(vout_window_t
*window
,
312 unsigned width
, unsigned height
)
314 window
->owner
.cbs
->resized(window
, width
, height
);
317 static inline void vout_window_ReportClose(vout_window_t
*window
)
319 if (window
->owner
.cbs
->closed
!= NULL
)
320 window
->owner
.cbs
->closed(window
);
324 * Reports the current window state.
326 * This notifies the owner of the window that the state of the window changed.
327 * \param state \see vout_window_state
329 static inline void vout_window_ReportState(vout_window_t
*window
,
332 if (window
->owner
.cbs
->state_changed
!= NULL
)
333 window
->owner
.cbs
->state_changed(window
, state
);
337 * Reports that the window is not in full screen.
339 * This notifies the owner of the window that the window is windowed, i.e. not
340 * in full screen mode.
342 static inline void vout_window_ReportWindowed(vout_window_t
*window
)
344 if (window
->owner
.cbs
->windowed
!= NULL
)
345 window
->owner
.cbs
->windowed(window
);
349 * Reports that the window is in full screen.
351 * \param id fullscreen output nul-terminated identifier, NULL for default
353 static inline void vout_window_ReportFullscreen(vout_window_t
*window
,
356 if (window
->owner
.cbs
->fullscreened
!= NULL
)
357 window
->owner
.cbs
->fullscreened(window
, id
);
360 static inline void vout_window_SendMouseEvent(vout_window_t
*window
,
361 const vout_window_mouse_event_t
*mouse
)
363 if (window
->owner
.cbs
->mouse_event
!= NULL
)
364 window
->owner
.cbs
->mouse_event(window
, mouse
);
368 * Send a mouse movement
370 * The mouse position must be expressed against window unit.
372 static inline void vout_window_ReportMouseMoved(vout_window_t
*window
,
375 const vout_window_mouse_event_t mouse
= {
376 VOUT_WINDOW_MOUSE_MOVED
, x
, y
, 0
378 vout_window_SendMouseEvent(window
, &mouse
);
382 * Send a mouse pressed event
384 static inline void vout_window_ReportMousePressed(vout_window_t
*window
,
387 const vout_window_mouse_event_t mouse
= {
388 VOUT_WINDOW_MOUSE_PRESSED
, 0, 0, button
,
390 vout_window_SendMouseEvent(window
, &mouse
);
394 * Send a mouse released event
396 static inline void vout_window_ReportMouseReleased(vout_window_t
*window
,
399 const vout_window_mouse_event_t mouse
= {
400 VOUT_WINDOW_MOUSE_RELEASED
, 0, 0, button
,
402 vout_window_SendMouseEvent(window
, &mouse
);
406 * Send a mouse double click event
408 static inline void vout_window_ReportMouseDoubleClick(vout_window_t
*window
,
411 const vout_window_mouse_event_t mouse
= {
412 VOUT_WINDOW_MOUSE_DOUBLE_CLICK
, 0, 0, button
,
414 vout_window_SendMouseEvent(window
, &mouse
);
417 static inline void vout_window_ReportKeyPress(vout_window_t
*window
, int key
)
419 if (window
->owner
.cbs
->keyboard_event
!= NULL
)
420 window
->owner
.cbs
->keyboard_event(window
, key
);
424 * Adds/removes a fullscreen output.
426 * This notifies the owner of the window that a usable fullscreen output has
427 * been added, changed or removed.
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.
433 * \param id unique nul-terminated identifier for the output
434 * \param name human-readable name
436 static inline void vout_window_ReportOutputDevice(vout_window_t
*window
,
440 if (window
->owner
.cbs
->output_event
!= NULL
)
441 window
->owner
.cbs
->output_event(window
, id
, name
);
445 #endif /* VLC_VOUT_WINDOW_H */