A Huffman code for a Theora DCT token.
Each set of Huffman codes in a given table must form a complete, prefix-free
code.
There is no requirement that all the tokens in a table have a valid code,
but the current encoder is not optimized to take advantage of this.
If each of the five grouops of 16 tables does not contain at least one table
with a code for every token, then the encoder may fail to encode certain
frames.
The complete table in the first group of 16 does not have to be in the same
place as the complete table in the other groups, but the complete tables in
the remaining four groups must all be in the same place.
A buffer for a single color plane in an uncompressed image.
This contains the image data in a left-to-right, top-down format.
Each row of pixels is stored contiguously in memory, but successive
rows need not be.
Use \a stride to compute the offset of the next row.
The encoder accepts both positive \a stride values (top-down in memory)
and negative (bottom-up in memory).
The decoder currently always generates images with positive strides.
Theora bitstream information.
This contains the basic playback parameters for a stream, and corresponds to
the initial ‘info’ header packet.
To initialize an encoder, the application fills in this structure and
passes it to th_encode_alloc().
A default encoding mode is chosen based on the values of the #quality and
#target_bitrate fields.
On decode, it is filled in by th_decode_headerin(), and then passed to
th_decode_alloc().
A complete set of quantization parameters.
The quantizer for each coefficient is calculated as:
\code
Q=MAX(MIN(qmin[qti][ci!=0],scale[ci!=0][qi]*base[qti][pli][qi][ci]/100),
1024).
\endcode
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.
\param _tc The #th_comment struct to add the comment to.
\param _comment Must be a null-terminated UTF-8 string containing the
comment in “TAG=the value” form.
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.
\param _tc The #th_comment struct to add the comment to.
\param _tag A null-terminated string containing the tag associated with
the comment.
\param _val The corresponding value as a null-terminated string.
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.
\param _tc The #th_comment struct to clear.
Initialize a #th_comment structure.
This should be called on a freshly allocated #th_comment structure
before attempting to use it.
\param _tc The #th_comment struct to initialize.
Look up a comment value by its tag.
\param _tc An initialized #th_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
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 \a _count parameter.
\return 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.
\retval NULL If no matching tag is found.
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.
\param _tc An initialized #th_comment structure.
\param _tag The tag to look up.
\return The number of instances of this particular tag.
Decoder control function.
This is used to provide advanced control of the decoding process.
\param _dec A #th_dec_ctx handle.
\param _req The control code to process.
See \ref decctlcodes “the list of available control codes”
for details.
\param _buf The parameters for this control code.
\param _buf_sz The size of the parameter buffer.
\return Possible return values depend on the control code used.
See \ref decctlcodes “the list of control codes” for
specific values. Generally 0 indicates success.
Decodes the header packets of a Theora stream.
This should be called on the initial packets of the stream, in succession,
until it returns 0, indicating that all headers have been
processed, or an error is encountered.
At least three header packets are required, and additional optional header
packets may follow.
This can be used on the first packet of any logical stream to determine if
that stream is a Theora stream.
\param _info A #th_info structure to fill in.
This must have been previously initialized with
th_info_init().
The application may immediately begin using the contents of
this structure after the first header is decoded, though it
must continue to be passed in on all subsequent calls.
\param _tc A #th_comment structure to fill in.
The application may immediately begin using the contents of
this structure after the second header is decoded, though it
must continue to be passed in on all subsequent calls.
\param _setup Returns a pointer to additional, private setup information
needed by the decoder.
The contents of this pointer must be initialized to
NULL on the first call, and the returned value must
continue to be passed in on all subsequent calls.
\param _op An ogg_packet structure which contains one of the
initial packets of an Ogg logical stream.
\return A positive value indicates that a Theora header was successfully
processed.
\retval 0 The first video data packet was encountered after all
required header packets were parsed.
The packet just passed in on this call should be saved
and fed to th_decode_packetin() to begin decoding
video data.
\retval TH_EFAULT One of \a _info, \a _tc, or \a _setup was
NULL.
\retval TH_EBADHEADER \a _op was NULL, the packet was not the next
header packet in the expected sequence, or the format
of the header data was invalid.
\retval TH_EVERSION The packet data was a Theora info header, but for a
bitstream version not decodable with this version of
libtheoradec.
\retval TH_ENOTFORMAT The packet was not a Theora header.
Submits a packet containing encoded video data to the decoder.
\param _dec A #th_dec_ctx handle.
\param _op An ogg_packet containing encoded video data.
\param _granpos Returns the granule position of the decoded packet.
If non-NULL, the granule position for this specific
packet is stored in this location.
This is computed incrementally from previously decoded
packets.
After a seek, the correct granule position must be set via
#TH_DECCTL_SET_GRANPOS for this to work properly.
\retval 0 Success.
A new decoded frame can be retrieved by calling
th_decode_ycbcr_out().
\retval TH_DUPFRAME The packet represented a dropped frame (either a
0-byte frame or an INTER frame with no coded blocks).
The player can skip the call to th_decode_ycbcr_out(),
as the contents of the decoded frame buffer have not
changed.
\retval TH_EFAULT \a _dec or \a _op was NULL.
\retval TH_EBADPACKET \a _op does not contain encoded video data.
\retval TH_EIMPL The video data uses bitstream features which this
library does not support.
Outputs the next available frame of decoded Y’CbCr data.
If a striped decode callback has been set with #TH_DECCTL_SET_STRIPE_CB,
then the application does not need to call this function.
\param _dec A #th_dec_ctx handle.
\param _ycbcr A video buffer structure to fill in.
libtheoradec will fill in all the members of this
structure, including the pointers to the uncompressed video
data.
The memory for this video data is owned by
libtheoradec.
It may be freed or overwritten without notification when
subsequent frames are decoded.
\retval 0 Success
\retval TH_EFAULT \a _dec or \a _ycbcr was NULL.
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).
\param _encdec A previously allocated #th_enc_ctx or #th_dec_ctx
handle.
\param _granpos The granule position to convert.
\returns The absolute frame index corresponding to \a _granpos.
\retval -1 The given granule position was invalid (i.e. negative).
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).
\param _encdec A previously allocated #th_enc_ctx or #th_dec_ctx
handle.
\param _granpos The granule position to convert.
\return The absolute time in seconds corresponding to \a _granpos.
This is the “end time” for the frame, or the latest time it should
be displayed.
It is not the presentation time.
\retval -1 The given granule position was invalid (i.e. negative).
Initializes a th_info structure.
This should be called on a freshly allocated #th_info structure before
attempting to use it.
\param _info The #th_info struct to initialize.
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).
\param _op An ogg_packet containing encoded Theora data.
\retval 1 The packet is a header packet
\retval 0 The packet is a video data packet.
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).
\param _op An ogg_packet containing encoded Theora data.
\retval 1 The packet contains a key frame.
\retval 0 The packet contains a delta frame.
\retval -1 The packet is not a video data packet.
Releases all storage used for the decoder setup information.
This should be called after you no longer want to create any decoders for
a stream whose headers you have parsed with th_decode_headerin().
\param _setup The setup information to free.
This can safely be NULL.
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:
\code
(VERSION_MAJOR<<16)+(VERSION_MINOR<<8)+(VERSION_SUBMINOR)
\endcode
\return the version number.
A callback function for striped decode.
This is a function pointer to an application-provided function that will be
called each time a section of the image is fully decoded in
th_decode_packetin().
This allows the application to process the section immediately, while it is
still in cache.
Note that the frame is decoded bottom to top, so \a _yfrag0 will steadily
decrease with each call until it reaches 0, at which point the full frame
is decoded.
The number of fragment rows made available in each call depends on the pixel
format and the number of post-processing filters enabled, and may not even
be constant for the entire frame.
If a non-NULL \a _granpos pointer is passed to
th_decode_packetin(), the granule position for the frame will be stored
in it before the first callback is made.
If an entire frame is dropped (a 0-byte packet), then no callbacks will be
made at all for that frame.
\param _ctx An application-provided context pointer.
\param _buf The image buffer for the decoded frame.
\param _yfrag0 The Y coordinate of the first row of 8x8 fragments
decoded.
Multiply this by 8 to obtain the pixel row number in the
luma plane.
If the chroma planes are subsampled in the Y direction,
this will always be divisible by two.
\param _yfrag_end The Y coordinate of the first row of 8x8 fragments past
the newly decoded section.
If the chroma planes are subsampled in the Y direction,
this will always be divisible by two.
I.e., this section contains fragment rows
\a _yfrag0 …\a _yfrag_end -1.
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.