net.sf.theora_java.jna
Interface TheoraLibrary

All Superinterfaces:

com.sun.jna.Library, XiphLibrary

public interface TheoraLibrary
extends XiphLibrary

Based on libtheora-1.0alpha7 theora.h

Author:

Ken Larson

Nested Class Summary

static class	TheoraLibrary.theora_comment Comment header metadata.
static class	TheoraLibrary.theora_info Theora bitstream info.
static class	TheoraLibrary.theora_state Codec internal state and context.
static class	TheoraLibrary.yuv_buffer A YUV buffer for passing uncompressed frames to and from the codec.

Nested classes/interfaces inherited from interface net.sf.theora_java.jna.XiphLibrary

XiphLibrary.ogg_packet

Nested classes/interfaces inherited from interface com.sun.jna.Library

com.sun.jna.Library.Handler

Field Summary

static TheoraLibrary	INSTANCE
static int	OC_BADHEADER < Requested action is disabled
static int	OC_BADPACKET < Feature or action not implemented
static int	OC_CS_ITU_REC_470BG < This is the best option for 'NTSC' content
static int	OC_CS_ITU_REC_470M < The colorspace is unknown or unspecified
static int	OC_CS_NSPACES < This is the best option for 'PAL' content
static int	OC_CS_UNSPECIFIED A Colorspace.
static int	OC_DISABLED < Library encountered invalid internal data
static int	OC_DUPFRAME < Packet is an (ignorable) unhandled extension
static int	OC_EINVAL < General failure
static int	OC_FAULT
static int	OC_IMPL < Bitstream version is not handled
static int	OC_NEWPACKET < Packet is corrupt
static int	OC_NOTFORMAT < Header packet was corrupt/invalid
static int	OC_PF_420 A Chroma subsampling These enumerate the available chroma subsampling options supported by the theora format.
static int	OC_PF_422 < Reserved value
static int	OC_PF_444 < Horizonatal chroma subsampling by 2 (4:2:2)
static int	OC_PF_RSVD < Chroma subsampling by 2 in each direction (4:2:0)
static int	OC_VERSION < Packet is not a theora packet

Fields inherited from interface com.sun.jna.Library

OPTION_FUNCTION_MAPPER, OPTION_STRUCTURE_ALIGNMENT, OPTION_TYPE_MAPPER

Method Summary

