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>
33 #include <vlc_vout_window.h>
36 * \defgroup video_display Video output display
37 * Video output display: output buffers and rendering
39 * \ingroup video_output
42 * Video output display modules interface
46 * Do NOT use video_format_t::i_aspect but i_sar_num/den everywhere. i_aspect
47 * will be removed as soon as possible.
50 typedef struct vout_display_t vout_display_t
;
51 typedef struct vout_display_sys_t vout_display_sys_t
;
52 typedef struct vout_display_owner_t vout_display_owner_t
;
53 typedef struct vout_display_owner_sys_t vout_display_owner_sys_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) */
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 } vout_display_cfg_t
;
121 * Information from a vout_display_t to configure
122 * the core behaviour.
124 * By default they are all false or NULL.
128 bool is_slow
; /* The picture memory has slow read/write */
129 bool has_double_click
; /* Is double-click generated */
130 bool has_hide_mouse
; /* Is mouse automatically hidden */
131 bool has_pictures_invalid
; /* Will VOUT_DISPLAY_EVENT_PICTURES_INVALID be used */
132 bool has_event_thread
; /* Will events (key at least) be emitted using an independent thread */
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.b_hide_mouse is false */
142 VOUT_DISPLAY_HIDE_MOUSE
,
144 /* Ask to reset the internal buffers after a VOUT_DISPLAY_EVENT_PICTURES_INVALID
147 VOUT_DISPLAY_RESET_PICTURES
,
149 /* Ask the module to acknowledge/refuse the fullscreen state change after
150 * being requested (externally or by VOUT_DISPLAY_EVENT_FULLSCREEN */
151 VOUT_DISPLAY_CHANGE_FULLSCREEN
, /* 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
, /* 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
, /* const video_format_t *p_source */
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
, /* const video_format_t *p_source */
181 * Event from vout_display_t
183 * Events modifiying the state may be sent multiple times.
184 * Only the transition will be retained and acted upon.
188 * ZOOM ? DISPLAY_FILLED ? ON_TOP ?
191 VOUT_DISPLAY_EVENT_PICTURES_INVALID
, /* The buffer are now invalid and need to be changed */
193 VOUT_DISPLAY_EVENT_FULLSCREEN
,
194 #if defined(_WIN32) || defined(__OS2__)
195 VOUT_DISPLAY_EVENT_WINDOW_STATE
,
198 VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, /* The display size need to change : int i_width, int i_height */
201 VOUT_DISPLAY_EVENT_CLOSE
,
202 VOUT_DISPLAY_EVENT_KEY
,
205 * You can use it OR use the other mouse events. The core will do
208 VOUT_DISPLAY_EVENT_MOUSE_STATE
,
211 VOUT_DISPLAY_EVENT_MOUSE_MOVED
,
212 VOUT_DISPLAY_EVENT_MOUSE_PRESSED
,
213 VOUT_DISPLAY_EVENT_MOUSE_RELEASED
,
214 VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
,
218 * Vout owner structures
220 struct vout_display_owner_t
{
221 /* Private place holder for the vout_display_t creator
223 vout_display_owner_sys_t
*sys
;
225 /* Event coming from the module
227 * This function is set prior to the module instantiation and must not
228 * be overwritten nor used directly (use the vout_display_SendEvent*
231 * You can send it at any time i.e. from any vout_display_t functions or
232 * from another thread.
233 * Be careful, it does not ensure correct serialization if it is used
234 * from multiple threads.
236 void (*event
)(vout_display_t
*, int, va_list);
240 * These functions are set prior to the module instantiation and must not
241 * be overwritten nor used directly (use the vout_display_*Window
243 vout_window_t
*(*window_new
)(vout_display_t
*, unsigned type
);
244 void (*window_del
)(vout_display_t
*, vout_window_t
*);
247 struct vout_display_t
{
253 /* Initial and current configuration.
254 * You cannot modify it directly, you must use the appropriate events.
256 * It reflects the current values, i.e. after the event has been accepted
257 * and applied/configured if needed.
259 const vout_display_cfg_t
*cfg
;
261 /* video source format.
263 * Cropping is not requested while in the open function.
264 * You cannot change it.
266 video_format_t source
;
270 * You can only change it inside the module open function to
271 * match what you want, and when a VOUT_DISPLAY_RESET_PICTURES control
272 * request is made and succeeds.
274 * By default, it is equal to ::source except for the aspect ratio
275 * which is undefined(0) and is ignored.
281 * You can only set them in the open function.
283 vout_display_info_t info
;
285 /* Return a pointer over the current picture_pool_t* (mandatory).
287 * For performance reasons, it is best to provide at least count
288 * pictures but it is not mandatory.
289 * You can return NULL when you cannot/do not want to allocate
291 * The vout display module keeps the ownership of the pool and can
292 * destroy it only when closing or on invalid pictures control.
294 picture_pool_t
*(*pool
)(vout_display_t
*, unsigned count
);
296 /* Prepare a picture and an optional subpicture for display (optional).
298 * It is called before the next pf_display call to provide as much
299 * time as possible to prepare the given picture and the subpicture
301 * You are guaranted that pf_display will always be called and using
302 * the exact same picture_t and subpicture_t.
303 * You cannot change the pixel content of the picture_t or of the
306 void (*prepare
)(vout_display_t
*, picture_t
*, subpicture_t
*);
308 /* Display a picture and an optional subpicture (mandatory).
310 * The picture and the optional subpicture must be displayed as soon as
312 * You cannot change the pixel content of the picture_t or of the
315 * This function gives away the ownership of the picture and of the
316 * subpicture, so you must release them as soon as possible.
318 void (*display
)(vout_display_t
*, picture_t
*, subpicture_t
*);
320 /* Control on the module (mandatory) */
321 int (*control
)(vout_display_t
*, int, va_list);
323 /* Manage pending event (optional) */
324 void (*manage
)(vout_display_t
*);
326 /* Private place holder for the vout_display_t module (optional)
328 * A module is free to use it as it wishes.
330 vout_display_sys_t
*sys
;
332 /* Reserved for the vout_display_t owner.
334 * It must not be overwritten nor used directly by a module.
336 vout_display_owner_t owner
;
339 static inline void vout_display_SendEvent(vout_display_t
*vd
, int query
, ...)
342 va_start(args
, query
);
343 vd
->owner
.event(vd
, query
, args
);
347 static inline void vout_display_SendEventDisplaySize(vout_display_t
*vd
, int width
, int height
)
349 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_DISPLAY_SIZE
, width
, height
);
351 static inline void vout_display_SendEventPicturesInvalid(vout_display_t
*vd
)
353 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_PICTURES_INVALID
);
355 static inline void vout_display_SendEventClose(vout_display_t
*vd
)
357 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_CLOSE
);
359 static inline void vout_display_SendEventKey(vout_display_t
*vd
, int key
)
361 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_KEY
, key
);
363 static inline void vout_display_SendEventFullscreen(vout_display_t
*vd
, bool is_fullscreen
)
365 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_FULLSCREEN
, is_fullscreen
);
368 static inline void vout_display_SendWindowState(vout_display_t
*vd
, unsigned state
)
370 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_WINDOW_STATE
, state
);
373 /* The mouse position (State and Moved event) must be expressed against vout_display_t::source unit */
374 static inline void vout_display_SendEventMouseState(vout_display_t
*vd
, int x
, int y
, int button_mask
)
376 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_STATE
, x
, y
, button_mask
);
378 static inline void vout_display_SendEventMouseMoved(vout_display_t
*vd
, int x
, int y
)
380 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_MOVED
, x
, y
);
382 static inline void vout_display_SendEventMousePressed(vout_display_t
*vd
, int button
)
384 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_PRESSED
, button
);
386 static inline void vout_display_SendEventMouseReleased(vout_display_t
*vd
, int button
)
388 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_RELEASED
, button
);
390 static inline void vout_display_SendEventMouseDoubleClick(vout_display_t
*vd
)
392 vout_display_SendEvent(vd
, VOUT_DISPLAY_EVENT_MOUSE_DOUBLE_CLICK
);
396 * Asks for a new window of a given type.
398 static inline vout_window_t
*vout_display_NewWindow(vout_display_t
*vd
, unsigned type
)
400 return vd
->owner
.window_new(vd
, type
);
403 * Deletes a window created by vout_display_NewWindow if window is non NULL
404 * or any unused windows otherwise.
406 static inline void vout_display_DeleteWindow(vout_display_t
*vd
,
407 vout_window_t
*window
)
409 vd
->owner
.window_del(vd
, window
);
412 static inline bool vout_display_IsWindowed(vout_display_t
*vd
)
414 vout_window_t
*window
= vout_display_NewWindow(vd
, VOUT_WINDOW_TYPE_INVALID
);
416 vout_display_DeleteWindow(vd
, window
);
417 return window
!= NULL
;
421 * Computes the default display size given the source and
422 * the display configuration.
424 * This asssumes that the picture is already cropped.
426 VLC_API
void vout_display_GetDefaultDisplaySize(unsigned *width
, unsigned *height
, const video_format_t
*source
, const vout_display_cfg_t
*);
430 * Structure used to store the result of a vout_display_PlacePicture.
437 } vout_display_place_t
;
440 * Computes how to place a picture inside the display to respect
441 * the given parameters.
442 * This assumes that cropping is done by an external mean.
444 * \param p_place Place inside the window (window pixel unit)
445 * \param p_source Video source format
446 * \param p_cfg Display configuration
447 * \param b_clip If true, prevent the video to go outside the display (break zoom).
449 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
);
453 * Helper function that applies the necessary transforms to the mouse position
454 * and then calls vout_display_SendEventMouseMoved.
456 * \param vd vout_display_t.
457 * \param orient_display The orientation of the picture as seen on screen (probably ORIENT_NORMAL).
458 * \param m_x Mouse x position (relative to place, origin is top left).
459 * \param m_y Mouse y position (relative to place, origin is top left).
460 * \param place Place of the picture.
462 VLC_API
void vout_display_SendMouseMovedDisplayCoordinates(vout_display_t
*vd
, video_orientation_t orient_display
, int m_x
, int m_y
,
463 vout_display_place_t
*place
);
466 #endif /* VLC_VOUT_DISPLAY_H */