1 /***************************************************************************** 2 * vlc_picture_pool.h: picture pool definitions 3 ***************************************************************************** 4 * Copyright (C) 2009 VLC authors and VideoLAN 5 * $Id: 8b04370bfb320749eec6bcf09aaf0ba76b78058f $ 6 * 7 * Authors: Laurent Aimar <fenrir _AT_ videolan _DOT_ org> 8 * 9 * This program is free software; you can redistribute it and/or modify it 10 * under the terms of the GNU Lesser General Public License as published by 11 * the Free Software Foundation; either version 2.1 of the License, or 12 * (at your option) any later version. 13 * 14 * This program is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 * GNU Lesser General Public License for more details. 18 * 19 * You should have received a copy of the GNU Lesser General Public License 20 * along with this program; if not, write to the Free Software Foundation, 21 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. 22 *****************************************************************************/ 23 24 #ifndef VLC_PICTURE_POOL_H 25 #define VLC_PICTURE_POOL_H 1 26 27 /** 28 * \file 29 * This file defines picture pool structures and functions in vlc 30 */ 31 32 #include <vlc_picture.h> 33 34 /** 35 * Picture pool handle 36 */ 37 typedef struct picture_pool_t picture_pool_t; 38 39 /** 40 * Picture pool configuration 41 */ 42 typedef struct { 43 unsigned picture_count; 44 picture_t *const *picture; 45 46 int (*lock)(picture_t *); 47 void (*unlock)(picture_t *); 48 } picture_pool_configuration_t; 49 50 /** 51 * Creates a pool of preallocated pictures. Free pictures can be allocated from 52 * the pool, and are returned to the pool when they are no longer referenced. 53 * 54 * This avoids allocating and deallocationg pictures repeatedly, and ensures 55 * that memory consumption remains within limits. 56 * 57 * To obtain a picture from the pool, use picture_pool_Get(). To increase and 58 * decrease the reference count, use picture_Hold() and picture_Release() 59 * respectively. 60 * 61 * If defined, picture_pool_configuration_t::lock will be called before 62 * a picture is used, and picture_pool_configuration_t::unlock will be called 63 * as soon as a picture is returned to the pool. 64 * Those callbacks can modify picture_t::p and access picture_t::p_sys. 65 * 66 * @return A pointer to the new pool on success, or NULL on error 67 * (pictures are <b>not</b> released on error). 68 */ 69 VLC_API picture_pool_t * picture_pool_NewExtended( const picture_pool_configuration_t * ) VLC_USED; 70 71 /** 72 * Creates a picture pool with pictures in a given array. 73 * This is a convenience wrapper for picture_pool_NewExtended() without the 74 * lock and unlock callbacks. 75 * 76 * @param count number of pictures in the array 77 * @param tab array of pictures 78 * 79 * @return a pointer to the new pool on success, or NULL on error 80 * (pictures are <b>not</b> released on error) 81 */ 82 VLC_API picture_pool_t * picture_pool_New(unsigned count, 83 picture_t *const *tab) VLC_USED; 84 85 /** 86 * Allocates pictures from the heap and creates a picture pool with them. 87 * This is a convenience wrapper for picture_NewFromFormat() and 88 * picture_pool_New(). 89 * 90 * @param fmt video format of pictures to allocate from the heap 91 * @param count number of pictures to allocate 92 * 93 * @return a pointer to the new pool on success, NULL on error 94 */ 95 VLC_API picture_pool_t * picture_pool_NewFromFormat(const video_format_t *fmt, 96 unsigned count) VLC_USED; 97 98 /** 99 * Releases a pool created by picture_pool_NewExtended(), picture_pool_New() 100 * or picture_pool_NewFromFormat(). 101 * 102 * @note If there are no pending references to the pooled pictures, and the 103 * picture_resource_t.pf_destroy callback was not NULL, it will be invoked. 104 * Otherwise the default callback will be used. 105 * 106 * @warning If there are pending references (a.k.a. late pictures), the 107 * pictures will remain valid until the all pending references are dropped by 108 * picture_Release(). 109 */ 110 VLC_API void picture_pool_Release( picture_pool_t * ); 111 112 /** 113 * Obtains a picture from a pool if any is immediately available. 114 * 115 * The picture must be released with picture_Release(). 116 * 117 * @return a picture, or NULL if all pictures in the pool are allocated 118 * 119 * @note This function is thread-safe. 120 */ 121 VLC_API picture_t * picture_pool_Get( picture_pool_t * ) VLC_USED; 122 123 /** 124 * Obtains a picture from a pool. 125 * 126 * The picture must be released with picture_Release(). 127 * 128 * @return a picture or NULL on memory error 129 * 130 * @note This function is thread-safe. 131 */ 132 VLC_API picture_t *picture_pool_Wait(picture_pool_t *) VLC_USED; 133 134 /** 135 * Enumerates all pictures in a pool, both free and allocated. 136 * 137 * @param cb callback to invoke once for each picture 138 * @param data opaque data parameter for the callback (first argument) 139 * 140 * @note Allocated pictures may be accessed asynchronously by other threads. 141 * Therefore, only read-only picture parameters can be read by the callback, 142 * typically picture_t.p_sys. 143 * Provided those rules are respected, the function is thread-safe. 144 */ 145 VLC_API void picture_pool_Enum( picture_pool_t *, 146 void (*cb)(void *, picture_t *), void *data ); 147 148 /** 149 * Cancel the picture pool. 150 * 151 * It won't return any pictures via picture_pool_Get or picture_pool_Wait if 152 * canceled is true. This function will also unblock picture_pool_Wait. 153 * picture_pool_Reset will also reset the cancel state to false. 154 */ 155 void picture_pool_Cancel( picture_pool_t *, bool canceled ); 156 157 /** 158 * Test if a picture belongs to the picture pool 159 * 160 * FIXME: remove this function when the vout_PutPicture() hack is fixed. 161 */ 162 bool picture_pool_OwnsPic( picture_pool_t *, picture_t *); 163 164 /** 165 * Reserves pictures from a pool and creates a new pool with those. 166 * 167 * When the new pool is released, pictures are returned to the master pool. 168 * If the master pool was already released, pictures will be destroyed. 169 * 170 * @param count number of picture to reserve 171 * 172 * @return the new pool, or NULL if there were not enough pictures available 173 * or on error 174 * 175 * @note This function is thread-safe (but it might return NULL if other 176 * threads have already allocated too many pictures). 177 */ 178 VLC_API picture_pool_t * picture_pool_Reserve(picture_pool_t *, unsigned count) 179 VLC_USED; 180 181 /** 182 * @return the total number of pictures in the given pool 183 * @note This function is thread-safe. 184 */ 185 VLC_API unsigned picture_pool_GetSize(const picture_pool_t *); 186 187 188 #endif /* VLC_PICTURE_POOL_H */ 189 190