void	theora_clear(TheoraLibrary.theora_state t) Free all internal data associated with a theora_state handle.
void	theora_comment_add_tag(TheoraLibrary.theora_comment tc, com.sun.jna.Pointer tag, com.sun.jna.Pointer value) Add a comment to an initialized theora_comment structure.
void	theora_comment_add(TheoraLibrary.theora_comment tc, com.sun.jna.Pointer comment) Add a comment to an initialized theora_comment structure \param tc A previously initialized theora comment structure \param comment A null-terminated string encoding the comment in the form "TAG=the value" Neither theora_comment_add() nor theora_comment_add_tag() support comments containing null values, although the bitstream format supports this.
void	theora_comment_clear(TheoraLibrary.theora_comment tc) Clear an allocated theora_comment struct so that it can be freed.
void	theora_comment_init(TheoraLibrary.theora_comment tc) Initialize an allocated theora_comment structure \param tc An allocated theora_comment structure
int	theora_comment_query_count(TheoraLibrary.theora_comment tc, com.sun.jna.Pointer tag) Look up the number of instances of a tag.
com.sun.jna.Pointer	theora_comment_query(TheoraLibrary.theora_comment tc, com.sun.jna.Pointer tag, int count) Look up a comment value by tag.
int	theora_decode_header(TheoraLibrary.theora_info ci, TheoraLibrary.theora_comment cc, XiphLibrary.ogg_packet op) Decode an Ogg packet, with the expectation that the packet contains an initial header, comment data or codebook tables.
int	theora_decode_init(TheoraLibrary.theora_state th, TheoraLibrary.theora_info c) Initialize a theora_state handle for decoding.
int	theora_decode_packetin(TheoraLibrary.theora_state th, XiphLibrary.ogg_packet op) Input a packet containing encoded data into the theora decoder.
int	theora_decode_YUVout(TheoraLibrary.theora_state th, TheoraLibrary.yuv_buffer yuv) Output the next available frame of decoded YUV data.
int	theora_encode_comment(TheoraLibrary.theora_comment tc, XiphLibrary.ogg_packet op) Request a comment header packet from provided metadata.
int	theora_encode_header(TheoraLibrary.theora_state t, XiphLibrary.ogg_packet op) Request a packet containing the initial header.
int	theora_encode_init(TheoraLibrary.theora_state th, TheoraLibrary.theora_info ti) Initialize the theora encoder.
int	theora_encode_packetout(TheoraLibrary.theora_state t, int last_p, XiphLibrary.ogg_packet op) Request the next packet of encoded video.
int	theora_encode_tables(TheoraLibrary.theora_state t, XiphLibrary.ogg_packet op) Request a packet containing the codebook tables for the stream.
int	theora_encode_YUVin(TheoraLibrary.theora_state t, TheoraLibrary.yuv_buffer yuv) Submit a YUV buffer to the theora encoder.
long	theora_granule_frame(TheoraLibrary.theora_state th, long granulepos) Convert a granulepos to an absolute frame number.
int	theora_granule_shift(TheoraLibrary.theora_info ti) Report the granulepos shift radix When embedded in Ogg, Theora uses a two-part granulepos, splitting the 64-bit field into two pieces.
double	theora_granule_time(TheoraLibrary.theora_state th, long granulepos) Convert a granulepos to absolute time in seconds.
void	theora_info_clear(TheoraLibrary.theora_info c) Clear a theora_info structure.
void	theora_info_init(TheoraLibrary.theora_info c) Initialize a theora_info structure.
int	theora_packet_isheader(XiphLibrary.ogg_packet op) Report whether a theora packet is a header or not This function does no verification beyond checking the header flag bit so it should not be used for bitstream identification; use theora_decode_header() for that.
int	theora_packet_iskeyframe(XiphLibrary.ogg_packet op) Report whether a theora packet is a keyframe or not \param op An ogg_packet containing encoded theora data.
int	theora_version_number() Retrieve a 32-bit version number.
java.lang.String	theora_version_string() Retrieve a human-readable string to identify the encoder vendor and version.

Field Detail

INSTANCE

static final TheoraLibrary INSTANCE

OC_CS_UNSPECIFIED

static final int OC_CS_UNSPECIFIED

A Colorspace.

See Also:

Constant Field Values

OC_CS_ITU_REC_470M

static final int OC_CS_ITU_REC_470M

< The colorspace is unknown or unspecified

See Also:

Constant Field Values

OC_CS_ITU_REC_470BG

static final int OC_CS_ITU_REC_470BG

< This is the best option for 'NTSC' content

See Also:

Constant Field Values

OC_CS_NSPACES

static final int OC_CS_NSPACES

< This is the best option for 'PAL' content

See Also:

Constant Field Values

OC_PF_420

static final int OC_PF_420

A Chroma subsampling These enumerate the available chroma subsampling options supported by the theora format. See Section 4.4 of the specification for exact definitions.

See Also:

Constant Field Values

OC_PF_RSVD

static final int OC_PF_RSVD

< Chroma subsampling by 2 in each direction (4:2:0)

See Also:

Constant Field Values

OC_PF_422

static final int OC_PF_422

< Reserved value

See Also:

Constant Field Values

OC_PF_444

static final int OC_PF_444

< Horizonatal chroma subsampling by 2 (4:2:2)

See Also:

Constant Field Values

OC_FAULT

static final int OC_FAULT

See Also:

Constant Field Values

OC_EINVAL

static final int OC_EINVAL

< General failure

See Also:

Constant Field Values

OC_DISABLED

static final int OC_DISABLED

< Library encountered invalid internal data

See Also:

Constant Field Values

OC_BADHEADER

static final int OC_BADHEADER

