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     bool            b_multiview_left_eye; /**< left eye or right eye in multiview */
 152     unsigned int    i_nb_fields;                  /**< number of displayed fields */
 153     picture_context_t *context;      /**< video format-specific data pointer */
 154     /**@}*/
 155
 156     /** Private data - the video output plugin might want to put stuff here to
 157      * keep track of the picture */
 158     void           *p_sys;
 159
 160     /** Next picture in a FIFO a pictures */
 161     struct picture_t *p_next;
 162
 163     atomic_uintptr_t refs;
 164 };
 165
 166 static inline vlc_video_context* picture_GetVideoContext(picture_t *pic)
 167 {
 168     return pic->context ? pic->context->vctx : NULL;
 169 }
 170
 171 /**
 172  * Check whether a picture has other pictures linked
 173  */
 174 static inline bool picture_HasChainedPics(const picture_t *pic)
 175 {
 176     return pic->p_next != NULL;
 177 }
 178
 179 /**
 180  * picture chaining helpers
 181  */
 182
 183 typedef struct vlc_pic_chain {
 184     picture_t *front;
 185     picture_t *tail;
 186 } vlc_picture_chain_t;
 187
 188 /**
 189  * Initializes or reset a picture chain
 190  *
 191  * \warning do not call this if the chain still holds pictures, it will leak them.
 192  */
 193 static inline void vlc_picture_chain_Init(vlc_picture_chain_t *chain)
 194 {
 195     chain->front = NULL;
 196     // chain->tail = NULL not needed
 197 }
 198
 199 /**
 200  * Check whether a picture chain holds pictures or not.
 201  *
 202  * \return true if it is empty.
 203  */
 204 static inline bool vlc_picture_chain_IsEmpty(const vlc_picture_chain_t *chain)
 205 {
 206     return chain->front == NULL;
 207 }
 208
 209 /**
 210  * Check whether a picture chain has more than one picture.
 211  */
 212 static inline bool vlc_picture_chain_HasNext(const vlc_picture_chain_t *chain)
 213 {
 214     return !vlc_picture_chain_IsEmpty(chain) && chain->front != chain->tail;
 215 }
 216
 217 /**
 218  * Pop the front of a picture chain.
 219  *
 220  * The next picture in the chain becomes the front of the picture chain.
 221  *
 222  * \return the front of the picture chain (the picture itself)
 223  */
 224 static inline picture_t * vlc_picture_chain_PopFront(vlc_picture_chain_t *chain)
 225 {
 226     picture_t *front = chain->front;
 227     if (front)
 228     {
 229         chain->front = front->p_next;
 230         // unlink the front picture from the rest of the chain
 231         front->p_next = NULL;
 232     }
 233     return front;
 234 }
 235
 236 /**
 237  * Peek the front of a picture chain.
 238  *
 239  * The picture chain is unchanged.
 240  *
 241  * \return the front of the picture chain (the picture itself)
 242  */
 243 static inline picture_t * vlc_picture_chain_PeekFront(vlc_picture_chain_t *chain)
 244 {
 245     return chain->front;
 246 }
 247
 248 /**
 249  * Append a picture to a picture chain.
 250  *
 251  * \param chain the picture chain pointer
 252  * \param tail the known tail of the picture chain
 253  * \param pic the picture to append to the chain
 254  *
 255  * \return the new tail of the picture chain
 256  */
 257 static inline void vlc_picture_chain_Append(vlc_picture_chain_t *chain,
 258                                             picture_t *pic)
 259 {
 260     if (chain->front == NULL)
 261         chain->front = pic;
 262     else
 263         chain->tail->p_next = pic;
 264     // make sure the picture doesn't have chained pics
 265     vlc_assert( !picture_HasChainedPics( pic ) );
 266     pic->p_next = NULL; // we're appending a picture, not a chain
 267     chain->tail = pic;
 268 }
 269
 270 /**
 271  * Append a picture chain to a picture chain.
 272  */
 273 static inline void vlc_picture_chain_AppendChain(picture_t *chain, picture_t *tail)
 274 {
 275     chain->p_next = tail;
 276 }
 277
 278 /**
 279  * Copy the picture chain in another picture chain and clear the original
 280  * picture chain.
 281  *
 282  * \param in picture chain to copy and clear
 283  * \param out picture chain to copy into
 284  */
 285 static inline void vlc_picture_chain_GetAndClear(vlc_picture_chain_t *in,
 286                                                  vlc_picture_chain_t *out)
 287 {
 288     *out = *in;
 289     vlc_picture_chain_Init(in);
 290 }
 291
 292 /**
 293  * Reset a picture chain.
 294  *
 295  * \return the picture chain that was contained in the picture
 296  */
 297 static inline vlc_picture_chain_t picture_GetAndResetChain(picture_t *pic)
 298 {
 299     vlc_picture_chain_t chain = (vlc_picture_chain_t) { pic->p_next, pic->p_next };
 300     while ( chain.tail && chain.tail->p_next ) // find the proper tail
 301         chain.tail = chain.tail->p_next;
 302     pic->p_next = NULL;
 303     return chain;
 304 }
 305
 306
 307 /**
 308  * This function will create a new picture.
 309  * The picture created will implement a default release management compatible
 310  * with picture_Hold and picture_Release. This default management will release
 311  * p_sys, gc.p_sys fields if non NULL.
 312  */
 313 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;
 314
 315 /**
 316  * This function will create a new picture using the given format.
 317  *
 318  * When possible, it is preferred to use this function over picture_New
 319  * as more information about the format is kept.
 320  */
 321 VLC_API picture_t * picture_NewFromFormat( const video_format_t *p_fmt ) VLC_USED;
 322
 323 /**
 324  * Resource for a picture.
 325  */
 326 typedef struct
 327 {
 328     void *p_sys;
 329     void (*pf_destroy)(picture_t *);
 330
 331     /* Plane resources
 332      * XXX all fields MUST be set to the right value.
 333      */
 334     struct
 335     {
 336         uint8_t *p_pixels;  /**< Start of the plane's data */
 337         int i_lines;        /**< Number of lines, including margins */
 338         int i_pitch;        /**< Number of bytes in a line, including margins */
 339     } p[PICTURE_PLANE_MAX];
 340
 341 } picture_resource_t;
 342
 343 /**
 344  * This function will create a new picture using the provided resource.
 345  */
 346 VLC_API picture_t * picture_NewFromResource( const video_format_t *, const picture_resource_t * ) VLC_USED;
 347
 348 /**
 349  * Destroys a picture without references.
 350  *
 351  * This function destroys a picture with zero references left.
 352  * Never call this function directly. Use picture_Release() instead.
 353  */
 354 VLC_API void picture_Destroy(picture_t *picture);
 355
 356 /**
 357  * Increments the picture reference count.
 358  *
 359  * \return picture
 360  */
 361 static inline picture_t *picture_Hold(picture_t *picture)
 362 {
 363     atomic_fetch_add_explicit(&picture->refs, (uintptr_t)1,
 364                               memory_order_relaxed);
 365     return picture;
 366 }
 367
 368 /**
 369  * Decrements the picture reference count.
 370  *
 371  * If the reference count reaches zero, the picture is destroyed. If it was
 372  * allocated from a pool, the underlying picture buffer will be returned to the
 373  * pool. Otherwise, the picture buffer will be freed.
 374  */
 375 static inline void picture_Release(picture_t *picture)
 376 {
 377     uintptr_t refs = atomic_fetch_sub_explicit(&picture->refs, (uintptr_t)1,
 378                                                memory_order_release);
 379     vlc_assert(refs > 0);
 380     if (refs == 1)
 381         picture_Destroy(picture);
 382 }
 383
 384 /**
 385  * This function will copy all picture dynamic properties.
 386  */
 387 VLC_API void picture_CopyProperties( picture_t *p_dst, const picture_t *p_src );
 388
 389 /**
 390  * This function will reset a picture information (properties and quantizers).
 391  * It is sometimes useful for reusing pictures (like from a pool).
 392  */
 393 VLC_API void picture_Reset( picture_t * );
 394
 395 /**
 396  * This function will copy the picture pixels.
 397  * You can safely copy between pictures that do not have the same size,
 398  * only the compatible(smaller) part will be copied.
 399  */
 400 VLC_API void picture_CopyPixels( picture_t *p_dst, const picture_t *p_src );
 401 VLC_API void plane_CopyPixels( plane_t *p_dst, const plane_t *p_src );
 402
 403 /**
 404  * This function will copy both picture dynamic properties and pixels.
 405  * You have to notice that sometime a simple picture_Hold may do what
 406  * you want without the copy overhead.
 407  * Provided for convenience.
 408  *
 409  * \param p_dst pointer to the destination picture.
 410  * \param p_src pointer to the source picture.
 411  */
 412 VLC_API void picture_Copy( picture_t *p_dst, const picture_t *p_src );
 413
 414 /**
 415  * Perform a shallow picture copy
 416  *
 417  * This function makes a shallow copy of an existing picture. The same planes
 418  * and resources will be used, and the cloned picture reference count will be
 419  * incremented.
 420  *
 421  * \return A clone picture on success, NULL on error.
 422  */
 423 VLC_API picture_t *picture_Clone(picture_t *pic);
 424
 425 /**
 426  * This function will export a picture to an encoded bitstream.
 427  *
 428  * pp_image will contain the encoded bitstream in psz_format format.
 429  *
 430  * p_fmt can be NULL otherwise it will be set with the format used for the
 431  * picture before encoding.
 432  *
 433  * i_override_width/height allow to override the width and/or the height of the
 434  * picture to be encoded:
 435  *  - if strictly lower than 0, the original dimension will be used.
 436  *  - if equal to 0, it will be deduced from the other dimension which must be
 437  *  different to 0.
 438  *  - if strictly higher than 0, it will either override the dimension if b_crop
 439  *  is false, or crop the picture to the provided size if b_crop is true.
 440  * If at most one of them is > 0 then the picture aspect ratio will be kept.
 441  */
 442 VLC_API int picture_Export( vlc_object_t *p_obj, block_t **pp_image, video_format_t *p_fmt,
 443                             picture_t *p_picture, vlc_fourcc_t i_format, int i_override_width,
 444                             int i_override_height, bool b_crop );
 445
 446 /**
 447  * This function will setup all fields of a picture_t without allocating any
 448  * memory.
 449  * XXX The memory must already be initialized.
 450  * It does not need to be released.
 451  *
 452  * It will return VLC_EGENERIC if the core does not understand the requested
 453  * format.
 454  *
 455  * It can be useful to get the properties of planes.
 456  */
 457 VLC_API int picture_Setup( picture_t *, const video_format_t * );
 458
 459
 460 /*****************************************************************************
 461  * Shortcuts to access image components
 462  *****************************************************************************/
 463
 464 /* Plane indices */
 465 enum
 466 {
 467     Y_PLANE = 0,
 468     U_PLANE = 1,
 469     V_PLANE = 2,
 470     A_PLANE = 3,
 471 };
 472
 473 /* Shortcuts */
 474 #define Y_PIXELS     p[Y_PLANE].p_pixels
 475 #define Y_PITCH      p[Y_PLANE].i_pitch
 476 #define U_PIXELS     p[U_PLANE].p_pixels
 477 #define U_PITCH      p[U_PLANE].i_pitch
 478 #define V_PIXELS     p[V_PLANE].p_pixels
 479 #define V_PITCH      p[V_PLANE].i_pitch
 480 #define A_PIXELS     p[A_PLANE].p_pixels
 481 #define A_PITCH      p[A_PLANE].i_pitch
 482
 483 /**
 484  * Swap UV planes of a Tri Planars picture.
 485  *
 486  * It just swap the planes information without doing any copy.
 487  */
 488 static inline void picture_SwapUV(picture_t *picture)
 489 {
 490     vlc_assert(picture->i_planes == 3);
 491
 492     plane_t tmp_plane   = picture->p[U_PLANE];
 493     picture->p[U_PLANE] = picture->p[V_PLANE];
 494     picture->p[V_PLANE] = tmp_plane;
 495 }
 496
 497 /**@}*/
 498
 499 #endif /* VLC_PICTURE_H */