home *** CD-ROM | disk | FTP | other *** search
/ mail.altrad.com / 2015.02.mail.altrad.com.tar / mail.altrad.com / TEST / vlc-2-0-5-win32.exe / sdk / include / vlc / plugins / vlc_picture.h < prev    next >
C/C++ Source or Header  |  2012-12-12  |  11KB  |  335 lines
  1. /*****************************************************************************
  2.  * vlc_picture.h: picture definitions
  3.  *****************************************************************************
  4.  * Copyright (C) 1999 - 2009 VLC authors and VideoLAN
  5.  * $Id: 75502cab11099d73441f6912c383d0dafe91c7ba $
  6.  *
  7.  * Authors: Vincent Seguin <seguin@via.ecp.fr>
  8.  *          Samuel Hocevar <sam@via.ecp.fr>
  9.  *          Olivier Aubert <oaubert 47 videolan d07 org>
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify it
  12.  * under the terms of the GNU Lesser General Public License as published by
  13.  * the Free Software Foundation; either version 2.1 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  19.  * GNU Lesser General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU Lesser General Public License
  22.  * along with this program; if not, write to the Free Software Foundation,
  23.  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  24.  *****************************************************************************/
  25.  
  26. #ifndef VLC_PICTURE_H
  27. #define VLC_PICTURE_H 1
  28.  
  29. /**
  30.  * \file
  31.  * This file defines picture structures and functions in vlc
  32.  */
  33.  
  34. #include <vlc_es.h>
  35.  
  36. /** Description of a planar graphic field */
  37. typedef struct plane_t
  38. {
  39.     uint8_t *p_pixels;                        /**< Start of the plane's data */
  40.  
  41.     /* Variables used for fast memcpy operations */
  42.     int i_lines;           /**< Number of lines, including margins */
  43.     int i_pitch;           /**< Number of bytes in a line, including margins */
  44.  
  45.     /** Size of a macropixel, defaults to 1 */
  46.     int i_pixel_pitch;
  47.  
  48.     /* Variables used for pictures with margins */
  49.     int i_visible_lines;            /**< How many visible lines are there ? */
  50.     int i_visible_pitch;            /**< How many visible pixels are there ? */
  51.  
  52. } plane_t;
  53.  
  54. /**
  55.  * Maximum number of plane for a picture
  56.  */
  57. #define PICTURE_PLANE_MAX (VOUT_MAX_PLANES)
  58.  
  59. /**
  60.  * A private definition to help overloading picture release
  61.  */
  62. typedef struct picture_release_sys_t picture_release_sys_t;
  63.  
  64. /**
  65.  * Video picture
  66.  */
  67. struct picture_t
  68. {
  69.     /**
  70.      * The properties of the picture
  71.      */
  72.     video_frame_format_t format;
  73.  
  74.     void           *p_data_orig;                /**< pointer before memalign */
  75.     plane_t         p[PICTURE_PLANE_MAX];     /**< description of the planes */
  76.     int             i_planes;                /**< number of allocated planes */
  77.  
  78.     /** \name Picture management properties
  79.      * These properties can be modified using the video output thread API,
  80.      * but should never be written directly */
  81.     /**@{*/
  82.     unsigned        i_refcount;                  /**< link reference counter */
  83.     mtime_t         date;                                  /**< display date */
  84.     bool            b_force;
  85.     /**@}*/
  86.  
  87.     /** \name Picture dynamic properties
  88.      * Those properties can be changed by the decoder
  89.      * @{
  90.      */
  91.     bool            b_progressive;          /**< is it a progressive frame ? */
  92.     bool            b_top_field_first;             /**< which field is first */
  93.     unsigned int    i_nb_fields;                  /**< # of displayed fields */
  94.     int8_t         *p_q;                           /**< quantification table */
  95.     int             i_qstride;                    /**< quantification stride */
  96.     int             i_qtype;                       /**< quantification style */
  97.     /**@}*/
  98.  
  99.     /** Private data - the video output plugin might want to put stuff here to
  100.      * keep track of the picture */
  101.     picture_sys_t * p_sys;
  102.  
  103.     /** This way the picture_Release can be overloaded */
  104.     void (*pf_release)( picture_t * );
  105.     picture_release_sys_t *p_release_sys;
  106.  
  107.     /** Next picture in a FIFO a pictures */
  108.     struct picture_t *p_next;
  109. };
  110.  
  111. /**
  112.  * This function will create a new picture.
  113.  * The picture created will implement a default release management compatible
  114.  * with picture_Hold and picture_Release. This default management will release
  115.  * p_sys, p_q, p_data_orig fields if non NULL.
  116.  */
  117. VLC_API picture_t * picture_New( vlc_fourcc_t i_chroma, int i_width, int i_height, int i_sar_num, int i_sar_den ) VLC_USED;
  118.  
  119. /**
  120.  * This function will create a new picture using the given format.
  121.  *
  122.  * When possible, it is preferred to use this function over picture_New
  123.  * as more information about the format is kept.
  124.  */
  125. VLC_API picture_t * picture_NewFromFormat( const video_format_t *p_fmt ) VLC_USED;
  126.  
  127. /**
  128.  * Resource for a picture.
  129.  */
  130. typedef struct
  131. {
  132.     picture_sys_t *p_sys;
  133.  
  134.     /* Plane resources
  135.      * XXX all fields MUST be set to the right value.
  136.      */
  137.     struct
  138.     {
  139.         uint8_t *p_pixels;  /**< Start of the plane's data */
  140.         int i_lines;        /**< Number of lines, including margins */
  141.         int i_pitch;        /**< Number of bytes in a line, including margins */
  142.     } p[PICTURE_PLANE_MAX];
  143.  
  144. } picture_resource_t;
  145.  
  146. /**
  147.  * This function will create a new picture using the provided resource.
  148.  *
  149.  * If the resource is NULL then a plain picture_NewFromFormat is returned.
  150.  */
  151. VLC_API picture_t * picture_NewFromResource( const video_format_t *, const picture_resource_t * ) VLC_USED;
  152.  
  153. /**
  154.  * This function will force the destruction a picture.
  155.  * The value of the picture reference count should be 0 before entering this
  156.  * function.
  157.  * Unless used for reimplementing pf_release, you should not use this
  158.  * function but picture_Release.
  159.  */
  160. VLC_API void picture_Delete( picture_t * );
  161.  
  162. /**
  163.  * This function will increase the picture reference count.
  164.  * It will not have any effect on picture obtained from vout
  165.  *
  166.  * It returns the given picture for convenience.
  167.  */
  168. static inline picture_t *picture_Hold( picture_t *p_picture )
  169. {
  170.     if( p_picture->pf_release )
  171.         p_picture->i_refcount++;
  172.     return p_picture;
  173. }
  174. /**
  175.  * This function will release a picture.
  176.  * It will not have any effect on picture obtained from vout
  177.  */
  178. static inline void picture_Release( picture_t *p_picture )
  179. {
  180.     /* FIXME why do we let pf_release handle the i_refcount ? */
  181.     if( p_picture->pf_release )
  182.         p_picture->pf_release( p_picture );
  183. }
  184.  
  185. /**
  186.  * This function will return true if you are not the only owner of the
  187.  * picture.
  188.  *
  189.  * It is only valid if it is created using picture_New.
  190.  */
  191. static inline bool picture_IsReferenced( picture_t *p_picture )
  192. {
  193.     return p_picture->i_refcount > 1;
  194. }
  195.  
  196. /**
  197.  * Cleanup quantization matrix data and set to 0
  198.  */
  199. static inline void picture_CleanupQuant( picture_t *p_pic )
  200. {
  201.     free( p_pic->p_q );
  202.     p_pic->p_q = NULL;
  203.     p_pic->i_qstride = 0;
  204.     p_pic->i_qtype = 0;
  205. }
  206.  
  207. /**
  208.  * This function will copy all picture dynamic properties.
  209.  */
  210. static inline void picture_CopyProperties( picture_t *p_dst, const picture_t *p_src )
  211. {
  212.     p_dst->date = p_src->date;
  213.     p_dst->b_force = p_src->b_force;
  214.  
  215.     p_dst->b_progressive = p_src->b_progressive;
  216.     p_dst->i_nb_fields = p_src->i_nb_fields;
  217.     p_dst->b_top_field_first = p_src->b_top_field_first;
  218.  
  219.     /* FIXME: copy ->p_q and ->p_qstride */
  220. }
  221.  
  222. /**
  223.  * This function will reset a picture information (properties and quantizers).
  224.  * It is sometimes useful for reusing pictures (like from a pool).
  225.  */
  226. VLC_API void picture_Reset( picture_t * );
  227.  
  228. /**
  229.  * This function will copy the picture pixels.
  230.  * You can safely copy between pictures that do not have the same size,
  231.  * only the compatible(smaller) part will be copied.
  232.  */
  233. VLC_API void picture_CopyPixels( picture_t *p_dst, const picture_t *p_src );
  234. VLC_API void plane_CopyPixels( plane_t *p_dst, const plane_t *p_src );
  235.  
  236. /**
  237.  * This function will copy both picture dynamic properties and pixels.
  238.  * You have to notice that sometime a simple picture_Hold may do what
  239.  * you want without the copy overhead.
  240.  * Provided for convenience.
  241.  *
  242.  * \param p_dst pointer to the destination picture.
  243.  * \param p_src pointer to the source picture.
  244.  */
  245. static inline void picture_Copy( picture_t *p_dst, const picture_t *p_src )
  246. {
  247.     picture_CopyPixels( p_dst, p_src );
  248.     picture_CopyProperties( p_dst, p_src );
  249. }
  250.  
  251. /**
  252.  * This function will export a picture to an encoded bitstream.
  253.  *
  254.  * pp_image will contain the encoded bitstream in psz_format format.
  255.  *
  256.  * p_fmt can be NULL otherwise it will be set with the format used for the
  257.  * picture before encoding.
  258.  *
  259.  * i_override_width/height allow to override the width and/or the height of the
  260.  * picture to be encoded:
  261.  *  - if strictly lower than 0, the original dimension will be used.
  262.  *  - if equal to 0, it will be deduced from the other dimension which must be
  263.  *  different to 0.
  264.  *  - if strictly higher than 0, it will override the dimension.
  265.  * If at most one of them is > 0 then the picture aspect ratio will be kept.
  266.  */
  267. VLC_API int picture_Export( vlc_object_t *p_obj, block_t **pp_image, video_format_t *p_fmt, picture_t *p_picture, vlc_fourcc_t i_format, int i_override_width, int i_override_height );
  268.  
  269. /**
  270.  * This function will setup all fields of a picture_t without allocating any
  271.  * memory.
  272.  * XXX The memory must already be initialized.
  273.  * It does not need to be released.
  274.  *
  275.  * It will return VLC_EGENERIC if the core does not understand the requested
  276.  * format.
  277.  *
  278.  * It can be useful to get the properties of planes.
  279.  */
  280. VLC_API int picture_Setup( picture_t *, vlc_fourcc_t i_chroma, int i_width, int i_height, int i_sar_num, int i_sar_den );
  281.  
  282.  
  283. /**
  284.  * This function will blend a given subpicture onto a picture.
  285.  *
  286.  * The subpicture and all its region must:
  287.  *  - be absolute.
  288.  *  - not be ephemere.
  289.  *  - not have the fade flag.
  290.  *  - contains only picture (no text rendering).
  291.  */
  292. VLC_API void picture_BlendSubpicture( picture_t *, filter_t *p_blend, subpicture_t * );
  293.  
  294.  
  295. /*****************************************************************************
  296.  * Flags used to describe the status of a picture
  297.  *****************************************************************************/
  298.  
  299. /* Quantification type */
  300. enum
  301. {
  302.     QTYPE_NONE,
  303.  
  304.     QTYPE_MPEG1,
  305.     QTYPE_MPEG2,
  306.     QTYPE_H264,
  307. };
  308.  
  309. /*****************************************************************************
  310.  * Shortcuts to access image components
  311.  *****************************************************************************/
  312.  
  313. /* Plane indices */
  314. enum
  315. {
  316.     Y_PLANE = 0,
  317.     U_PLANE = 1,
  318.     V_PLANE = 2,
  319.     A_PLANE = 3,
  320. };
  321.  
  322. /* Shortcuts */
  323. #define Y_PIXELS     p[Y_PLANE].p_pixels
  324. #define Y_PITCH      p[Y_PLANE].i_pitch
  325. #define U_PIXELS     p[U_PLANE].p_pixels
  326. #define U_PITCH      p[U_PLANE].i_pitch
  327. #define V_PIXELS     p[V_PLANE].p_pixels
  328. #define V_PITCH      p[V_PLANE].i_pitch
  329. #define A_PIXELS     p[A_PLANE].p_pixels
  330. #define A_PITCH      p[A_PLANE].i_pitch
  331.  
  332. /**@}*/
  333.  
  334. #endif /* VLC_PICTURE_H */
  335.