Video sub-pictures

Subpictures are pictures that should be displayed on top of the video, like subtitles and OSD. More...

Collaboration diagram for Video sub-pictures:

Files
file	vlc_subpicture.h
	Subpictures functions.

Data Structures
struct	subpicture_region_t
	Video subtitle region. More...
struct	vlc_spu_highlight_t
struct	vlc_spu_updater_ops
	Subpicture updater operation virtual table. More...
struct	subpicture_updater_t
struct	subpicture_region_rendered
struct	vlc_render_subpicture
struct	subpicture_t
	Video subtitle. More...

Macros
#define	VLC_SUBPIC_TEXT_FLAG_NO_REGION_BG   (1 << 4)
#define	VLC_SUBPIC_TEXT_FLAG_GRID_MODE   (1 << 5)
	if the decoder sends row/cols based output
#define	VLC_SUBPIC_TEXT_FLAG_TEXT_NOT_BALANCED   (1 << 6)
	don't try to balance wrapped text lines
#define	VLC_SUBPIC_TEXT_FLAG_IS_TEXT   (1 << 7)
	mark the subpicture region as a text flag
#define	vlc_spu_regions_init(p_rs)    vlc_list_init((p_rs))
#define	vlc_spu_regions_push(p_rs, reg)    vlc_list_append(&(reg)->node, (p_rs))
#define	vlc_spu_regions_foreach(reg, p_rs)    vlc_list_foreach(reg, (p_rs), node)
#define	vlc_spu_regions_foreach_const(reg, p_rs)    vlc_list_foreach_const(reg, (p_rs), node)
#define	vlc_spu_regions_is_empty(p_rs)    vlc_list_is_empty((p_rs))
#define	vlc_spu_regions_first_or_null(p_rs)    vlc_list_first_entry_or_null((p_rs), subpicture_region_t, node)
#define	vlc_spu_regions_remove(p_rs, reg)    vlc_list_remove(&(reg)->node)
#define	SUBPICTURE_ALIGN_LEFT   0x1
#define	SUBPICTURE_ALIGN_RIGHT   0x2
#define	SUBPICTURE_ALIGN_TOP   0x4
#define	SUBPICTURE_ALIGN_BOTTOM   0x8
#define	SUBPICTURE_ALIGN_MASK
#define	subpicture_region_IsText(r)    (((r)->text_flags & VLC_SUBPIC_TEXT_FLAG_IS_TEXT) != 0)
	Tells if the region is a text-based region.

Typedefs
typedef struct subpicture_region_private_t	subpicture_region_private_t
	Video subtitle region spu core private.
typedef struct vlc_spu_highlight_t	vlc_spu_highlight_t
typedef struct filter_t	vlc_blender_t
	render background under text only
typedef struct vlc_list	vlc_spu_regions
typedef struct subpicture_private_t	subpicture_private_t
typedef struct vlc_render_subpicture	vlc_render_subpicture

Functions
subpicture_region_t *	subpicture_region_New (const video_format_t *p_fmt)
	This function will create a new subpicture region.
subpicture_region_t *	subpicture_region_NewText (void)
	This function will create a new text subpicture region.
subpicture_region_t *	subpicture_region_ForPicture (const video_format_t *p_fmt, picture_t *pic)
	Create a subpicture region containing the picture.
void	subpicture_region_Delete (subpicture_region_t *p_region)
	This function will destroy a subpicture region allocated by subpicture_region_New.
void	vlc_spu_regions_Clear (vlc_spu_regions *)
	This function will clear a list of subpicture regions allocated by subpicture_region_New.
subpicture_t *	subpicture_New (const subpicture_updater_t *)
	This function create a new empty subpicture.
void	subpicture_Delete (subpicture_t *p_subpic)
	This function delete a subpicture created by subpicture_New.
subpicture_t *	subpicture_NewFromPicture (vlc_object_t *, picture_t *, vlc_fourcc_t i_chroma)
	This function will create a subpicture having one region in the requested chroma showing the given picture.
