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
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 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 General Public License for more details.
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, 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
29 * This file defines vout display structures and functions in vlc
33 #include <vlc_picture.h>
34 #include <vlc_subpicture.h>
36 #include <vlc_mouse.h>
37 #include <vlc_vout_window.h>
40 * Do NOT use video_format_t::i_aspect but i_sar_num/den everywhere. i_aspect
41 * will be removed as soon as possible.
44 typedef struct vout_display_t vout_display_t
;
45 typedef struct vout_display_sys_t vout_display_sys_t
;
46 typedef struct vout_display_owner_t vout_display_owner_t
;
47 typedef struct vout_display_owner_sys_t vout_display_owner_sys_t
;
50 * Possible alignments for vout_display.
54 VOUT_DISPLAY_ALIGN_CENTER
,
56 VOUT_DISPLAY_ALIGN_LEFT
,
57 VOUT_DISPLAY_ALIGN_RIGHT
,
59 VOUT_DISPLAY_ALIGN_TOP
,
60 VOUT_DISPLAY_ALIGN_BOTTOM
,
61 } vout_display_align_t
;
64 * Initial/Current configuration for a vout_display_t
67 bool is_fullscreen
; /* Is the display fullscreen */
69 /* Display properties */
71 /* Window title (may be NULL) */
85 /* Alignment of the picture inside the display */
91 /* Do we fill up the display with the video */
92 bool is_display_filled
;
95 * It will be applied to the whole display if b_display_filled is set, otherwise
96 * only on the video source */
102 } vout_display_cfg_t
;
105 * Informations from a vout_display_t to configure
106 * the core behaviour.
108 * By default they are all false.
112 bool is_slow
; /* The picture memory has slow read/write */
113 bool has_double_click
; /* Is double-click generated */
114 bool has_hide_mouse
; /* Is mouse automatically hidden */
115 bool has_pictures_invalid
;/* Will VOUT_DISPLAY_EVENT_PICTURES_INVALID be used */
116 } vout_display_info_t
;
119 * Control query for vout_display_t
122 /* Hide the mouse. It will be sent when
123 * vout_display_t::info.b_hide_mouse is false */
124 VOUT_DISPLAY_HIDE_MOUSE
,
126 /* Ask to reset the internal buffers after a VOUT_DISPLAY_EVENT_PICTURES_INVALID
129 VOUT_DISPLAY_RESET_PICTURES
,
131 /* Ask the module to acknowledge/refuse the fullscreen state change after
132 * being requested (externally or by VOUT_DISPLAY_EVENT_FULLSCREEN */
133 VOUT_DISPLAY_CHANGE_FULLSCREEN
, /* const vout_display_cfg_t *p_cfg */
135 /* Ask the module to acknowledge/refuse the "always on top" state change
136 * after being requested externally or by VOUT_DISPLAY_EVENT_ON_TOP */
137 VOUT_DISPLAY_CHANGE_ON_TOP
, /* int b_on_top */
139 /* Ask the module to acknowledge/refuse the display size change requested
140 * (externally or by VOUT_DISPLAY_EVENT_DISPLAY_SIZE) */
141 VOUT_DISPLAY_CHANGE_DISPLAY_SIZE
, /* const vout_display_cfg_t *p_cfg, int is_forced */
143 /* Ask the module to acknowledge/refuse fill display state change after
144 * being requested externally */
145 VOUT_DISPLAY_CHANGE_DISPLAY_FILLED
, /* const vout_display_cfg_t *p_cfg */
147 /* Ask the module to acknowledge/refuse zoom change after being requested
149 VOUT_DISPLAY_CHANGE_ZOOM
, /* const vout_display_cfg_t *p_cfg */
151 /* Ask the module to acknowledge/refuse source aspect ratio after being
152 * requested externally */
153 VOUT_DISPLAY_CHANGE_SOURCE_ASPECT
, /* const video_format_t *p_source */
155 /* Ask the module to acknowledge/refuse source crop change after being
156 * requested externally.
157 * The cropping requested is stored by video_format_t::i_x/y_offset and
158 * video_format_t::i_visible_width/height */
159 VOUT_DISPLAY_CHANGE_SOURCE_CROP
, /* const video_format_t *p_source */
163 * Event from vout_display_t
165 * Events modifiying the state may be sent multiple times.
166 * Only the transition will be retained and acted upon.
170 * ZOOM ? DISPLAY_FILLED ? ON_TOP ?
173 VOUT_DISPLAY_EVENT_PICTURES_INVALID
, /* The buffer are now invalid and need to be changed */
175 VOUT_DISPLAY_EVENT_FULLSCREEN
,
176 VOUT_DISPLAY_EVENT_ON_TOP
,
178 VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, /* The display size need to change : int i_width, int i_height, bool is_fullscreen */
181 VOUT_DISPLAY_EVENT_CLOSE
,
182 VOUT_DISPLAY_EVENT_KEY
,
185 * You can use it OR use the other mouse events. The core will do
188 VOUT_DISPLAY_EVENT_MOUSE_STATE
,
191 VOUT_DISPLAY_EVENT_MOUSE_MOVED
,
192 VOUT_DISPLAY_EVENT_MOUSE_PRESSED
,
193 VOUT_DISPLAY_EVENT_MOUSE_RELEASED
,
194 VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
,
198 * Vout owner structures
200 struct vout_display_owner_t
{
201 /* Private place holder for the vout_display_t creator
203 vout_display_owner_sys_t
*sys
;
205 /* Event coming from the module
207 * This function is set prior to the module instantiation and must not
208 * be overwritten nor used directly (use the vout_display_SendEvent*
211 * You can send it at any time i.e. from any vout_display_t functions or
212 * from another thread.
213 * Becarefull, it does not ensure correct serialization if it is used
214 * from multiple threads.
216 void (*event
)(vout_display_t
*, int, va_list);
220 * These functions are set prior to the module instantiation and must not
221 * be overwritten nor used directly (use the vout_display_*Window
223 vout_window_t
*(*window_new
)(vout_display_t
*, const vout_window_cfg_t
*);
224 void (*window_del
)(vout_display_t
*, vout_window_t
*);
227 struct vout_display_t
{
233 /* Initial and current configuration.
234 * You cannot modify it directly, you must use the appropriate events.
236 * It reflects the current values, i.e. after the event has been accepted
237 * and applied/configured if needed.
239 const vout_display_cfg_t
*cfg
;
241 /* video source format.
243 * Cropping is not requested while in the open function.
244 * You cannot change it.
246 video_format_t source
;
250 * You can only change it inside the module open function to
251 * match what you want, and when a VOUT_DISPLAY_RESET_PICTURES control
252 * request is made and succeeds.
254 * By default, it is equal to ::source except for the aspect ratio
255 * which is undefined(0) and is ignored.
261 * You can only set them in the open function.
263 vout_display_info_t info
;
265 /* Return a new picture_t (mandatory).
267 * You can return NULL when you cannot/do not want to allocate
269 * If you want to create a pool of reusable pictures, you can
270 * use a picture_pool_t.
272 picture_t
*(*get
)(vout_display_t
*);
274 /* Prepare a picture for display (optional).
276 * It is called before the next pf_display call to provide as much
277 * time as possible to prepare the given picture for display.
278 * You are guaranted that pf_display will always be called and using
279 * the exact same picture_t.
280 * You cannot change the pixel content of the picture_t.
282 void (*prepare
)(vout_display_t
*, picture_t
*);
284 /* Display a picture (mandatory).
286 * The picture must be displayed as soon as possible.
287 * You cannot change the pixel content of the picture_t.
289 * This function gives away the ownership of the picture, so you must
290 * release it as soon as possible.
292 void (*display
)(vout_display_t
*, picture_t
*);
294 /* Control on the module (mandatory) */
295 int (*control
)(vout_display_t
*, int, va_list);
297 /* Manage pending event (optional) */
298 void (*manage
)(vout_display_t
*);
300 /* Private place holder for the vout_display_t module (optional)
302 * A module is free to use it as it wishes.
304 vout_display_sys_t
*sys
;
306 /* Reserved for the vout_display_t owner.
308 * It must not be overwritten nor used directly by a module.
310 vout_display_owner_t owner
;
313 static inline void vout_display_SendEvent(vout_display_t
*vd
, int query
, ...)
316 va_start(args
, query
);
317 vd
->owner
.event(vd
, query
, args
);
321 static inline void vout_display_SendEventDisplaySize(vout_display_t
*vd
, int width
, int height
, bool is_fullscreen
)
323 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, width
, height
, is_fullscreen
);
325 static inline void vout_display_SendEventPicturesInvalid(vout_display_t
*vd
)
327 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_PICTURES_INVALID
);
329 static inline void vout_display_SendEventClose(vout_display_t
*vd
)
331 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_CLOSE
);
333 static inline void vout_display_SendEventKey(vout_display_t
*vd
, int key
)
335 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_KEY
, key
);
337 static inline void vout_display_SendEventFullscreen(vout_display_t
*vd
, bool is_fullscreen
)
339 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_FULLSCREEN
, is_fullscreen
);
341 static inline void vout_display_SendEventOnTop(vout_display_t
*vd
, bool is_on_top
)
343 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_ON_TOP
, is_on_top
);
345 /* The mouse position (State and Moved event) must be expressed against vout_display_t::source unit */
346 static inline void vout_display_SendEventMouseState(vout_display_t
*vd
, int x
, int y
, int button_mask
)
348 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_STATE
, x
, y
, button_mask
);
350 static inline void vout_display_SendEventMouseMoved(vout_display_t
*vd
, int x
, int y
)
352 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_MOVED
, x
, y
);
354 static inline void vout_display_SendEventMousePressed(vout_display_t
*vd
, int button
)
356 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_PRESSED
, button
);
358 static inline void vout_display_SendEventMouseReleased(vout_display_t
*vd
, int button
)
360 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_RELEASED
, button
);
362 static inline void vout_display_SendEventMouseDoubleClick(vout_display_t
*vd
)
364 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
);
368 * Asks for a new window with the given configuration as hint.
370 * b_standalone/i_x/i_y may be overwritten by the core
372 static inline vout_window_t
*vout_display_NewWindow(vout_display_t
*vd
, const vout_window_cfg_t
*cfg
)
374 return vd
->owner
.window_new(vd
, cfg
);
376 static inline void vout_display_DeleteWindow(vout_display_t
*vd
,
377 vout_window_t
*window
)
379 vd
->owner
.window_del(vd
, window
);
383 * Computes the default display size given the source and
384 * the display configuration.
386 * This asssumes that the picture is already cropped.
388 VLC_EXPORT( void, vout_display_GetDefaultDisplaySize
, (unsigned *width
, unsigned *height
, const video_format_t
*source
, const vout_display_cfg_t
*) );
392 * Structure used to store the result of a vout_display_PlacePicture.
399 } vout_display_place_t
;
402 * Computes how to place a picture inside the display to respect
403 * the given parameters.
404 * This assumes that cropping is done by an external mean.
406 * \param p_place Place inside the window (window pixel unit)
407 * \param p_source Video source format
408 * \param p_cfg Display configuration
409 * \param b_clip If true, prevent the video to go outside the display (break zoom).
411 VLC_EXPORT( void, vout_display_PlacePicture
, (vout_display_place_t
*place
, const video_format_t
*source
, const vout_display_cfg_t
*cfg
, bool do_clipping
) );
413 #endif /* VLC_VOUT_DISPLAY_H */