Video output display

Video output display: output buffers and rendering. More...

Collaboration diagram for Video output display:

Topics
	Video alignment

Files
file	vlc_vout_display.h
	Video output display modules interface.

Data Structures
struct	vout_display_placement
	Display placement and zoom configuration. More...
struct	vout_display_cfg
	User configuration for a video output display (vout_display_t). More...
struct	vout_display_info_t
	Information from a vout_display_t to configure the core behaviour. More...
struct	vout_display_owner_t
	Vout owner structures. More...
struct	vlc_display_operations
struct	vout_display_place_t
	Video placement. More...
struct	vout_display_t

Macros
#define	set_callback_display(activate, priority)

Typedefs
typedef struct vout_display_t	vout_display_t
typedef struct vout_display_owner_t	vout_display_owner_t
typedef struct vout_display_cfg	vout_display_cfg_t
	User configuration for a video output display (vout_display_t).
typedef int(*	vout_display_open_cb) (vout_display_t *vd, video_format_t *fmtp, vlc_video_context *context)
	"vout display" open callback
typedef struct vout_display_place_t	vout_display_place_t
	Video placement.

Enumerations
enum	vlc_video_fitting {   VLC_VIDEO_FIT_NONE , VLC_VIDEO_FIT_SMALLER , VLC_VIDEO_FIT_LARGER , VLC_VIDEO_FIT_WIDTH ,   VLC_VIDEO_FIT_HEIGHT }
	Video automatic scale fitting. More...

Functions
vout_display_t *	vout_display_New (vlc_object_t *, const video_format_t *, vlc_video_context *, const vout_display_cfg_t *, const char *module, const vout_display_owner_t *)
	Creates video output display.
void	vout_display_Delete (vout_display_t *)
	Destroys a video output display.
picture_t *	vout_display_Prepare (vout_display_t *vd, picture_t *picture, const struct vlc_render_subpicture *subpic, vlc_tick_t date)
	Prepares a picture for display.
static void	vout_display_Display (vout_display_t *vd, picture_t *picture)
	Displays a picture.
void	vout_display_SetSize (vout_display_t *vd, unsigned width, unsigned height)
int	vout_display_SetFormat (vout_display_t *, const video_format_t *fmt, vlc_video_context *vctx)
	Updates the video format for an existing display.
static void	vout_display_SendEventMousePressed (vout_display_t *vd, int button)
static void	vout_display_SendEventMouseReleased (vout_display_t *vd, int button)
static void	vout_display_SendEventViewpointMoved (vout_display_t *vd, const vlc_viewpoint_t *vp)
static void	vout_display_SendMouseMovedDisplayCoordinates (vout_display_t *vd, int m_x, int m_y)
	Helper function that applies the necessary transforms to the mouse position and then calls vout_display_SendEventMouseMoved.
static bool	vout_display_cfg_IsWindowed (const vout_display_cfg_t *cfg)
static int	vout_display_ChangeProjection (vout_display_t *display, video_projection_mode_t projection)
	Set the source projection used by the display.
void	vout_display_GetDefaultDisplaySize (unsigned *width, unsigned *height, const video_format_t *source, const struct vout_display_placement *)
	Computes the default display size given the source and the display configuration.
static bool	vout_display_PlaceEquals (const vout_display_place_t *p1, const vout_display_place_t *p2)
	Compares two vout_display_place_t.
void	vout_display_PlacePicture (vout_display_place_t *restrict place, const video_format_t *restrict source, const struct vout_display_placement *cfg)
	Computes the intended picture placement inside the display.
void	vout_display_TranslateCoordinates (int *x, int *y, const video_format_t *fmt, const struct vout_display_placement *dp)
	Translates coordinates.

Detailed Description

Video output display: output buffers and rendering.

Macro Definition Documentation

set_callback_display

#define set_callback_display	(		activate,
			priority )

Value:

    { \
        vout_display_open_cb open__ = activate; \
        (void) open__; \
        set_callback(activate) \
    } \
    set_capability( "vout display", priority )

Typedef Documentation

vout_display_cfg_t

typedef struct vout_display_cfg vout_display_cfg_t

User configuration for a video output display (vout_display_t).

This primarily controls the size of the display area within the video window, as follows:

• If vout_display_placement::fitting is not disabled, ie. equals to VLC_VIDEO_FIT_NONE, in vout_display_cfg::display, the video size is fitted to the display size.
• If window size is valid, the video size is set to the window size,
• Otherwise, the video size is determined from the original video format, multiplied by the zoom factor.

vout_display_open_cb

typedef int(* vout_display_open_cb) (vout_display_t *vd, video_format_t *fmtp, vlc_video_context *context)

"vout display" open callback

Parameters

vd	vout display context
fmtp	It can be changed by the module to request a different format.
context	The video context to configure the display for.

Returns

VLC_SUCCESS or a VLC error code

