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_picture_pool.h>
35 #include <vlc_subpicture.h>
37 #include <vlc_mouse.h>
38 #include <vlc_vout_window.h>
41 * Do NOT use video_format_t::i_aspect but i_sar_num/den everywhere. i_aspect
42 * will be removed as soon as possible.
45 typedef struct vout_display_t vout_display_t
;
46 typedef struct vout_display_sys_t vout_display_sys_t
;
47 typedef struct vout_display_owner_t vout_display_owner_t
;
48 typedef struct vout_display_owner_sys_t vout_display_owner_sys_t
;
51 * Possible alignments for vout_display.
55 VOUT_DISPLAY_ALIGN_CENTER
,
57 VOUT_DISPLAY_ALIGN_LEFT
,
58 VOUT_DISPLAY_ALIGN_RIGHT
,
60 VOUT_DISPLAY_ALIGN_TOP
,
61 VOUT_DISPLAY_ALIGN_BOTTOM
,
62 } vout_display_align_t
;
65 * Window management state.
68 VOUT_WINDOW_STATE_NORMAL
=0,
69 VOUT_WINDOW_STATE_ABOVE
=1,
70 VOUT_WINDOW_STATE_BELOW
=2,
71 VOUT_WINDOW_STACK_MASK
=3,
75 * Initial/Current configuration for a vout_display_t
78 bool is_fullscreen
; /* Is the display fullscreen */
80 /* Display properties */
82 /* Window title (may be NULL) */
96 /* Alignment of the picture inside the display */
102 /* Do we fill up the display with the video */
103 bool is_display_filled
;
106 * It will be applied to the whole display if b_display_filled is set, otherwise
107 * only on the video source */
113 } vout_display_cfg_t
;
116 * Information from a vout_display_t to configure
117 * the core behaviour.
119 * By default they are all false.
123 bool is_slow
; /* The picture memory has slow read/write */
124 bool has_double_click
; /* Is double-click generated */
125 bool has_hide_mouse
; /* Is mouse automatically hidden */
126 bool has_pictures_invalid
;/* Will VOUT_DISPLAY_EVENT_PICTURES_INVALID be used */
127 bool has_event_thread
; /* Will events (key at least) be emitted using an independent thread */
128 } vout_display_info_t
;
131 * Control query for vout_display_t
134 /* Hide the mouse. It will be sent when
135 * vout_display_t::info.b_hide_mouse is false */
136 VOUT_DISPLAY_HIDE_MOUSE
,
138 /* Ask to reset the internal buffers after a VOUT_DISPLAY_EVENT_PICTURES_INVALID
141 VOUT_DISPLAY_RESET_PICTURES
,
143 /* Ask the module to acknowledge/refuse the fullscreen state change after
144 * being requested (externally or by VOUT_DISPLAY_EVENT_FULLSCREEN */
145 VOUT_DISPLAY_CHANGE_FULLSCREEN
, /* const vout_display_cfg_t *p_cfg */
147 /* Ask the module to acknowledge/refuse the window management state change
148 * after being requested externally or by VOUT_DISPLAY_WINDOW_STATE */
149 VOUT_DISPLAY_CHANGE_WINDOW_STATE
, /* unsigned state */
151 /* Ask the module to acknowledge/refuse the display size change requested
152 * (externally or by VOUT_DISPLAY_EVENT_DISPLAY_SIZE) */
153 VOUT_DISPLAY_CHANGE_DISPLAY_SIZE
, /* const vout_display_cfg_t *p_cfg, int is_forced */
155 /* Ask the module to acknowledge/refuse fill display state change after
156 * being requested externally */
157 VOUT_DISPLAY_CHANGE_DISPLAY_FILLED
, /* const vout_display_cfg_t *p_cfg */
159 /* Ask the module to acknowledge/refuse zoom change after being requested
161 VOUT_DISPLAY_CHANGE_ZOOM
, /* const vout_display_cfg_t *p_cfg */
163 /* Ask the module to acknowledge/refuse source aspect ratio after being
164 * requested externally */
165 VOUT_DISPLAY_CHANGE_SOURCE_ASPECT
, /* const video_format_t *p_source */
167 /* Ask the module to acknowledge/refuse source crop change after being
168 * requested externally.
169 * The cropping requested is stored by video_format_t::i_x/y_offset and
170 * video_format_t::i_visible_width/height */
171 VOUT_DISPLAY_CHANGE_SOURCE_CROP
, /* const video_format_t *p_source */
173 /* Ask an opengl interface if available. */
174 VOUT_DISPLAY_GET_OPENGL
, /* vout_opengl_t ** */
178 * Event from vout_display_t
180 * Events modifiying the state may be sent multiple times.
181 * Only the transition will be retained and acted upon.
185 * ZOOM ? DISPLAY_FILLED ? ON_TOP ?
188 VOUT_DISPLAY_EVENT_PICTURES_INVALID
, /* The buffer are now invalid and need to be changed */
190 VOUT_DISPLAY_EVENT_FULLSCREEN
,
191 VOUT_DISPLAY_EVENT_WINDOW_STATE
,
193 VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, /* The display size need to change : int i_width, int i_height, bool is_fullscreen */
196 VOUT_DISPLAY_EVENT_CLOSE
,
197 VOUT_DISPLAY_EVENT_KEY
,
200 * You can use it OR use the other mouse events. The core will do
203 VOUT_DISPLAY_EVENT_MOUSE_STATE
,
206 VOUT_DISPLAY_EVENT_MOUSE_MOVED
,
207 VOUT_DISPLAY_EVENT_MOUSE_PRESSED
,
208 VOUT_DISPLAY_EVENT_MOUSE_RELEASED
,
209 VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
,
213 * Vout owner structures
215 struct vout_display_owner_t
{
216 /* Private place holder for the vout_display_t creator
218 vout_display_owner_sys_t
*sys
;
220 /* Event coming from the module
222 * This function is set prior to the module instantiation and must not
223 * be overwritten nor used directly (use the vout_display_SendEvent*
226 * You can send it at any time i.e. from any vout_display_t functions or
227 * from another thread.
228 * Be careful, it does not ensure correct serialization if it is used
229 * from multiple threads.
231 void (*event
)(vout_display_t
*, int, va_list);
235 * These functions are set prior to the module instantiation and must not
236 * be overwritten nor used directly (use the vout_display_*Window
238 vout_window_t
*(*window_new
)(vout_display_t
*, const vout_window_cfg_t
*);
239 void (*window_del
)(vout_display_t
*, vout_window_t
*);
242 struct vout_display_t
{
248 /* Initial and current configuration.
249 * You cannot modify it directly, you must use the appropriate events.
251 * It reflects the current values, i.e. after the event has been accepted
252 * and applied/configured if needed.
254 const vout_display_cfg_t
*cfg
;
256 /* video source format.
258 * Cropping is not requested while in the open function.
259 * You cannot change it.
261 video_format_t source
;
265 * You can only change it inside the module open function to
266 * match what you want, and when a VOUT_DISPLAY_RESET_PICTURES control
267 * request is made and succeeds.
269 * By default, it is equal to ::source except for the aspect ratio
270 * which is undefined(0) and is ignored.
276 * You can only set them in the open function.
278 vout_display_info_t info
;
280 /* Return a pointer over the current picture_pool_t* (mandatory).
282 * For performance reasons, it is best to provide at least count
283 * pictures but it is not mandatory.
284 * You can return NULL when you cannot/do not want to allocate
286 * The vout display module keeps the ownership of the pool and can
287 * destroy it only when closing or on invalid pictures control.
289 picture_pool_t
*(*pool
)(vout_display_t
*, unsigned count
);
291 /* Prepare a picture for display (optional).
293 * It is called before the next pf_display call to provide as much
294 * time as possible to prepare the given picture for display.
295 * You are guaranted that pf_display will always be called and using
296 * the exact same picture_t.
297 * You cannot change the pixel content of the picture_t.
299 void (*prepare
)(vout_display_t
*, picture_t
*);
301 /* Display a picture (mandatory).
303 * The picture must be displayed as soon as possible.
304 * You cannot change the pixel content of the picture_t.
306 * This function gives away the ownership of the picture, so you must
307 * release it as soon as possible.
309 void (*display
)(vout_display_t
*, picture_t
*);
311 /* Control on the module (mandatory) */
312 int (*control
)(vout_display_t
*, int, va_list);
314 /* Manage pending event (optional) */
315 void (*manage
)(vout_display_t
*);
317 /* Private place holder for the vout_display_t module (optional)
319 * A module is free to use it as it wishes.
321 vout_display_sys_t
*sys
;
323 /* Reserved for the vout_display_t owner.
325 * It must not be overwritten nor used directly by a module.
327 vout_display_owner_t owner
;
330 static inline void vout_display_SendEvent(vout_display_t
*vd
, int query
, ...)
333 va_start(args
, query
);
334 vd
->owner
.event(vd
, query
, args
);
338 static inline void vout_display_SendEventDisplaySize(vout_display_t
*vd
, int width
, int height
, bool is_fullscreen
)
340 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, width
, height
, is_fullscreen
);
342 static inline void vout_display_SendEventPicturesInvalid(vout_display_t
*vd
)
344 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_PICTURES_INVALID
);
346 static inline void vout_display_SendEventClose(vout_display_t
*vd
)
348 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_CLOSE
);
350 static inline void vout_display_SendEventKey(vout_display_t
*vd
, int key
)
352 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_KEY
, key
);
354 static inline void vout_display_SendEventFullscreen(vout_display_t
*vd
, bool is_fullscreen
)
356 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_FULLSCREEN
, is_fullscreen
);
358 static inline void vout_display_SendWindowState(vout_display_t
*vd
, unsigned state
)
360 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_WINDOW_STATE
, state
);
362 /* The mouse position (State and Moved event) must be expressed against vout_display_t::source unit */
363 static inline void vout_display_SendEventMouseState(vout_display_t
*vd
, int x
, int y
, int button_mask
)
365 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_STATE
, x
, y
, button_mask
);
367 static inline void vout_display_SendEventMouseMoved(vout_display_t
*vd
, int x
, int y
)
369 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_MOVED
, x
, y
);
371 static inline void vout_display_SendEventMousePressed(vout_display_t
*vd
, int button
)
373 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_PRESSED
, button
);
375 static inline void vout_display_SendEventMouseReleased(vout_display_t
*vd
, int button
)
377 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_RELEASED
, button
);
379 static inline void vout_display_SendEventMouseDoubleClick(vout_display_t
*vd
)
381 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
);
385 * Asks for a new window with the given configuration as hint.
387 * b_standalone/i_x/i_y may be overwritten by the core
389 static inline vout_window_t
*vout_display_NewWindow(vout_display_t
*vd
, const vout_window_cfg_t
*cfg
)
391 return vd
->owner
.window_new(vd
, cfg
);
394 * Deletes a window created by vout_display_NewWindow if window is non NULL
395 * or any unused windows otherwise.
397 static inline void vout_display_DeleteWindow(vout_display_t
*vd
,
398 vout_window_t
*window
)
400 vd
->owner
.window_del(vd
, window
);
404 * Computes the default display size given the source and
405 * the display configuration.
407 * This asssumes that the picture is already cropped.
409 VLC_EXPORT( void, vout_display_GetDefaultDisplaySize
, (unsigned *width
, unsigned *height
, const video_format_t
*source
, const vout_display_cfg_t
*) );
413 * Structure used to store the result of a vout_display_PlacePicture.
420 } vout_display_place_t
;
423 * Computes how to place a picture inside the display to respect
424 * the given parameters.
425 * This assumes that cropping is done by an external mean.
427 * \param p_place Place inside the window (window pixel unit)
428 * \param p_source Video source format
429 * \param p_cfg Display configuration
430 * \param b_clip If true, prevent the video to go outside the display (break zoom).
432 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
) );
434 #endif /* VLC_VOUT_DISPLAY_H */