void	subpicture_Update (subpicture_t *, const video_format_t *src, const video_format_t *, vlc_tick_t)
	This function will update the content of a subpicture created with a non NULL subpicture_updater_t.
unsigned	picture_BlendSubpicture (picture_t *, vlc_blender_t *, vlc_render_subpicture *)
	This function will blend a given subpicture onto a picture.
vlc_render_subpicture *	vlc_render_subpicture_New (void)
	Create a vlc_render_subpicture.
void	vlc_render_subpicture_Delete (vlc_render_subpicture *)
	Destroy a vlc_render_subpicture.

Detailed Description

Subpictures are pictures that should be displayed on top of the video, like subtitles and OSD.

Macro Definition Documentation

SUBPICTURE_ALIGN_BOTTOM

#define SUBPICTURE_ALIGN_BOTTOM   0x8

SUBPICTURE_ALIGN_LEFT

#define SUBPICTURE_ALIGN_LEFT   0x1

SUBPICTURE_ALIGN_MASK

#define SUBPICTURE_ALIGN_MASK

Value:

                                ( SUBPICTURE_ALIGN_LEFT|SUBPICTURE_ALIGN_RIGHT| \
                                SUBPICTURE_ALIGN_TOP |SUBPICTURE_ALIGN_BOTTOM )

SUBPICTURE_ALIGN_RIGHT

#define SUBPICTURE_ALIGN_RIGHT   0x2

SUBPICTURE_ALIGN_TOP

#define SUBPICTURE_ALIGN_TOP   0x4

subpicture_region_IsText

#define subpicture_region_IsText

(

r

)

(((r)->text_flags & VLC_SUBPIC_TEXT_FLAG_IS_TEXT) != 0)

Tells if the region is a text-based region.

vlc_spu_regions_first_or_null

#define vlc_spu_regions_first_or_null

(

p_rs

)

vlc_list_first_entry_or_null((p_rs), subpicture_region_t, node)

vlc_spu_regions_foreach

#define vlc_spu_regions_foreach	(		reg,
			p_rs
	)		vlc_list_foreach(reg, (p_rs), node)

vlc_spu_regions_foreach_const

#define vlc_spu_regions_foreach_const	(		reg,
			p_rs
	)		vlc_list_foreach_const(reg, (p_rs), node)

vlc_spu_regions_init

#define vlc_spu_regions_init

(

p_rs

)

vlc_list_init((p_rs))

vlc_spu_regions_is_empty

#define vlc_spu_regions_is_empty

(

p_rs

)

vlc_list_is_empty((p_rs))

vlc_spu_regions_push

#define vlc_spu_regions_push	(		p_rs,
			reg
	)		vlc_list_append(&(reg)->node, (p_rs))

vlc_spu_regions_remove

#define vlc_spu_regions_remove	(		p_rs,
			reg
	)		vlc_list_remove(&(reg)->node)

VLC_SUBPIC_TEXT_FLAG_GRID_MODE

#define VLC_SUBPIC_TEXT_FLAG_GRID_MODE   (1 << 5)

if the decoder sends row/cols based output

VLC_SUBPIC_TEXT_FLAG_IS_TEXT

#define VLC_SUBPIC_TEXT_FLAG_IS_TEXT   (1 << 7)

mark the subpicture region as a text flag

VLC_SUBPIC_TEXT_FLAG_NO_REGION_BG

#define VLC_SUBPIC_TEXT_FLAG_NO_REGION_BG   (1 << 4)

VLC_SUBPIC_TEXT_FLAG_TEXT_NOT_BALANCED

#define VLC_SUBPIC_TEXT_FLAG_TEXT_NOT_BALANCED   (1 << 6)

don't try to balance wrapped text lines

Typedef Documentation

subpicture_private_t

typedef struct subpicture_private_t subpicture_private_t

subpicture_region_private_t

typedef struct subpicture_region_private_t subpicture_region_private_t

Video subtitle region spu core private.

vlc_blender_t

typedef struct filter_t vlc_blender_t

render background under text only

vlc_render_subpicture

typedef struct vlc_render_subpicture vlc_render_subpicture

vlc_spu_highlight_t