< Requested action is disabled

See Also:

Constant Field Values

OC_NOTFORMAT

static final int OC_NOTFORMAT

< Header packet was corrupt/invalid

See Also:

Constant Field Values

OC_VERSION

static final int OC_VERSION

< Packet is not a theora packet

See Also:

Constant Field Values

OC_IMPL

static final int OC_IMPL

< Bitstream version is not handled

See Also:

Constant Field Values

OC_BADPACKET

static final int OC_BADPACKET

< Feature or action not implemented

See Also:

Constant Field Values

OC_NEWPACKET

static final int OC_NEWPACKET

< Packet is corrupt

See Also:

Constant Field Values

OC_DUPFRAME

static final int OC_DUPFRAME

< Packet is an (ignorable) unhandled extension

See Also:

Constant Field Values

Method Detail

theora_version_string

java.lang.String theora_version_string()

Retrieve a human-readable string to identify the encoder vendor and version. \returns A version string.

theora_version_number

int theora_version_number()

Retrieve a 32-bit version number. 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_SUB)
        

\returns The version number.

theora_encode_init

int theora_encode_init(TheoraLibrary.theora_state th,
                       TheoraLibrary.theora_info ti)

Initialize the theora encoder. \param th The theora_state handle to initialize for encoding. \param ti A theora_info struct filled with the desired encoding parameters. \retval 0 Success

theora_encode_YUVin

int theora_encode_YUVin(TheoraLibrary.theora_state t,
                        TheoraLibrary.yuv_buffer yuv)

Submit a YUV buffer to the theora encoder. \param t A theora_state handle previously initialized for encoding. \param yuv A buffer of YUV data to encode. \retval OC_EINVAL Encoder is not ready, or is finished. \retval -1 The size of the given frame differs from those previously input \retval 0 Success

theora_encode_packetout

int theora_encode_packetout(TheoraLibrary.theora_state t,
                            int last_p,
                            XiphLibrary.ogg_packet op)

Request the next packet of encoded video. The encoded data is placed in a user-provided ogg_packet structure. \param t A theora_state handle previously initialized for encoding. \param last_p whether this is the last packet the encoder should produce. \param op An ogg_packet structure to fill. libtheora will set all elements of this structure, including a pointer to encoded data. The memory for the encoded data is owned by libtheora. \retval 0 No internal storage exists OR no packet is ready \retval -1 The encoding process has completed \retval 1 Success

theora_encode_header

int theora_encode_header(TheoraLibrary.theora_state t,
                         XiphLibrary.ogg_packet op)

Request a packet containing the initial header. A pointer to the header data is placed in a user-provided ogg_packet structure. \param t A theora_state handle previously initialized for encoding. \param op An ogg_packet structure to fill. libtheora will set all elements of this structure, including a pointer to the header data. The memory for the header data is owned by libtheora. \retval 0 Success

theora_encode_comment

int theora_encode_comment(TheoraLibrary.theora_comment tc,
                          XiphLibrary.ogg_packet op)

Request a comment header packet from provided metadata. A pointer to the comment data is placed in a user-provided ogg_packet structure. \param tc A theora_comment structure filled with the desired metadata \param op An ogg_packet structure to fill. libtheora will set all elements of this structure, including a pointer to the encoded comment data. The memory for the comment data is owned by libtheora. \retval 0 Success

theora_encode_tables

int theora_encode_tables(TheoraLibrary.theora_state t,
                         XiphLibrary.ogg_packet op)

Request a packet containing the codebook tables for the stream. A pointer to the codebook data is placed in a user-provided ogg_packet structure. \param t A theora_state handle previously initialized for encoding. \param op An ogg_packet structure to fill. libtheora will set all elements of this structure, including a pointer to the codebook data. The memory for the header data is owned by libtheora. \retval 0 Success

theora_decode_header

int theora_decode_header(TheoraLibrary.theora_info ci,
                         TheoraLibrary.theora_comment cc,
                         XiphLibrary.ogg_packet op)

