Encoding

Functions
int	kate_encode_init (kate_state *k, kate_info *ki)
int	kate_encode_text_raw_times (kate_state *k, kate_int64_t t0, kate_int64_t t1, const char *text, size_t sz, kate_packet *kp)
int	kate_encode_text (kate_state *k, kate_float t0, kate_float t1, const char *text, size_t sz, kate_packet *kp)
int	kate_encode_keepalive_raw_times (kate_state *k, kate_int64_t t, kate_packet *kp)
int	kate_encode_keepalive (kate_state *k, kate_float t, kate_packet *kp)
int	kate_encode_repeat_raw_times (kate_state *k, kate_int64_t t, kate_int64_t threshold, kate_packet *kp)
int	kate_encode_repeat (kate_state *k, kate_float t, kate_float threshold, kate_packet *kp)
int	kate_encode_finish_raw_times (kate_state *k, kate_int64_t t, kate_packet *kp)
int	kate_encode_finish (kate_state *k, kate_float t, kate_packet *kp)
int	kate_encode_headers (kate_state *k, kate_comment *kc, kate_packet *kp)
int	kate_encode_add_motion (kate_state *k, kate_motion *km, int destroy)
int	kate_encode_add_motion_index (kate_state *k, size_t motion)
int	kate_encode_add_bitmap (kate_state *k, const kate_bitmap *kb)
int	kate_encode_add_bitmap_index (kate_state *k, size_t bitmap)
int	kate_encode_set_region_index (kate_state *k, size_t region)
int	kate_encode_set_region (kate_state *k, const kate_region *kr)
int	kate_encode_set_style_index (kate_state *k, size_t style)
int	kate_encode_set_style (kate_state *k, const kate_style *ks)
int	kate_encode_set_secondary_style_index (kate_state *k, size_t style)
int	kate_encode_set_secondary_style (kate_state *k, const kate_style *ks)
int	kate_encode_set_palette_index (kate_state *k, size_t palette)
int	kate_encode_set_palette (kate_state *k, const kate_palette *kp)
int	kate_encode_set_bitmap_index (kate_state *k, size_t bitmap)
int	kate_encode_set_bitmap (kate_state *k, const kate_bitmap *kb)
int	kate_encode_set_font_mapping_index (kate_state *k, size_t font_mapping)
int	kate_encode_set_text_encoding (kate_state *k, kate_text_encoding text_encoding)
int	kate_encode_set_text_directionality (kate_state *k, kate_text_directionality text_directionality)
int	kate_encode_set_id (kate_state *k, kate_int32_t id)
int	kate_encode_set_language (kate_state *k, const char *language)
int	kate_encode_set_markup_type (kate_state *k, int text_markup_type)
int	kate_encode_add_meta (kate_state *k, const kate_meta *km)
int	kate_encode_merge_meta (kate_state *k, kate_meta *km)
kate_int64_t	kate_encode_get_granule (const kate_state *k)

---

Detailed Description

---

Function Documentation

int kate_encode_add_bitmap	(	kate_state *	k,
		const kate_bitmap *	kb
	)

Adds a bitmap to the currently encoded event.

Parameters:

k

the kate_state to add the bitmap to Parameters: kb  the bitmap to add Returns: 0 success KATE_E_* error

References KATE_E_INIT, and KATE_E_INVALID_PARAMETER.

int kate_encode_add_bitmap_index	(	kate_state *	k,
		size_t	bitmap
	)

Adds a bitmap to the currently encoded event by its index into the list of predefined bitmaps.

Parameters:

k

the kate_state to add the bitmap to Parameters: bitmap  the index of the bitmap to add Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, kate_state::ki, and kate_info::nbitmaps.

int kate_encode_add_meta	(	kate_state *	k,
		const kate_meta *	km
	)

Adds a set of metadata to this event

Parameters:

k

the kate_state to encode to Parameters: km  the metadata to add (a reference is taken, km must be live until the event is encoded) Returns: 0 success KATE_E_* error

References KATE_E_INIT, and KATE_E_INVALID_PARAMETER.

int kate_encode_add_motion	(	kate_state *	k,
		kate_motion *	km,
		int	destroy
	)

Adds a motion to the currently encoded event. If destroy is set, the motion will be automatically destroyed after the current event has been encoded.

Parameters:

k

the kate_state to add the motion to Parameters: km  the motion to add Parameters: destroy  if true, the motion will be destroyed when the event is fully encoded Returns: 0 success KATE_E_* error

References KATE_E_INIT, and KATE_E_INVALID_PARAMETER.

