1 /*****************************************************************************
2 * vlc_vout_display.h: vout_display_t definitions
3 *****************************************************************************
4 * Copyright (C) 2009 Laurent Aimar
6 * Authors: Laurent Aimar <fenrir _AT_ videolan _DOT_ org>
8 * This program is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU Lesser General Public License as published by
10 * the Free Software Foundation; either version 2.1 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with this program; if not, write to the Free Software Foundation,
20 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21 *****************************************************************************/
23 #ifndef VLC_VOUT_DISPLAY_H
24 #define VLC_VOUT_DISPLAY_H 1
27 #include <vlc_picture.h>
28 #include <vlc_picture_pool.h>
29 #include <vlc_subpicture.h>
30 #include <vlc_actions.h>
31 #include <vlc_mouse.h>
33 #include <vlc_vout_window.h>
34 #include <vlc_viewpoint.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
46 typedef struct vout_display_t vout_display_t
;
47 typedef struct vout_display_sys_t vout_display_sys_t
;
48 typedef struct vout_display_owner_t vout_display_owner_t
;
51 * \defgroup video_align Video alignment
54 #define VLC_VIDEO_ALIGN_CENTER 0
55 #define VLC_VIDEO_ALIGN_LEFT 1
56 #define VLC_VIDEO_ALIGN_RIGHT 2
57 #define VLC_VIDEO_ALIGN_TOP 1
58 #define VLC_VIDEO_ALIGN_BOTTOM 2
61 * Video alignment within the display.
63 typedef struct vlc_video_align
{
65 * Horizontal alignment.
67 * This must be one of \ref VLC_VIDEO_ALIGN_CENTER,
68 * \ref VLC_VIDEO_ALIGN_LEFT or \ref VLC_VIDEO_ALIGN_RIGHT.
75 * This must be one of \ref VLC_VIDEO_ALIGN_CENTER,
76 * \ref VLC_VIDEO_ALIGN_TOP or \ref VLC_VIDEO_ALIGN_BOTTOM.
83 * User configuration for a video output display (\ref vout_display_t)
85 * This primarily controls the size of the display area within the video
87 * - If \ref is_display_filled is set,
88 * the video size is fitted to the display size.
89 * - If \ref window size is valid, the video size is set to the window size,
90 * - Otherwise, the video size is determined from the original video format,
91 * multiplied by the zoom factor.
93 typedef struct vout_display_cfg
{
94 struct vout_window_t
*window
; /**< Window */
96 bool is_fullscreen VLC_DEPRECATED
; /* Is the display fullscreen */
99 /** Display properties */
101 unsigned width
; /**< Requested display pixel width (0 by default). */
102 unsigned height
; /**< Requested display pixel height (0 by default). */
103 vlc_rational_t sar
; /**< Requested sample aspect ratio */
109 * Should be ignored from display modules.
112 /** Current window width */
114 /** Current window height */
118 /** Alignment of the video within the window */
119 vlc_video_align_t align
;
121 /** Automatic scaling/fitting flag */
122 bool is_display_filled
;
130 vlc_viewpoint_t viewpoint
;
131 } vout_display_cfg_t
;
134 * Information from a vout_display_t to configure
135 * the core behaviour.
137 * By default they are all false or NULL.
141 bool can_scale_spu
; /* Handles subpictures with a non default zoom factor */
142 const vlc_fourcc_t
*subpicture_chromas
; /* List of supported chromas for subpicture rendering. */
143 } vout_display_info_t
;
146 * Control query for vout_display_t
148 enum vout_display_query
{
150 /* Ask the module to acknowledge/refuse the fullscreen state change after
151 * being requested (externally or by VOUT_DISPLAY_EVENT_FULLSCREEN */
152 VOUT_DISPLAY_CHANGE_FULLSCREEN VLC_DEPRECATED_ENUM
,
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 VLC_DEPRECATED_ENUM
,
158 * Notifies a change in display size.
160 * \retval VLC_SUCCESS if the display handled the change
161 * \retval VLC_EGENERIC if a \ref reset_pictures request is necessary
163 VOUT_DISPLAY_CHANGE_DISPLAY_SIZE
,
166 * Notifies a change of the display fill display flag by the user.
168 * \retval VLC_SUCCESS if the display handled the change
169 * \retval VLC_EGENERIC if a \ref reset_pictures request is necessary
171 VOUT_DISPLAY_CHANGE_DISPLAY_FILLED
,
174 * Notifies a change of the user zoom factor.
176 * \retval VLC_SUCCESS if the display handled the change
177 * \retval VLC_EGENERIC if a \ref reset_pictures request is necessary
179 VOUT_DISPLAY_CHANGE_ZOOM
,
182 * Notifies a change of the sample aspect ratio.
184 * \retval VLC_SUCCESS if the display handled the change
185 * \retval VLC_EGENERIC if a \ref reset_pictures request is necessary
187 VOUT_DISPLAY_CHANGE_SOURCE_ASPECT
,
190 * Notifies a change of the source cropping.
192 * The cropping requested is stored by source video_format_t::i_x/y_offset
193 * and video_format_t::i_visible_width/height
195 * \retval VLC_SUCCESS if the display handled the change
196 * \retval VLC_EGENERIC if a \ref reset_pictures request is necessary
198 VOUT_DISPLAY_CHANGE_SOURCE_CROP
,
202 * Vout owner structures
204 struct vout_display_owner_t
{
205 /* Private place holder for the vout_display_t creator
209 /* Event coming from the module
211 * This function is set prior to the module instantiation and must not
212 * be overwritten nor used directly (use the vout_display_SendEvent*
215 * You can send it at any time i.e. from any vout_display_t functions or
216 * from another thread.
217 * Be careful, it does not ensure correct serialization if it is used
218 * from multiple threads.
220 void (*viewpoint_moved
)(void *sys
, const vlc_viewpoint_t
*vp
);
224 * "vout display" open callback
226 * @param vd vout display context
227 * @param cfg Initial and current configuration.
228 * @param fmtp It can be changed by the module to request a different format.
229 * @param context XXX: to be defined.
230 * @return VLC_SUCCESS or a VLC error code
232 typedef int (*vout_display_open_cb
)(vout_display_t
*vd
,
233 const vout_display_cfg_t
*cfg
,
234 video_format_t
*fmtp
,
235 vlc_video_context
*context
);
237 #define set_callback_display(activate, priority) \
239 vout_display_open_cb open__ = activate; \
241 set_callback(activate) \
243 set_capability( "vout display", priority )
245 struct vlc_display_operations
248 * Destroys the display.
250 void (*close
)(vout_display_t
*);
253 * Prepares a picture and an optional subpicture for display (optional).
255 * This callback is called once a picture buffer content is ready,
256 * as far in advance as possible to the intended display time,
257 * but only after the previous picture was displayed.
259 * The callback should perform any preprocessing operation that will not
260 * actually cause the picture to be shown, such as blending the subpicture
261 * or upload the picture to video memory. If supported, this can also
262 * queue the picture to be shown asynchronously at the given date.
264 * If prepare is not \c NULL, there is an implicit guarantee that display
265 * will be invoked with the exact same picture afterwards:
266 * prepare 1st picture, display 1st picture, prepare 2nd picture, display
267 * 2nd picture, and so on.
269 * \note The picture buffers may have multiple references.
270 * Therefore the pixel content of the picture or of the subpicture
271 * must not be changed.
274 * \param subpic subpicture to render over the picture
275 * \param date time when the picture is intended to be shown
277 void (*prepare
)(vout_display_t
*, picture_t
*pic
,
278 subpicture_t
*subpic
, vlc_tick_t date
);
281 * Displays a picture.
283 * This callback is invoked at the time when the picture should be shown.
284 * The picture must be displayed as soon as possible.
286 * \note The picture buffers may have multiple references.
287 * Therefore the pixel content of the picture or of the subpicture
288 * must not be changed.
290 void (*display
)(vout_display_t
*, picture_t
*pic
);
293 * Performs a control request (mandatory).
295 * \param query request type
297 * See \ref vout_display_query for the list of request types.
299 int (*control
)(vout_display_t
*, int query
);
302 * Reset the picture format handled by the module.
303 * This occurs after a
304 * \ref VOUT_DISPLAY_CHANGE_DISPLAY_SIZE,
305 * \ref VOUT_DISPLAY_CHANGE_DISPLAY_FILLED,
306 * \ref VOUT_DISPLAY_CHANGE_ZOOM,
307 * \ref VOUT_DISPLAY_CHANGE_SOURCE_ASPECT or
308 * \ref VOUT_DISPLAY_CHANGE_SOURCE_CROP
309 * control query returns an error.
311 * \param ftmp video format that the module expects as input
313 int (*reset_pictures
)(vout_display_t
*, video_format_t
*fmtp
);
316 * Notifies a change of VR/360° viewpoint.
320 * \param vp viewpoint to use on the next render
322 int (*set_viewpoint
)(vout_display_t
*, const vlc_viewpoint_t
*vp
);
325 struct vout_display_t
{
326 struct vlc_object_t obj
;
329 * User configuration.
331 * This cannot be modified directly. It reflects the current values.
333 const vout_display_cfg_t
*cfg
;
336 * Source video format.
338 * This is the format of the video that is being displayed (after decoding
339 * and filtering). It cannot be modified.
342 * Cropping is not requested while in the open function.
344 const video_format_t
*source
;
349 * This is the format of the pictures that are supplied to the
350 * \ref prepare and \ref display callbacks. Ideally, it should be identical
351 * or as close as possible as \ref source.
353 * This can only be changed from the display module activation callback,
354 * or within a \ref reset_pictures request.
356 * By default, it is equal to ::source except for the aspect ratio
357 * which is undefined(0) and is ignored.
359 const video_format_t
*fmt
;
363 * You can only set them in the open function.
365 vout_display_info_t info
;
367 /* Reserved for the vout_display_t owner.
369 * It must not be overwritten nor used directly by a module.
371 vout_display_owner_t owner
;
374 * Private data for the display module.
376 * A module is free to use it as it wishes.
378 vout_display_sys_t
*sys
;
381 * Callbacks the display module must set on Open.
383 const struct vlc_display_operations
*ops
;
387 * Creates video output display.
390 vout_display_t
*vout_display_New(vlc_object_t
*,
391 const video_format_t
*, vlc_video_context
*,
392 const vout_display_cfg_t
*, const char *module
,
393 const vout_display_owner_t
*);
396 * Destroys a video output display.
398 VLC_API
void vout_display_Delete(vout_display_t
*);
401 * Prepares a picture for display.
403 * This renders a picture for subsequent display, with vout_display_Display().
405 * \note A reference to the input picture is consumed by the function, which
406 * returns a reference to an output picture for display. The input and output
407 * picture may or may not be equal depending on the underlying display setup.
409 * \bug Currently, only one picture can be prepared at a time. It must be
410 * displayed with vout_display_Display() before any picture is prepared or
411 * before the display is destroyd with vout_display_Delete().
413 \ bug Rendering subpictures is not supported with this function yet.
414 * \c subpic must be @c NULL .
416 * \param vd display to prepare the picture for
417 * \param picture picure to be prepared
418 * \param subpic reserved, must be NULL
419 * \param date intended time to show the picture
420 * \return The prepared picture is returned, NULL on error.
422 VLC_API picture_t
*vout_display_Prepare(vout_display_t
*vd
, picture_t
*picture
,
423 subpicture_t
*subpic
, vlc_tick_t date
);
426 * Displays a picture.
428 static inline void vout_display_Display(vout_display_t
*vd
, picture_t
*picture
)
430 if (vd
->ops
->display
!= NULL
)
431 vd
->ops
->display(vd
, picture
);
432 picture_Release(picture
);
436 void vout_display_SetSize(vout_display_t
*vd
, unsigned width
, unsigned height
);
438 static inline void vout_display_SendEventMousePressed(vout_display_t
*vd
, int button
)
440 vout_window_ReportMousePressed(vd
->cfg
->window
, button
);
442 static inline void vout_display_SendEventMouseReleased(vout_display_t
*vd
, int button
)
444 vout_window_ReportMouseReleased(vd
->cfg
->window
, button
);
446 static inline void vout_display_SendEventMouseDoubleClick(vout_display_t
*vd
)
448 vout_window_ReportMouseDoubleClick(vd
->cfg
->window
, MOUSE_BUTTON_LEFT
);
450 static inline void vout_display_SendEventViewpointMoved(vout_display_t
*vd
,
451 const vlc_viewpoint_t
*vp
)
453 if (vd
->owner
.viewpoint_moved
)
454 vd
->owner
.viewpoint_moved(vd
->owner
.sys
, vp
);
458 * Helper function that applies the necessary transforms to the mouse position
459 * and then calls vout_display_SendEventMouseMoved.
461 * \param vd vout_display_t.
462 * \param m_x Mouse x position (relative to place, origin is top left).
463 * \param m_y Mouse y position (relative to place, origin is top left).
465 static inline void vout_display_SendMouseMovedDisplayCoordinates(vout_display_t
*vd
, int m_x
, int m_y
)
467 vout_window_ReportMouseMoved(vd
->cfg
->window
, m_x
, m_y
);
470 static inline bool vout_display_cfg_IsWindowed(const vout_display_cfg_t
*cfg
)
472 return cfg
->window
->type
!= VOUT_WINDOW_TYPE_DUMMY
;
476 * Computes the default display size given the source and
477 * the display configuration.
479 * This asssumes that the picture is already cropped.
481 VLC_API
void vout_display_GetDefaultDisplaySize(unsigned *width
, unsigned *height
, const video_format_t
*source
, const vout_display_cfg_t
*);
487 * This structure stores the result of a vout_display_PlacePicture() call.
490 int x
; /*< Relative pixel offset from the display left edge */
491 int y
; /*< Relative pixel offset from the display top edge */
492 unsigned width
; /*< Picture pixel width */
493 unsigned height
; /*< Picture pixel height */
494 } vout_display_place_t
;
497 * Compares two \ref vout_display_place_t.
499 static inline bool vout_display_PlaceEquals(const vout_display_place_t
*p1
,
500 const vout_display_place_t
*p2
)
502 return p1
->x
== p2
->x
&& p1
->width
== p2
->width
&&
503 p1
->y
== p2
->y
&& p1
->height
== p2
->height
;
507 * Computes the intended picture placement inside the display.
509 * This function computes where to show a picture inside the display with
510 * respect to the provided parameters, and returns the result
511 * in a \ref vout_display_place_t structure.
513 * This assumes that cropping is done by an external mean.
515 * \param place Storage space for the picture placement [OUT]
516 * \param source Video source format
517 * \param cfg Display configuration
519 VLC_API
void vout_display_PlacePicture(vout_display_place_t
*place
, const video_format_t
*source
, const vout_display_cfg_t
*cfg
);
522 * Translates mouse state.
524 * This translates the mouse (pointer) state from window coordinates to
526 * @note @c video and @c window pointers may alias.
528 void vout_display_TranslateMouseState(vout_display_t
*vd
, vlc_mouse_t
*video
,
529 const vlc_mouse_t
*window
);
532 #endif /* VLC_VOUT_DISPLAY_H */