1 /*****************************************************************************
2 * vlc_vout_display.h: vout_display_t definitions
3 *****************************************************************************
4 * Copyright (C) 2009 Laurent Aimar
7 * Authors: Laurent Aimar <fenrir _AT_ videolan _DOT_ org>
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.
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.
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 *****************************************************************************/
24 #ifndef VLC_VOUT_DISPLAY_H
25 #define VLC_VOUT_DISPLAY_H 1
28 #include <vlc_picture.h>
29 #include <vlc_picture_pool.h>
30 #include <vlc_subpicture.h>
31 #include <vlc_actions.h>
32 #include <vlc_mouse.h>
34 #include <vlc_vout_window.h>
35 #include <vlc_viewpoint.h>
38 * \defgroup video_display Video output display
39 * Video output display: output buffers and rendering
41 * \ingroup video_output
44 * Video output display modules interface
48 * Do NOT use video_format_t::i_aspect but i_sar_num/den everywhere. i_aspect
49 * will be removed as soon as possible.
52 typedef struct vout_display_t vout_display_t
;
53 typedef struct vout_display_sys_t vout_display_sys_t
;
54 typedef struct vout_display_owner_t vout_display_owner_t
;
57 * Possible alignments for vout_display.
61 VOUT_DISPLAY_ALIGN_CENTER
,
63 VOUT_DISPLAY_ALIGN_LEFT
,
64 VOUT_DISPLAY_ALIGN_RIGHT
,
66 VOUT_DISPLAY_ALIGN_TOP
,
67 VOUT_DISPLAY_ALIGN_BOTTOM
,
68 } vout_display_align_t
;
71 * Window management state.
74 VOUT_WINDOW_STATE_NORMAL
=0,
75 VOUT_WINDOW_STATE_ABOVE
=1,
76 VOUT_WINDOW_STATE_BELOW
=2,
77 VOUT_WINDOW_STACK_MASK
=3,
81 * Initial/Current configuration for a vout_display_t
84 #if defined(_WIN32) || defined(__OS2__)
85 bool is_fullscreen VLC_DEPRECATED
; /* Is the display fullscreen */
88 /* Display properties */
90 /* Window title (may be NULL) */
101 /* Alignment of the picture inside the display */
107 /* Do we fill up the display with the video */
108 bool is_display_filled
;
111 * It will be applied to the whole display if b_display_filled is set, otherwise
112 * only on the video source */
118 vlc_viewpoint_t viewpoint
;
119 } vout_display_cfg_t
;
122 * Information from a vout_display_t to configure
123 * the core behaviour.
125 * By default they are all false or NULL.
129 bool is_slow
; /* The picture memory has slow read/write */
130 bool has_double_click
; /* Is double-click generated */
131 bool needs_hide_mouse
; /* Needs VOUT_DISPLAY_HIDE_MOUSE */
132 bool has_pictures_invalid
; /* Will VOUT_DISPLAY_EVENT_PICTURES_INVALID be used */
133 const vlc_fourcc_t
*subpicture_chromas
; /* List of supported chromas for subpicture rendering. */
134 } vout_display_info_t
;
137 * Control query for vout_display_t
140 /* Hide the mouse. It will be sent when
141 * vout_display_t::info.needs_hide_mouse is true */
142 VOUT_DISPLAY_HIDE_MOUSE VLC_DEPRECATED_ENUM
,
144 /* Ask to reset the internal buffers after a VOUT_DISPLAY_EVENT_PICTURES_INVALID
147 VOUT_DISPLAY_RESET_PICTURES
,
149 #if defined(_WIN32) || defined(__OS2__)
150 /* Ask the module to acknowledge/refuse the fullscreen state change after
151 * being requested (externally or by VOUT_DISPLAY_EVENT_FULLSCREEN */
152 VOUT_DISPLAY_CHANGE_FULLSCREEN VLC_DEPRECATED_ENUM
, /* bool fs */
153 /* Ask the module to acknowledge/refuse the window management state change
154 * after being requested externally or by VOUT_DISPLAY_WINDOW_STATE */
155 VOUT_DISPLAY_CHANGE_WINDOW_STATE VLC_DEPRECATED_ENUM
, /* unsigned state */
157 /* Ask the module to acknowledge/refuse the display size change requested
158 * (externally or by VOUT_DISPLAY_EVENT_DISPLAY_SIZE) */
159 VOUT_DISPLAY_CHANGE_DISPLAY_SIZE
, /* const vout_display_cfg_t *p_cfg */
161 /* Ask the module to acknowledge/refuse fill display state change after
162 * being requested externally */
163 VOUT_DISPLAY_CHANGE_DISPLAY_FILLED
, /* const vout_display_cfg_t *p_cfg */
165 /* Ask the module to acknowledge/refuse zoom change after being requested
167 VOUT_DISPLAY_CHANGE_ZOOM
, /* const vout_display_cfg_t *p_cfg */
169 /* Ask the module to acknowledge/refuse source aspect ratio after being
170 * requested externally */
171 VOUT_DISPLAY_CHANGE_SOURCE_ASPECT
,
173 /* Ask the module to acknowledge/refuse source crop change after being
174 * requested externally.
175 * The cropping requested is stored by video_format_t::i_x/y_offset and
176 * video_format_t::i_visible_width/height */
177 VOUT_DISPLAY_CHANGE_SOURCE_CROP
,
179 /* Ask the module to acknowledge/refuse VR/360° viewing direction after
180 * being requested externally */
181 VOUT_DISPLAY_CHANGE_VIEWPOINT
, /* const vout_display_cfg_t *p_cfg */
185 * Event from vout_display_t
187 * Events modifiying the state may be sent multiple times.
188 * Only the transition will be retained and acted upon.
192 * ZOOM ? DISPLAY_FILLED ? ON_TOP ?
195 VOUT_DISPLAY_EVENT_PICTURES_INVALID
, /* The buffer are now invalid and need to be changed */
197 #if defined(_WIN32) || defined(__OS2__)
198 VOUT_DISPLAY_EVENT_FULLSCREEN
,
199 VOUT_DISPLAY_EVENT_WINDOW_STATE
,
202 VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, /* The display size need to change : int i_width, int i_height */
205 VOUT_DISPLAY_EVENT_CLOSE
,
206 VOUT_DISPLAY_EVENT_KEY
,
209 * You can use it OR use the other mouse events. The core will do
212 VOUT_DISPLAY_EVENT_MOUSE_STATE
,
215 VOUT_DISPLAY_EVENT_MOUSE_MOVED
,
216 VOUT_DISPLAY_EVENT_MOUSE_PRESSED
,
217 VOUT_DISPLAY_EVENT_MOUSE_RELEASED
,
218 VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
,
221 VOUT_DISPLAY_EVENT_VIEWPOINT_MOVED
,
225 * Vout owner structures
227 struct vout_display_owner_t
{
228 /* Private place holder for the vout_display_t creator
232 /* Event coming from the module
234 * This function is set prior to the module instantiation and must not
235 * be overwritten nor used directly (use the vout_display_SendEvent*
238 * You can send it at any time i.e. from any vout_display_t functions or
239 * from another thread.
240 * Be careful, it does not ensure correct serialization if it is used
241 * from multiple threads.
243 void (*event
)(vout_display_t
*, int, va_list);
247 * These functions are set prior to the module instantiation and must not
248 * be overwritten nor used directly (use the vout_display_*Window
250 vout_window_t
*(*window_new
)(vout_display_t
*, unsigned type
);
251 void (*window_del
)(vout_display_t
*, vout_window_t
*);
254 struct vout_display_t
{
260 /* Initial and current configuration.
261 * You cannot modify it directly, you must use the appropriate events.
263 * It reflects the current values, i.e. after the event has been accepted
264 * and applied/configured if needed.
266 const vout_display_cfg_t
*cfg
;
268 /* video source format.
270 * Cropping is not requested while in the open function.
271 * You cannot change it.
273 video_format_t source
;
277 * You can only change it inside the module open function to
278 * match what you want, and when a VOUT_DISPLAY_RESET_PICTURES control
279 * request is made and succeeds.
281 * By default, it is equal to ::source except for the aspect ratio
282 * which is undefined(0) and is ignored.
288 * You can only set them in the open function.
290 vout_display_info_t info
;
292 /* Return a pointer over the current picture_pool_t* (mandatory).
294 * For performance reasons, it is best to provide at least count
295 * pictures but it is not mandatory.
296 * You can return NULL when you cannot/do not want to allocate
298 * The vout display module keeps the ownership of the pool and can
299 * destroy it only when closing or on invalid pictures control.
301 picture_pool_t
*(*pool
)(vout_display_t
*, unsigned count
);
303 /* Prepare a picture and an optional subpicture for display (optional).
305 * It is called before the next pf_display call to provide as much
306 * time as possible to prepare the given picture and the subpicture
308 * You are guaranted that pf_display will always be called and using
309 * the exact same picture_t and subpicture_t.
310 * You cannot change the pixel content of the picture_t or of the
313 void (*prepare
)(vout_display_t
*, picture_t
*, subpicture_t
*);
315 /* Display a picture and an optional subpicture (mandatory).
317 * The picture and the optional subpicture must be displayed as soon as
319 * You cannot change the pixel content of the picture_t or of the
322 * This function gives away the ownership of the picture and of the
323 * subpicture, so you must release them as soon as possible.
325 void (*display
)(vout_display_t
*, picture_t
*, subpicture_t
*);
327 /* Control on the module (mandatory) */
328 int (*control
)(vout_display_t
*, int, va_list);
330 /* Manage pending event (optional) */
331 void (*manage
)(vout_display_t
*) VLC_DEPRECATED
;
333 /* Private place holder for the vout_display_t module (optional)
335 * A module is free to use it as it wishes.
337 vout_display_sys_t
*sys
;
339 /* Reserved for the vout_display_t owner.
341 * It must not be overwritten nor used directly by a module.
343 vout_display_owner_t owner
;
346 static inline void vout_display_SendEvent(vout_display_t
*vd
, int query
, ...)
349 va_start(args
, query
);
350 vd
->owner
.event(vd
, query
, args
);
354 static inline void vout_display_SendEventDisplaySize(vout_display_t
*vd
, int width
, int height
)
356 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, width
, height
);
358 static inline void vout_display_SendEventPicturesInvalid(vout_display_t
*vd
)
360 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_PICTURES_INVALID
);
362 static inline void vout_display_SendEventClose(vout_display_t
*vd
)
364 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_CLOSE
);
366 static inline void vout_display_SendEventKey(vout_display_t
*vd
, int key
)
368 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_KEY
, key
);
370 #if defined(_WIN32) || defined(__OS2__)
371 static inline void vout_display_SendEventFullscreen(vout_display_t
*vd
, bool is_fullscreen
,
372 bool is_window_fullscreen
)
374 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_FULLSCREEN
, is_fullscreen
, is_window_fullscreen
);
376 static inline void vout_display_SendWindowState(vout_display_t
*vd
, unsigned state
)
378 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_WINDOW_STATE
, state
);
381 /* The mouse position (State and Moved event) must be expressed against vout_display_t::source unit */
382 static inline void vout_display_SendEventMouseState(vout_display_t
*vd
, int x
, int y
, int button_mask
)
384 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_STATE
, x
, y
, button_mask
);
386 static inline void vout_display_SendEventMouseMoved(vout_display_t
*vd
, int x
, int y
)
388 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_MOVED
, x
, y
);
390 static inline void vout_display_SendEventMousePressed(vout_display_t
*vd
, int button
)
392 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_PRESSED
, button
);
394 static inline void vout_display_SendEventMouseReleased(vout_display_t
*vd
, int button
)
396 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_RELEASED
, button
);
398 static inline void vout_display_SendEventMouseDoubleClick(vout_display_t
*vd
)
400 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
);
402 static inline void vout_display_SendEventViewpointMoved(vout_display_t
*vd
,
403 const vlc_viewpoint_t
*vp
)
405 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_VIEWPOINT_MOVED
, vp
);
409 * Asks for a new window of a given type.
411 static inline vout_window_t
*vout_display_NewWindow(vout_display_t
*vd
, unsigned type
)
413 return vd
->owner
.window_new(vd
, type
);
416 * Deletes a window created by vout_display_NewWindow if window is non NULL
417 * or any unused windows otherwise.
419 static inline void vout_display_DeleteWindow(vout_display_t
*vd
,
420 vout_window_t
*window
)
422 vd
->owner
.window_del(vd
, window
);
425 static inline bool vout_display_IsWindowed(vout_display_t
*vd
)
427 vout_window_t
*window
= vout_display_NewWindow(vd
, VOUT_WINDOW_TYPE_INVALID
);
429 vout_display_DeleteWindow(vd
, window
);
430 return window
!= NULL
;
434 * Computes the default display size given the source and
435 * the display configuration.
437 * This asssumes that the picture is already cropped.
439 VLC_API
void vout_display_GetDefaultDisplaySize(unsigned *width
, unsigned *height
, const video_format_t
*source
, const vout_display_cfg_t
*);
443 * Structure used to store the result of a vout_display_PlacePicture.
450 } vout_display_place_t
;
453 * Computes how to place a picture inside the display to respect
454 * the given parameters.
455 * This assumes that cropping is done by an external mean.
457 * \param p_place Place inside the window (window pixel unit)
458 * \param p_source Video source format
459 * \param p_cfg Display configuration
460 * \param b_clip If true, prevent the video to go outside the display (break zoom).
462 VLC_API
void vout_display_PlacePicture(vout_display_place_t
*place
, const video_format_t
*source
, const vout_display_cfg_t
*cfg
, bool do_clipping
);
466 * Helper function that applies the necessary transforms to the mouse position
467 * and then calls vout_display_SendEventMouseMoved.
469 * \param vd vout_display_t.
470 * \param orient_display The orientation of the picture as seen on screen (probably ORIENT_NORMAL).
471 * \param m_x Mouse x position (relative to place, origin is top left).
472 * \param m_y Mouse y position (relative to place, origin is top left).
473 * \param place Place of the picture.
475 VLC_API
void vout_display_SendMouseMovedDisplayCoordinates(vout_display_t
*vd
, video_orientation_t orient_display
, int m_x
, int m_y
,
476 vout_display_place_t
*place
);
479 #endif /* VLC_VOUT_DISPLAY_H */