int kate_encode_add_motion_index	(	kate_state *	k,
		size_t	motion
	)

Adds a motion to the currently encoded event by its index into the list of predefined motions.

Parameters:

k

the kate_state to add the motion to Parameters: motion  the index of the motion to add Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, kate_state::ki, and kate_info::nmotions.

int kate_encode_finish	(	kate_state *	k,
		kate_float	t,
		kate_packet *	kp
	)

Finalizes the currently encoded stream. No more events may be added after this is called.

Parameters:

k

the kate_state to encode to Parameters: t  the timestamp for the end (if negative, the end time of the last event will be used) Parameters: kp  the packet to encode to Returns: 0 success KATE_E_* error

References kate_duration_granule(), KATE_E_INVALID_PARAMETER, kate_encode_finish_raw_times(), and kate_state::ki.

Referenced by kate_ogg_encode_finish().

int kate_encode_finish_raw_times	(	kate_state *	k,
		kate_int64_t	t,
		kate_packet *	kp
	)

Finalizes the currently encoded stream. No more events may be added after this is called.

Parameters:

k

the kate_state to encode to Parameters: t  the timestamp (in granule rate units) for the end (if negative, the end time of the last event will be used) Parameters: kp  the packet to encode to Returns: 0 success KATE_E_* error

References kate_info::granule_shift, KATE_E_BAD_GRANULE, KATE_E_INIT, KATE_E_INVALID_PARAMETER, KATE_E_NOT_FOUND, and kate_state::ki.

Referenced by kate_encode_finish(), and kate_ogg_encode_finish_raw_times().

kate_int64_t kate_encode_get_granule

(

const kate_state *

k

)

Retrieves the current granulepos

Parameters:

k

the kate_state to encode to Returns: >=0 the current granulepos (the one of the last encoded packet) KATE_E_* error

References KATE_E_INIT, and KATE_E_INVALID_PARAMETER.

int kate_encode_headers	(	kate_state *	k,
		kate_comment *	kc,
		kate_packet *	kp
	)

Encodes a header. This should be repeatedly called at the beginning of encoding, until a positive value is returned, marking the encoding of the last header.

Parameters:

k

the kate_state to encode to Parameters: kc  the list of comments to add to the headers Parameters: kp  the packet to encode to Returns: 0 success 1 success, and all headers have been encoded KATE_E_* error

References KATE_E_INIT, and KATE_E_INVALID_PARAMETER.

Referenced by kate_ogg_encode_headers().

int kate_encode_init	(	kate_state *	k,
		kate_info *	ki
	)

Initializes a kate_state structure for encoding using the supplied kate_info structure. When done, the kate_state structure should be cleared using kate_clear.

Parameters:

k

the kate_state structure to initialize for encoding Parameters: ki  the kate_info structure containing the encoding parameters Returns: 0 success KATE_E_* error

References KATE_E_INVALID_PARAMETER, KATE_E_OUT_OF_MEMORY, kate_state::ki, and kate_info::num_headers.

int kate_encode_keepalive	(	kate_state *	k,
		kate_float	t,
		kate_packet *	kp
	)

Emits a keepalive packet, to help with seeking.

Parameters:

k

the kate_state to encode to Parameters: t  the timestamp for the keepalive packet Parameters: kp  the packet to encode to Returns: 0 success KATE_E_* error

References kate_duration_granule(), KATE_E_INVALID_PARAMETER, kate_encode_keepalive_raw_times(), and kate_state::ki.

Referenced by kate_ogg_encode_keepalive().

int kate_encode_keepalive_raw_times	(	kate_state *	k,
		kate_int64_t	t,
		kate_packet *	kp
	)

Emits a keepalive packet, to help with seeking.

Parameters:

k

the kate_state to encode to Parameters: t  the timestamp (in granule rate units) for the keepalive packet Parameters: kp  the packet to encode to Returns: 0 success KATE_E_* error

References kate_info::granule_shift, KATE_E_BAD_GRANULE, KATE_E_INIT, KATE_E_INVALID_PARAMETER, KATE_E_NOT_FOUND, and kate_state::ki.

Referenced by kate_encode_keepalive(), and kate_ogg_encode_keepalive_raw_times().

int kate_encode_merge_meta	(	kate_state *	k,
		kate_meta *	km
	)

Adds a set of metadata to this event

Parameters:

k

the kate_state to encode to Parameters: km  the metadata to add (will become invalid after this call returns successfully) Returns: 0 success KATE_E_* error

References KATE_E_INIT, and KATE_E_INVALID_PARAMETER.

