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 #include <vlc_atomic.h>
  30
  31 /**
  32  * \file
  33  * This file defines picture structures and functions in vlc
  34  */
  35
  36 #include <vlc_es.h>
  37
  38 /** Description of a planar graphic field */
  39 typedef struct plane_t
  40 {
  41     uint8_t *p_pixels;                        /**< Start of the plane's data */
  42
  43     /* Variables used for fast memcpy operations */
  44     int i_lines;           /**< Number of lines, including margins */
  45     int i_pitch;           /**< Number of bytes in a line, including margins */
  46
  47     /** Size of a macropixel, defaults to 1 */
  48     int i_pixel_pitch;
  49
  50     /* Variables used for pictures with margins */
  51     int i_visible_lines;            /**< How many visible lines are there? */
  52     int i_visible_pitch;            /**< How many visible pixels are there? */
  53
  54 } plane_t;
  55
  56 /**
  57  * Maximum number of plane for a picture
  58  */
  59 #define PICTURE_PLANE_MAX (VOUT_MAX_PLANES)
  60
  61 typedef struct picture_context_t
  62 {
  63     void (*destroy)(struct picture_context_t *);
  64     struct picture_context_t *(*copy)(struct picture_context_t *);
  65     struct vlc_video_context *vctx;
  66 } picture_context_t;
  67
  68 typedef struct picture_buffer_t
  69 {
  70     int fd;
  71     void *base;
  72     size_t size;
  73     off_t offset;
  74 } picture_buffer_t;
  75
  76 typedef struct vlc_decoder_device vlc_decoder_device;
  77 typedef struct vlc_video_context vlc_video_context;
  78
  79 struct vlc_video_context_operations
  80 {
  81     void (*destroy)(void *priv);
  82 };
  83
  84 /** Decoder device type */
  85 enum vlc_video_context_type
  86 {
  87     VLC_VIDEO_CONTEXT_NONE,
  88     VLC_VIDEO_CONTEXT_VAAPI,
  89     VLC_VIDEO_CONTEXT_VDPAU,
  90     VLC_VIDEO_CONTEXT_DXVA2, /**< private: d3d9_video_context_t* */
  91     VLC_VIDEO_CONTEXT_D3D11VA,  /**< private: d3d11_video_context_t* */
  92     VLC_VIDEO_CONTEXT_AWINDOW, /**< private: android_video_context_t* */
  93     VLC_VIDEO_CONTEXT_NVDEC,
  94     VLC_VIDEO_CONTEXT_CVPX,
  95     VLC_VIDEO_CONTEXT_MMAL,
  96 };
  97
  98 VLC_API vlc_video_context * vlc_video_context_Create(vlc_decoder_device *,
  99                                         enum vlc_video_context_type private_type,
 100                                         size_t private_size,
 101                                         const struct vlc_video_context_operations *);
 102 VLC_API void vlc_video_context_Release(vlc_video_context *);
 103
 104 VLC_API enum vlc_video_context_type vlc_video_context_GetType(const vlc_video_context *);
 105 VLC_API void *vlc_video_context_GetPrivate(vlc_video_context *, enum vlc_video_context_type);
 106 VLC_API vlc_video_context *vlc_video_context_Hold(vlc_video_context *);
 107
 108 /**
 109  * Get the decoder device used by the device context.
 110  *
 111  * This will increment the refcount of the decoder device.
 112  */
 113 VLC_API vlc_decoder_device *vlc_video_context_HoldDevice(vlc_video_context *);
 114
 115
 116 /**
 117  * Video picture
 118  */
 119 struct picture_t
 120 {
 121     /**
 122      * The properties of the picture
 123      */
 124     video_frame_format_t format;
 125
 126     plane_t         p[PICTURE_PLANE_MAX];     /**< description of the planes */
 127     int             i_planes;                /**< number of allocated planes */
 128
 129     /** \name Picture management properties
 130      * These properties can be modified using the video output thread API,
 131      * but should never be written directly */
 132     /**@{*/
 133     vlc_tick_t      date;                                  /**< display date */
 134     bool            b_force;
 135     bool            b_still;
 136     /**@}*/
 137
 138     /** \name Picture dynamic properties
 139      * Those properties can be changed by the decoder
 140      * @{
 141      */
 142     bool            b_progressive;          /**< is it a progressive frame? */
 143     bool            b_top_field_first;             /**< which field is first */
 144     bool            b_multiview_left_eye; /**< left eye or right eye in multiview */
 145     unsigned int    i_nb_fields;                  /**< number of displayed fields */
 146     picture_context_t *context;      /**< video format-specific data pointer */
 147     /**@}*/
 148
 149     /** Private data - the video output plugin might want to put stuff here to
 150      * keep track of the picture */
 151     void           *p_sys;
 152
 153     /** Next picture in a FIFO a pictures */
 154     struct picture_t *p_next;
 155
 156     vlc_atomic_rc_t refs;
 157 };
 158
 159 static inline vlc_video_context* picture_GetVideoContext(picture_t *pic)
 160 {
 161     return pic->context ? pic->context->vctx : NULL;
 162 }
 163
 164 /**
 165  * Check whether a picture has other pictures linked
 166  */
 167 static inline bool picture_HasChainedPics(const picture_t *pic)
 168 {
 169     return pic->p_next != NULL;
 170 }
 171
 172 /**
 173  * picture chaining helpers
 174  */
 175
 176 typedef struct vlc_pic_chain {
 177     picture_t *front;
 178     picture_t *tail;
 179 } vlc_picture_chain_t;
 180
 181 /**
 182  * Initializes or reset a picture chain
 183  *
 184  * \warning do not call this if the chain still holds pictures, it will leak them.
 185  */
 186 static inline void vlc_picture_chain_Init(vlc_picture_chain_t *chain)
 187 {
 188     chain->front = NULL;
 189     // chain->tail = NULL not needed
 190 }
 191
 192 /**
 193  * Check whether a picture chain holds pictures or not.
 194  *
 195  * \return true if it is empty.
 196  */
 197 static inline bool vlc_picture_chain_IsEmpty(const vlc_picture_chain_t *chain)
 198 {
 199     return chain->front == NULL;
 200 }
 201
 202 /**
 203  * Check whether a picture chain has more than one picture.
 204  */
 205 static inline bool vlc_picture_chain_HasNext(const vlc_picture_chain_t *chain)
 206 {
 207     return !vlc_picture_chain_IsEmpty(chain) && chain->front != chain->tail;
 208 }
 209
 210 /**
 211  * Pop the front of a picture chain.
 212  *
 213  * The next picture in the chain becomes the front of the picture chain.
 214  *
 215  * \return the front of the picture chain (the picture itself)
 216  */
 217 static inline picture_t * vlc_picture_chain_PopFront(vlc_picture_chain_t *chain)
 218 {
 219     picture_t *front = chain->front;
 220     if (front)
 221     {
 222         chain->front = front->p_next;
 223         // unlink the front picture from the rest of the chain
 224         front->p_next = NULL;
 225     }
 226     return front;
 227 }
 228
 229 /**
 230  * Peek the front of a picture chain.
 231  *
 232  * The picture chain is unchanged.
 233  *
 234  * \return the front of the picture chain (the picture itself)
 235  */
 236 static inline picture_t * vlc_picture_chain_PeekFront(vlc_picture_chain_t *chain)
 237 {
 238     return chain->front;
 239 }
 240
 241 /**
 242  * Append a picture to a picture chain.
 243  *
 244  * \param chain the picture chain pointer
 245  * \param tail the known tail of the picture chain
 246  * \param pic the picture to append to the chain
 247  *
 248  * \return the new tail of the picture chain
 249  */
 250 static inline void vlc_picture_chain_Append(vlc_picture_chain_t *chain,
 251                                             picture_t *pic)
 252 {
 253     if (chain->front == NULL)
 254         chain->front = pic;
 255     else
 256         chain->tail->p_next = pic;
 257     // make sure the picture doesn't have chained pics
 258     vlc_assert( !picture_HasChainedPics( pic ) );
 259     pic->p_next = NULL; // we're appending a picture, not a chain
 260     chain->tail = pic;
 261 }
 262
 263 /**
 264  * Append a picture chain to a picture chain.
 265  */
 266 static inline void vlc_picture_chain_AppendChain(picture_t *chain, picture_t *tail)
 267 {
 268     chain->p_next = tail;
 269 }
 270
 271 /**
 272  * Copy the picture chain in another picture chain and clear the original
 273  * picture chain.
 274  *
 275  * \param in picture chain to copy and clear
 276  * \param out picture chain to copy into
 277  */
 278 static inline void vlc_picture_chain_GetAndClear(vlc_picture_chain_t *in,
 279                                                  vlc_picture_chain_t *out)
 280 {
 281     *out = *in;
 282     vlc_picture_chain_Init(in);
 283 }
 284
 285 /**
 286  * Reset a picture chain.
 287  *
 288  * \return the picture chain that was contained in the picture
 289  */
 290 static inline vlc_picture_chain_t picture_GetAndResetChain(picture_t *pic)
 291 {
 292     vlc_picture_chain_t chain = { pic->p_next, pic->p_next };
 293     while ( chain.tail && chain.tail->p_next ) // find the proper tail
 294         chain.tail = chain.tail->p_next;
 295     pic->p_next = NULL;
 296     return chain;
 297 }
 298
 299
 300 /**
 301  * This function will create a new picture.
 302  * The picture created will implement a default release management compatible
 303  * with picture_Hold and picture_Release. This default management will release
 304  * p_sys, gc.p_sys fields if non NULL.
 305  */
 306 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;
 307
 308 /**
 309  * This function will create a new picture using the given format.
 310  *
 311  * When possible, it is preferred to use this function over picture_New
 312  * as more information about the format is kept.
 313  */
 314 VLC_API picture_t * picture_NewFromFormat( const video_format_t *p_fmt ) VLC_USED;
 315
 316 /**
 317  * Resource for a picture.
 318  */
 319 typedef struct
 320 {
 321     void *p_sys;
 322     void (*pf_destroy)(picture_t *);
 323
 324     /* Plane resources
 325      * XXX all fields MUST be set to the right value.
 326      */
 327     struct
 328     {
 329         uint8_t *p_pixels;  /**< Start of the plane's data */
 330         int i_lines;        /**< Number of lines, including margins */
 331         int i_pitch;        /**< Number of bytes in a line, including margins */
 332     } p[PICTURE_PLANE_MAX];
 333
 334 } picture_resource_t;
 335
 336 /**
 337  * This function will create a new picture using the provided resource.
 338  */
 339 VLC_API picture_t * picture_NewFromResource( const video_format_t *, const picture_resource_t * ) VLC_USED;
 340
 341 /**
 342  * Destroys a picture without references.
 343  *
 344  * This function destroys a picture with zero references left.
 345  * Never call this function directly. Use picture_Release() instead.
 346  */
 347 VLC_API void picture_Destroy(picture_t *picture);
 348
 349 /**
 350  * Increments the picture reference count.
 351  *
 352  * \return picture
 353  */
 354 static inline picture_t *picture_Hold(picture_t *picture)
 355 {
 356     vlc_atomic_rc_inc(&picture->refs);
 357     return picture;
 358 }
 359
 360 /**
 361  * Decrements the picture reference count.
 362  *
 363  * If the reference count reaches zero, the picture is destroyed. If it was
 364  * allocated from a pool, the underlying picture buffer will be returned to the
 365  * pool. Otherwise, the picture buffer will be freed.
 366  */
 367 static inline void picture_Release(picture_t *picture)
 368 {
 369     if (vlc_atomic_rc_dec(&picture->refs))
 370         picture_Destroy(picture);
 371 }
 372
 373 /**
 374  * This function will copy all picture dynamic properties.
 375  */
 376 VLC_API void picture_CopyProperties( picture_t *p_dst, const picture_t *p_src );
 377
 378 /**
 379  * This function will reset a picture information (properties and quantizers).
 380  * It is sometimes useful for reusing pictures (like from a pool).
 381  */
 382 VLC_API void picture_Reset( picture_t * );
 383
 384 /**
 385  * This function will copy the picture pixels.
 386  * You can safely copy between pictures that do not have the same size,
 387  * only the compatible(smaller) part will be copied.
 388  */
 389 VLC_API void picture_CopyPixels( picture_t *p_dst, const picture_t *p_src );
 390 VLC_API void plane_CopyPixels( plane_t *p_dst, const plane_t *p_src );
 391
 392 /**
 393  * This function will copy both picture dynamic properties and pixels.
 394  * You have to notice that sometime a simple picture_Hold may do what
 395  * you want without the copy overhead.
 396  * Provided for convenience.
 397  *
 398  * \param p_dst pointer to the destination picture.
 399  * \param p_src pointer to the source picture.
 400  */
 401 VLC_API void picture_Copy( picture_t *p_dst, const picture_t *p_src );
 402
 403 /**
 404  * Perform a shallow picture copy
 405  *
 406  * This function makes a shallow copy of an existing picture. The same planes
 407  * and resources will be used, and the cloned picture reference count will be
 408  * incremented.
 409  *
 410  * \return A clone picture on success, NULL on error.
 411  */
 412 VLC_API picture_t *picture_Clone(picture_t *pic);
 413
 414 /**
 415  * This function will export a picture to an encoded bitstream.
 416  *
 417  * pp_image will contain the encoded bitstream in psz_format format.
 418  *
 419  * p_fmt can be NULL otherwise it will be set with the format used for the
 420  * picture before encoding.
 421  *
 422  * i_override_width/height allow to override the width and/or the height of the
 423  * picture to be encoded:
 424  *  - if strictly lower than 0, the original dimension will be used.
 425  *  - if equal to 0, it will be deduced from the other dimension which must be
 426  *  different to 0.
 427  *  - if strictly higher than 0, it will either override the dimension if b_crop
 428  *  is false, or crop the picture to the provided size if b_crop is true.
 429  * If at most one of them is > 0 then the picture aspect ratio will be kept.
 430  */
 431 VLC_API int picture_Export( vlc_object_t *p_obj, block_t **pp_image, video_format_t *p_fmt,
 432                             picture_t *p_picture, vlc_fourcc_t i_format, int i_override_width,
 433                             int i_override_height, bool b_crop );
 434
 435 /**
 436  * This function will setup all fields of a picture_t without allocating any
 437  * memory.
 438  * XXX The memory must already be initialized.
 439  * It does not need to be released.
 440  *
 441  * It will return VLC_EGENERIC if the core does not understand the requested
 442  * format.
 443  *
 444  * It can be useful to get the properties of planes.
 445  */
 446 VLC_API int picture_Setup( picture_t *, const video_format_t * );
 447
 448
 449 /*****************************************************************************
 450  * Shortcuts to access image components
 451  *****************************************************************************/
 452
 453 /* Plane indices */
 454 enum
 455 {
 456     Y_PLANE = 0,
 457     U_PLANE = 1,
 458     V_PLANE = 2,
 459     A_PLANE = 3,
 460 };
 461
 462 /* Shortcuts */
 463 #define Y_PIXELS     p[Y_PLANE].p_pixels
 464 #define Y_PITCH      p[Y_PLANE].i_pitch
 465 #define U_PIXELS     p[U_PLANE].p_pixels
 466 #define U_PITCH      p[U_PLANE].i_pitch
 467 #define V_PIXELS     p[V_PLANE].p_pixels
 468 #define V_PITCH      p[V_PLANE].i_pitch
 469 #define A_PIXELS     p[A_PLANE].p_pixels
 470 #define A_PITCH      p[A_PLANE].i_pitch
 471
 472 /**
 473  * Swap UV planes of a Tri Planars picture.
 474  *
 475  * It just swap the planes information without doing any copy.
 476  */
 477 static inline void picture_SwapUV(picture_t *picture)
 478 {
 479     vlc_assert(picture->i_planes == 3);
 480
 481     plane_t tmp_plane   = picture->p[U_PLANE];
 482     picture->p[U_PLANE] = picture->p[V_PLANE];
 483     picture->p[V_PLANE] = tmp_plane;
 484 }
 485
 486 /**@}*/
 487
 488 #endif /* VLC_PICTURE_H */