typedef struct vlc_spu_highlight_t vlc_spu_highlight_t

vlc_spu_regions

typedef struct vlc_list vlc_spu_regions

Function Documentation

picture_BlendSubpicture()

unsigned picture_BlendSubpicture	(	picture_t *	dst,
		vlc_blender_t *	blend,
		vlc_render_subpicture *	src
	)

This function will blend a given subpicture onto a picture.

The subpicture and all its region must:

• be absolute.
• not be ephemere.
• not have the fade flag.
• contains only picture (no text rendering).

  Returns

  the number of region(s) successfully blent

References filter_Blend(), filter_ConfigureBlend(), filter_t::fmt_in, filter_t::fmt_out, picture_t::format, subpicture_region_rendered::i_alpha, video_format_t::i_chroma, video_format_t::i_height, video_format_t::i_width, msg_Err, subpicture_region_rendered::p_picture, subpicture_region_rendered::place, vlc_render_subpicture::regions, es_format_t::video, vlc_vector_foreach, vout_display_place_t::x, and vout_display_place_t::y.

Referenced by ConvertRGBAAndBlend(), and PrerenderPicture().

subpicture_Delete()

void subpicture_Delete

(

subpicture_t *

p_subpic

)

This function delete a subpicture created by subpicture_New.

You may give it NULL.

References vlc_spu_updater_ops::destroy, subpicture_private_t::dst, subpicture_updater_t::ops, subpicture_t::p_private, subpicture_t::regions, subpicture_private_t::src, subpicture_t::updater, video_format_Clean(), and vlc_spu_regions_Clear().

Referenced by ModuleThread_PlaySpu(), ModuleThread_QueueSpu(), spu_Channel_CleanEntry(), spu_PutSubpicture(), subpicture_NewFromPicture(), and vout_PutSubpicture().

subpicture_New()

subpicture_t * subpicture_New

(

const subpicture_updater_t *

p_upd

)

This function create a new empty subpicture.

You must use subpicture_Delete to destroy it.

References subpicture_t::b_fade, subpicture_t::b_subtitle, subpicture_private_t::dst, subpicture_t::i_alpha, subpicture_t::i_order, subpicture_updater_t::ops, subpicture_t::p_private, subpicture_t::regions, subpicture_private_t::src, subpicture_updater_t::sys, subpicture_t::updater, video_format_Init(), and vlc_spu_regions_init.

Referenced by ModuleThread_NewSpuBuffer(), OSDWidget(), sub_new_buffer(), subpicture_NewFromPicture(), vout_OSDEpg(), and vout_OSDText().

subpicture_NewFromPicture()

subpicture_t * subpicture_NewFromPicture	(	vlc_object_t *	p_obj,
		picture_t *	p_picture,
		vlc_fourcc_t	i_chroma
	)

This function will create a subpicture having one region in the requested chroma showing the given picture.

The picture_t given is not released nor used inside the returned subpicture_t.

References subpicture_region_t::b_absolute, subpicture_region_t::fmt, picture_t::format, video_format_t::i_chroma, subpicture_t::i_original_picture_height, subpicture_t::i_original_picture_width, video_format_t::i_sar_den, video_format_t::i_sar_num, video_format_t::i_visible_height, video_format_t::i_visible_width, subpicture_region_t::i_x, subpicture_region_t::i_y, image_Convert, image_HandlerCreate, image_HandlerDelete(), likely, subpicture_region_rendered::p_picture, picture_Release(), subpicture_t::regions, subpicture_Delete(), subpicture_New(), subpicture_region_ForPicture(), unlikely, and vlc_spu_regions_push.

Referenced by VoutSnapshotPip().

subpicture_region_Delete()

void subpicture_region_Delete

(

subpicture_region_t *

p_region

)

This function will destroy a subpicture region allocated by subpicture_region_New.

You may give it NULL.

References subpicture_region_t::fmt, subpicture_region_t::p_picture, subpicture_region_t::p_private, subpicture_region_t::p_text, picture_Release(), subpicture_region_private_Delete(), text_segment_ChainDelete(), and video_format_Clean().

