kate_info access

Functions
int	kate_info_init (kate_info *ki)
int	kate_info_set_granule_encoding (kate_info *ki, kate_float resolution, kate_float max_length, kate_float max_event_lifetime)
int	kate_info_set_language (kate_info *ki, const char *language)
int	kate_info_set_text_directionality (kate_info *ki, kate_text_directionality text_directionality)
int	kate_info_set_category (kate_info *ki, const char *category)
int	kate_info_set_markup_type (kate_info *ki, kate_markup_type text_markup_type)
int	kate_info_set_original_canvas_size (kate_info *ki, size_t width, size_t height)
int	kate_info_add_region (kate_info *ki, kate_region *kr)
int	kate_info_add_style (kate_info *ki, kate_style *ks)
int	kate_info_add_curve (kate_info *ki, kate_curve *kc)
int	kate_info_add_motion (kate_info *ki, kate_motion *km)
int	kate_info_add_palette (kate_info *ki, kate_palette *kp)
int	kate_info_add_bitmap (kate_info *ki, kate_bitmap *kb)
int	kate_info_add_font_range (kate_info *ki, kate_font_range *kfr)
int	kate_info_add_font_mapping (kate_info *ki, kate_font_mapping *kfm)
int	kate_info_matches_language (const kate_info *ki, const char *language)
int	kate_info_remove_markup (kate_info *ki, int flag)
int	kate_info_no_limits (kate_info *ki, int flag)
int	kate_info_clear (kate_info *ki)

Detailed Description

Function Documentation

kate_info_add_bitmap()

int kate_info_add_bitmap	(	kate_info *	ki,
		kate_bitmap *	kb
	)

Adds a predefined bitmap so it can be referred to by index later.

Parameters

ki	the kate_info structure for the stream
kb	the bitmap to add

Returns

0 success

KATE_E_* error

References kate_info::bitmaps, and kate_info::nbitmaps.

kate_info_add_curve()

int kate_info_add_curve	(	kate_info *	ki,
		kate_curve *	kc
	)

Adds a predefined curve so it can be referred to by index later.

Parameters

ki	the kate_info structure for the stream
kc	the curve to add

Returns

0 success

KATE_E_* error

References kate_info::curves, and kate_info::ncurves.

kate_info_add_font_mapping()

int kate_info_add_font_mapping	(	kate_info *	ki,
		kate_font_mapping *	kfm
	)

Adds a predefined font mapping so it can be referred to by index later.

Parameters

ki	the kate_info structure for the stream
kfm	the font mapping to add

Returns

0 success

KATE_E_* error

References kate_info::font_mappings, and kate_info::nfont_mappings.

kate_info_add_font_range()

int kate_info_add_font_range	(	kate_info *	ki,
		kate_font_range *	kfr
	)

Adds a predefined font range so it can be referred to by index later.

Parameters

ki	the kate_info structure for the stream
kfr	the font range to add

Returns

0 success

KATE_E_* error

References kate_info::font_ranges, and kate_info::nfont_ranges.

kate_info_add_motion()

int kate_info_add_motion	(	kate_info *	ki,
		kate_motion *	km
	)

Adds a predefined motion so it can be referred to by index later.

Parameters

ki	the kate_info structure for the stream
km	the motion to add

Returns

0 success

KATE_E_* error

References kate_info::motions, and kate_info::nmotions.

kate_info_add_palette()

int kate_info_add_palette	(	kate_info *	ki,
		kate_palette *	kp
	)

Adds a predefined palette so it can be referred to by index later.

Parameters

ki	the kate_info structure for the stream
kp	the palette to add

Returns

0 success

KATE_E_* error

References kate_info::npalettes, and kate_info::palettes.

kate_info_add_region()

int kate_info_add_region	(	kate_info *	ki,
		kate_region *	kr
	)

Adds a predefined region so it can be referred to by index later.

Parameters

ki	the kate_info structure for the stream
kr	the region to add

Returns

0 success

