include/vlc_picture_pool.h

   1 /*****************************************************************************
   2  * vlc_picture_pool.h: picture pool definitions
   3  *****************************************************************************
   4  * Copyright (C) 2009 VLC authors and VideoLAN
   5  *
   6  * Authors: Laurent Aimar <fenrir _AT_ videolan _DOT_ org>
   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_PICTURE_POOL_H
  24 #define VLC_PICTURE_POOL_H 1
  25
  26 /**
  27  * \file
  28  * This file defines picture pool structures and functions in vlc
  29  */
  30
  31 #include <vlc_picture.h>
  32
  33 /**
  34  * Picture pool handle
  35  */
  36 typedef struct picture_pool_t picture_pool_t;
  37
  38 /**
  39  * Creates a pool of preallocated pictures. Free pictures can be allocated from
  40  * the pool, and are returned to the pool when they are no longer referenced.
  41  *
  42  * This avoids allocating and deallocationg pictures repeatedly, and ensures
  43  * that memory consumption remains within limits.
  44  *
  45  * To obtain a picture from the pool, use picture_pool_Get(). To increase and
  46  * decrease the reference count, use picture_Hold() and picture_Release()
  47  * respectively.
  48  *
  49  * @param count number of pictures in the array
  50  * @param tab array of pictures
  51  *
  52  * @return a pointer to the new pool on success, or NULL on error
  53  * (pictures are <b>not</b> released on error)
  54  */
  55 VLC_API picture_pool_t * picture_pool_New(unsigned count,
  56                                           picture_t *const *tab) VLC_USED;
  57
  58 /**
  59  * Allocates pictures from the heap and creates a picture pool with them.
  60  * This is a convenience wrapper for picture_NewFromFormat() and
  61  * picture_pool_New().
  62  *
  63  * @param fmt video format of pictures to allocate from the heap
  64  * @param count number of pictures to allocate
  65  *
  66  * @return a pointer to the new pool on success, NULL on error
  67  */
  68 VLC_API picture_pool_t * picture_pool_NewFromFormat(const video_format_t *fmt,
  69                                                     unsigned count) VLC_USED;
  70
  71 /**
  72  * Releases a pool created by picture_pool_New()
  73  * or picture_pool_NewFromFormat().
  74  *
  75  * @note If there are no pending references to the pooled pictures, and the
  76  * picture_resource_t.pf_destroy callback was not NULL, it will be invoked.
  77  * Otherwise the default callback will be used.
  78  *
  79  * @warning If there are pending references (a.k.a. late pictures), the
  80  * pictures will remain valid until the all pending references are dropped by
  81  * picture_Release().
  82  */
  83 VLC_API void picture_pool_Release( picture_pool_t * );
  84
  85 /**
  86  * Obtains a picture from a pool if any is immediately available.
  87  *
  88  * The picture must be released with picture_Release().
  89  *
  90  * @return a picture, or NULL if all pictures in the pool are allocated
  91  *
  92  * @note This function is thread-safe.
  93  */
  94 VLC_API picture_t * picture_pool_Get( picture_pool_t * ) VLC_USED;
  95
  96 /**
  97  * Obtains a picture from a pool.
  98  *
  99  * The picture must be released with picture_Release().
 100  *
 101  * @return a picture or NULL on memory error
 102  *
 103  * @note This function is thread-safe.
 104  */
 105 VLC_API picture_t *picture_pool_Wait(picture_pool_t *) VLC_USED;
 106
 107 /**
 108  * Cancel the picture pool.
 109  *
 110  * It won't return any pictures via picture_pool_Get or picture_pool_Wait if
 111  * canceled is true. This function will also unblock picture_pool_Wait.
 112  * picture_pool_Reset will also reset the cancel state to false.
 113  */
 114 void picture_pool_Cancel( picture_pool_t *, bool canceled );
 115
 116 /**
 117  * Reserves pictures from a pool and creates a new pool with those.
 118  *
 119  * When the new pool is released, pictures are returned to the master pool.
 120  * If the master pool was already released, pictures will be destroyed.
 121  *
 122  * @param count number of picture to reserve
 123  *
 124  * @return the new pool, or NULL if there were not enough pictures available
 125  * or on error
 126  *
 127  * @note This function is thread-safe (but it might return NULL if other
 128  * threads have already allocated too many pictures).
 129  */
 130 VLC_API picture_pool_t * picture_pool_Reserve(picture_pool_t *, unsigned count)
 131 VLC_USED;
 132
 133 /**
 134  * @return the total number of pictures in the given pool
 135  * @note This function is thread-safe.
 136  */
 137 unsigned picture_pool_GetSize(const picture_pool_t *);
 138
 139
 140 #endif /* VLC_PICTURE_POOL_H */
 141