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 * - Otherwise, the video size is determined from the original video format,
90 * multiplied by the zoom factor.
92 typedef struct vout_display_cfg
{
93 struct vout_window_t
*window
; /**< Window */
95 bool is_fullscreen VLC_DEPRECATED
; /* Is the display fullscreen */
98 /** Display properties */
100 unsigned width
; /**< Requested display pixel width (0 by default). */
101 unsigned height
; /**< Requested display pixel height (0 by default). */
102 vlc_rational_t sar
; /**< Requested sample aspect ratio */
105 /** Alignment of the video within the window */
106 vlc_video_align_t align
;
108 /** Automatic scaling/fitting flag */
109 bool is_display_filled
;
117 vlc_viewpoint_t viewpoint
;
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 can_scale_spu
; /* Handles subpictures with a non default zoom factor */
129 const vlc_fourcc_t
*subpicture_chromas
; /* List of supported chromas for subpicture rendering. */
130 } vout_display_info_t
;
133 * Control query for vout_display_t
135 enum vout_display_query
{
137 * Asks to reset the internal buffers and picture format.
139 * This occurs after a
140 * \ref VOUT_DISPLAY_CHANGE_DISPLAY_SIZE,
141 * \ref VOUT_DISPLAY_CHANGE_DISPLAY_FILLED,
142 * \ref VOUT_DISPLAY_CHANGE_ZOOM,
143 * \ref VOUT_DISPLAY_CHANGE_SOURCE_ASPECT or
144 * \ref VOUT_DISPLAY_CHANGE_SOURCE_CROP
145 * control query returns an error.
147 VOUT_DISPLAY_RESET_PICTURES
, /* const vout_display_cfg_t *, video_format_t * */
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
, /* 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 VLC_DEPRECATED_ENUM
, /* unsigned state */
158 * Notifies a change in display size.
160 * \retval VLC_SUCCESS if the display handled the change
161 * \retval VLC_EGENERIC if a \ref VOUT_DISPLAY_RESET_PICTURES request
164 VOUT_DISPLAY_CHANGE_DISPLAY_SIZE
, /* const vout_display_cfg_t *p_cfg */
167 * Notifies a change of the display fill display flag by the user.
169 * \retval VLC_SUCCESS if the display handled the change
170 * \retval VLC_EGENERIC if a \ref VOUT_DISPLAY_RESET_PICTURES request
173 VOUT_DISPLAY_CHANGE_DISPLAY_FILLED
, /* const vout_display_cfg_t *p_cfg */
176 * Notifies a change of the user zoom factor.
178 * \retval VLC_SUCCESS if the display handled the change
179 * \retval VLC_EGENERIC if a \ref VOUT_DISPLAY_RESET_PICTURES request
182 VOUT_DISPLAY_CHANGE_ZOOM
, /* const vout_display_cfg_t *p_cfg */
185 * Notifies a change of the sample aspect ratio.
187 * \retval VLC_SUCCESS if the display handled the change
188 * \retval VLC_EGENERIC if a \ref VOUT_DISPLAY_RESET_PICTURES request
191 VOUT_DISPLAY_CHANGE_SOURCE_ASPECT
, /* const vout_display_cfg_t *p_cfg */
194 * Notifies a change of the source cropping.
196 * The cropping requested is stored by source video_format_t::i_x/y_offset
197 * and video_format_t::i_visible_width/height
199 * \retval VLC_SUCCESS if the display handled the change
200 * \retval VLC_EGENERIC if a \ref VOUT_DISPLAY_RESET_PICTURES request
203 VOUT_DISPLAY_CHANGE_SOURCE_CROP
, /* const vout_display_cfg_t *p_cfg */
206 * Notifies a change of VR/360° viewpoint.
208 VOUT_DISPLAY_CHANGE_VIEWPOINT
, /* const vout_display_cfg_t *p_cfg */
212 * Vout owner structures
214 struct vout_display_owner_t
{
215 /* Private place holder for the vout_display_t creator
219 /* Event coming from the module
221 * This function is set prior to the module instantiation and must not
222 * be overwritten nor used directly (use the vout_display_SendEvent*
225 * You can send it at any time i.e. from any vout_display_t functions or
226 * from another thread.
227 * Be careful, it does not ensure correct serialization if it is used
228 * from multiple threads.
230 void (*viewpoint_moved
)(void *sys
, const vlc_viewpoint_t
*vp
);
234 * "vout display" open callback
236 * @param vd vout display context
237 * @param cfg Initial and current configuration.
238 * @param fmtp By default, it is equal to vd->source except for the aspect
239 * ratio which is undefined(0) and is ignored. It can be changed by the module
240 * to request a different format.
241 * @param context XXX: to be defined.
242 * @return VLC_SUCCESS or a VLC error code
244 typedef int (*vout_display_open_cb
)(vout_display_t
*vd
,
245 const vout_display_cfg_t
*cfg
,
246 video_format_t
*fmtp
,
247 vlc_video_context
*context
);
249 #define set_callback_display(activate, priority) \
251 vout_display_open_cb open__ = activate; \
253 set_callback(activate) \
255 set_capability( "vout display", priority )
258 struct vout_display_t
{
259 struct vlc_object_t obj
;
262 * User configuration.
264 * This cannot be modified directly. It reflects the current values.
266 const vout_display_cfg_t
*cfg
;
269 * Source video format.
271 * This is the format of the video that is being displayed (after decoding
272 * and filtering). It cannot be modified.
275 * Cropping is not requested while in the open function.
277 video_format_t source
;
282 * This is the format of the pictures that are supplied to the
283 * \ref prepare and \ref display callbacks. Ideally, it should be identical
284 * or as close as possible as \ref source.
286 * This can only be changed from the display module activation callback,
287 * or within a VOUT_DISPLAY_RESET_PICTURES control request.
289 * By default, it is equal to ::source except for the aspect ratio
290 * which is undefined(0) and is ignored.
296 * You can only set them in the open function.
298 vout_display_info_t info
;
301 * Prepares a picture and an optional subpicture for display (optional).
303 * This callback is called once a picture buffer content is ready,
304 * as far in advance as possible to the intended display time,
305 * but only after the previous picture was displayed.
307 * The callback should perform any preprocessing operation that will not
308 * actually cause the picture to be shown, such as blending the subpicture
309 * or upload the picture to video memory. If supported, this can also
310 * queue the picture to be shown asynchronously at the given date.
312 * If prepare is not \c NULL, there is an implicit guarantee that display
313 * will be invoked with the exact same picture afterwards:
314 * prepare 1st picture, display 1st picture, prepare 2nd picture, display
315 * 2nd picture, and so on.
317 * \note The picture buffers may have multiple references.
318 * Therefore the pixel content of the picture or of the subpicture
319 * must not be changed.
322 * \param subpic subpicture to render over the picture
323 * \param date time when the picture is intended to be shown
325 void (*prepare
)(vout_display_t
*, picture_t
*pic
,
326 subpicture_t
*subpic
, vlc_tick_t date
);
329 * Displays a picture.
331 * This callback is invoked at the time when the picture should be shown.
332 * The picture must be displayed as soon as possible.
334 * \note The picture buffers may have multiple references.
335 * Therefore the pixel content of the picture or of the subpicture
336 * must not be changed.
338 void (*display
)(vout_display_t
*, picture_t
*pic
);
341 * Performs a control request (mandatory).
343 * \param query request type
345 * See \ref vout_display_query for the list of request types.
347 int (*control
)(vout_display_t
*, int query
, va_list);
350 * Destroys the display.
352 void (*close
)(vout_display_t
*);
355 * Private data for the display module.
357 * A module is free to use it as it wishes.
359 vout_display_sys_t
*sys
;
361 /* Reserved for the vout_display_t owner.
363 * It must not be overwritten nor used directly by a module.
365 vout_display_owner_t owner
;
369 * Creates video output display.
372 vout_display_t
*vout_display_New(vlc_object_t
*,
373 const video_format_t
*, vlc_video_context
*,
374 const vout_display_cfg_t
*, const char *module
,
375 const vout_display_owner_t
*);
378 * Destroys a video output display.
380 VLC_API
void vout_display_Delete(vout_display_t
*);
383 * Prepares a picture for display.
385 * This renders a picture for subsequent display, with vout_display_Display().
387 * \note A reference to the input picture is consumed by the function, which
388 * returns a reference to an output picture for display. The input and output
389 * picture may or may not be equal depending on the underlying display setup.
391 * \bug Currently, only one picture can be prepared at a time. It must be
392 * displayed with vout_display_Display() before any picture is prepared or
393 * before the display is destroyd with vout_display_Delete().
395 \ bug Rendering subpictures is not supported with this function yet.
396 * \c subpic must be @c NULL .
398 * \param vd display to prepare the picture for
399 * \param picture picure to be prepared
400 * \param subpic reserved, must be NULL
401 * \param date intended time to show the picture
402 * \return The prepared picture is returned, NULL on error.
404 VLC_API picture_t
*vout_display_Prepare(vout_display_t
*vd
, picture_t
*picture
,
405 subpicture_t
*subpic
, vlc_tick_t date
);
408 * Displays a picture.
410 static inline void vout_display_Display(vout_display_t
*vd
, picture_t
*picture
)
412 if (vd
->display
!= NULL
)
413 vd
->display(vd
, picture
);
414 picture_Release(picture
);
418 void vout_display_SetSize(vout_display_t
*vd
, unsigned width
, unsigned height
);
420 VLC_API
void vout_display_SendEventPicturesInvalid(vout_display_t
*vd
);
422 static inline void vout_display_SendEventMousePressed(vout_display_t
*vd
, int button
)
424 vout_window_ReportMousePressed(vd
->cfg
->window
, button
);
426 static inline void vout_display_SendEventMouseReleased(vout_display_t
*vd
, int button
)
428 vout_window_ReportMouseReleased(vd
->cfg
->window
, button
);
430 static inline void vout_display_SendEventMouseDoubleClick(vout_display_t
*vd
)
432 vout_window_ReportMouseDoubleClick(vd
->cfg
->window
, MOUSE_BUTTON_LEFT
);
434 static inline void vout_display_SendEventViewpointMoved(vout_display_t
*vd
,
435 const vlc_viewpoint_t
*vp
)
437 if (vd
->owner
.viewpoint_moved
)
438 vd
->owner
.viewpoint_moved(vd
->owner
.sys
, vp
);
442 * Helper function that applies the necessary transforms to the mouse position
443 * and then calls vout_display_SendEventMouseMoved.
445 * \param vd vout_display_t.
446 * \param m_x Mouse x position (relative to place, origin is top left).
447 * \param m_y Mouse y position (relative to place, origin is top left).
449 static inline void vout_display_SendMouseMovedDisplayCoordinates(vout_display_t
*vd
, int m_x
, int m_y
)
451 vout_window_ReportMouseMoved(vd
->cfg
->window
, m_x
, m_y
);
454 static inline bool vout_display_cfg_IsWindowed(const vout_display_cfg_t
*cfg
)
456 return cfg
->window
->type
!= VOUT_WINDOW_TYPE_DUMMY
;
460 * Computes the default display size given the source and
461 * the display configuration.
463 * This asssumes that the picture is already cropped.
465 VLC_API
void vout_display_GetDefaultDisplaySize(unsigned *width
, unsigned *height
, const video_format_t
*source
, const vout_display_cfg_t
*);
471 * This structure stores the result of a vout_display_PlacePicture() call.
474 int x
; /*< Relative pixel offset from the display left edge */
475 int y
; /*< Relative pixel offset from the display top edge */
476 unsigned width
; /*< Picture pixel width */
477 unsigned height
; /*< Picture pixel height */
478 } vout_display_place_t
;
481 * Compares two \ref vout_display_place_t.
483 static inline bool vout_display_PlaceEquals(const vout_display_place_t
*p1
,
484 const vout_display_place_t
*p2
)
486 return p1
->x
== p2
->x
&& p1
->width
== p2
->width
&&
487 p1
->y
== p2
->y
&& p1
->height
== p2
->height
;
491 * Computes the intended picture placement inside the display.
493 * This function computes where to show a picture inside the display with
494 * respect to the provided parameters, and returns the result
495 * in a \ref vout_display_place_t structure.
497 * This assumes that cropping is done by an external mean.
499 * \param place Storage space for the picture placement [OUT]
500 * \param source Video source format
501 * \param cfg Display configuration
503 VLC_API
void vout_display_PlacePicture(vout_display_place_t
*place
, const video_format_t
*source
, const vout_display_cfg_t
*cfg
);
506 * Translates mouse state.
508 * This translates the mouse (pointer) state from window coordinates to
510 * @note @c video and @c window pointers may alias.
512 void vout_display_TranslateMouseState(vout_display_t
*vd
, vlc_mouse_t
*video
,
513 const vlc_mouse_t
*window
);
516 #endif /* VLC_VOUT_DISPLAY_H */