int kate_encode_repeat	(	kate_state *	k,
		kate_float	t,
		kate_float	threshold,
		kate_packet *	kp
	)

Emits a repeat packet, to help with seeking. The first active event at time t, if it or its latest repeat (whichever is the latest) was emitted more than threshold ago, of if threshold is zero, will have a repeat packet emitted. kate_encode_repeat is designed to be called in a loop, as it will return a repeat packet for only one event even if more than one event needs a repeat. When the returned value is 0, no more events need repeating at time t.

Parameters:

k

the kate_state to encode to Parameters: t  the timestamp for the the packets, if any Parameters: threshold  the time threshold at which to emit a repeat packets (zero to force a repeat) Parameters: kp  the packet to encode to Returns: 0 success, and no repeat packet was encoded 1 success, and a repeat packet was encoded KATE_E_* error

References kate_duration_granule(), KATE_E_INVALID_PARAMETER, kate_encode_repeat_raw_times(), and kate_state::ki.

Referenced by kate_ogg_encode_repeat().

int kate_encode_repeat_raw_times	(	kate_state *	k,
		kate_int64_t	t,
		kate_int64_t	threshold,
		kate_packet *	kp
	)

Emits a repeat packet, to help with seeking. The first active event at time t, if it or its latest repeat (whichever is the latest) was emitted more than threshold ago, of if threshold is zero, will have a repeat packet emitted. kate_encode_repeat is designed to be called in a loop, as it will return a repeat packet for only one event even if more than one event needs a repeat. When the returned value is 0, no more events need repeating at time t.

Parameters:

k

the kate_state to encode to Parameters: t  the timestamp (in granule rate units) for the the packets, if any Parameters: threshold  the time threshold (in granule rate units) at which to emit a repeat packets (zero to force a repeat) Parameters: kp  the packet to encode to Returns: 0 success, and no repeat packet was encoded 1 success, and a repeat packet was encoded KATE_E_* error

References kate_info::granule_shift, KATE_E_BAD_GRANULE, KATE_E_INIT, KATE_E_INVALID_PARAMETER, KATE_E_NOT_FOUND, and kate_state::ki.

Referenced by kate_encode_repeat(), and kate_ogg_encode_repeat_raw_times().

int kate_encode_set_bitmap	(	kate_state *	k,
		const kate_bitmap *	kb
	)

Adds a bitmap to the currently encoded event.

Parameters:

k

the kate_state to set the bitmap for Parameters: kb  the bitmap to set Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, and kate_state::ki.

int kate_encode_set_bitmap_index	(	kate_state *	k,
		size_t	bitmap
	)

Sets the bitmap the event should use, by its index in the predefined bitmap list.

Parameters:

k

the kate_state to encode to Parameters: bitmap  the index of the predefined bitmap to use Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, kate_state::ki, and kate_info::nbitmaps.

int kate_encode_set_font_mapping_index	(	kate_state *	k,
		size_t	font_mapping
	)

Sets the font mapping this event's text should be displayed with, by its index into the predefined font mappings list.

Parameters:

k

the kate_state to encode to Parameters: font_mapping  the font mapping to use Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, kate_state::ki, and kate_info::nfont_mappings.

int kate_encode_set_id	(	kate_state *	k,
		kate_int32_t	id
	)

This function is obsolete and should not be used. An event identifier is automatically generated for each event. It used to set a unique identifier for the currently encoded event, so it can be referred to later, but not does nothing.

Parameters:

k

the kate_state to encode to Parameters: id  unused Returns: KATE_E_* error

References KATE_E_IMPL, KATE_E_INIT, and KATE_E_INVALID_PARAMETER.

int kate_encode_set_language	(	kate_state *	k,
		const char *	language
	)

Sets the language used in this event's text, overriding the default language

Parameters:

k

the kate_state to encode to Parameters: language  the language for this event's text - may be NULL (use the default language) Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, and KATE_E_OUT_OF_MEMORY.

int kate_encode_set_markup_type	(	kate_state *	k,
		int	text_markup_type
	)

Sets the markup type of this event

Parameters:

k

the kate_state to encode to Parameters: text_markup_type  the markup type of this event Returns: 0 success KATE_E_* error

References KATE_E_INIT, and KATE_E_INVALID_PARAMETER.

int kate_encode_set_palette	(	kate_state *	k,
		const kate_palette *	kp
	)

Adds a palette to the currently encoded event.

Parameters:

k

the kate_state to set the palette for Parameters: kp  the palette to set Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, and kate_state::ki.

int kate_encode_set_palette_index	(	kate_state *	k,
		size_t	palette
	)

Sets the palette the event should use for its bitmap, by its index in the predefined palette list.

