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>
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 bool is_fullscreen
; /* Is the display fullscreen */
86 /* Display properties */
88 /* Window title (may be NULL) */
99 /* Alignment of the picture inside the display */
105 /* Do we fill up the display with the video */
106 bool is_display_filled
;
109 * It will be applied to the whole display if b_display_filled is set, otherwise
110 * only on the video source */
116 vlc_viewpoint_t viewpoint
;
117 } vout_display_cfg_t
;
120 * Information from a vout_display_t to configure
121 * the core behaviour.
123 * By default they are all false or NULL.
127 bool is_slow
; /* The picture memory has slow read/write */
128 bool has_double_click
; /* Is double-click generated */
129 bool has_hide_mouse
; /* Is mouse automatically hidden */
130 bool has_pictures_invalid
; /* Will VOUT_DISPLAY_EVENT_PICTURES_INVALID be used */
131 bool needs_event_thread VLC_DEPRECATED
; /* Will events (key at least) be emitted using an independent thread */
132 const vlc_fourcc_t
*subpicture_chromas
; /* List of supported chromas for subpicture rendering. */
133 } vout_display_info_t
;
136 * Control query for vout_display_t
139 /* Hide the mouse. It will be sent when
140 * vout_display_t::info.b_hide_mouse is false */
141 VOUT_DISPLAY_HIDE_MOUSE
,
143 /* Ask to reset the internal buffers after a VOUT_DISPLAY_EVENT_PICTURES_INVALID
146 VOUT_DISPLAY_RESET_PICTURES
,
148 /* Ask the module to acknowledge/refuse the fullscreen state change after
149 * being requested (externally or by VOUT_DISPLAY_EVENT_FULLSCREEN */
150 VOUT_DISPLAY_CHANGE_FULLSCREEN
, /* bool fs */
151 #if defined(_WIN32) || defined(__OS2__)
152 /* Ask the module to acknowledge/refuse the window management state change
153 * after being requested externally or by VOUT_DISPLAY_WINDOW_STATE */
154 VOUT_DISPLAY_CHANGE_WINDOW_STATE
, /* unsigned state */
156 /* Ask the module to acknowledge/refuse the display size change requested
157 * (externally or by VOUT_DISPLAY_EVENT_DISPLAY_SIZE) */
158 VOUT_DISPLAY_CHANGE_DISPLAY_SIZE
, /* const vout_display_cfg_t *p_cfg */
160 /* Ask the module to acknowledge/refuse fill display state change after
161 * being requested externally */
162 VOUT_DISPLAY_CHANGE_DISPLAY_FILLED
, /* const vout_display_cfg_t *p_cfg */
164 /* Ask the module to acknowledge/refuse zoom change after being requested
166 VOUT_DISPLAY_CHANGE_ZOOM
, /* const vout_display_cfg_t *p_cfg */
168 /* Ask the module to acknowledge/refuse source aspect ratio after being
169 * requested externally */
170 VOUT_DISPLAY_CHANGE_SOURCE_ASPECT
, /* const video_format_t *p_source */
172 /* Ask the module to acknowledge/refuse source crop change after being
173 * requested externally.
174 * The cropping requested is stored by video_format_t::i_x/y_offset and
175 * video_format_t::i_visible_width/height */
176 VOUT_DISPLAY_CHANGE_SOURCE_CROP
, /* const video_format_t *p_source */
178 /* Ask the module to acknowledge/refuse VR/360° viewing direction after
179 * being requested externally */
180 VOUT_DISPLAY_CHANGE_VIEWPOINT
, /* const vout_display_cfg_t *p_cfg */
184 * Event from vout_display_t
186 * Events modifiying the state may be sent multiple times.
187 * Only the transition will be retained and acted upon.
191 * ZOOM ? DISPLAY_FILLED ? ON_TOP ?
194 VOUT_DISPLAY_EVENT_PICTURES_INVALID
, /* The buffer are now invalid and need to be changed */
196 VOUT_DISPLAY_EVENT_FULLSCREEN
,
197 #if defined(_WIN32) || defined(__OS2__)
198 VOUT_DISPLAY_EVENT_WINDOW_STATE
,
201 VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, /* The display size need to change : int i_width, int i_height */
204 VOUT_DISPLAY_EVENT_CLOSE
,
205 VOUT_DISPLAY_EVENT_KEY
,
208 * You can use it OR use the other mouse events. The core will do
211 VOUT_DISPLAY_EVENT_MOUSE_STATE
,
214 VOUT_DISPLAY_EVENT_MOUSE_MOVED
,
215 VOUT_DISPLAY_EVENT_MOUSE_PRESSED
,
216 VOUT_DISPLAY_EVENT_MOUSE_RELEASED
,
217 VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
,
220 VOUT_DISPLAY_EVENT_VIEWPOINT_MOVED
,
224 * Vout owner structures
226 struct vout_display_owner_t
{
227 /* Private place holder for the vout_display_t creator
231 /* Event coming from the module
233 * This function is set prior to the module instantiation and must not
234 * be overwritten nor used directly (use the vout_display_SendEvent*
237 * You can send it at any time i.e. from any vout_display_t functions or
238 * from another thread.
239 * Be careful, it does not ensure correct serialization if it is used
240 * from multiple threads.
242 void (*event
)(vout_display_t
*, int, va_list);
246 * These functions are set prior to the module instantiation and must not
247 * be overwritten nor used directly (use the vout_display_*Window
249 vout_window_t
*(*window_new
)(vout_display_t
*, unsigned type
);
250 void (*window_del
)(vout_display_t
*, vout_window_t
*);
253 struct vout_display_t
{
259 /* Initial and current configuration.
260 * You cannot modify it directly, you must use the appropriate events.
262 * It reflects the current values, i.e. after the event has been accepted
263 * and applied/configured if needed.
265 const vout_display_cfg_t
*cfg
;
267 /* video source format.
269 * Cropping is not requested while in the open function.
270 * You cannot change it.
272 video_format_t source
;
276 * You can only change it inside the module open function to
277 * match what you want, and when a VOUT_DISPLAY_RESET_PICTURES control
278 * request is made and succeeds.
280 * By default, it is equal to ::source except for the aspect ratio
281 * which is undefined(0) and is ignored.
287 * You can only set them in the open function.
289 vout_display_info_t info
;
291 /* Return a pointer over the current picture_pool_t* (mandatory).
293 * For performance reasons, it is best to provide at least count
294 * pictures but it is not mandatory.
295 * You can return NULL when you cannot/do not want to allocate
297 * The vout display module keeps the ownership of the pool and can
298 * destroy it only when closing or on invalid pictures control.
300 picture_pool_t
*(*pool
)(vout_display_t
*, unsigned count
);
302 /* Prepare a picture and an optional subpicture for display (optional).
304 * It is called before the next pf_display call to provide as much
305 * time as possible to prepare the given picture and the subpicture
307 * You are guaranted that pf_display will always be called and using
308 * the exact same picture_t and subpicture_t.
309 * You cannot change the pixel content of the picture_t or of the
312 void (*prepare
)(vout_display_t
*, picture_t
*, subpicture_t
*);
314 /* Display a picture and an optional subpicture (mandatory).
316 * The picture and the optional subpicture must be displayed as soon as
318 * You cannot change the pixel content of the picture_t or of the
321 * This function gives away the ownership of the picture and of the
322 * subpicture, so you must release them as soon as possible.
324 void (*display
)(vout_display_t
*, picture_t
*, subpicture_t
*);
326 /* Control on the module (mandatory) */
327 int (*control
)(vout_display_t
*, int, va_list);
329 /* Manage pending event (optional) */
330 void (*manage
)(vout_display_t
*);
332 /* Private place holder for the vout_display_t module (optional)
334 * A module is free to use it as it wishes.
336 vout_display_sys_t
*sys
;
338 /* Reserved for the vout_display_t owner.
340 * It must not be overwritten nor used directly by a module.
342 vout_display_owner_t owner
;
345 static inline void vout_display_SendEvent(vout_display_t
*vd
, int query
, ...)
348 va_start(args
, query
);
349 vd
->owner
.event(vd
, query
, args
);
353 static inline void vout_display_SendEventDisplaySize(vout_display_t
*vd
, int width
, int height
)
355 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, width
, height
);
357 static inline void vout_display_SendEventPicturesInvalid(vout_display_t
*vd
)
359 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_PICTURES_INVALID
);
361 static inline void vout_display_SendEventClose(vout_display_t
*vd
)
363 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_CLOSE
);
365 static inline void vout_display_SendEventKey(vout_display_t
*vd
, int key
)
367 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_KEY
, key
);
369 static inline void vout_display_SendEventFullscreen(vout_display_t
*vd
, bool is_fullscreen
,
370 bool is_window_fullscreen
)
372 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_FULLSCREEN
, is_fullscreen
, is_window_fullscreen
);
374 #if defined(_WIN32) || defined(__OS2__)
375 static inline void vout_display_SendWindowState(vout_display_t
*vd
, unsigned state
)
377 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_WINDOW_STATE
, state
);
380 /* The mouse position (State and Moved event) must be expressed against vout_display_t::source unit */
381 static inline void vout_display_SendEventMouseState(vout_display_t
*vd
, int x
, int y
, int button_mask
)
383 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_STATE
, x
, y
, button_mask
);
385 static inline void vout_display_SendEventMouseMoved(vout_display_t
*vd
, int x
, int y
)
387 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_MOVED
, x
, y
);
389 static inline void vout_display_SendEventMousePressed(vout_display_t
*vd
, int button
)
391 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_PRESSED
, button
);
393 static inline void vout_display_SendEventMouseReleased(vout_display_t
*vd
, int button
)
395 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_RELEASED
, button
);
397 static inline void vout_display_SendEventMouseDoubleClick(vout_display_t
*vd
)
399 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
);
401 static inline void vout_display_SendEventViewpointMoved(vout_display_t
*vd
,
402 const vlc_viewpoint_t
*vp
)
404 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_VIEWPOINT_MOVED
, vp
);
408 * Asks for a new window of a given type.
410 static inline vout_window_t
*vout_display_NewWindow(vout_display_t
*vd
, unsigned type
)
412 return vd
->owner
.window_new(vd
, type
);
415 * Deletes a window created by vout_display_NewWindow if window is non NULL
416 * or any unused windows otherwise.
418 static inline void vout_display_DeleteWindow(vout_display_t
*vd
,
419 vout_window_t
*window
)
421 vd
->owner
.window_del(vd
, window
);
424 static inline bool vout_display_IsWindowed(vout_display_t
*vd
)
426 vout_window_t
*window
= vout_display_NewWindow(vd
, VOUT_WINDOW_TYPE_INVALID
);
428 vout_display_DeleteWindow(vd
, window
);
429 return window
!= NULL
;
433 * Computes the default display size given the source and
434 * the display configuration.
436 * This asssumes that the picture is already cropped.
438 VLC_API
void vout_display_GetDefaultDisplaySize(unsigned *width
, unsigned *height
, const video_format_t
*source
, const vout_display_cfg_t
*);
442 * Structure used to store the result of a vout_display_PlacePicture.
449 } vout_display_place_t
;
452 * Computes how to place a picture inside the display to respect
453 * the given parameters.
454 * This assumes that cropping is done by an external mean.
456 * \param p_place Place inside the window (window pixel unit)
457 * \param p_source Video source format
458 * \param p_cfg Display configuration
459 * \param b_clip If true, prevent the video to go outside the display (break zoom).
461 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
);
465 * Helper function that applies the necessary transforms to the mouse position
466 * and then calls vout_display_SendEventMouseMoved.
468 * \param vd vout_display_t.
469 * \param orient_display The orientation of the picture as seen on screen (probably ORIENT_NORMAL).
470 * \param m_x Mouse x position (relative to place, origin is top left).
471 * \param m_y Mouse y position (relative to place, origin is top left).
472 * \param place Place of the picture.
474 VLC_API
void vout_display_SendMouseMovedDisplayCoordinates(vout_display_t
*vd
, video_orientation_t orient_display
, int m_x
, int m_y
,
475 vout_display_place_t
*place
);
478 #endif /* VLC_VOUT_DISPLAY_H */