KATE_E_* error

References kate_info::nregions, and kate_info::regions.

kate_info_add_style()

int kate_info_add_style	(	kate_info *	ki,
		kate_style *	ks
	)

Adds a predefined style so it can be referred to by index later. Adds a predefined region so it can be referred to by index later.

Parameters

ki	the kate_info structure for the stream
ks	the style to add

Returns

0 success

KATE_E_* error

References kate_info::nstyles, and kate_info::styles.

kate_info_clear()

int kate_info_clear

(

kate_info *

ki

)

Clears a kate_info structure previously initialized with kate_info_init. It may not be used again until kate_info_init is called again on it.

Parameters

ki	the kate_info structure to clear, must have been initialized with kate_info_init

Returns

0 success

KATE_E_* error

References kate_info::bitmaps, kate_info::category, kate_palette::colors, kate_info::curves, kate_style::font, kate_info::font_mappings, kate_info::font_ranges, KATE_E_INVALID_PARAMETER, kate_meta_destroy(), kate_info::language, kate_info::motions, kate_info::nbitmaps, kate_info::ncurves, kate_info::nfont_mappings, kate_info::nfont_ranges, kate_info::nmotions, kate_info::npalettes, kate_font_mapping::nranges, kate_info::nregions, kate_info::nstyles, kate_info::palettes, kate_bitmap::pixels, kate_curve::pts, kate_font_mapping::ranges, kate_info::regions, and kate_info::styles.

Referenced by kate_high_decode_init().

kate_info_init()

int kate_info_init

(

kate_info *

ki

)

Initializes a kate_info structure. When done, it should be clear using kate_info_clear.

Parameters

ki	the kate_info structure to initialize

Returns

0 success

KATE_E_* error

References kate_info::bitmaps, kate_info::bitstream_version_major, kate_info::bitstream_version_minor, kate_info::category, kate_info::curves, kate_info::font_mappings, kate_info::font_ranges, kate_info::gps_denominator, kate_info::gps_numerator, kate_info::granule_shift, KATE_BITSTREAM_VERSION_MAJOR, KATE_BITSTREAM_VERSION_MINOR, KATE_E_INVALID_PARAMETER, kate_l2r_t2b, kate_markup_none, kate_utf8, kate_info::language, kate_info::motions, kate_info::nbitmaps, kate_info::ncurves, kate_info::nfont_mappings, kate_info::nfont_ranges, kate_info::nmotions, kate_info::npalettes, kate_info::nregions, kate_info::nstyles, kate_info::num_headers, kate_info::original_canvas_height, kate_info::original_canvas_width, kate_info::palettes, kate_info::regions, kate_info::styles, kate_info::text_directionality, kate_info::text_encoding, and kate_info::text_markup_type.

Referenced by kate_high_decode_init().

kate_info_matches_language()

int kate_info_matches_language	(	const kate_info *	ki,
		const char *	language
	)

Checks whether the given language matches (fully or partially) the language described in the kate_info structure. Exact (case insensitive) matching of the two languages is required for a perfect match. Exact (case insensitive) matching of the primary tags for each language (which each may or may not have one or more secondary tags) is required for a partial match. An empty language for either the stream language or the language passed as parameter will cause a partial match.

Parameters

ki	the kate_info structure for the stream
language	the language to check against

Returns

0 success, but the language doesn't match

1 success, the language matches perfectly

2 success, the language matches partially

KATE_E_* error

References KATE_E_INVALID_PARAMETER, and kate_info::language.

kate_info_no_limits()

int kate_info_no_limits	(	kate_info *	ki,
		int	flag
	)

Requests whether large quantities of various things should be rejected or not, as a simple defense against DOS.

Parameters

ki	the kate_info structure for the stream
flag	if zero, values deemed arbitrarily too large will be treated as an error, else they will be accepted

Returns

0 success

KATE_E_* error

References KATE_E_INVALID_PARAMETER.

kate_info_remove_markup()