vout_display_owner_t

typedef struct vout_display_owner_t vout_display_owner_t

vout_display_place_t

typedef struct vout_display_place_t vout_display_place_t

Video placement.

This structure stores the result of a vout_display_PlacePicture() call.

vout_display_t

typedef struct vout_display_t vout_display_t

Enumeration Type Documentation

vlc_video_fitting

enum vlc_video_fitting

Video automatic scale fitting.

Enumerator
VLC_VIDEO_FIT_NONE	No automatic scaling (use explicit zoom ratio).
VLC_VIDEO_FIT_SMALLER	Fit inside / to smallest dimension.
VLC_VIDEO_FIT_LARGER	Fit outside / to largest dimension.
VLC_VIDEO_FIT_WIDTH	Fit to width.
VLC_VIDEO_FIT_HEIGHT	Fit to height.

Function Documentation

vout_display_cfg_IsWindowed()

bool vout_display_cfg_IsWindowed ( const vout_display_cfg_t * cfg )

inlinestatic

References vlc_window::type, VLC_WINDOW_TYPE_DUMMY, and vout_display_cfg::window.

vout_display_ChangeProjection()

int vout_display_ChangeProjection ( vout_display_t * display, video_projection_mode_t projection )

inlinestatic

Set the source projection used by the display.

May be NULL.

Parameters

display	the display to change projection for
projection	the new projection mode considered for the source

Returns

VLC_SUCCESS on success, another value if changing projection failed

Return values

VLC_ENOTSUP

the display does not implement projection changes

References vlc_display_operations::display, and VLC_ENOTSUP.

Referenced by vout_SetDisplayProjection().

vout_display_Delete()

void vout_display_Delete

(

vout_display_t *

vd

)

Destroys a video output display.

References vlc_display_operations::close, container_of, vout_display_priv_t::converter, vout_display_priv_t::display_fmt, vout_display_t::ops, vout_display_priv_t::source, vout_display_priv_t::src_vctx, video_format_Clean(), VLC_OBJECT, vlc_object_delete, vlc_objres_clear(), vlc_video_context_Release(), and VoutConverterRelease().

Referenced by vout_CloseWrapper().

vout_display_Display()

void vout_display_Display ( vout_display_t * vd, picture_t * picture )

inlinestatic

Displays a picture.

This callback is invoked at the time when the picture should be shown. The picture must be displayed as soon as possible.

If NULL, prepare must be valid. In that case, the plugin can handle asynchronous display at the time given by the prepare call.

Note

The picture buffers may have multiple references. Therefore the pixel content of the picture or of the subpicture must not be changed.

References vlc_display_operations::display, and vout_display_t::ops.

Referenced by RenderPicture().

vout_display_GetDefaultDisplaySize()

void vout_display_GetDefaultDisplaySize	(	unsigned *	width,
		unsigned *	height,
		const video_format_t *	source,
		const struct vout_display_placement *	dp )

Computes the default display size given the source and the display configuration.

This assumes that the picture is already cropped.

References vlc_rational_t::den, video_format_t::i_sar_den, video_format_t::i_sar_num, video_format_t::i_visible_height, video_format_t::i_visible_width, vlc_rational_t::num, ORIENT_IS_SWAP, video_format_t::orientation, vout_display_placement::sar, and vout_display_placement::zoom.

Referenced by vout_display_New(), and vout_display_PlaceRotatedPicture().

vout_display_New()

vout_display_t * vout_display_New	(	vlc_object_t *	parent,
		const video_format_t *	source,
		vlc_video_context *	vctx,
		const vout_display_cfg_t *	cfg,
		const char *	module,
		const vout_display_owner_t *	owner )

Creates video output display.

References vout_display_priv_t::cfg, vout_display_t::cfg, vlc_display_operations::close, vout_display_priv_t::converter, vout_display_priv_t::crop, vlc_display_operations::display, vout_display_cfg::display, vout_display_priv_t::display, vout_display_priv_t::display_fmt, vout_display_t::fmt, vlc_object_t::force, vout_display_placement::height, vout_display_t::info, vout_crop::mode, module_get_object(), msg_Dbg, msg_Warn, vout_display_t::obj, vout_display_t::ops, vout_display_t::owner, vout_display_t::place, PlaceVideoInDisplay(), vlc_display_operations::prepare, vout_display_priv_t::source, vout_display_t::source, vout_display_priv_t::src_place, vout_display_priv_t::src_vctx, vout_display_cfg::stereo_mode, vout_display_t::sys, unlikely, video_format_Clean(), video_format_Copy(), vlc_custom_create, vlc_module_map(), vlc_module_match(), VLC_OBJECT, vlc_object_delete, vlc_object_logger, vlc_objres_clear(), VLC_SUCCESS, vlc_video_context_Hold(), VOUT_CROP_NONE, vout_display_GetDefaultDisplaySize(), VoutConverterCreate(), and vout_display_placement::width.