Referenced by spu_PrerenderText(), SpuRenderSubpictures(), and vlc_spu_regions_Clear().

subpicture_region_ForPicture()

subpicture_region_t * subpicture_region_ForPicture	(	const video_format_t *	p_fmt,
		picture_t *	pic
	)

Create a subpicture region containing the picture.

A reference will be added to the picture on success.

You must use subpicture_region_Delete to destroy it.

The chroma of the format must match the one of the picture. The dimensions of the format should not exceed the ones of the picture. This is not checked explicitly in the function.

Parameters

p_fmt

format for the subpicture cropping/SAR (may be NULL)

Note

if p_fmt is NULL, the format of the picture will be used.

References subpicture_region_t::fmt, picture_t::format, video_format_t::i_chroma, video_format_t::p_palette, subpicture_region_t::p_picture, picture_Hold(), subpicture_region_NewInternal(), video_format_Clean(), video_format_Copy(), video_format_IsSameChroma(), VLC_CODEC_RGBP, and VLC_CODEC_YUVP.

Referenced by spuregion_CreateFromPicture(), and subpicture_NewFromPicture().

subpicture_region_New()

subpicture_region_t * subpicture_region_New

(

const video_format_t *

p_fmt

)

This function will create a new subpicture region.

You must use subpicture_region_Delete to destroy it.

Note

use subpicture_region_NewText() to create a text region

References subpicture_region_t::fmt, picture_t::format, video_format_t::i_chroma, video_format_t::p_palette, subpicture_region_t::p_picture, picture_NewFromFormat(), picture_Release(), subpicture_region_NewInternal(), video_format_Clean(), video_format_Copy(), VLC_CODEC_RGBP, VLC_CODEC_TEXT, and VLC_CODEC_YUVP.

Referenced by OSDRegion(), vout_OSDBackground(), and vout_OSDEpgSlider().

subpicture_region_NewText()

subpicture_region_t * subpicture_region_NewText

(

void

)

This function will create a new text subpicture region.

You must use subpicture_region_Delete to destroy it.

References subpicture_region_t::fmt, subpicture_region_NewInternal(), subpicture_region_t::text_flags, video_format_Init(), and VLC_SUBPIC_TEXT_FLAG_IS_TEXT.

Referenced by OSDTextUpdate(), and vout_OSDTextRegion().

subpicture_Update()

void subpicture_Update	(	subpicture_t *	p_subpicture,
		const video_format_t *	src,
		const video_format_t *	p_fmt_dst,
		vlc_tick_t	i_ts
	)

This function will update the content of a subpicture created with a non NULL subpicture_updater_t.

References subpicture_private_t::dst, subpicture_updater_t::ops, subpicture_t::p_private, subpicture_private_t::src, vlc_spu_updater_ops::update, subpicture_t::updater, video_format_Clean(), and video_format_Copy().

Referenced by spu_PrerenderText(), and spu_Render().

vlc_render_subpicture_Delete()

void vlc_render_subpicture_Delete

(

vlc_render_subpicture *

p_subpic

)

Destroy a vlc_render_subpicture.

References subpicture_region_rendered::p_picture, picture_Release(), vlc_render_subpicture::regions, vlc_vector_clear, and vlc_vector_foreach.

Referenced by PrerenderPicture(), and RenderPicture().

vlc_render_subpicture_New()

vlc_render_subpicture * vlc_render_subpicture_New

(

void

)

Create a vlc_render_subpicture.

It should be released with vlc_render_subpicture_Delete.

References vlc_render_subpicture::regions, unlikely, and vlc_vector_init.

Referenced by SpuRenderSubpictures().

vlc_spu_regions_Clear()

void vlc_spu_regions_Clear

(

vlc_spu_regions *

regions

)

This function will clear a list of subpicture regions allocated by subpicture_region_New.

Provided for convenience.

References subpicture_region_Delete(), vlc_spu_regions_foreach, and vlc_spu_regions_remove.

Referenced by OSDEpgUpdate(), OSDTextUpdate(), OSDWidgetUpdate(), and subpicture_Delete().