#include "kate/kate_config.h"

Data Structures
struct	kate_region
struct	kate_color
struct	kate_style
struct	kate_curve
struct	kate_motion
struct	kate_palette
struct	kate_bitmap
struct	kate_font_range
struct	kate_font_mapping
struct	kate_info
struct	kate_state
struct	kate_comment
struct	kate_event
struct	kate_tracker
struct	kate_packet
Defines
API version

#define	KATE_VERSION_MAJOR 0
#define	KATE_VERSION_MINOR 3
#define	KATE_VERSION_PATCH 7
Bitstream version

#define	KATE_BITSTREAM_VERSION_MAJOR 0
#define	KATE_BITSTREAM_VERSION_MINOR 5
Error codes

#define	KATE_E_NOT_FOUND (-1)
#define	KATE_E_INVALID_PARAMETER (-2)
#define	KATE_E_OUT_OF_MEMORY (-3)
#define	KATE_E_BAD_GRANULE (-4)
#define	KATE_E_INIT (-5)
#define	KATE_E_BAD_PACKET (-6)
#define	KATE_E_TEXT (-7)
#define	KATE_E_LIMIT (-8)
#define	KATE_E_VERSION (-9)
#define	KATE_E_NOT_KATE (-10)
#define	KATE_E_BAD_TAG (-11)
#define	KATE_E_IMPL (-12)
Typedefs
typedef struct kate_region	kate_region
typedef struct kate_color	kate_color
typedef struct kate_style	kate_style
typedef enum kate_curve_type	kate_curve_type
typedef struct kate_curve	kate_curve
typedef enum kate_motion_mapping	kate_motion_mapping
typedef enum kate_motion_semantics	kate_motion_semantics
typedef struct kate_motion	kate_motion
typedef enum kate_text_directionality	kate_text_directionality
typedef struct kate_palette	kate_palette
typedef enum kate_bitmap_type	kate_bitmap_type
typedef struct kate_bitmap	kate_bitmap
typedef struct kate_font_range	kate_font_range
typedef struct kate_font_mapping	kate_font_mapping
typedef struct kate_info	kate_info
typedef struct kate_state	kate_state
typedef struct kate_comment	kate_comment
typedef struct kate_event	kate_event
typedef struct kate_tracker	kate_tracker
typedef struct kate_packet	kate_packet
Enumerations
enum	kate_text_encoding { kate_utf8 }
enum	kate_markup_type { kate_markup_none, kate_markup_simple }
enum	kate_space_metric { kate_pixel, kate_percentage, kate_millionths }
enum	kate_wrap_mode { kate_wrap_word, kate_wrap_none }
enum	kate_curve_type { kate_curve_none, kate_curve_static, kate_curve_linear, kate_curve_catmull_rom_spline, kate_curve_bezier_cubic_spline, kate_curve_bspline }
enum	kate_motion_mapping { kate_motion_mapping_none, kate_motion_mapping_frame, kate_motion_mapping_window, kate_motion_mapping_region, kate_motion_mapping_event_duration, kate_motion_mapping_bitmap_size, kate_motion_mapping_user = 128 }
enum	kate_motion_semantics { kate_motion_semantics_time, kate_motion_semantics_z, kate_motion_semantics_region_position, kate_motion_semantics_region_size, kate_motion_semantics_text_alignment_int, kate_motion_semantics_text_alignment_ext, kate_motion_semantics_text_position, kate_motion_semantics_text_size, kate_motion_semantics_marker1_position, kate_motion_semantics_marker2_position, kate_motion_semantics_marker3_position, kate_motion_semantics_marker4_position, kate_motion_semantics_glyph_pointer_1, kate_motion_semantics_glyph_pointer_2, kate_motion_semantics_glyph_pointer_3, kate_motion_semantics_glyph_pointer_4, kate_motion_semantics_text_color_rg, kate_motion_semantics_text_color_ba, kate_motion_semantics_background_color_rg, kate_motion_semantics_background_color_ba, kate_motion_semantics_draw_color_rg, kate_motion_semantics_draw_color_ba, kate_motion_semantics_style_morph, kate_motion_semantics_text_path, kate_motion_semantics_text_path_section, kate_motion_semantics_draw, kate_motion_semantics_text_visible_section, kate_motion_semantics_horizontal_margins, kate_motion_semantics_vertical_margins, kate_motion_semantics_bitmap_position, kate_motion_semantics_bitmap_size, kate_motion_semantics_marker1_bitmap, kate_motion_semantics_marker2_bitmap, kate_motion_semantics_marker3_bitmap, kate_motion_semantics_marker4_bitmap, kate_motion_semantics_glyph_pointer_1_bitmap, kate_motion_semantics_glyph_pointer_2_bitmap, kate_motion_semantics_glyph_pointer_3_bitmap, kate_motion_semantics_glyph_pointer_4_bitmap, kate_motion_semantics_draw_width, kate_motion_semantics_user = 128 }
enum	kate_text_directionality { kate_l2r_t2b, kate_r2l_t2b, kate_t2b_r2l, kate_t2b_l2r }
enum	kate_bitmap_type { kate_bitmap_type_paletted, kate_bitmap_type_png }
Functions
int	kate_get_version (void)
const char *	kate_get_version_string (void)
int	kate_get_bitstream_version (void)
const char *	kate_get_bitstream_version_string (void)
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_markup_type (kate_info *ki, kate_markup_type text_markup_type)
int	kate_info_set_category (kate_info ki, const char category)
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)
int	kate_granule_shift (const kate_info *ki)
int	kate_granule_split_time (const kate_info ki, kate_int64_t granulepos, kate_float base, kate_float *offset)
kate_float	kate_granule_time (const kate_info *ki, kate_int64_t granulepos)
kate_int64_t	kate_duration_granule (const kate_info *ki, kate_float duration)
kate_float	kate_granule_duration (const kate_info *ki, kate_int64_t duration)
int	kate_clear (kate_state *k)
int	kate_motion_get_point (const kate_motion km, kate_float duration, kate_float t, kate_float x, kate_float *y)
int	kate_curve_get_point (const kate_curve kc, kate_float t, kate_float x, kate_float *y)
int	kate_region_init (kate_region *kr)
int	kate_style_init (kate_style *ks)
int	kate_palette_init (kate_palette *kp)
int	kate_bitmap_init (kate_bitmap *kb)
int	kate_curve_init (kate_curve *kc)
int	kate_motion_init (kate_motion *km)
int	kate_text_get_character (kate_text_encoding text_encoding, const char *const text, size_t len0)
int	kate_text_set_character (kate_text_encoding text_encoding, int c, char *const text, size_t len0)
int	kate_text_remove_markup (kate_text_encoding text_encoding, char text, size_t len0)
int	kate_text_validate (kate_text_encoding text_encoding, const char *text, size_t len0)
int	kate_comment_init (kate_comment *kc)
int	kate_comment_clear (kate_comment *kc)
int	kate_comment_add (kate_comment kc, const char comment)
int	kate_comment_add_length (kate_comment kc, const char comment, size_t len)
int	kate_comment_add_tag (kate_comment kc, const char tag, const char *value)
const char *	kate_comment_query (const kate_comment kc, const char tag, int count)
int	kate_comment_query_count (const kate_comment kc, const char tag)
int	kate_encode_init (kate_state k, kate_info ki)
int	kate_encode_headers (kate_state k, kate_comment kc, kate_packet *kp)
int	kate_encode_text (kate_state k, kate_float start_time, kate_float stop_time, const char text, size_t sz, kate_packet *kp)
int	kate_encode_text_raw_times (kate_state k, kate_int64_t start_time, kate_int64_t stop_time, const char text, size_t sz, kate_packet *kp)
int	kate_encode_keepalive (kate_state k, kate_float t, kate_packet kp)
int	kate_encode_keepalive_raw_times (kate_state k, kate_int64_t t, kate_packet kp)
int	kate_encode_repeat (kate_state k, kate_float t, kate_float threshold, 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_finish (kate_state k, kate_float t, kate_packet kp)
int	kate_encode_finish_raw_times (kate_state k, kate_int64_t t, kate_packet kp)
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_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_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_font_mapping_index (kate_state *k, size_t font_mapping)
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_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_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_markup_type (kate_state *k, int markup_type)
kate_int64_t	kate_encode_get_granule (const kate_state *k)
int	kate_decode_is_idheader (const kate_packet *kp)
int	kate_decode_init (kate_state k, kate_info ki)
int	kate_decode_headerin (kate_info ki, kate_comment kc, kate_packet *kp)
int	kate_decode_packetin (kate_state k, kate_packet kp)
int	kate_decode_eventout (kate_state k, kate_const kate_event *ev)
int	kate_decode_seek (kate_state *k)
int	kate_tracker_init (kate_tracker kin, const kate_info ki, kate_const kate_event *ev)
int	kate_tracker_clear (kate_tracker *kin)
int	kate_tracker_update (kate_tracker *kin, kate_float t, int window_w, int window_h, int frame_x, int frame_y, int frame_w, int frame_h)
int	kate_tracker_morph_styles (kate_style style, kate_float t, const kate_style from, const kate_style *to)
int	kate_tracker_get_text_path_position (kate_tracker kin, size_t glyph, int x, int *y)
int	kate_tracker_update_property_at_duration (const kate_tracker kin, kate_float duration, kate_float t, kate_motion_semantics semantics, kate_float x, kate_float *y)
int	kate_tracker_remap (const kate_tracker kin, kate_motion_mapping x_mapping, kate_motion_mapping y_mapping, kate_float x, kate_float *y)
int	kate_font_get_index_from_code_point (const kate_font_mapping *kfm, int c)
int	kate_high_decode_init (kate_state *k)
int	kate_high_decode_packetin (kate_state k, kate_packet kp, kate_const kate_event **ev)
int	kate_high_decode_clear (kate_state *k)
const kate_comment *	kate_high_decode_get_comments (kate_state *k)
int	kate_packet_wrap (kate_packet kp, size_t nbytes, const void data)
int	kate_packet_init (kate_packet kp, size_t nbytes, const void data)
int	kate_packet_clear (kate_packet *kp)

Detailed Description

The libkate public API.

Define Documentation

#define KATE_BITSTREAM_VERSION_MAJOR 0

major version number of the highest bitstream version this version of libkate supports

Referenced by kate_get_bitstream_version(), and kate_get_bitstream_version_string().

#define KATE_BITSTREAM_VERSION_MINOR 5

minor version number of the highest bitstream version this version of libkate supports

Referenced by kate_get_bitstream_version_string().

#define KATE_E_BAD_GRANULE (-4)

decreasing granule

Referenced by kate_encode_keepalive_raw_times(), kate_encode_repeat_raw_times(), and kate_encode_text_raw_times().

#define KATE_E_BAD_PACKET (-6)

packet contains invalid data

#define KATE_E_BAD_TAG (-11)

a tag does not comply with the Vorbis comment rules

#define KATE_E_IMPL (-12)

the requested feature is not implemented

#define KATE_E_INIT (-5)

initializing twice, using an uninitialized state, etc

#define KATE_E_INVALID_PARAMETER (-2)

a bogus parameter was passed (usually NULL)

#define KATE_E_LIMIT (-8)

a limit was exceeded (eg, string too long, pixel value above bpp, etc)

Referenced by kate_time_granule().

#define KATE_E_NOT_FOUND (-1)

whatever was requested was not found

Referenced by kate_encode_finish_raw_times(), kate_encode_keepalive_raw_times(), and kate_encode_repeat_raw_times().

#define KATE_E_NOT_KATE (-10)

the packet is not a Kate packet

#define KATE_E_OUT_OF_MEMORY (-3)

we're running out of cheese, bring some more

#define KATE_E_TEXT (-7)

invalid/truncated character/sequence, etc

#define KATE_E_VERSION (-9)

we do not understand that bitstream version

#define KATE_VERSION_MAJOR 0

major version number of the libkate API

Referenced by kate_get_version(), and kate_get_version_string().

#define KATE_VERSION_MINOR 3

minor version number of the libkate API

Referenced by kate_get_version(), and kate_get_version_string().

#define KATE_VERSION_PATCH 7

patch version number of the libkate API

Referenced by kate_get_version(), and kate_get_version_string().

Typedef Documentation

typedef struct kate_bitmap kate_bitmap

defines a paletted image

typedef enum kate_bitmap_type kate_bitmap_type

defines a particular type of bitmap

typedef struct kate_color kate_color

defines an RGBA color

typedef struct kate_comment kate_comment

Vorbis comments - this is the same as Vorbis and Theora comments

typedef struct kate_curve kate_curve

defines a curve

typedef enum kate_curve_type kate_curve_type

defines a type of curve

typedef struct kate_event kate_event

This is an event passed to the user. A kate_tracker may be used to track animation changes to this event.

typedef struct kate_font_mapping kate_font_mapping

defines a set of ranges to define a font mapping

typedef struct kate_font_range kate_font_range

defines a set of images to map to a range of Unicode code points

typedef struct kate_info kate_info

Information about a Kate bitstream. On encoding, this information will be filled by the encoder. On decoding, it will be extracted from the stream headers.

typedef struct kate_motion kate_motion

defines a motion - well, try to find a better explanation

typedef enum kate_motion_mapping kate_motion_mapping

defines a way to transform a curve point

typedef enum kate_motion_semantics kate_motion_semantics

defines what uses a motion can have

typedef struct kate_packet kate_packet

a kate packet raw data

typedef struct kate_palette kate_palette

defines colors to correspond to a bitmap's pixels

typedef struct kate_region kate_region

defines an area where to draw

typedef struct kate_state kate_state

top level information about a Kate bitstream

typedef struct kate_style kate_style

defines a style to display text

typedef enum kate_text_directionality kate_text_directionality

defines the direction in which glyphs within a text are drawn

typedef struct kate_tracker kate_tracker

this keeps track of changes during an event's lifetime

Enumeration Type Documentation

enum kate_bitmap_type

defines a particular type of bitmap

Enumerator:

kate_bitmap_type_paletted	paletted bitmap
kate_bitmap_type_png	a PNG bitmap

enum kate_curve_type

defines a type of curve

Enumerator:

kate_curve_none	no curve
kate_curve_static	a single point
kate_curve_linear	linear interpolation of line segments
kate_curve_catmull_rom_spline	Catmull-Rom spline, goes through each point (even the first and last)
kate_curve_bezier_cubic_spline	Bezier cubic spline, goes through the first and last points, but not others
kate_curve_bspline	Cubic uniform B-spline with 3-multiplicity end knots (goes through each point)

enum kate_markup_type

defines the type of markup in a text

Enumerator:

kate_markup_none	the text should not be interpreted for markup
kate_markup_simple	the text should be interpreted for simple markup

enum kate_motion_mapping

defines a way to transform a curve point

Enumerator:

kate_motion_mapping_none	motion maps to itself
kate_motion_mapping_frame	0x0 at top left of frame, 1x1 at bottom right of frame
kate_motion_mapping_window	0x0 at top left of window, 1x1 at bottom right of window
kate_motion_mapping_region	0x0 at top left of region, 1x1 at bottom right of region
kate_motion_mapping_event_duration	0-1 map to 0 to the duration of the event (to be used with time)
kate_motion_mapping_bitmap_size	0x0 at top left of bitmap, 1x1 at bottom right of bitmap
kate_motion_mapping_user	128 to 255 for user specific mappings

enum kate_motion_semantics

defines what uses a motion can have

Enumerator:

kate_motion_semantics_time	controls the flow of time - 1D
kate_motion_semantics_z	controls the "depth" of the plane - 1D
kate_motion_semantics_region_position	controls the region position
kate_motion_semantics_region_size	controls the region size
kate_motion_semantics_text_alignment_int	controls internal text alignment
kate_motion_semantics_text_alignment_ext	controls external text alignment
kate_motion_semantics_text_position	controls the text position
kate_motion_semantics_text_size	controls the text size
kate_motion_semantics_marker1_position	controls the position of a point
kate_motion_semantics_marker2_position	controls the position of a point
kate_motion_semantics_marker3_position	controls the position of a point
kate_motion_semantics_marker4_position	controls the position of a point
kate_motion_semantics_glyph_pointer_1	controls a pointer to a particular glyph in the text
kate_motion_semantics_glyph_pointer_2	controls a pointer to a particular glyph in the text
kate_motion_semantics_glyph_pointer_3	controls a pointer to a particular glyph in the text
kate_motion_semantics_glyph_pointer_4	controls a pointer to a particular glyph in the text
kate_motion_semantics_text_color_rg	controls the red and green components of the text color
kate_motion_semantics_text_color_ba	controls the blue and alpha components of the text color
kate_motion_semantics_background_color_rg	controls the red and green components of the background color
kate_motion_semantics_background_color_ba	controls the blue and alpha components of the background color
kate_motion_semantics_draw_color_rg	controls the red and green components of the draw color
kate_motion_semantics_draw_color_ba	controls the blue and alpha components of the draw color
kate_motion_semantics_style_morph	controls morphing between style and secondary style
kate_motion_semantics_text_path	controls the path on which text is drawn
kate_motion_semantics_text_path_section	controls the section of the path on which text is drawn
kate_motion_semantics_draw	controls drawing
kate_motion_semantics_text_visible_section	controls the section of the text which is visible
kate_motion_semantics_horizontal_margins	controls the size of the left and right margins
kate_motion_semantics_vertical_margins	controls the size of the top and bottom margins
kate_motion_semantics_bitmap_position	controls the position of the background image
kate_motion_semantics_bitmap_size	controls the size of the background image
kate_motion_semantics_marker1_bitmap	controls the bitmap of the image used for marker 1
kate_motion_semantics_marker2_bitmap	controls the bitmap of the image used for marker 2
kate_motion_semantics_marker3_bitmap	controls the bitmap of the image used for marker 3
kate_motion_semantics_marker4_bitmap	controls the bitmap of the image used for marker 4
kate_motion_semantics_glyph_pointer_1_bitmap	controls the bitmap of the image used for glyph pointer 1
kate_motion_semantics_glyph_pointer_2_bitmap	controls the bitmap of the image used for glyph pointer 2
kate_motion_semantics_glyph_pointer_3_bitmap	controls the bitmap of the image used for glyph pointer 3
kate_motion_semantics_glyph_pointer_4_bitmap	controls the bitmap of the image used for glyph pointer 4
kate_motion_semantics_draw_width	controls the width of the drawn line
kate_motion_semantics_user	128 to 255 for user specific semantics

enum kate_space_metric

defines how to interpret spatial dimension values

Enumerator:

kate_pixel	dimensions are in pixels
kate_percentage	dimensions are in percentage of total size
kate_millionths	dimensions are in millionths of total size

enum kate_text_directionality

defines the direction in which glyphs within a text are drawn

Enumerator:

kate_l2r_t2b	left to right, top to bottom: eg, English
kate_r2l_t2b	right to left, top to bottom: eg, Arabic
kate_t2b_r2l	top to bottom, right to left: eg, Japanese
kate_t2b_l2r	top to bottom, left to right: eg, Sometimes Japanese

enum kate_text_encoding

defines the character encoding used by text

Enumerator:

kate_utf8

utf-8 variable length byte encoding, see RFC 3629

enum kate_wrap_mode

defines how to wrap text if necessary

Enumerator:

kate_wrap_word	allow wrapping at word boundaries
kate_wrap_none	forbid wrapping

Function Documentation

int kate_clear ( kate_state * k )

Destroys a kate_state structure. The kate_state structure should have been initialized with kate_decode_init or kate_encode_init.

Parameters:

k

the kate_state structure to clear

Returns:: 0 success; KATE_E_* error

Examples:: decoding.c, and encoding.c.

References kate_clear().

Referenced by kate_clear(), and kate_high_decode_clear().

int kate_curve_get_point	(	const kate_curve *	kc,
		kate_float	t,
		kate_float *	x,
		kate_float *	y
	)

Returns the point defined by the given curve at the given time. t will be between 0 and 1

Parameters:

	kc	the curve to get the point from
	t	the time at which the point should be taken (between 0 and motion duration)
	x	a pointer to the first coordinate of the computed point (may be NULL)
	y	a pointer to the second coordinate of the computed point (may be NULL)

Returns:: 0 success; 1 no point at this time in the curve; KATE_E_* error

References kate_curve_bezier_cubic_spline, kate_curve_bspline, kate_curve_catmull_rom_spline, kate_curve_get_point(), kate_curve_linear, kate_curve_none, kate_curve_static, kate_curve::npts, kate_curve::pts, and kate_curve::type.

Referenced by kate_curve_get_point(), and kate_motion_get_point().

int kate_motion_get_point	(	const kate_motion *	km,
		kate_float	duration,
		kate_float	t,
		kate_float *	x,
		kate_float *	y
	)

Returns the point defined by the given motion at the given time. t will be between 0 and the duration of the motion

Parameters:

	km	the motion to get the point from
	duration	the duration the motion spans
	t	the time at which the point should be taken (between 0 and motion duration)
	x	a pointer to the first coordinate of the computed point (may be NULL)
	y	a pointer to the second coordinate of the computed point (may be NULL)

Returns:: 0 success; 1 no point at this time in the motion; KATE_E_* error

References kate_motion::curves, kate_motion::durations, kate_curve_get_point(), kate_motion_get_point(), kate_motion::ncurves, and kate_motion::periodic.

Referenced by kate_motion_get_point(), kate_tracker_update(), and kate_tracker_update_property_at_duration().

/home/builduser/trunk/pkgs/libkate/BUILD/libkate-0.3.7/include/kate/kate.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation