libtheora  1.1.1
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.

Detailed Description

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
_tcThe th_comment struct to add the comment to.
_commentMust 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
_tcThe th_comment struct to add the comment to.
_tagA null-terminated string containing the tag associated with the comment.
_valThe 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
_tcThe 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
_tcThe 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
_tcAn initialized th_comment structure.
_tagThe tag to look up.
_countThe 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
NULLIf 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
_tcAn initialized th_comment structure.
_tagThe 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
_encdecA previously allocated th_enc_ctx or th_dec_ctx handle.
_granposThe granule position to convert.
Returns
The absolute frame index corresponding to _granpos.
Return values
-1The 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
_encdecA previously allocated th_enc_ctx or th_dec_ctx handle.
_granposThe 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
-1The 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
_infoThe 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
_infoThe 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
_opAn ogg_packet containing encoded Theora data.
Return values
1The packet is a header packet
0The 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
_opAn ogg_packet containing encoded Theora data.
Return values
1The packet contains a key frame.
0The packet contains a delta frame.
-1The 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.