Referenced by vout_OpenWrapper().

vout_display_PlaceEquals()

bool vout_display_PlaceEquals ( const vout_display_place_t * p1, const vout_display_place_t * p2 )

inlinestatic

Compares two vout_display_place_t.

References vout_display_place_t::height, vout_display_place_t::width, vout_display_place_t::x, and vout_display_place_t::y.

Referenced by PlaceVideoInDisplay().

vout_display_PlacePicture()

void vout_display_PlacePicture	(	vout_display_place_t *restrict	place,
		const video_format_t *restrict	source,
		const struct vout_display_placement *	cfg )

Computes the intended picture placement inside the display.

This function computes where to show a picture inside the display with respect to the provided parameters, and returns the result in a vout_display_place_t structure.

This assumes that cropping is done by an external mean.

Parameters

place	Storage space for the picture placement [OUT]
source	Video source format
cfg	Display configuration

vout_display_Prepare()

picture_t * vout_display_Prepare	(	vout_display_t *	vd,
		picture_t *	picture,
		const struct vlc_render_subpicture *	subpic,
		vlc_tick_t	date )

Prepares a picture for display.

This renders a picture for subsequent display, with vout_display_Display().

Note

A reference to the input picture is consumed by the function, which returns a reference to an output picture for display. The input and output picture may or may not be equal depending on the underlying display setup.

Bug

Currently, only one picture can be prepared at a time. It must be displayed with vout_display_Display() before any picture is prepared or before the display is destroyed with vout_display_Delete().

\ bug Rendering subpictures is not supported with this function yet. subpic must be NULL .

Parameters

vd	display to prepare the picture for
picture	picure to be prepared
subpic	reserved, must be NULL
date	intended time to show the picture

Returns

The prepared picture is returned, NULL on error.

References VLC_API.

vout_display_SendEventMousePressed()

void vout_display_SendEventMousePressed ( vout_display_t * vd, int button )

inlinestatic

References vout_display_t::cfg, vlc_window_ReportMousePressed(), and vout_display_cfg::window.

vout_display_SendEventMouseReleased()

void vout_display_SendEventMouseReleased ( vout_display_t * vd, int button )

inlinestatic

References vout_display_t::cfg, vlc_window_ReportMouseReleased(), and vout_display_cfg::window.

vout_display_SendEventViewpointMoved()

void vout_display_SendEventViewpointMoved ( vout_display_t * vd, const vlc_viewpoint_t * vp )

inlinestatic

References vout_display_t::owner, vout_display_owner_t::sys, and vout_display_owner_t::viewpoint_moved.

vout_display_SendMouseMovedDisplayCoordinates()

void vout_display_SendMouseMovedDisplayCoordinates ( vout_display_t * vd, int m_x, int m_y )

inlinestatic

Helper function that applies the necessary transforms to the mouse position and then calls vout_display_SendEventMouseMoved.

Parameters

vd	vout_display_t.
m_x	Mouse x position (relative to place, origin is top left).
m_y	Mouse y position (relative to place, origin is top left).

References vout_display_t::cfg, vlc_window_ReportMouseMoved(), and vout_display_cfg::window.

vout_display_SetFormat()

int vout_display_SetFormat	(	vout_display_t *	vd,
		const video_format_t *	fmt,
		vlc_video_context *	vctx )

Updates the video format for an existing display.

This function changes the input video format of a vout display by calling the display module's update_format callback. It handles internal format updates, video context management, and display converter cleanup when the format change is accepted by the display module.

Note

The format size is not expected to change.

Parameters

vd	the vout display to update
fmt	the new video format to set
vctx	the video context associated with the format (may be NULL)

Returns

VLC_SUCCESS on success, VLC_EGENERIC if the display module doesn't support format updates, or another error code on failure

References vout_SetDisplayFormat().

vout_display_SetSize()

void vout_display_SetSize	(	vout_display_t *	vd,
		unsigned	width,
		unsigned	height )

References vout_display_priv_t::cfg, vout_display_t::cfg, container_of, vout_display_cfg::display, vout_display_placement::height, vout_display_t::ops, vout_display_t::place, PlaceVideoInDisplay(), vlc_display_operations::set_display_size, vout_display_t::source, UpdateSourceSAR(), vlc_display_operations::video_place_changed, VLC_SUCCESS, vout_display_Reset(), and vout_display_placement::width.

Referenced by vout_ChangeDisplaySize().

vout_display_TranslateCoordinates()

void vout_display_TranslateCoordinates	(	int *	x,
		int *	y,
		const video_format_t *	fmt,
		const struct vout_display_placement *	dp )

Translates coordinates.

This translates coordinates from window pixel coordinate space to original video sample coordinate space.

Parameters

x	pointer to abscissa to be translated
y	pointer to ordinate to be translated
fmt	video format
dp	display configuration