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>
37 * \defgroup video_display Video output display
38 * Video output display: output buffers and rendering
40 * \ingroup video_output
43 * Video output display modules interface
47 * Do NOT use video_format_t::i_aspect but i_sar_num/den everywhere. i_aspect
48 * will be removed as soon as possible.
51 typedef struct vout_display_t vout_display_t
;
52 typedef struct vout_display_sys_t vout_display_sys_t
;
53 typedef struct vout_display_owner_t vout_display_owner_t
;
56 * Possible alignments for vout_display.
60 VOUT_DISPLAY_ALIGN_CENTER
,
62 VOUT_DISPLAY_ALIGN_LEFT
,
63 VOUT_DISPLAY_ALIGN_RIGHT
,
65 VOUT_DISPLAY_ALIGN_TOP
,
66 VOUT_DISPLAY_ALIGN_BOTTOM
,
67 } vout_display_align_t
;
70 * Window management state.
73 VOUT_WINDOW_STATE_NORMAL
=0,
74 VOUT_WINDOW_STATE_ABOVE
=1,
75 VOUT_WINDOW_STATE_BELOW
=2,
76 VOUT_WINDOW_STACK_MASK
=3,
80 * Initial/Current configuration for a vout_display_t
83 bool is_fullscreen
; /* Is the display fullscreen */
85 /* Display properties */
87 /* Window title (may be NULL) */
98 /* Alignment of the picture inside the display */
104 /* Do we fill up the display with the video */
105 bool is_display_filled
;
108 * It will be applied to the whole display if b_display_filled is set, otherwise
109 * only on the video source */
115 vlc_viewpoint_t viewpoint
;
116 } vout_display_cfg_t
;
119 * Information from a vout_display_t to configure
120 * the core behaviour.
122 * By default they are all false or NULL.
126 bool is_slow
; /* The picture memory has slow read/write */
127 bool has_double_click
; /* Is double-click generated */
128 bool has_hide_mouse
; /* Is mouse automatically hidden */
129 bool has_pictures_invalid
; /* Will VOUT_DISPLAY_EVENT_PICTURES_INVALID be used */
130 bool needs_event_thread VLC_DEPRECATED
; /* Will events (key at least) be emitted using an independent thread */
131 const vlc_fourcc_t
*subpicture_chromas
; /* List of supported chromas for subpicture rendering. */
132 } vout_display_info_t
;
135 * Control query for vout_display_t
138 /* Hide the mouse. It will be sent when
139 * vout_display_t::info.b_hide_mouse is false */
140 VOUT_DISPLAY_HIDE_MOUSE
,
142 /* Ask to reset the internal buffers after a VOUT_DISPLAY_EVENT_PICTURES_INVALID
145 VOUT_DISPLAY_RESET_PICTURES
,
147 /* Ask the module to acknowledge/refuse the fullscreen state change after
148 * being requested (externally or by VOUT_DISPLAY_EVENT_FULLSCREEN */
149 VOUT_DISPLAY_CHANGE_FULLSCREEN
, /* bool fs */
150 #if defined(_WIN32) || defined(__OS2__)
151 /* Ask the module to acknowledge/refuse the window management state change
152 * after being requested externally or by VOUT_DISPLAY_WINDOW_STATE */
153 VOUT_DISPLAY_CHANGE_WINDOW_STATE
, /* unsigned state */
155 /* Ask the module to acknowledge/refuse the display size change requested
156 * (externally or by VOUT_DISPLAY_EVENT_DISPLAY_SIZE) */
157 VOUT_DISPLAY_CHANGE_DISPLAY_SIZE
, /* const vout_display_cfg_t *p_cfg */
159 /* Ask the module to acknowledge/refuse fill display state change after
160 * being requested externally */
161 VOUT_DISPLAY_CHANGE_DISPLAY_FILLED
, /* const vout_display_cfg_t *p_cfg */
163 /* Ask the module to acknowledge/refuse zoom change after being requested
165 VOUT_DISPLAY_CHANGE_ZOOM
, /* const vout_display_cfg_t *p_cfg */
167 /* Ask the module to acknowledge/refuse source aspect ratio after being
168 * requested externally */
169 VOUT_DISPLAY_CHANGE_SOURCE_ASPECT
, /* const video_format_t *p_source */
171 /* Ask the module to acknowledge/refuse source crop change after being
172 * requested externally.
173 * The cropping requested is stored by video_format_t::i_x/y_offset and
174 * video_format_t::i_visible_width/height */
175 VOUT_DISPLAY_CHANGE_SOURCE_CROP
, /* const video_format_t *p_source */
177 /* Ask the module to acknowledge/refuse VR/360° viewing direction after
178 * being requested externally */
179 VOUT_DISPLAY_CHANGE_VIEWPOINT
, /* const vout_display_cfg_t *p_cfg */
183 * Event from vout_display_t
185 * Events modifiying the state may be sent multiple times.
186 * Only the transition will be retained and acted upon.
190 * ZOOM ? DISPLAY_FILLED ? ON_TOP ?
193 VOUT_DISPLAY_EVENT_PICTURES_INVALID
, /* The buffer are now invalid and need to be changed */
195 VOUT_DISPLAY_EVENT_FULLSCREEN
,
196 #if defined(_WIN32) || defined(__OS2__)
197 VOUT_DISPLAY_EVENT_WINDOW_STATE
,
200 VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, /* The display size need to change : int i_width, int i_height */
203 VOUT_DISPLAY_EVENT_CLOSE
,
204 VOUT_DISPLAY_EVENT_KEY
,
207 * You can use it OR use the other mouse events. The core will do
210 VOUT_DISPLAY_EVENT_MOUSE_STATE
,
213 VOUT_DISPLAY_EVENT_MOUSE_MOVED
,
214 VOUT_DISPLAY_EVENT_MOUSE_PRESSED
,
215 VOUT_DISPLAY_EVENT_MOUSE_RELEASED
,
216 VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
,
220 * Vout owner structures
222 struct vout_display_owner_t
{
223 /* Private place holder for the vout_display_t creator
227 /* Event coming from the module
229 * This function is set prior to the module instantiation and must not
230 * be overwritten nor used directly (use the vout_display_SendEvent*
233 * You can send it at any time i.e. from any vout_display_t functions or
234 * from another thread.
235 * Be careful, it does not ensure correct serialization if it is used
236 * from multiple threads.
238 void (*event
)(vout_display_t
*, int, va_list);
242 * These functions are set prior to the module instantiation and must not
243 * be overwritten nor used directly (use the vout_display_*Window
245 vout_window_t
*(*window_new
)(vout_display_t
*, unsigned type
);
246 void (*window_del
)(vout_display_t
*, vout_window_t
*);
249 struct vout_display_t
{
255 /* Initial and current configuration.
256 * You cannot modify it directly, you must use the appropriate events.
258 * It reflects the current values, i.e. after the event has been accepted
259 * and applied/configured if needed.
261 const vout_display_cfg_t
*cfg
;
263 /* video source format.
265 * Cropping is not requested while in the open function.
266 * You cannot change it.
268 video_format_t source
;
272 * You can only change it inside the module open function to
273 * match what you want, and when a VOUT_DISPLAY_RESET_PICTURES control
274 * request is made and succeeds.
276 * By default, it is equal to ::source except for the aspect ratio
277 * which is undefined(0) and is ignored.
283 * You can only set them in the open function.
285 vout_display_info_t info
;
287 /* Return a pointer over the current picture_pool_t* (mandatory).
289 * For performance reasons, it is best to provide at least count
290 * pictures but it is not mandatory.
291 * You can return NULL when you cannot/do not want to allocate
293 * The vout display module keeps the ownership of the pool and can
294 * destroy it only when closing or on invalid pictures control.
296 picture_pool_t
*(*pool
)(vout_display_t
*, unsigned count
);
298 /* Prepare a picture and an optional subpicture for display (optional).
300 * It is called before the next pf_display call to provide as much
301 * time as possible to prepare the given picture and the subpicture
303 * You are guaranted that pf_display will always be called and using
304 * the exact same picture_t and subpicture_t.
305 * You cannot change the pixel content of the picture_t or of the
308 void (*prepare
)(vout_display_t
*, picture_t
*, subpicture_t
*);
310 /* Display a picture and an optional subpicture (mandatory).
312 * The picture and the optional subpicture must be displayed as soon as
314 * You cannot change the pixel content of the picture_t or of the
317 * This function gives away the ownership of the picture and of the
318 * subpicture, so you must release them as soon as possible.
320 void (*display
)(vout_display_t
*, picture_t
*, subpicture_t
*);
322 /* Control on the module (mandatory) */
323 int (*control
)(vout_display_t
*, int, va_list);
325 /* Manage pending event (optional) */
326 void (*manage
)(vout_display_t
*);
328 /* Private place holder for the vout_display_t module (optional)
330 * A module is free to use it as it wishes.
332 vout_display_sys_t
*sys
;
334 /* Reserved for the vout_display_t owner.
336 * It must not be overwritten nor used directly by a module.
338 vout_display_owner_t owner
;
341 static inline void vout_display_SendEvent(vout_display_t
*vd
, int query
, ...)
344 va_start(args
, query
);
345 vd
->owner
.event(vd
, query
, args
);
349 static inline void vout_display_SendEventDisplaySize(vout_display_t
*vd
, int width
, int height
)
351 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, width
, height
);
353 static inline void vout_display_SendEventPicturesInvalid(vout_display_t
*vd
)
355 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_PICTURES_INVALID
);
357 static inline void vout_display_SendEventClose(vout_display_t
*vd
)
359 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_CLOSE
);
361 static inline void vout_display_SendEventKey(vout_display_t
*vd
, int key
)
363 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_KEY
, key
);
365 static inline void vout_display_SendEventFullscreen(vout_display_t
*vd
, bool is_fullscreen
)
367 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_FULLSCREEN
, is_fullscreen
);
370 static inline void vout_display_SendWindowState(vout_display_t
*vd
, unsigned state
)
372 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_WINDOW_STATE
, state
);
375 /* The mouse position (State and Moved event) must be expressed against vout_display_t::source unit */
376 static inline void vout_display_SendEventMouseState(vout_display_t
*vd
, int x
, int y
, int button_mask
)
378 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_STATE
, x
, y
, button_mask
);
380 static inline void vout_display_SendEventMouseMoved(vout_display_t
*vd
, int x
, int y
)
382 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_MOVED
, x
, y
);
384 static inline void vout_display_SendEventMousePressed(vout_display_t
*vd
, int button
)
386 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_PRESSED
, button
);
388 static inline void vout_display_SendEventMouseReleased(vout_display_t
*vd
, int button
)
390 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_RELEASED
, button
);
392 static inline void vout_display_SendEventMouseDoubleClick(vout_display_t
*vd
)
394 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
);
398 * Asks for a new window of a given type.
400 static inline vout_window_t
*vout_display_NewWindow(vout_display_t
*vd
, unsigned type
)
402 return vd
->owner
.window_new(vd
, type
);
405 * Deletes a window created by vout_display_NewWindow if window is non NULL
406 * or any unused windows otherwise.
408 static inline void vout_display_DeleteWindow(vout_display_t
*vd
,
409 vout_window_t
*window
)
411 vd
->owner
.window_del(vd
, window
);
414 static inline bool vout_display_IsWindowed(vout_display_t
*vd
)
416 vout_window_t
*window
= vout_display_NewWindow(vd
, VOUT_WINDOW_TYPE_INVALID
);
418 vout_display_DeleteWindow(vd
, window
);
419 return window
!= NULL
;
423 * Computes the default display size given the source and
424 * the display configuration.
426 * This asssumes that the picture is already cropped.
428 VLC_API
void vout_display_GetDefaultDisplaySize(unsigned *width
, unsigned *height
, const video_format_t
*source
, const vout_display_cfg_t
*);
432 * Structure used to store the result of a vout_display_PlacePicture.
439 } vout_display_place_t
;
442 * Computes how to place a picture inside the display to respect
443 * the given parameters.
444 * This assumes that cropping is done by an external mean.
446 * \param p_place Place inside the window (window pixel unit)
447 * \param p_source Video source format
448 * \param p_cfg Display configuration
449 * \param b_clip If true, prevent the video to go outside the display (break zoom).
451 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
);
455 * Helper function that applies the necessary transforms to the mouse position
456 * and then calls vout_display_SendEventMouseMoved.
458 * \param vd vout_display_t.
459 * \param orient_display The orientation of the picture as seen on screen (probably ORIENT_NORMAL).
460 * \param m_x Mouse x position (relative to place, origin is top left).
461 * \param m_y Mouse y position (relative to place, origin is top left).
462 * \param place Place of the picture.
464 VLC_API
void vout_display_SendMouseMovedDisplayCoordinates(vout_display_t
*vd
, video_orientation_t orient_display
, int m_x
, int m_y
,
465 vout_display_place_t
*place
);
468 #endif /* VLC_VOUT_DISPLAY_H */