include/vlc_picture.h

   1 /*****************************************************************************
   2  * vlc_picture.h: picture definitions
   3  *****************************************************************************
   4  * Copyright (C) 1999 - 2009 VLC authors and VideoLAN
   5  *
   6  * Authors: Vincent Seguin <seguin@via.ecp.fr>
   7  *          Samuel Hocevar <sam@via.ecp.fr>
   8  *          Olivier Aubert <oaubert 47 videolan d07 org>
   9  *
  10  * This program is free software; you can redistribute it and/or modify it
  11  * under the terms of the GNU Lesser General Public License as published by
  12  * the Free Software Foundation; either version 2.1 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public License
  21  * along with this program; if not, write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  23  *****************************************************************************/
  24
  25 #ifndef VLC_PICTURE_H
  26 #define VLC_PICTURE_H 1
  27
  28 #include <assert.h>
  29 #ifndef __cplusplus
  30 #include <stdatomic.h>
  31 #else
  32 #include <atomic>
  33 using std::atomic_uintptr_t;
  34 using std::memory_order_relaxed;
  35 using std::memory_order_release;
  36 #endif
  37
  38 /**
  39  * \file
  40  * This file defines picture structures and functions in vlc
  41  */
  42
  43 #include <vlc_es.h>
  44
  45 /** Description of a planar graphic field */
  46 typedef struct plane_t
  47 {
  48     uint8_t *p_pixels;                        /**< Start of the plane's data */
  49
  50     /* Variables used for fast memcpy operations */
  51     int i_lines;           /**< Number of lines, including margins */
  52     int i_pitch;           /**< Number of bytes in a line, including margins */
  53
  54     /** Size of a macropixel, defaults to 1 */
  55     int i_pixel_pitch;
  56
  57     /* Variables used for pictures with margins */
  58     int i_visible_lines;            /**< How many visible lines are there? */
  59     int i_visible_pitch;            /**< How many visible pixels are there? */
  60
  61 } plane_t;
  62
  63 /**
  64  * Maximum number of plane for a picture
  65  */
  66 #define PICTURE_PLANE_MAX (VOUT_MAX_PLANES)
  67
  68 typedef struct picture_context_t
  69 {
  70     void (*destroy)(struct picture_context_t *);
  71     struct picture_context_t *(*copy)(struct picture_context_t *);
  72     struct vlc_video_context *vctx;
  73 } picture_context_t;
  74
  75 typedef struct picture_buffer_t
  76 {
  77     int fd;
  78     void *base;
  79     size_t size;
  80     off_t offset;
  81 } picture_buffer_t;
  82
  83 typedef struct vlc_decoder_device vlc_decoder_device;
  84 typedef struct vlc_video_context vlc_video_context;
  85
  86 struct vlc_video_context_operations
  87 {
  88     void (*destroy)(void *priv);
  89 };
  90
  91 /** Decoder device type */
  92 enum vlc_video_context_type
  93 {
  94     VLC_VIDEO_CONTEXT_NONE,
  95     VLC_VIDEO_CONTEXT_VAAPI,
  96     VLC_VIDEO_CONTEXT_VDPAU,
  97     VLC_VIDEO_CONTEXT_DXVA2, /**< private: d3d9_video_context_t* */
  98     VLC_VIDEO_CONTEXT_D3D11VA,  /**< private: d3d11_video_context_t* */
  99     VLC_VIDEO_CONTEXT_AWINDOW, /**< private: android_video_context_t* */
 100     VLC_VIDEO_CONTEXT_NVDEC,
 101     VLC_VIDEO_CONTEXT_CVPX,
 102     VLC_VIDEO_CONTEXT_MMAL,
 103 };
 104
 105 VLC_API vlc_video_context * vlc_video_context_Create(vlc_decoder_device *,
 106                                         enum vlc_video_context_type private_type,
 107                                         size_t private_size,
 108                                         const struct vlc_video_context_operations *);
 109 VLC_API void vlc_video_context_Release(vlc_video_context *);
 110
 111 VLC_API enum vlc_video_context_type vlc_video_context_GetType(const vlc_video_context *);
 112 VLC_API void *vlc_video_context_GetPrivate(vlc_video_context *, enum vlc_video_context_type);
 113 VLC_API vlc_video_context *vlc_video_context_Hold(vlc_video_context *);
 114
 115 /**
 116  * Get the decoder device used by the device context.
 117  *
 118  * This will increment the refcount of the decoder device.
 119  */
 120 VLC_API vlc_decoder_device *vlc_video_context_HoldDevice(vlc_video_context *);
 121
 122
 123 /**
 124  * Video picture
 125  */
 126 struct picture_t
 127 {
 128     /**
 129      * The properties of the picture
 130      */
 131     video_frame_format_t format;
 132
 133     plane_t         p[PICTURE_PLANE_MAX];     /**< description of the planes */
 134     int             i_planes;                /**< number of allocated planes */
 135
 136     /** \name Picture management properties
 137      * These properties can be modified using the video output thread API,
 138      * but should never be written directly */
 139     /**@{*/
 140     vlc_tick_t      date;                                  /**< display date */
 141     bool            b_force;
 142     bool            b_still;
 143     /**@}*/
 144
 145     /** \name Picture dynamic properties
 146      * Those properties can be changed by the decoder
 147      * @{
 148      */
 149     bool            b_progressive;          /**< is it a progressive frame? */
 150     bool            b_top_field_first;             /**< which field is first */
 151     unsigned int    i_nb_fields;                  /**< number of displayed fields */
 152     picture_context_t *context;      /**< video format-specific data pointer */
 153     /**@}*/
 154
 155     /** Private data - the video output plugin might want to put stuff here to
 156      * keep track of the picture */
 157     void           *p_sys;
 158
 159     /** Next picture in a FIFO a pictures */
 160     struct picture_t *p_next;
 161
 162     atomic_uintptr_t refs;
 163 };
 164
 165 static inline vlc_video_context* picture_GetVideoContext(picture_t *pic)
 166 {
 167     return pic->context ? pic->context->vctx : NULL;
 168 }
 169
 170 /**
 171  * This function will create a new picture.
 172  * The picture created will implement a default release management compatible
 173  * with picture_Hold and picture_Release. This default management will release
 174  * p_sys, gc.p_sys fields if non NULL.
 175  */
 176 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;
 177
 178 /**
 179  * This function will create a new picture using the given format.
 180  *
 181  * When possible, it is preferred to use this function over picture_New
 182  * as more information about the format is kept.
 183  */
 184 VLC_API picture_t * picture_NewFromFormat( const video_format_t *p_fmt ) VLC_USED;
 185
 186 /**
 187  * Resource for a picture.
 188  */
 189 typedef struct
 190 {
 191     void *p_sys;
 192     void (*pf_destroy)(picture_t *);
 193
 194     /* Plane resources
 195      * XXX all fields MUST be set to the right value.
 196      */
 197     struct
 198     {
 199         uint8_t *p_pixels;  /**< Start of the plane's data */
 200         int i_lines;        /**< Number of lines, including margins */
 201         int i_pitch;        /**< Number of bytes in a line, including margins */
 202     } p[PICTURE_PLANE_MAX];
 203
 204 } picture_resource_t;
 205
 206 /**
 207  * This function will create a new picture using the provided resource.
 208  */
 209 VLC_API picture_t * picture_NewFromResource( const video_format_t *, const picture_resource_t * ) VLC_USED;
 210
 211 /**
 212  * Destroys a picture without references.
 213  *
 214  * This function destroys a picture with zero references left.
 215  * Never call this function directly. Use picture_Release() instead.
 216  */
 217 VLC_API void picture_Destroy(picture_t *picture);
 218
 219 /**
 220  * Increments the picture reference count.
 221  *
 222  * \return picture
 223  */
 224 static inline picture_t *picture_Hold(picture_t *picture)
 225 {
 226     atomic_fetch_add_explicit(&picture->refs, (uintptr_t)1,
 227                               memory_order_relaxed);
 228     return picture;
 229 }
 230
 231 /**
 232  * Decrements the picture reference count.
 233  *
 234  * If the reference count reaches zero, the picture is destroyed. If it was
 235  * allocated from a pool, the underlying picture buffer will be returned to the
 236  * pool. Otherwise, the picture buffer will be freed.
 237  */
 238 static inline void picture_Release(picture_t *picture)
 239 {
 240     uintptr_t refs = atomic_fetch_sub_explicit(&picture->refs, (uintptr_t)1,
 241                                                memory_order_release);
 242     vlc_assert(refs > 0);
 243     if (refs == 1)
 244         picture_Destroy(picture);
 245 }
 246
 247 /**
 248  * This function will copy all picture dynamic properties.
 249  */
 250 VLC_API void picture_CopyProperties( picture_t *p_dst, const picture_t *p_src );
 251
 252 /**
 253  * This function will reset a picture information (properties and quantizers).
 254  * It is sometimes useful for reusing pictures (like from a pool).
 255  */
 256 VLC_API void picture_Reset( picture_t * );
 257
 258 /**
 259  * This function will copy the picture pixels.
 260  * You can safely copy between pictures that do not have the same size,
 261  * only the compatible(smaller) part will be copied.
 262  */
 263 VLC_API void picture_CopyPixels( picture_t *p_dst, const picture_t *p_src );
 264 VLC_API void plane_CopyPixels( plane_t *p_dst, const plane_t *p_src );
 265
 266 /**
 267  * This function will copy both picture dynamic properties and pixels.
 268  * You have to notice that sometime a simple picture_Hold may do what
 269  * you want without the copy overhead.
 270  * Provided for convenience.
 271  *
 272  * \param p_dst pointer to the destination picture.
 273  * \param p_src pointer to the source picture.
 274  */
 275 VLC_API void picture_Copy( picture_t *p_dst, const picture_t *p_src );
 276
 277 /**
 278  * Perform a shallow picture copy
 279  *
 280  * This function makes a shallow copy of an existing picture. The same planes
 281  * and resources will be used, and the cloned picture reference count will be
 282  * incremented.
 283  *
 284  * \return A clone picture on success, NULL on error.
 285  */
 286 VLC_API picture_t *picture_Clone(picture_t *pic);
 287
 288 /**
 289  * This function will export a picture to an encoded bitstream.
 290  *
 291  * pp_image will contain the encoded bitstream in psz_format format.
 292  *
 293  * p_fmt can be NULL otherwise it will be set with the format used for the
 294  * picture before encoding.
 295  *
 296  * i_override_width/height allow to override the width and/or the height of the
 297  * picture to be encoded:
 298  *  - if strictly lower than 0, the original dimension will be used.
 299  *  - if equal to 0, it will be deduced from the other dimension which must be
 300  *  different to 0.
 301  *  - if strictly higher than 0, it will either override the dimension if b_crop
 302  *  is false, or crop the picture to the provided size if b_crop is true.
 303  * If at most one of them is > 0 then the picture aspect ratio will be kept.
 304  */
 305 VLC_API int picture_Export( vlc_object_t *p_obj, block_t **pp_image, video_format_t *p_fmt,
 306                             picture_t *p_picture, vlc_fourcc_t i_format, int i_override_width,
 307                             int i_override_height, bool b_crop );
 308
 309 /**
 310  * This function will setup all fields of a picture_t without allocating any
 311  * memory.
 312  * XXX The memory must already be initialized.
 313  * It does not need to be released.
 314  *
 315  * It will return VLC_EGENERIC if the core does not understand the requested
 316  * format.
 317  *
 318  * It can be useful to get the properties of planes.
 319  */
 320 VLC_API int picture_Setup( picture_t *, const video_format_t * );
 321
 322
 323 /*****************************************************************************
 324  * Shortcuts to access image components
 325  *****************************************************************************/
 326
 327 /* Plane indices */
 328 enum
 329 {
 330     Y_PLANE = 0,
 331     U_PLANE = 1,
 332     V_PLANE = 2,
 333     A_PLANE = 3,
 334 };
 335
 336 /* Shortcuts */
 337 #define Y_PIXELS     p[Y_PLANE].p_pixels
 338 #define Y_PITCH      p[Y_PLANE].i_pitch
 339 #define U_PIXELS     p[U_PLANE].p_pixels
 340 #define U_PITCH      p[U_PLANE].i_pitch
 341 #define V_PIXELS     p[V_PLANE].p_pixels
 342 #define V_PITCH      p[V_PLANE].i_pitch
 343 #define A_PIXELS     p[A_PLANE].p_pixels
 344 #define A_PITCH      p[A_PLANE].i_pitch
 345
 346 /**
 347  * Swap UV planes of a Tri Planars picture.
 348  *
 349  * It just swap the planes information without doing any copy.
 350  */
 351 static inline void picture_SwapUV(picture_t *picture)
 352 {
 353     vlc_assert(picture->i_planes == 3);
 354
 355     plane_t tmp_plane   = picture->p[U_PLANE];
 356     picture->p[U_PLANE] = picture->p[V_PLANE];
 357     picture->p[V_PLANE] = tmp_plane;
 358 }
 359
 360 /**@}*/
 361
 362 #endif /* VLC_PICTURE_H */