th_info Struct Reference

Theora bitstream information. More...

#include <codec.h>

Data Fields
ogg_uint32_t	frame_width
	The encoded frame width.
ogg_uint32_t	frame_height
	The encoded frame height.
ogg_uint32_t	pic_width
	The displayed picture width.
ogg_uint32_t	pic_height
	The displayed picture height.
ogg_uint32_t	pic_x
	The X offset of the displayed picture.
ogg_uint32_t	pic_y
	The Y offset of the displayed picture.
th_colorspace	colorspace
	The color space.
th_pixel_fmt	pixel_fmt
	The pixel format.
int	target_bitrate
	The target bit-rate in bits per second.
int	quality
	The target quality level.
int	keyframe_granule_shift
	The amount to shift to extract the last keyframe number from the granule position.
Theora version
Bitstream version information.
unsigned char	version_major
unsigned char	version_minor
unsigned char	version_subminor
Frame rate
The frame rate, as a fraction. If either is 0, the frame rate is undefined.
ogg_uint32_t	fps_numerator
ogg_uint32_t	fps_denominator
Aspect ratio
The aspect ratio of the pixels. If either value is zero, the aspect ratio is undefined. If not specified by any external means, 1:1 should be assumed. The aspect ratio of the full picture can be computed as aspect_numerator*pic_width/(aspect_denominator*pic_height).
ogg_uint32_t	aspect_numerator
ogg_uint32_t	aspect_denominator

---

Detailed Description

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

Encoded Theora frames must be a multiple of 16 in size; this is what the frame_width and frame_height members represent. To handle arbitrary picture sizes, a crop rectangle is specified in the pic_x, pic_y, pic_width and pic_height members.

All frame buffers contain pointers to the full, padded frame. However, the current encoder will not reference pixels outside of the cropped picture region, and the application does not need to fill them in. The decoder will allocate storage for a full frame, but the application should not rely on the padding containing sensible data.

It is also generally recommended that the offsets and sizes should still be multiples of 2 to avoid chroma sampling shifts when chroma is sub-sampled. See the Theora specification, Section 4.4, for more details.

Frame rate, in frames per second, is stored as a rational fraction, as is the pixel aspect ratio. Note that this refers to the aspect ratio of the individual pixels, not of the overall frame itself. The frame aspect ratio can be computed from pixel aspect ratio using the image dimensions.

---

Field Documentation

ogg_uint32_t th_info::aspect_denominator

ogg_uint32_t th_info::aspect_numerator

th_colorspace th_info::colorspace

The color space.

ogg_uint32_t th_info::fps_denominator

ogg_uint32_t th_info::fps_numerator

ogg_uint32_t th_info::frame_height

The encoded frame height.

This must be a multiple of 16, and less than 1048576.

ogg_uint32_t th_info::frame_width

The encoded frame width.

This must be a multiple of 16, and less than 1048576.

int th_info::keyframe_granule_shift

The amount to shift to extract the last keyframe number from the granule position.

This can be at most 31. th_info_init() will set this to a default value (currently 6, which is good for streaming applications), but you can set it to 0 to make every frame a keyframe. The maximum distance between key frames is 1<<keyframe_granule_shift. The keyframe frequency can be more finely controlled with TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE, which can also be adjusted during encoding (for example, to force the next frame to be a keyframe), but it cannot be set larger than the amount permitted by this field after the headers have been output.

ogg_uint32_t th_info::pic_height

The displayed picture height.

This must be no larger than height.

ogg_uint32_t th_info::pic_width

The displayed picture width.

This must be no larger than width.

ogg_uint32_t th_info::pic_x

The X offset of the displayed picture.

This must be no larger than frame_width-pic_width or 255, whichever is smaller.

ogg_uint32_t th_info::pic_y

The Y offset of the displayed picture.

This must be no larger than frame_height-pic_height, and frame_height-pic_height-pic_y must be no larger than 255. This slightly funny restriction is due to the fact that the offset is specified from the top of the image for consistency with the standard graphics left-handed coordinate system used throughout this API, while it is stored in the encoded stream as an offset from the bottom.

th_pixel_fmt th_info::pixel_fmt

The pixel format.

int th_info::quality

The target quality level.

Valid values range from 0 to 63, inclusive, with higher values giving higher quality. If initializing an encoder with this struct, and target_bitrate is set to zero, VBR encoding at this quality will be activated by default.

int th_info::target_bitrate

The target bit-rate in bits per second.

If initializing an encoder with this struct, set this field to a non-zero value to activate CBR encoding by default.

unsigned char th_info::version_major

unsigned char th_info::version_minor

unsigned char th_info::version_subminor

---

The documentation for this struct was generated from the following file:

• codec.h