Decode an Ogg packet, with the expectation that the packet contains an initial header, comment data or codebook tables. \param ci A theora_info structure to fill. This must have been previously initialized with theora_info_init(). If \a op contains an initial header, theora_decode_header() will fill \a ci with the parsed header values. If \a op contains codebook tables, theora_decode_header() will parse these and attach an internal representation to \a ci->codec_setup. \param cc A theora_comment structure to fill. If \a op contains comment data, theora_decode_header() will fill \a cc with the parsed comments. \param op An ogg_packet structure which you expect contains an initial header, comment data or codebook tables. \retval OC_BADHEADER \a op is NULL; OR the first byte of \a op->packet has the signature of an initial packet, but op is not a b_o_s packet; OR this packet has the signature of an initial header packet, but an initial header packet has already been seen; OR this packet has the signature of a comment packet, but the initial header has not yet been seen; OR this packet has the signature of a comment packet, but contains invalid data; OR this packet has the signature of codebook tables, but the initial header or comments have not yet been seen; OR this packet has the signature of codebook tables, but contains invalid data; OR the stream being decoded has a compatible version but this packet does not have the signature of a theora initial header, comments, or codebook packet \retval OC_VERSION The packet data of \a op is an initial header with a version which is incompatible with this version of libtheora. \retval OC_NEWPACKET the stream being decoded has an incompatible (future) version and contains an unknown signature. \retval 0 Success \note The normal usage is that theora_decode_header() be called on the first three packets of a theora logical bitstream in succession.

theora_decode_init

int theora_decode_init(TheoraLibrary.theora_state th,
                       TheoraLibrary.theora_info c)

Initialize a theora_state handle for decoding. \param th The theora_state handle to initialize. \param c A theora_info struct filled with the desired decoding parameters. This is of course usually obtained from a previous call to theora_decode_header(). \retval 0 Success

theora_decode_packetin

int theora_decode_packetin(TheoraLibrary.theora_state th,
                           XiphLibrary.ogg_packet op)

Input a packet containing encoded data into the theora decoder. \param th A theora_state handle previously initialized for decoding. \param op An ogg_packet containing encoded theora data. \retval 0 Success \retval OC_BADPACKET \a op does not contain encoded video data

theora_decode_YUVout

int theora_decode_YUVout(TheoraLibrary.theora_state th,
                         TheoraLibrary.yuv_buffer yuv)

Output the next available frame of decoded YUV data. \param th A theora_state handle previously initialized for decoding. \param yuv A yuv_buffer in which libtheora should place the decoded data. \retval 0 Success

theora_packet_isheader

int theora_packet_isheader(XiphLibrary.ogg_packet op)

Report whether a theora packet is a header or not This function does no verification beyond checking the header flag bit so it should not be used for bitstream identification; use theora_decode_header() for that. \param op An ogg_packet containing encoded theora data. \retval 1 The packet is a header packet \retval 0 The packet is not a header packet (and so contains frame data) Thus function was added in the 1.0alpha4 release.

theora_packet_iskeyframe

int theora_packet_iskeyframe(XiphLibrary.ogg_packet op)

Report whether a theora packet is a keyframe or not \param op An ogg_packet containing encoded theora data. \retval 1 The packet contains a keyframe image \retval 0 The packet is contains an interframe delta \retval -1 The packet is not an image data packet at all Thus function was added in the 1.0alpha4 release.

theora_granule_shift

int theora_granule_shift(TheoraLibrary.theora_info ti)

Report the granulepos shift radix When embedded in Ogg, Theora uses a two-part granulepos, splitting the 64-bit field into two pieces. The more-significant section represents the frame count at the last keyframe, and the less-significant section represents the count of frames since the last keyframe. In this way the overall field is still non-decreasing with time, but usefully encodes a pointer to the last keyframe, which is necessary for correctly restarting decode after a seek. This function reports the number of bits used to represent the distance to the last keyframe, and thus how the granulepos field must be shifted or masked to obtain the two parts. Since libtheora returns compressed data in an ogg_packet structure, this may be generally useful even if the Theora packets are not being used in an Ogg container. \param ti A previously initialized theora_info struct \returns The bit shift dividing the two granulepos fields This function was added in the 1.0alpha5 release.

