libtheora: codec.h File Reference

libtheora 1.1.1

Data Structures | Macros
codec.h File Reference

The shared `libtheoradec` and `libtheoraenc` C API. More...

`#include <ogg/ogg.h>`

Go to the source code of this file.

## Data Structures
struct | th_img_plane
| A buffer for a single color plane in an uncompressed image. More...
struct | th_info
| Theora bitstream information. More...
struct | th_comment
| The comment information. More...
struct | th_quant_ranges
| A set of qi ranges. More...
struct | th_quant_info
| A complete set of quantization parameters. More...
struct | th_huff_code
| A Huffman code for a Theora DCT token. More...

## Macros
#define | _O_THEORA_CODEC_H_ (1)

## Functions
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.

## Return codes
#define | TH_EFAULT (-1)
| An invalid pointer was provided.
#define | TH_EINVAL (-10)
| An invalid argument was provided.
#define | TH_EBADHEADER (-20)
| The contents of the header were incomplete, invalid, or unexpected.
#define | TH_ENOTFORMAT (-21)
| The header does not belong to a Theora stream.
#define | TH_EVERSION (-22)
| The bitstream version is too high.
#define | TH_EIMPL (-23)
| The specified function is not implemented.
#define | TH_EBADPACKET (-24)
| There were errors in the video data packet.
#define | TH_DUPFRAME (1)
| The decoded packet represented a dropped frame.
#define | TH_NHUFFMAN_TABLES (80)
| The number of Huffman tables used by Theora.
#define | TH_NDCT_TOKENS (32)
| The number of DCT token values in each table.
enum | th_colorspace { TH_CS_UNSPECIFIED , TH_CS_ITU_REC_470M , TH_CS_ITU_REC_470BG , TH_CS_NSPACES }
| The currently defined color space tags. More...
enum | th_pixel_fmt { TH_PF_420 , TH_PF_RSVD , TH_PF_422 , TH_PF_444 , TH_PF_NFORMATS }
| The currently defined pixel format tags. More...
typedef th_img_plane | th_ycbcr_buffer[3]
| A complete image buffer for an uncompressed frame.
typedef struct th_comment | th_comment
| The comment information.
typedef unsigned char | th_quant_base[64]
| A single base matrix.

## Detailed Description

The shared `libtheoradec` and `libtheoraenc` C API.

You don't need to include this directly.

## Macro Definition Documentation

## ◆ _O_THEORA_CODEC_H_

#define _O_THEORA_CODEC_H_ (1)

## ◆ TH_DUPFRAME

#define TH_DUPFRAME (1)

The decoded packet represented a dropped frame.

The player can continue to display the current frame, as the contents of the decoded frame buffer have not changed.

## ◆ TH_EBADHEADER

#define TH_EBADHEADER (-20)

The contents of the header were incomplete, invalid, or unexpected.

## ◆ TH_EBADPACKET

#define TH_EBADPACKET (-24)

There were errors in the video data packet.

## ◆ TH_EFAULT

#define TH_EFAULT (-1)

An invalid pointer was provided.

## ◆ TH_EIMPL

#define TH_EIMPL (-23)

The specified function is not implemented.

## ◆ TH_EINVAL

#define TH_EINVAL (-10)

An invalid argument was provided.

## ◆ TH_ENOTFORMAT

#define TH_ENOTFORMAT (-21)

The header does not belong to a Theora stream.

## ◆ TH_EVERSION

#define TH_EVERSION (-22)

The bitstream version is too high.

## ◆ TH_NDCT_TOKENS

#define TH_NDCT_TOKENS (32)

The number of DCT token values in each table.

## ◆ TH_NHUFFMAN_TABLES

#define TH_NHUFFMAN_TABLES (80)

The number of Huffman tables used by Theora.

## Typedef Documentation

## ◆ th_comment

typedef struct th_comment th_comment

The comment information.

This structure holds the in-stream metadata corresponding to the 'comment' header packet. The comment header is meant to be used much like someone jotting a quick note on the label of a video. It should be a short, to the point text note that can be more than a couple words, but not more than a short paragraph.

The metadata is stored as a series of (tag, value) pairs, in length-encoded string vectors. The first occurrence of the '=' character delimits the tag and value. A particular tag may occur more than once, and order is significant. The character set encoding for the strings is always UTF-8, but the tag names are limited to ASCII, and treated as case-insensitive. See the Theora specification, Section 6.3.3 for details.

In filling in this structure, th_decode_headerin() will null-terminate the user_comment strings for safety. However, the bitstream format itself treats them as 8-bit clean vectors, possibly containing null characters, and so the length array should be treated as their authoritative length.

## ◆ th_quant_base

typedef unsigned char th_quant_base[64]

A single base matrix.

## ◆ th_ycbcr_buffer

typedef th_img_plane th_ycbcr_buffer[3]

A complete image buffer for an uncompressed frame.

The chroma planes may be decimated by a factor of two in either direction, as indicated by th_info::pixel_fmt. The width and height of the Y' plane must be multiples of 16. They may need to be cropped for display, using the rectangle specified by th_info::pic_x, th_info::pic_y, th_info::pic_width, and th_info::pic_height. All samples are 8 bits.

Note
  The term YUV often used to describe a colorspace is ambiguous. The exact parameters of the RGB to YUV conversion process aside, in many contexts the U and V channels actually have opposite meanings. To avoid this confusion, we are explicit: the name of the color channels are Y'CbCr, and they appear in that order, always. The prime symbol denotes that the Y channel is non-linear. Cb and Cr stand for "Chroma blue" and "Chroma red", respectively.

## Enumeration Type Documentation

## ◆ th_colorspace

enum th_colorspace

The currently defined color space tags.

See the Theora specification, Chapter 4, for exact details on the meaning of each of these color spaces.

Enumerator
TH_CS_UNSPECIFIED | The color space was not specified at the encoder. It may be conveyed by an external means.
TH_CS_ITU_REC_470M | A color space designed for NTSC content.
TH_CS_ITU_REC_470BG | A color space designed for PAL/SECAM content.
TH_CS_NSPACES | The total number of currently defined color spaces.

## ◆ th_pixel_fmt

enum th_pixel_fmt

The currently defined pixel format tags.

See the Theora specification, Section 4.4, for details on the precise sample locations.

Enumerator
TH_PF_420 | Chroma decimation by 2 in both the X and Y directions (4:2:0). The Cb and Cr chroma planes are half the width and half the height of the luma plane.
TH_PF_RSVD | Currently reserved.
TH_PF_422 | Chroma decimation by 2 in the X direction (4:2:2). The Cb and Cr chroma planes are half the width of the luma plane, but full height.
TH_PF_444 | No chroma decimation (4:4:4). The Cb and Cr chroma planes are full width and full height.
TH_PF_NFORMATS | The total number of currently defined pixel formats.

## Function Documentation

## ◆ th_comment_add()

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.

## ◆ th_comment_add_tag()

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.

## ◆ th_comment_clear()

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.

## ◆ th_comment_init()

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.

## ◆ th_comment_query()

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.

## ◆ th_comment_query_count()

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.

## ◆ th_granule_frame()

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

## ◆ th_granule_time()

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

## ◆ th_info_clear()

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.

## ◆ th_info_init()

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.

## ◆ th_packet_isheader()

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.

## ◆ th_packet_iskeyframe()

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.

## ◆ th_version_number()

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.

## ◆ th_version_string()

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

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

Returns
  the version string.