int kate_info_remove_markup	(	kate_info *	ki,
		int	flag
	)

Requests whether future events will strip text of markup or not.

Parameters

ki	the kate_info structure for the stream
flag	if zero, markup will be kept, else if will be removed

Returns

0 success

KATE_E_* error

References KATE_E_INVALID_PARAMETER.

kate_info_set_category()

int kate_info_set_category	(	kate_info *	ki,
		const char *	category
	)

Sets the category for this bitstream. The category is an ASCII string limited to 15 characters. Predefined categories include "subtitles", "lyrics", etc. Categories prefixed with "x-" are reserved for private use.

Note

Categories are not meant to be localized strings, but machine readable strings. While they may be displayed to the user as is, players are encouraged to recognize well known predefined categories such as the ones mentioned above, and supply translation for these.

Parameters

ki	the kate_info structure for the stream
category	the stream's category

Returns

0 success

KATE_E_* error

References kate_info::category, KATE_E_INVALID_PARAMETER, and KATE_E_LIMIT.

kate_info_set_granule_encoding()

int kate_info_set_granule_encoding	(	kate_info *	ki,
		kate_float	resolution,
		kate_float	max_length,
		kate_float	max_event_lifetime
	)

Sets up the granule encoding parameters so that events may be timestamped with the given resolution, and may not last longer than the given lifetime.

Parameters

ki	the kate_info structure to set the granule encoding parameters in.
resolution	the timestamping resolution, in seconds (eg, 0.001 means millisecond resolution)
max_length	the maximum time we need to represent, in seconds
max_event_lifetime	the maximum time an event may last, in seconds

Returns

0 success

KATE_E_* error

References kate_info::gps_denominator, kate_info::gps_numerator, kate_info::granule_shift, KATE_E_BAD_GRANULE, and KATE_E_INVALID_PARAMETER.

kate_info_set_language()

int kate_info_set_language	(	kate_info *	ki,
		const char *	language
	)

Sets the default language for this bitstream. The language should be a RFC 3066 language tag (most of the time, a ISO 639-1 code, optionally followed by a country secondary tag). This function does some basic validation, and will truncate the tag according to RFC 4646 rules. However, it may still accept some invalid tags. The maximum length of a language tag is 15 characters. If RFC 4646 truncation is possible, the tag will be truncated. If not, it will be rejected. In case of truncation, the tag that was actually set may be read back from the language field of the kate_info structure.

Parameters

ki	the kate_info structure for the stream
language	the default language to set for this stream

Returns

0 success

1 success, but the tag was truncated (the resulting tag may be read back from ki->language)

KATE_E_* error

References KATE_E_INVALID_PARAMETER, and kate_info::language.

kate_info_set_markup_type()

int kate_info_set_markup_type	(	kate_info *	ki,
		kate_markup_type	text_markup_type
	)

Sets the default text markup type for this bitstream

Parameters

ki	the kate_info structure for the stream
text_markup_type	the default text markup type to set for this stream

Returns

0 success

KATE_E_* error

References KATE_E_INVALID_PARAMETER, and kate_info::text_markup_type.

kate_info_set_original_canvas_size()

int kate_info_set_original_canvas_size	(	kate_info *	ki,
		size_t	width,
		size_t	height
	)

Sets the size of the canvas this stream is being authored for

Parameters

ki	the kate_info structure for the stream
width	the width of the canvas
height	the height of the canvas

Returns

0 success

KATE_E_* error

References KATE_E_INVALID_PARAMETER, kate_info::original_canvas_height, and kate_info::original_canvas_width.

kate_info_set_text_directionality()

int kate_info_set_text_directionality	(	kate_info *	ki,
		kate_text_directionality	text_directionality
	)

Sets the default text directionality for this bitstream

Parameters

ki	the kate_info structure for the stream
text_directionality	the default text directionality to set for this stream

Returns

0 success

KATE_E_* error

References KATE_E_INVALID_PARAMETER, and kate_info::text_directionality.