libkate: kate_info access

# 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

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.

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.

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.

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.

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.

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.

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.

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.

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_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().

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::no_limits, 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::probe, kate_info::regions, kate_info::remove_markup, kate_info::styles, kate_info::text_directionality, kate_info::text_encoding, and kate_info::text_markup_type.

Referenced by kate_high_decode_init().

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.

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, and kate_info::no_limits.

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, and kate_info::remove_markup.

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.

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.

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.

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.

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.

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.