lqt.h

这个库实现了录象功能

/*******************************************************************************
 lqt.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 _LQT_H_
#define _LQT_H_

#include "quicktime.h"
#include "lqt_atoms.h"
#include "lqt_codecinfo.h"
#include "lqt_qtvr.h"

#pragma GCC visibility push(default)


#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/**
 * @file lqt.h
 * Public api header for libquicktime.
 */
  
void *lqt_bufalloc(size_t size);


  
/** \ingroup log
 *  \brief Set callback for global logging
 *  \param cb Callback function
 *  \param data Application supplied data
 */

void lqt_set_log_callback(lqt_log_callback_t cb, void * data);
                           
  
/** \ingroup general
 *
 * \brief Return the raw filedescriptor associated with the file
 * \param file A quicktime handle
 * \returns The filesecriptor
 *
 * Use this of you want to call some low-level functions of the file.
 * Note, that this routine should be used with care, since it's easy
 * to screw things up.
 */
  
int lqt_fileno(quicktime_t *file);

/** \ingroup audio
 *  \brief Set a codec parameter for an audio track
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *  \param key Short name of the parameter
 *  \param value Parameter value.
 *
 *  For integer parameters, value must be of the type int*. For string parameters,
 *  use char*.  For floating-point parameters, use float*.
 */
  
void lqt_set_audio_parameter(quicktime_t *file,int track, const char *key,const void *value);

/** \ingroup video
 *  \brief Set a codec parameter for a video track
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *  \param key Short name of the parameter
 *  \param value Parameter value.
 *
 *  For integer parameters, value must be of the type int*. For string parameters,
 *  use char*.  For floating-point parameters, use float*.
 */

void lqt_set_video_parameter(quicktime_t *file,int track, const char *key,const void *value);

/** \ingroup video_decode
 *  \brief Get the pixel aspect ratio of a video track
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *  \param pixel_width returns the pixel width
 *  \param pixel_height returns the pixel height
 *  \returns 1 if the call was successful, 0 if there is no such track
 */


int lqt_get_pixel_aspect(quicktime_t *file, int track, int * pixel_width,
                         int * pixel_height);

/** \ingroup video_encode
 *  \brief Set the pixel aspect ratio of a video track
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *  \param pixel_width Pixel width
 *  \param pixel_height Pixel height
 *  \returns 1 if the call was successful, 0 if there is no such track
 *
 */

int lqt_set_pixel_aspect(quicktime_t *file, int track, int pixel_width,
                         int pixel_height);

/** \ingroup video_decode
    \brief Get the interlace mode
    \param file A quicktime handle
    \param track Track index (starting with 0)
    \returns The interlace mode.

    The interlace mode is stored in the fiel atom, which is used
    by default. If there is no fiel atom and the interlace mode is
    not implied by
    the codec, \ref LQT_INTERLACE_NONE is returned, which might be wrong.
*/

lqt_interlace_mode_t lqt_get_interlace_mode(quicktime_t * file, int track);

/** \ingroup video_encode
 *  \brief Set the interlace mode
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *  \param mode The interlace mode.
 *  \returns 1 if the call was successful, 0 if there is no such track
 *
 *  This will in most cases store the correct interlacing information
 *  in the file (e.g. in the fiel atom). For tweaking the fiel atom
 *  directly, advanced users might look at \ref lqt_set_fiel.
 */

int lqt_set_interlace_mode(quicktime_t * file, int track,
                           lqt_interlace_mode_t mode);

  
/** \ingroup video
    \brief Convert an interlace mode to a human readable string
    \param mode An interlace mode
    \returns A description of the interlace mode
*/
const char * lqt_interlace_mode_to_string(lqt_interlace_mode_t mode);

/** \ingroup video_decode
    \brief Get the chroma placement
    \param file A quicktime handle
    \param track Track index (starting with 0)
    \returns The chroma placement

    The chroma placement is implied by the codec and makes only sense
    for YUV420 formats.
*/
  
lqt_chroma_placement_t lqt_get_chroma_placement(quicktime_t * file, int track);

/** \ingroup video
    \brief Convert a chroma placement to a human readable string
    \param chroma_placement A chroma placement
    \returns A description of the chroma placement
*/

const char * lqt_chroma_placement_to_string(lqt_chroma_placement_t chroma_placement);

/** \ingroup general
    \brief Get the codec API version.
    \returns The codec API version, libquicktime was compiled with

    Normally you don't need this function. It is used internally to
    detect codec modules, which were compiled with an incompatible
    libquicktime version.
    
*/
  
int lqt_get_codec_api_version();

/** \ingroup multichannel
 *  \brief Convert a channel identifier to a human readnable string
 *  \param ch A channel
 *  \returns A string describing the channel.
 */
  
