include/vlc/libvlc_picture.h

   1 /*****************************************************************************
   2  * libvlc_picture.h:  libvlc external API
   3  *****************************************************************************
   4  * Copyright (C) 2018 VLC authors and VideoLAN
   5  *
   6  * Authors: Hugo Beauzée-Luyssen <hugo@beauzee.fr>
   7  *
   8  * This program is free software; you can redistribute it and/or modify it
   9  * under the terms of the GNU Lesser General Public License as published by
  10  * the Free Software Foundation; either version 2.1 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16  * GNU Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public License
  19  * along with this program; if not, write to the Free Software Foundation,
  20  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  21  *****************************************************************************/
  22
  23 #ifndef VLC_LIBVLC_PICTURE_H
  24 #define VLC_LIBVLC_PICTURE_H 1
  25
  26 # ifdef __cplusplus
  27 extern "C" {
  28 # endif
  29
  30 typedef struct libvlc_picture_t libvlc_picture_t;
  31
  32 typedef enum libvlc_picture_type_t
  33 {
  34     libvlc_picture_Argb,
  35     libvlc_picture_Png,
  36     libvlc_picture_Jpg,
  37 } libvlc_picture_type_t;
  38
  39 /**
  40  * Increment the reference count of this picture.
  41  *
  42  * \see libvlc_picture_release()
  43  * \param pic A picture object
  44  */
  45 LIBVLC_API void
  46 libvlc_picture_retain( libvlc_picture_t* pic );
  47
  48 /**
  49  * Decrement the reference count of this picture.
  50  * When the reference count reaches 0, the picture will be released.
  51  * The picture must not be accessed after calling this function.
  52  *
  53  * \see libvlc_picture_retain
  54  * \param pic A picture object
  55  */
  56 LIBVLC_API void
  57 libvlc_picture_release( libvlc_picture_t* pic );
  58
  59 /**
  60  * Saves this picture to a file. The image format is the same as the one
  61  * returned by \link libvlc_picture_type \endlink
  62  *
  63  * \param pic A picture object
  64  * \param path The path to the generated file
  65  * \return 0 in case of success, -1 otherwise
  66  */
  67 LIBVLC_API int
  68 libvlc_picture_save( const libvlc_picture_t* pic, const char* path );
  69
  70 /**
  71  * Returns the image internal buffer, including potential padding.
  72  * The libvlc_picture_t owns the returned buffer, which must not be modified nor
  73  * freed.
  74  *
  75  * \param pic A picture object
  76  * \param size A pointer to a size_t that will hold the size of the buffer [required]
  77  * \return A pointer to the internal buffer.
  78  */
  79 LIBVLC_API const unsigned char*
  80 libvlc_picture_get_buffer( const libvlc_picture_t* pic, size_t *size );
  81
  82 /**
  83  * Returns the picture type
  84  *
  85  * \param pic A picture object
  86  * \see libvlc_picture_type_t
  87  */
  88 LIBVLC_API libvlc_picture_type_t
  89 libvlc_picture_type( const libvlc_picture_t* pic );
  90
  91 /**
  92  * Returns the image stride, ie. the number of bytes per line.
  93  * This can only be called on images of type libvlc_picture_Argb
  94  *
  95  * \param pic A picture object
  96  */
  97 LIBVLC_API unsigned int
  98 libvlc_picture_get_stride( const libvlc_picture_t* pic );
  99
 100 /**
 101  * Returns the width of the image in pixels
 102  *
 103  * \param pic A picture object
 104  */
 105 LIBVLC_API unsigned int
 106 libvlc_picture_get_width( const libvlc_picture_t* pic );
 107
 108 /**
 109  * Returns the height of the image in pixels
 110  *
 111  * \param pic A picture object
 112  */
 113 LIBVLC_API unsigned int
 114 libvlc_picture_get_height( const libvlc_picture_t* pic );
 115
 116 /**
 117  * Returns the time at which this picture was generated, in milliseconds
 118  * \param pic A picture object
 119  */
 120 LIBVLC_API libvlc_time_t
 121 libvlc_picture_get_time( const libvlc_picture_t* pic );
 122
 123 # ifdef __cplusplus
 124 }
 125 # endif
 126
 127 #endif // VLC_LIBVLC_PICTURE_H