theora_granule_frame

long theora_granule_frame(TheoraLibrary.theora_state th,
                          long granulepos)

Convert a granulepos to an absolute frame number. The granulepos is interpreted in the context of a given theora_state handle. \param th A previously initialized theora_state handle (encode or decode) \param granulepos The granulepos to convert. \returns The frame number corresponding to \a granulepos. \retval -1 The given granulepos is undefined (i.e. negative) Thus function was added in the 1.0alpha4 release.

theora_granule_time

double theora_granule_time(TheoraLibrary.theora_state th,
                           long granulepos)

Convert a granulepos to absolute time in seconds. The granulepos is interpreted in the context of a given theora_state handle. \param th A previously initialized theora_state handle (encode or decode) \param granulepos The granulepos to convert. \returns The absolute time in seconds corresponding to \a granulepos. \retval -1. The given granulepos is undefined (i.e. negative), or \retval -1. The function has been disabled because floating point support is not available.

theora_info_init

void theora_info_init(TheoraLibrary.theora_info c)

Initialize a theora_info structure. All values within the given theora_info structure are initialized, and space is allocated within libtheora for internal codec setup data. \param c A theora_info struct to initialize.

theora_info_clear

void theora_info_clear(TheoraLibrary.theora_info c)

Clear a theora_info structure. All values within the given theora_info structure are cleared, and associated internal codec setup data is freed. \param c A theora_info struct to initialize.

theora_clear

void theora_clear(TheoraLibrary.theora_state t)

Free all internal data associated with a theora_state handle. \param t A theora_state handle.

theora_comment_init

void theora_comment_init(TheoraLibrary.theora_comment tc)

Initialize an allocated theora_comment structure \param tc An allocated theora_comment structure

theora_comment_add

void theora_comment_add(TheoraLibrary.theora_comment tc,
                        com.sun.jna.Pointer comment)

Add a comment to an initialized theora_comment structure \param tc A previously initialized theora comment structure \param comment A null-terminated string encoding the comment in the form "TAG=the value" Neither theora_comment_add() nor theora_comment_add_tag() support comments containing null values, although the bitstream format supports this. To add such comments you will need to manipulate the theora_comment structure directly.

theora_comment_add_tag

void theora_comment_add_tag(TheoraLibrary.theora_comment tc,
                            com.sun.jna.Pointer tag,
                            com.sun.jna.Pointer value)

Add a comment to an initialized theora_comment structure. \param tc A previously initialized theora comment structure \param tag A null-terminated string containing the tag associated with the comment. \param value The corresponding value as a null-terminated string Neither theora_comment_add() nor theora_comment_add_tag() support comments containing null values, although the bitstream format supports this. To add such comments you will need to manipulate the theora_comment structure directly.

theora_comment_query

com.sun.jna.Pointer theora_comment_query(TheoraLibrary.theora_comment tc,
                                         com.sun.jna.Pointer tag,
                                         int count)

Look up a comment value by tag. \param tc Tn initialized theora_comment structure \param tag The tag to look up \param count The instance of the tag. The same tag can appear multiple times, each with a distinct and ordered value, so an index is required to retrieve them all. \returns A pointer to the queried tag's value \retval NULL No matching tag is found \note Use theora_comment_query_count() to get the legal range for the count parameter.

theora_comment_query_count

int theora_comment_query_count(TheoraLibrary.theora_comment tc,
                               com.sun.jna.Pointer tag)

Look up the number of instances of a tag. \param tc An initialized theora_comment structure \param tag The tag to look up \returns The number on instances of a particular tag. Call this first when querying for a specific tag and then interate over the number of instances with separate calls to theora_comment_query() to retrieve all instances in order.

theora_comment_clear

void theora_comment_clear(TheoraLibrary.theora_comment tc)

Clear an allocated theora_comment struct so that it can be freed. \param tc An allocated theora_comment structure.