Parameters:

k

the kate_state to encode to Parameters: palette  the index of the predefined palette to use Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, kate_state::ki, and kate_info::npalettes.

int kate_encode_set_region	(	kate_state *	k,
		const kate_region *	kr
	)

Sets the region the event should be displayed in.

Parameters:

k

the kate_state to encode to Parameters: kr  the region to use Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, and kate_state::ki.

int kate_encode_set_region_index	(	kate_state *	k,
		size_t	region
	)

Sets the region the event should be displayed in, by its index in the predefined regions list.

Parameters:

k

the kate_state to encode to Parameters: region  the index of the predefined region to use Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, kate_state::ki, and kate_info::nregions.

int kate_encode_set_secondary_style	(	kate_state *	k,
		const kate_style *	ks
	)

Sets the secondary style the event should be displayed with.

Parameters:

k

the kate_state to encode to Parameters: ks  the style to use Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, and kate_state::ki.

int kate_encode_set_secondary_style_index	(	kate_state *	k,
		size_t	style
	)

Sets the secondary style the event should be displayed with, by its index in the predefined styles list.

Parameters:

k

the kate_state to encode to Parameters: style  the index of the predefined style to use Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, kate_state::ki, and kate_info::nstyles.

int kate_encode_set_style	(	kate_state *	k,
		const kate_style *	ks
	)

Sets the style the event should be displayed with.

Parameters:

k

the kate_state to encode to Parameters: ks  the style to use Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, and kate_state::ki.

int kate_encode_set_style_index	(	kate_state *	k,
		size_t	style
	)

Sets the style the event should be displayed with, by its index in the predefined styles list.

Parameters:

k

the kate_state to encode to Parameters: style  the index of the predefined style to use Returns: 0 success KATE_E_* error

References KATE_E_INIT, KATE_E_INVALID_PARAMETER, kate_state::ki, and kate_info::nstyles.

int kate_encode_set_text_directionality	(	kate_state *	k,
		kate_text_directionality	text_directionality
	)

Sets the text directionality used in this event's text, overriding the default text directionality.

Parameters:

k

the kate_state to encode to Parameters: text_directionality  the text directionality for this event's text Returns: 0 success KATE_E_* error

References KATE_E_INIT, and KATE_E_INVALID_PARAMETER.

int kate_encode_set_text_encoding	(	kate_state *	k,
		kate_text_encoding	text_encoding
	)

Sets the character encoding used in this event's text, overriding the default character encoding.

Parameters:

k

the kate_state to encode to Parameters: text_encoding  the text encoding for this event's text Returns: 0 success KATE_E_* error

References KATE_E_INIT, and KATE_E_INVALID_PARAMETER.

int kate_encode_text	(	kate_state *	k,
		kate_float	t0,
		kate_float	t1,
		const char *	text,
		size_t	sz,
		kate_packet *	kp
	)

Encodes a text (which may be NULL) of the given size, starting at t0 and ending at t1. This should always be called when encoding an event, even if the text is NULL. After this is called, the event is fully encoded and cannot be added to anymore.

Parameters:

k

the kate_state to add the text to Parameters: t0  the start time in seconds of the text Parameters: t1  the end time in seconds of the text Parameters: text  the text to add (may be NULL) Parameters: sz  the length in bytes of the text to add Parameters: kp  the packet to encode to Returns: 0 success KATE_E_* error

References kate_duration_granule(), KATE_E_INVALID_PARAMETER, kate_encode_text_raw_times(), and kate_state::ki.

Referenced by kate_ogg_encode_text().

int kate_encode_text_raw_times	(	kate_state *	k,
		kate_int64_t	t0,
		kate_int64_t	t1,
		const char *	text,
		size_t	sz,
		kate_packet *	kp
	)

Encodes a text (which may be NULL) of the given size, starting at t0 and ending at t1. This should always be called when encoding an event, even if the text is NULL. After this is called, the event is fully encoded and cannot be added to anymore.

Parameters:

k

the kate_state to add the text to Parameters: t0  the start time in granule units of the text Parameters: t1  the end time in granule units of the text Parameters: text  the text to add (may be NULL) Parameters: sz  the length in bytes of the text to add Parameters: kp  the packet to encode to Returns: 0 success KATE_E_* error

References kate_packet::data, kate_info::granule_shift, KATE_E_BAD_GRANULE, KATE_E_INIT, KATE_E_INVALID_PARAMETER, kate_text_validate(), kate_state::ki, and kate_packet::nbytes.

Referenced by kate_encode_text(), and kate_ogg_encode_text_raw_times().