michael@0: /********************************************************************
michael@0: * *
michael@0: * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. *
michael@0: * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS *
michael@0: * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
michael@0: * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
michael@0: * *
michael@0: * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 *
michael@0: * by the Xiph.Org Foundation http://www.xiph.org/ *
michael@0: * *
michael@0: ********************************************************************
michael@0:
michael@0: function:
michael@0: last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $
michael@0:
michael@0: ********************************************************************/
michael@0:
michael@0: /**\file
michael@0: * The libtheoradec C decoding API.*/
michael@0:
michael@0: #if !defined(_O_THEORA_THEORADEC_H_)
michael@0: # define _O_THEORA_THEORADEC_H_ (1)
michael@0: # include
michael@0: # include
michael@0: # include "codec.h"
michael@0:
michael@0: #if defined(__cplusplus)
michael@0: extern "C" {
michael@0: #endif
michael@0:
michael@0:
michael@0:
michael@0: /**\name th_decode_ctl() codes
michael@0: * \anchor decctlcodes
michael@0: * These are the available request codes for th_decode_ctl().
michael@0: * By convention, these are odd, to distinguish them from the
michael@0: * \ref encctlcodes "encoder control codes".
michael@0: * Keep any experimental or vendor-specific values above \c 0x8000.*/
michael@0: /*@{*/
michael@0: /**Gets the maximum post-processing level.
michael@0: * The decoder supports a post-processing filter that can improve
michael@0: * the appearance of the decoded images. This returns the highest
michael@0: * level setting for this post-processor, corresponding to maximum
michael@0: * improvement and computational expense.
michael@0: *
michael@0: * \param[out] _buf int: The maximum post-processing level.
michael@0: * \retval TH_EFAULT \a _dec_ctx or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(int).
michael@0: * \retval TH_EIMPL Not supported by this implementation.*/
michael@0: #define TH_DECCTL_GET_PPLEVEL_MAX (1)
michael@0: /**Sets the post-processing level.
michael@0: * By default, post-processing is disabled.
michael@0: *
michael@0: * Sets the level of post-processing to use when decoding the
michael@0: * compressed stream. This must be a value between zero (off)
michael@0: * and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX.
michael@0: *
michael@0: * \param[in] _buf int: The new post-processing level.
michael@0: * 0 to disable; larger values use more CPU.
michael@0: * \retval TH_EFAULT \a _dec_ctx or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(int), or the
michael@0: * post-processing level is out of bounds.
michael@0: * The maximum post-processing level may be
michael@0: * implementation-specific, and can be obtained via
michael@0: * #TH_DECCTL_GET_PPLEVEL_MAX.
michael@0: * \retval TH_EIMPL Not supported by this implementation.*/
michael@0: #define TH_DECCTL_SET_PPLEVEL (3)
michael@0: /**Sets the granule position.
michael@0: * Call this after a seek, before decoding the first frame, to ensure that the
michael@0: * proper granule position is returned for all subsequent frames.
michael@0: * If you track timestamps yourself and do not use the granule position
michael@0: * returned by the decoder, then you need not call this function.
michael@0: *
michael@0: * \param[in] _buf ogg_int64_t: The granule position of the next
michael@0: * frame.
michael@0: * \retval TH_EFAULT \a _dec_ctx or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(ogg_int64_t), or the
michael@0: * granule position is negative.*/
michael@0: #define TH_DECCTL_SET_GRANPOS (5)
michael@0: /**Sets the striped decode callback function.
michael@0: * If set, this function will be called as each piece of a frame is fully
michael@0: * decoded in th_decode_packetin().
michael@0: * You can pass in a #th_stripe_callback with
michael@0: * th_stripe_callback#stripe_decoded set to NULL to disable the
michael@0: * callbacks at any point.
michael@0: * Enabling striped decode does not prevent you from calling
michael@0: * th_decode_ycbcr_out() after the frame is fully decoded.
michael@0: *
michael@0: * \param[in] _buf #th_stripe_callback: The callback parameters.
michael@0: * \retval TH_EFAULT \a _dec_ctx or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not
michael@0: * sizeof(th_stripe_callback).*/
michael@0: #define TH_DECCTL_SET_STRIPE_CB (7)
michael@0:
michael@0: /**Enables telemetry and sets the macroblock display mode */
michael@0: #define TH_DECCTL_SET_TELEMETRY_MBMODE (9)
michael@0: /**Enables telemetry and sets the motion vector display mode */
michael@0: #define TH_DECCTL_SET_TELEMETRY_MV (11)
michael@0: /**Enables telemetry and sets the adaptive quantization display mode */
michael@0: #define TH_DECCTL_SET_TELEMETRY_QI (13)
michael@0: /**Enables telemetry and sets the bitstream breakdown visualization mode */
michael@0: #define TH_DECCTL_SET_TELEMETRY_BITS (15)
michael@0: /*@}*/
michael@0:
michael@0:
michael@0:
michael@0: /**A callback function for striped decode.
michael@0: * This is a function pointer to an application-provided function that will be
michael@0: * called each time a section of the image is fully decoded in
michael@0: * th_decode_packetin().
michael@0: * This allows the application to process the section immediately, while it is
michael@0: * still in cache.
michael@0: * Note that the frame is decoded bottom to top, so \a _yfrag0 will steadily
michael@0: * decrease with each call until it reaches 0, at which point the full frame
michael@0: * is decoded.
michael@0: * The number of fragment rows made available in each call depends on the pixel
michael@0: * format and the number of post-processing filters enabled, and may not even
michael@0: * be constant for the entire frame.
michael@0: * If a non-NULL \a _granpos pointer is passed to
michael@0: * th_decode_packetin(), the granule position for the frame will be stored
michael@0: * in it before the first callback is made.
michael@0: * If an entire frame is dropped (a 0-byte packet), then no callbacks will be
michael@0: * made at all for that frame.
michael@0: * \param _ctx An application-provided context pointer.
michael@0: * \param _buf The image buffer for the decoded frame.
michael@0: * \param _yfrag0 The Y coordinate of the first row of 8x8 fragments
michael@0: * decoded.
michael@0: * Multiply this by 8 to obtain the pixel row number in the
michael@0: * luma plane.
michael@0: * If the chroma planes are subsampled in the Y direction,
michael@0: * this will always be divisible by two.
michael@0: * \param _yfrag_end The Y coordinate of the first row of 8x8 fragments past
michael@0: * the newly decoded section.
michael@0: * If the chroma planes are subsampled in the Y direction,
michael@0: * this will always be divisible by two.
michael@0: * I.e., this section contains fragment rows
michael@0: * \a _yfrag0 ...\a _yfrag_end -1.*/
michael@0: typedef void (*th_stripe_decoded_func)(void *_ctx,th_ycbcr_buffer _buf,
michael@0: int _yfrag0,int _yfrag_end);
michael@0:
michael@0: /**The striped decode callback data to pass to #TH_DECCTL_SET_STRIPE_CB.*/
michael@0: typedef struct{
michael@0: /**An application-provided context pointer.
michael@0: * This will be passed back verbatim to the application.*/
michael@0: void *ctx;
michael@0: /**The callback function pointer.*/
michael@0: th_stripe_decoded_func stripe_decoded;
michael@0: }th_stripe_callback;
michael@0:
michael@0:
michael@0:
michael@0: /**\name Decoder state
michael@0: The following data structures are opaque, and their contents are not
michael@0: publicly defined by this API.
michael@0: Referring to their internals directly is unsupported, and may break without
michael@0: warning.*/
michael@0: /*@{*/
michael@0: /**The decoder context.*/
michael@0: typedef struct th_dec_ctx th_dec_ctx;
michael@0: /**Setup information.
michael@0: This contains auxiliary information (Huffman tables and quantization
michael@0: parameters) decoded from the setup header by th_decode_headerin() to be
michael@0: passed to th_decode_alloc().
michael@0: It can be re-used to initialize any number of decoders, and can be freed
michael@0: via th_setup_free() at any time.*/
michael@0: typedef struct th_setup_info th_setup_info;
michael@0: /*@}*/
michael@0:
michael@0:
michael@0:
michael@0: /**\defgroup decfuncs Functions for Decoding*/
michael@0: /*@{*/
michael@0: /**\name Functions for decoding
michael@0: * You must link to libtheoradec if you use any of the
michael@0: * functions in this section.
michael@0: *
michael@0: * The functions are listed in the order they are used in a typical decode.
michael@0: * The basic steps are:
michael@0: * - Parse the header packets by repeatedly calling th_decode_headerin().
michael@0: * - Allocate a #th_dec_ctx handle with th_decode_alloc().
michael@0: * - Call th_setup_free() to free any memory used for codec setup
michael@0: * information.
michael@0: * - Perform any additional decoder configuration with th_decode_ctl().
michael@0: * - For each video data packet:
michael@0: * - Submit the packet to the decoder via th_decode_packetin().
michael@0: * - Retrieve the uncompressed video data via th_decode_ycbcr_out().
michael@0: * - Call th_decode_free() to release all decoder memory.*/
michael@0: /*@{*/
michael@0: /**Decodes the header packets of a Theora stream.
michael@0: * This should be called on the initial packets of the stream, in succession,
michael@0: * until it returns 0, indicating that all headers have been
michael@0: * processed, or an error is encountered.
michael@0: * At least three header packets are required, and additional optional header
michael@0: * packets may follow.
michael@0: * This can be used on the first packet of any logical stream to determine if
michael@0: * that stream is a Theora stream.
michael@0: * \param _info A #th_info structure to fill in.
michael@0: * This must have been previously initialized with
michael@0: * th_info_init().
michael@0: * The application may immediately begin using the contents of
michael@0: * this structure after the first header is decoded, though it
michael@0: * must continue to be passed in on all subsequent calls.
michael@0: * \param _tc A #th_comment structure to fill in.
michael@0: * The application may immediately begin using the contents of
michael@0: * this structure after the second header is decoded, though it
michael@0: * must continue to be passed in on all subsequent calls.
michael@0: * \param _setup Returns a pointer to additional, private setup information
michael@0: * needed by the decoder.
michael@0: * The contents of this pointer must be initialized to
michael@0: * NULL on the first call, and the returned value must
michael@0: * continue to be passed in on all subsequent calls.
michael@0: * \param _op An ogg_packet structure which contains one of the
michael@0: * initial packets of an Ogg logical stream.
michael@0: * \return A positive value indicates that a Theora header was successfully
michael@0: * processed.
michael@0: * \retval 0 The first video data packet was encountered after all
michael@0: * required header packets were parsed.
michael@0: * The packet just passed in on this call should be saved
michael@0: * and fed to th_decode_packetin() to begin decoding
michael@0: * video data.
michael@0: * \retval TH_EFAULT One of \a _info, \a _tc, or \a _setup was
michael@0: * NULL.
michael@0: * \retval TH_EBADHEADER \a _op was NULL, the packet was not the next
michael@0: * header packet in the expected sequence, or the format
michael@0: * of the header data was invalid.
michael@0: * \retval TH_EVERSION The packet data was a Theora info header, but for a
michael@0: * bitstream version not decodable with this version of
michael@0: * libtheoradec.
michael@0: * \retval TH_ENOTFORMAT The packet was not a Theora header.
michael@0: */
michael@0: extern int th_decode_headerin(th_info *_info,th_comment *_tc,
michael@0: th_setup_info **_setup,ogg_packet *_op);
michael@0: /**Allocates a decoder instance.
michael@0: *
michael@0: * Security Warning: The Theora format supports very large frame sizes,
michael@0: * potentially even larger than the address space of a 32-bit machine, and
michael@0: * creating a decoder context allocates the space for several frames of data.
michael@0: * If the allocation fails here, your program will crash, possibly at some
michael@0: * future point because the OS kernel returned a valid memory range and will
michael@0: * only fail when it tries to map the pages in it the first time they are
michael@0: * used.
michael@0: * Even if it succeeds, you may experience a denial of service if the frame
michael@0: * size is large enough to cause excessive paging.
michael@0: * If you are integrating libtheora in a larger application where such things
michael@0: * are undesirable, it is highly recommended that you check the frame size in
michael@0: * \a _info before calling this function and refuse to decode streams where it
michael@0: * is larger than some reasonable maximum.
michael@0: * libtheora will not check this for you, because there may be machines that
michael@0: * can handle such streams and applications that wish to.
michael@0: * \param _info A #th_info struct filled via th_decode_headerin().
michael@0: * \param _setup A #th_setup_info handle returned via
michael@0: * th_decode_headerin().
michael@0: * \return The initialized #th_dec_ctx handle.
michael@0: * \retval NULL If the decoding parameters were invalid.*/
michael@0: extern th_dec_ctx *th_decode_alloc(const th_info *_info,
michael@0: const th_setup_info *_setup);
michael@0: /**Releases all storage used for the decoder setup information.
michael@0: * This should be called after you no longer want to create any decoders for
michael@0: * a stream whose headers you have parsed with th_decode_headerin().
michael@0: * \param _setup The setup information to free.
michael@0: * This can safely be NULL.*/
michael@0: extern void th_setup_free(th_setup_info *_setup);
michael@0: /**Decoder control function.
michael@0: * This is used to provide advanced control of the decoding process.
michael@0: * \param _dec A #th_dec_ctx handle.
michael@0: * \param _req The control code to process.
michael@0: * See \ref decctlcodes "the list of available control codes"
michael@0: * for details.
michael@0: * \param _buf The parameters for this control code.
michael@0: * \param _buf_sz The size of the parameter buffer.*/
michael@0: extern int th_decode_ctl(th_dec_ctx *_dec,int _req,void *_buf,
michael@0: size_t _buf_sz);
michael@0: /**Submits a packet containing encoded video data to the decoder.
michael@0: * \param _dec A #th_dec_ctx handle.
michael@0: * \param _op An ogg_packet containing encoded video data.
michael@0: * \param _granpos Returns the granule position of the decoded packet.
michael@0: * If non-NULL, the granule position for this specific
michael@0: * packet is stored in this location.
michael@0: * This is computed incrementally from previously decoded
michael@0: * packets.
michael@0: * After a seek, the correct granule position must be set via
michael@0: * #TH_DECCTL_SET_GRANPOS for this to work properly.
michael@0: * \retval 0 Success.
michael@0: * A new decoded frame can be retrieved by calling
michael@0: * th_decode_ycbcr_out().
michael@0: * \retval TH_DUPFRAME The packet represented a dropped frame (either a
michael@0: * 0-byte frame or an INTER frame with no coded blocks).
michael@0: * The player can skip the call to th_decode_ycbcr_out(),
michael@0: * as the contents of the decoded frame buffer have not
michael@0: * changed.
michael@0: * \retval TH_EFAULT \a _dec or \a _op was NULL.
michael@0: * \retval TH_EBADPACKET \a _op does not contain encoded video data.
michael@0: * \retval TH_EIMPL The video data uses bitstream features which this
michael@0: * library does not support.*/
michael@0: extern int th_decode_packetin(th_dec_ctx *_dec,const ogg_packet *_op,
michael@0: ogg_int64_t *_granpos);
michael@0: /**Outputs the next available frame of decoded Y'CbCr data.
michael@0: * If a striped decode callback has been set with #TH_DECCTL_SET_STRIPE_CB,
michael@0: * then the application does not need to call this function.
michael@0: * \param _dec A #th_dec_ctx handle.
michael@0: * \param _ycbcr A video buffer structure to fill in.
michael@0: * libtheoradec will fill in all the members of this
michael@0: * structure, including the pointers to the uncompressed video
michael@0: * data.
michael@0: * The memory for this video data is owned by
michael@0: * libtheoradec.
michael@0: * It may be freed or overwritten without notification when
michael@0: * subsequent frames are decoded.
michael@0: * \retval 0 Success
michael@0: * \retval TH_EFAULT \a _dec or \a _ycbcr was NULL.
michael@0: */
michael@0: extern int th_decode_ycbcr_out(th_dec_ctx *_dec,
michael@0: th_ycbcr_buffer _ycbcr);
michael@0: /**Frees an allocated decoder instance.
michael@0: * \param _dec A #th_dec_ctx handle.*/
michael@0: extern void th_decode_free(th_dec_ctx *_dec);
michael@0: /*@}*/
michael@0: /*@}*/
michael@0:
michael@0:
michael@0:
michael@0: #if defined(__cplusplus)
michael@0: }
michael@0: #endif
michael@0:
michael@0: #endif