libkate: Encoding

# 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
  | 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
  | 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
  | 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
  | km | the motion to add
  | 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
  | 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
  | t | the timestamp for the end (if negative, the end time of the last event will be used)
  | 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
  | t | the timestamp (in granule rate units) for the end (if negative, the end time of the last event will be used)
  | 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
  | kc | the list of comments to add to the headers
  | 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
  | 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
  | t | the timestamp for the keepalive packet
  | 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
  | t | the timestamp (in granule rate units) for the keepalive packet
  | 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
  | 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
  | t | the timestamp for the the packets, if any
  | threshold | the time threshold at which to emit a repeat packets (zero to force a repeat)
  | 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
  | t | the timestamp (in granule rate units) for the the packets, if any
  | threshold | the time threshold (in granule rate units) at which to emit a repeat packets (zero to force a repeat)
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | 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
  | t0 | the start time in seconds of the text
  | t1 | the end time in seconds of the text
  | text | the text to add (may be NULL)
  | sz | the length in bytes of the text to add
  | 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
  | t0 | the start time in granule units of the text
  | t1 | the end time in granule units of the text
  | text | the text to add (may be NULL)
  | sz | the length in bytes of the text to add
  | 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().