const char * lqt_channel_to_string(lqt_channel_t ch);

/** \ingroup multichannel
 *  \brief Set a channel setup for an audio track
 *  \param file A quicktime handle
 *  \param track index (starting with 0)
 *  \param ch Channel array
 *
 *  Set the desired channel setup for a file. Note, that libquicktime
 *  may reorder the channels. It is therefore necessary to call
 *  \ref lqt_get_channel_setup after to know the final truth.
 */

void lqt_set_channel_setup(quicktime_t * file, int track, lqt_channel_t * ch);

/** \ingroup multichannel
 *  \brief Get a channel setup from a file
 *  \param file A quicktime handle
 *  \param track index (starting with 0)
 *  \returns The channel array
 *
 *  Get the channel setup from a quicktime file. Works for en- and decoding.
 *  The return value is owned by libquicktime and must not be freed.
 */
  
const lqt_channel_t * lqt_get_channel_setup(quicktime_t * file, int track);


/** \defgroup text Text
    \brief Text related definitions and functions

    Libquicktime supports reading and writing of text tracks from/to
    Quicktime and mp4 files. Text tracks contain samples, which
    are simple text strings. Libquicktime tries to handle character set issues
    internally, all string you pass to/from libquicktime can assumed to be UTF-8.

    A text track can either be used for subtitles (which is the default), or for
    chapters. In the latter case, each text sample denotes the title of the chapter,
    the corresponding timestamp is the start time of the chapter.

    For subtitles, there is only a start time defined for each sample, not the duration,
    after which the subtitle will be hidden. To make subtitles disappear at a specified
    time, insert an empty subtitle with the right timestamp.

    What's not supported are text attributes, font selection etc. Feel free to make a
    proposal how to support these things.
*/
  
/** \defgroup text_encode Writing text
    \ingroup text
    \brief Encode text

    @{
*/

/** \brief Add a text track
 *  \param file A quicktime handle
 *  \param timescale The timescale, in which timestamps will be given.
 */
  
int lqt_add_text_track(quicktime_t * file, int timescale);

/** \brief Set the language for a text track
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *  \param language ISO-639 Language code
 *
 *  The language code is a 3-character code, English is "eng",
 *  Japanese is "jpn".
 */

void lqt_set_text_language(quicktime_t * file, int track, const char * language);

/** \brief Make a text track a chapter track
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *
 *  By default, text tracks are subtitles. By calling this function,
 *  you tell libquicktime, that the text track should be a chapter track.
 */


  
void lqt_set_chapter_track(quicktime_t * file, int track);

/** \brief Set the text box of a text track
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *  \param top Top border
 *  \param left Left border
 *  \param bottom Bottom border
 *  \param right Right border
 */
  
void lqt_set_text_box(quicktime_t * file, int track,
                      uint16_t top, uint16_t left,
                      uint16_t bottom, uint16_t right);

/** \brief Set the foreground color of a text track
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *  \param r Red
 *  \param g Green
 *  \param b Blue
 *  \param a Alpha
 *
 *  Color values are between 0x0000 and 0xffff. The alpha value
 *  is only used for mp4.
 */
  
void lqt_set_text_fg_color(quicktime_t * file, int track,
                           uint16_t r, uint16_t g,
                           uint16_t b, uint16_t a);

/** \brief Set the background color of a text track
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *  \param r Red
 *  \param g Green
 *  \param b Blue
 *  \param a Alpha
 *
 *  Color values are between 0x0000 and 0xffff. The alpha value
 *  is only used for mp4. For Quicktime, the text box is set to transparent
 *  if the alpha value is below 0x8000.
 */
  
void lqt_set_text_bg_color(quicktime_t * file, int track,
                           uint16_t r, uint16_t g,
                           uint16_t b, uint16_t a);

  
  
  
/** \brief Write a text sample
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *  \param text A null-terminated UTF-8 string
 *  \param duration The duration associated with this sample
 *  \returns 0 if a the text sample could be written to the file, nonzero else
 */
  
int lqt_write_text(quicktime_t * file, int track, const char * text, int64_t duration);
  
/**
   @}
*/
  
/** \defgroup text_decode Reading text
    \ingroup text
    \brief Decode text

    @{

*/

/** \brief Get the number of text tracks
 *  \param file A quicktime handle
 *  \returns The number of text tracks found in the file
 */
  
int lqt_text_tracks(quicktime_t * file);

/** \brief Get the text language
 *  \param file A quicktime handle
 *  \param track Track index (starting with 0)
 *  \param language Returns ISO-639 Language code
 *  \returns 1 on success, 0 on error.
 *
 *  The language code is a 3-character code, English is "eng",
 *  Japanese is "jpn".
 */

int lqt_get_text_language(quicktime_t * file, int track, char * language);