theora.h

mediastreamer2是开源的网络传输媒体流的库

/**
 * 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
 */
extern int theora_encode_comment(theora_comment *tc, 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
 */
extern int theora_encode_tables(theora_state *t, 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.
 */
extern int theora_decode_header(theora_info *ci, theora_comment *cc,
                                ogg_packet *op);

/**
 * 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
 */
extern int theora_decode_init(theora_state *th, theora_info *c);

/**
 * 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
 */
extern int theora_decode_packetin(theora_state *th,ogg_packet *op);

/**
 * 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
 */
extern int theora_decode_YUVout(theora_state *th,yuv_buffer *yuv);

/**
 * 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.
 */
extern int theora_packet_isheader(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.
 */
extern int theora_packet_iskeyframe(ogg_packet *op);

/**
 * 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.
 */
int theora_granule_shift(theora_info *ti);

/**
 * 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.
 */
extern ogg_int64_t theora_granule_frame(theora_state *th,ogg_int64_t 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.
 */
extern double theora_granule_time(theora_state *th,ogg_int64_t granulepos);

/**
 * 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.
 */
extern void theora_info_init(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.
 */
extern void theora_info_clear(theora_info *c);

/**
 * Free all internal data associated with a theora_state handle.
 * \param t A theora_state handle.
 */
extern void theora_clear(theora_state *t);

/**
 * Initialize an allocated theora_comment structure
 * \param tc An allocated theora_comment structure 
 **/
extern void theora_comment_init(theora_comment *tc);

/**
 * 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.
 **/

extern void theora_comment_add(theora_comment *tc, char *comment);

/**
 * 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.
 **/
extern void theora_comment_add_tag(theora_comment *tc,
                                       char *tag, char *value);

/**
 * 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.
 **/

extern char *theora_comment_query(theora_comment *tc, char *tag, int count);

/** 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.
 **/
extern int   theora_comment_query_count(theora_comment *tc, char *tag);

/**
 * Clear an allocated theora_comment struct so that it can be freed.
 * \param tc An allocated theora_comment structure.
 **/
extern void  theora_comment_clear(theora_comment *tc);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* _O_THEORA_H_ */