# Functions Shared by Encode and Decode

## Basic shared functions

const char * | th_version_string (void)
| Retrieves a human-readable string to identify the library vendor and version.
ogg_uint32_t | th_version_number (void)
| Retrieves the library version number.
ogg_int64_t | th_granule_frame (void *_encdec, ogg_int64_t _granpos)
| Converts a granule position to an absolute frame index, starting at `0`.
double | th_granule_time (void *_encdec, ogg_int64_t _granpos)
| Converts a granule position to an absolute time in seconds.
int | th_packet_isheader (ogg_packet *_op)
| Determines whether a Theora packet is a header or not.
int | th_packet_iskeyframe (ogg_packet *_op)
| Determines whether a theora packet is a key frame or not.

## Functions for manipulating header data

void | th_info_init (th_info *_info)
| Initializes a th_info structure.
void | th_info_clear (th_info *_info)
| Clears a th_info structure.
void | th_comment_init (th_comment *_tc)
| Initialize a th_comment structure.
void | th_comment_add (th_comment *_tc, char *_comment)
| Add a comment to an initialized th_comment structure.
void | th_comment_add_tag (th_comment *_tc, char *_tag, char *_val)
| Add a comment to an initialized th_comment structure.
char * | th_comment_query (th_comment *_tc, char *_tag, int _count)
| Look up a comment value by its tag.
int | th_comment_query_count (th_comment *_tc, char *_tag)
| Look up the number of instances of a tag.
void | th_comment_clear (th_comment *_tc)
| Clears a th_comment structure.

## Function Documentation

void th_comment_add | ( | th_comment * | _tc,
|  | char * | _comment |
| ) |  |  |

Add a comment to an initialized th_comment structure.

Note:
  Neither th_comment_add() nor th_comment_add_tag() support comments containing null values, although the bitstream format does support them. To add such comments you will need to manipulate the th_comment structure directly.

Parameters:

  | _tc | The th_comment struct to add the comment to.
  | _comment | Must be a null-terminated UTF-8 string containing the comment in "TAG=the value" form.

void th_comment_add_tag | ( | th_comment * | _tc,
|  | char * | _tag,
|  | char * | _val |
| ) |  |  |

Add a comment to an initialized th_comment structure.

Note:
  Neither th_comment_add() nor th_comment_add_tag() support comments containing null values, although the bitstream format does support them. To add such comments you will need to manipulate the th_comment structure directly.

Parameters:

  | _tc | The th_comment struct to add the comment to.
  | _tag | A null-terminated string containing the tag associated with the comment.
  | _val | The corresponding value as a null-terminated string.

void th_comment_clear | ( | th_comment * | _tc | ) |

Clears a th_comment structure.

This should be called on a th_comment structure after it is no longer needed. It will free all memory used by the structure members.

Parameters:

  | _tc | The th_comment struct to clear.

void th_comment_init | ( | th_comment * | _tc | ) |

Initialize a th_comment structure.

This should be called on a freshly allocated th_comment structure before attempting to use it.

Parameters:

  | _tc | The th_comment struct to initialize.

char* th_comment_query | ( | th_comment * | _tc,
|  | char * | _tag,
|  | int | _count |
| ) |  |  |

Look up a comment value by its tag.

Parameters:

  | _tc | An initialized th_comment structure.
  | _tag | The tag to look up.
  | _count | The instance of the tag. The same tag can appear multiple times, each with a distinct value, so an index is required to retrieve them all. The order in which these values appear is significant and should be preserved. Use th_comment_query_count() to get the legal range for the _count parameter.

Returns:
  A pointer to the queried tag's value. This points directly to data in the th_comment structure. It should not be modified or freed by the application, and modifications to the structure may invalidate the pointer.

Return values:

  | NULL | If no matching tag is found.

int th_comment_query_count | ( | th_comment * | _tc,
|  | char * | _tag |
| ) |  |  |

Look up the number of instances of a tag.

Call this first when querying for a specific tag and then iterate over the number of instances with separate calls to th_comment_query() to retrieve all the values for that tag in order.

Parameters:

  | _tc | An initialized th_comment structure.
  | _tag | The tag to look up.

Returns:
  The number on instances of this particular tag.

ogg_int64_t th_granule_frame | ( | void * | _encdec,
|  | ogg_int64_t | _granpos |
| ) |  |  |

Converts a granule position to an absolute frame index, starting at `0`.

The granule position is interpreted in the context of a given th_enc_ctx or th_dec_ctx handle (either will suffice).

Parameters:

  | _encdec | A previously allocated th_enc_ctx or th_dec_ctx handle.
  | _granpos | The granule position to convert.

Returns:
  The absolute frame index corresponding to _granpos.

Return values:

  | -1 | The given granule position was invalid (i.e. negative).

double th_granule_time | ( | void * | _encdec,
|  | ogg_int64_t | _granpos |
| ) |  |  |

Converts a granule position to an absolute time in seconds.

The granule position is interpreted in the context of a given th_enc_ctx or th_dec_ctx handle (either will suffice).

Parameters:

  | _encdec | A previously allocated th_enc_ctx or th_dec_ctx handle.
  | _granpos | The granule position to convert.

Returns:
  The absolute time in seconds corresponding to _granpos. This is the "end time" for the frame, or the latest time it should be displayed. It is not the presentation time.

Return values:

  | -1 | The given granule position was invalid (i.e. negative).

void th_info_clear | ( | th_info * | _info | ) |

Clears a th_info structure.

This should be called on a th_info structure after it is no longer needed.

Parameters:

  | _info | The th_info struct to clear.

void th_info_init | ( | th_info * | _info | ) |

Initializes a th_info structure.

This should be called on a freshly allocated th_info structure before attempting to use it.

Parameters:

  | _info | The th_info struct to initialize.

int th_packet_isheader | ( | ogg_packet * | _op | ) |

Determines whether a Theora packet is a header or not.

This function does no verification beyond checking the packet type bit, so it should not be used for bitstream identification; use th_decode_headerin() for that. As per the Theora specification, an empty (0-byte) packet is treated as a data packet (a delta frame with no coded blocks).

Parameters:

  | _op | An `ogg_packet` containing encoded Theora data.

Return values:

  | 1 | The packet is a header packet
  | 0 | The packet is a video data packet.

int th_packet_iskeyframe | ( | ogg_packet * | _op | ) |

Determines whether a theora packet is a key frame or not.

This function does no verification beyond checking the packet type and key frame bits, so it should not be used for bitstream identification; use th_decode_headerin() for that. As per the Theora specification, an empty (0-byte) packet is treated as a delta frame (with no coded blocks).

Parameters:

  | _op | An `ogg_packet` containing encoded Theora data.

Return values:

  | 1 | The packet contains a key frame.
  | 0 | The packet contains a delta frame.
  | -1 | The packet is not a video data packet.

ogg_uint32_t th_version_number | ( | void |  | ) |

Retrieves the library version number.

This is the highest bitstream version that the encoder library will produce, or that the decoder library can decode. This number is composed of a 16-bit major version, 8-bit minor version and 8 bit sub-version, composed as follows:

     (VERSION_MAJOR<<16)+(VERSION_MINOR<<8)+(VERSION_SUBMINOR)

Returns:
  the version number.

const char* th_version_string | ( | void |  | ) |

Retrieves a human-readable string to identify the library vendor and version.

Returns:
  the version string.