quicktime.h

这个库实现了录象功能

/*******************************************************************************
 quicktime.h

 libquicktime - A library for reading and writing quicktime/avi/mp4 files.
 http://libquicktime.sourceforge.net

 Copyright (C) 2002 Heroine Virtual Ltd.
 Copyright (C) 2002-2007 Members of the libquicktime project.

 This library is free software; you can redistribute it and/or modify it under
 the terms of the GNU Lesser General Public License as published by the Free
 Software Foundation; either version 2.1 of the License, or (at your option)
 any later version.

 This library is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
 details.

 You should have received a copy of the GNU Lesser General Public License along
 with this library; if not, write to the Free Software Foundation, Inc., 51
 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*******************************************************************************/

#ifndef QUICKTIME_H
#define QUICKTIME_H

#ifdef __cplusplus
extern "C" {
#endif

#include <inttypes.h>
#include <stddef.h>

#pragma GCC visibility push(default)
  
/* Some public enums needed by most subsequent headers */

/**
 * @file quicktime.h
 * Public api header for the quicktime4linux compatibility layer.
 */

/** \defgroup general General
    \brief General structures and functions
 */

/** \defgroup log Logging
    \brief Message handling
 */

  
/** \defgroup audio Audio
    \brief Audio related definitions and functions
 */

/** \defgroup audio_decode Audio decoding
 *  \ingroup audio
 *  \brief Audio related definitions and functions (reading)
 *
 * The audio API changed a lot during the last years (causing lot of confusion), so here is the
 * preferred way: First get the number of audio tracks with \ref quicktime_audio_tracks. Then
 * for each track you want to decode, use \ref quicktime_supported_audio to verify that a codec
 * is available. Then get the audio format with \ref quicktime_track_channels and \ref quicktime_sample_rate .
 * Then use \ref lqt_decode_audio_track to decode noninterleaved channels in either 16bit integer
 * or floating point [-1.0..1.0] format. This method will convert all internally used formats to the datatypes
 * you want, but won't output the full precision for 24/32 bit formats. If you want the samples as raw as possible
 * (bypassing all internal sample format conversions), use \ref lqt_get_sample_format to get the sampleformat
 * natively used by the codec and \ref lqt_decode_audio_raw to decode it.
 */

/** \defgroup audio_encode Audio encoding
 *  \ingroup audio
 *  \brief Audio related definitions and functions (writing)
 *
 * The audio API changed a lot during the last years (causing lot of confusion), so here is the
 * preferred way: Use the \ref codec_registry functions to get all supported audio encoders.
 * Once you found a codec (i.e. a \ref lqt_codec_info_t ), call \ref lqt_add_audio_track to
 * add the track to the file. You can repeat this procedure to add as many tracks as you like
 * with different formats and/or codecs.
 *
 * Next you might want to set some compression parameters. This is done by calling \ref lqt_set_audio_parameter.
 * Supported parameters and valid ranges are in the \ref lqt_codec_info_t.
 *
 * For each track, encode noninterleaved samples (either in 16bit integer
 * or floating point [-1.0..1.0] format) with \ref lqt_encode_audio_track . In this case, libquicktime
 * will convert your samples to the format used by the codec. This won't give the
 * full precision when using 24/32 bit formats. If you want to pass the samples as raw as possible
 * (bypassing all internal sample format conversions), use \ref lqt_get_sample_format to get the sampleformat
 * natively used by the codec and \ref lqt_encode_audio_raw to encode it.
 * 
 */

/** \defgroup multichannel Multichannel support
 *  \ingroup audio
 *
 * This is an optional API extension, which allows multichannel
 * configuration to be saved into a file. The mechanisms used are the
 * quicktime chan atom as well as some codec specific multichannel
 * setups.
 *
 *  When decoding, simply get the channel setup with \ref lqt_get_channel_setup.
 *  It can happen, that this function returns NULL when no specific mapping is known.
 *
 *  When encoding, things are more complicated. Some codecs have fixed channel
 *  setups. After setting up an audio track, call \ref lqt_get_channel_setup to
 *  check, if there is already a prefefined channel setup. If this is the case (i.e. if non
 *  NULL is returned), you MUST use this  channel setup.
 *
 *  If there is no predefined setup (i.e. \ref lqt_get_channel_setup returns NULL after
 *  creation of the audio track), call \ref lqt_set_channel_setup to set your desired
 *  setup. It can happen, that libquicktime will reorder the channel setup. Thus
 *  you need a final call to \ref lqt_get_channel_setup to know the whole truth.

*/

/** \ingroup log
 *  \brief Log level
 */

typedef enum
  {
    LQT_LOG_ERROR   = (1<<0),
    LQT_LOG_WARNING = (1<<1),
    LQT_LOG_INFO    = (1<<2),
    LQT_LOG_DEBUG   = (1<<3),
  } lqt_log_level_t;

/** \ingroup log
 *  \brief Log callback
 *  \param level The log level
 *  \param domain Log domain (e.g. name of the module)
 *  \param message The message to pass
 *  \param data Application supplied data
 */

typedef void (*lqt_log_callback_t)(lqt_log_level_t level,
                                   const char * domain,
                                   const char * message,
                                   void * data);

  
/** \ingroup General
 *  \brief File types
 *
 * These are bitmasks since codecs need lists of supported file formats
 */

typedef enum
  {
    LQT_FILE_NONE = 0,        /*!< Undefined or not yet set */
    LQT_FILE_QT_OLD   = (1<<0), /*!< Old libquicktime format (without ftyp) */
    LQT_FILE_QT       = (1<<1), /*!< New libquicktime format (ftyp = "qt  ") */
    LQT_FILE_AVI      = (1<<2), /*!< AVI */
    LQT_FILE_AVI_ODML = (1<<3), /*!< Opendml AVI (> 2G) */
    LQT_FILE_MP4      = (1<<4), /*!< .mp4 (ftyp = "mp42") */
    LQT_FILE_M4A      = (1<<5), /*!< .m4a  */
    LQT_FILE_3GP      = (1<<6), /*!< .3gp  */
  } lqt_file_type_t;

  
/** \ingroup multichannel
 *  \brief Channel definitions
 *
 *  These are the channel types defined in the public API. They should
 *  enable to support most channel configurations. Internally,
 *  many more channel types exist. They can be added to the public part
 *  on demand.
 *
 */

typedef enum 
  {
    LQT_CHANNEL_UNKNOWN,
    LQT_CHANNEL_FRONT_LEFT,
    LQT_CHANNEL_FRONT_RIGHT,
    LQT_CHANNEL_FRONT_CENTER,
    LQT_CHANNEL_FRONT_CENTER_LEFT,
    LQT_CHANNEL_FRONT_CENTER_RIGHT,
    LQT_CHANNEL_BACK_CENTER,
    LQT_CHANNEL_BACK_LEFT,
    LQT_CHANNEL_BACK_RIGHT,
    LQT_CHANNEL_SIDE_LEFT,
    LQT_CHANNEL_SIDE_RIGHT,
    LQT_CHANNEL_LFE,
  } lqt_channel_t;

  
/** \defgroup video Video
    \brief Video related definitions and functions
 */

/** \defgroup video_decode Video decoding
 * \ingroup video
 * \brief Video related definitions and functions (reading)
 *
 * The video API changed a lot during the last years (causing lot of confusion), so here is the
 * preferred way: First get the number of video tracks with \ref quicktime_video_tracks. Then
 * for each track you want to decode, use \ref quicktime_supported_video to verify that a codec
 * is available. Then for each track, get the frame size with \ref quicktime_video_width and
 * \ref quicktime_video_height . The framerate is only exact when handled as a rational number.
 * Thus, you'll need 2 functions \ref lqt_video_time_scale and \ref lqt_frame_duration .
 * The framerate in frames/sec becomes time_scale/frame_duration. Further format information can
 * be obtained with \ref lqt_get_pixel_aspect, \ref lqt_get_interlace_mode and \ref lqt_get_chroma_placement.
 *
 * A very important thing is the colormodel (see \ref color): First obtain the colormodel used natively
 * by the codec with \ref lqt_get_cmodel. Your application might or might not support all colormodels,
 * which exist in libquicktime. The more colormodels you can handle yourself, the better, since libquicktimes
 * built in colormodel converter is not the best. Thus, it's the best idea to pack all colormodels you
 * can handle yourself into an array, and call \ref lqt_get_best_colormodel to get the best colormodel. After you
 * figured out, which colormodel you use, tell this to libquicktime with \ref lqt_set_cmodel.
 *
 * When decoding frames, libquicktime by default assumes, that the frames you pass to it have no padding bytes
 * between the scanlines. Some APIs however padd scanlines to certain boundaries. If this is the case, you must
 * tell this to libquicktime by calling \ref lqt_set_row_span and \ref lqt_set_row_span_uv (for planar formats).
 *
 * Then, for each frame, it's wise to get the timestamp with \ref lqt_frame_time before decoding it. This will
 * make sure, that you'll support tracks with nonconstant framerates. The actual decoding then should happen with
 * \ref lqt_decode_video.
 */

/** \defgroup video_encode Video encoding
 *  \ingroup video
 *  \brief Video related definitions and functions (writing)
 *
 * The video API changed a lot during the last years (causing lot of confusion), so here is the
 * preferred way: Use the \ref codec_registry functions to get all supported video encoders.
 * Once you found a codec (i.e. a \ref lqt_codec_info_t ), call \ref lqt_add_video_track to
 * add the track to the file. You can repeat this procedure to add as many tracks as you like
 * with different formats and/or codecs. You can pass further format parameters with \ref lqt_set_pixel_aspect.
 *
 * A very important thing is the colormodel (see \ref color): First obtain the colormodel used natively
 * by the codec with \ref lqt_get_cmodel. Your application might or might not support all colormodels,
 * which exist in libquicktime. The more colormodels you can handle yourself, the better, since libquicktimes
 * built in colormodel converter is not the best. Thus, it's the best idea to pack all colormodels you
 * can handle yourself into an array, and call \ref lqt_get_best_colormodel to get the best colormodel. After you
 * figured out, which colormodel you use, tell this to libquicktime with \ref lqt_set_cmodel.
 *
 * Next you might want to set some compression parameters. This is done by calling \ref lqt_set_video_parameter.
 * Supported parameters and valid ranges are in the \ref lqt_codec_info_t.
 * 
 * Actual encoding should happen with \ref lqt_encode_video.
 */

/** \ingroup video
 * \brief interlace modes
 *
 * This is the interlace mode of a video track. Read it with
 * \ref lqt_get_interlace_mode .
 */
 
typedef enum 
  {
    LQT_INTERLACE_NONE = 0, /*!< No interlacing (= progressive) */
    LQT_INTERLACE_TOP_FIRST, /*!< Top field first */
    LQT_INTERLACE_BOTTOM_FIRST  /*!< Bottom field first */
  } lqt_interlace_mode_t;

/** \ingroup video
 * \brief Chroma placement
 *
 * This describes the chroma placement of a video track. Read it with
 * \ref lqt_get_chroma_placement . Chroma placement makes only sense for
 * YUV420 formats. For other pixelformats, it is set implicitely to
 * LQT_CHROMA_PLACEMENT_DEFAULT.
 */
  
typedef enum 
  {
    LQT_CHROMA_PLACEMENT_DEFAULT = 0, /*!< MPEG-1, JPEG or non 4:2:0 */
    LQT_CHROMA_PLACEMENT_MPEG2,       /*!< MPEG-2 */
    LQT_CHROMA_PLACEMENT_DVPAL,       /*!< DV PAL */
  } lqt_chroma_placement_t;

/** \ingroup audio
 * \brief Sample format definitions for audio
 *
 * This defines the datatype for audio samples, which will be used by a
 * particular codec. You'll need this, if you want to use \ref lqt_decode_audio_raw
 * or \ref lqt_encode_audio_raw . Byte order of the data is always machine native.
 * Endianess conversion is responsibility of the codec.
 */
  
typedef enum 
  {
    LQT_SAMPLE_UNDEFINED = 0, /*!< If this is returned, we have an error */
    LQT_SAMPLE_INT8,      /*!< int8_t */
    LQT_SAMPLE_UINT8,     /*!< uint8_t */
    LQT_SAMPLE_INT16,     /*!< int16_t */
    LQT_SAMPLE_INT32,     /*!< int32_t */
    LQT_SAMPLE_FLOAT,     /*!< Float (machine native) */
    LQT_SAMPLE_DOUBLE     /*!< Double (machine native, since version 1.0.3) */
  } lqt_sample_format_t;
  
/** \ingroup general
    \brief Quicktime handle

    Opaque file handle used both for reading and writing. In quicktime4linux, this structure is
    public, resulting in programmers doing wrong things with it. In libquicktime, this is
    a private structure, which is accessed exclusively by functions.
 */
  
typedef struct quicktime_s quicktime_t;
  
/* This is the reference for all your library entry points. */

/* ===== compression formats for which codecs exist ====== */

/** \defgroup video_codecs Video codec identifiers
 *  \brief Video codec identifiers
 *
 *  These definintions are for some more commonly used codecs.
 *  They can be used as the compressor argument for \ref quicktime_set_video .
 *  There is, however, no way to check, if a
 *  codec is accually present on the system.
 *  It should also be noted, that libquicktime supports more codecs, than
 *  are listed here. For these reasons, it's strongly recommended
 *  to use the more sophisticated codec selection mechanism via the
 *  \ref codec_registry .
 */

/** \ingroup video_codecs
 * \brief Non compatible divx
 *
 * Never hardcode this in an application!
 */

#define QUICKTIME_DIVX "DIVX"

/** \ingroup video_codecs
 * \brief Divx for AVI files
 *
 * Never hardcode this in an application!
 */

#define QUICKTIME_DIV3 "DIV3"

/** \ingroup video_codecs
 * \brief DV
 *
 * Never hardcode this in an application!
 */
  
#define QUICKTIME_DV "dvc "
/* AVID DV codec can be processed with libdv as well */

/** \ingroup video_codecs
 * \brief DV
 *
 * Never hardcode this in an application!
 */

#define QUICKTIME_DV_AVID "AVdv"

/** \ingroup video_codecs
 * \brief DV
 *
 * Never hardcode this in an application!
 */

#define QUICKTIME_DV_AVID_A "dvcp"

/** \ingroup video_codecs
 * \brief Uncompressed RGB.
 *
 * Never hardcode this in an application. There are 2 encoders with
 * this fourcc, one for RGB and one for RGBA.
 */
  
/* RGB uncompressed.  Allows alpha */
#define QUICKTIME_RAW  "raw "

/** \ingroup video_codecs
 * \brief JPEG-Photo
 *
 * Might be missing if libjpeg headers aren't there during compilation.
 */
  
/* Jpeg Photo */
#define QUICKTIME_JPEG "jpeg"

/* Concatenated png images.  Allows alpha */

/** \ingroup video_codecs
 * \brief JPEG-Photo
 *
 * Might be missing if libjpeg headers aren't there during compilation.
 * There are 2 encoders, one for RGB, the other for RGBA.
 */

#define QUICKTIME_PNG "png "

/** \ingroup video_codecs
 * \brief Motion JPEG-A
 *
 * Might be missing if libjpeg headers aren't there during compilation.
 * A good choice for high quality interlaced storage.
 */

#define QUICKTIME_MJPA "mjpa"

/** \ingroup video_codecs
 * \brief 8 bit Packed full-range (not video) YUV 4:2:2
 *
 * Should always be there, can safely be hardcoded.
 */
  
#define QUICKTIME_YUV2 "yuv2"

/** \ingroup video_codecs
 * \brief YUV 4:2:0
 *
 * Not compatible with standard quicktime.
 */
  
#define QUICKTIME_YUV4 "yuv4"

/** \ingroup video_codecs
 * \brief 8 bit planar YUV 4:2:0
 *
 * Practically no external information about this codec exists. It should
 * always be available, but nevertheless not used.
 */
  
#define QUICKTIME_YUV420  "yv12"

/** \ingroup video_codecs
 * \brief 8 bit Packed YUV (video range) 4:2:2
 *
 * Should always be there, can safely be hardcoded.
 */
  
#define QUICKTIME_2VUY "2vuy"