decoder: separate aout initialization from buffer allocation
[vlc.git] / include / vlc_picture_pool.h
1 /*****************************************************************************
2  * vlc_picture_pool.h: picture pool definitions
3  *****************************************************************************
4  * Copyright (C) 2009 VLC authors and VideoLAN
5  * $Id$
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  * XXX it is not thread safe, all pool manipulations and picture_Release
38  * must be properly locked if needed.
39  */
40 typedef struct picture_pool_t picture_pool_t;
41
42 /**
43  * Picture pool configuration
44  */
45 typedef struct {
46     int       picture_count;
47     picture_t **picture;
48
49     int       (*lock)(picture_t *);
50     void      (*unlock)(picture_t *);
51 } picture_pool_configuration_t;
52
53 /**
54  * It creates a picture_pool_t wrapping the given configuration.
55  *
56  * It avoids useless picture creations/destructions.
57  * The given picture must not have a reference count greater than 1.
58  * The pool takes ownership of the picture and MUST not be used directly.
59  * When deleted, the pool will release the pictures using picture_Release.
60  * If defined, picture_pool_configuration_t::lock will be called before
61  * a picture is used, and picture_pool_configuration_t::unlock will be called
62  * as soon as a picture is unused. They are allowed to modify picture_t::p and
63  * access picture_t::p_sys.
64  */
65 VLC_API picture_pool_t * picture_pool_NewExtended( const picture_pool_configuration_t * ) VLC_USED;
66
67 /**
68  * It creates a picture_pool_t wrapping the given arrays of picture.
69  *
70  * It is provided as convenience.
71  */
72 VLC_API picture_pool_t * picture_pool_New( int picture_count, picture_t *picture[] ) VLC_USED;
73
74 /**
75  * It creates a picture_pool_t creating images using the given format.
76  *
77  * Provided for convenience.
78  */
79 VLC_API picture_pool_t * picture_pool_NewFromFormat( const video_format_t *, int picture_count ) VLC_USED;
80
81 /**
82  * It destroys a pool created by picture_pool_New.
83  *
84  * All pictures must already be released to the pool. The pool will then
85  * released them.
86  */
87 VLC_API void picture_pool_Delete( picture_pool_t * );
88
89 /**
90  * It retreives a picture_t from a pool.
91  *
92  * The picture must be release by using picture_Release.
93  */
94 VLC_API picture_t * picture_pool_Get( picture_pool_t * ) VLC_USED;
95
96 /**
97  * It forces the next picture_pool_Get to return a picture even if no
98  * pictures are free.
99  *
100  * If b_reset is true, all pictures will be marked as free.
101  *
102  * It does it by releasing itself the oldest used picture if none is
103  * available.
104  * XXX it should be used with great care, the only reason you may need
105  * it is to workaround a bug.
106  */
107 VLC_API void picture_pool_NonEmpty( picture_pool_t *, bool reset );
108
109 /**
110  * It reserves picture_count pictures from the given pool and returns
111  * a new pool with thoses pictures.
112  *
113  * The master pool must be full.
114  * The returned pool must be deleted before the master pool.
115  * When deleted, all pictures return to the master pool.
116  */
117 VLC_API picture_pool_t * picture_pool_Reserve(picture_pool_t *, int picture_count) VLC_USED;
118
119 /**
120  * It returns the size of the given pool.
121  */
122 VLC_API int picture_pool_GetSize(picture_pool_t *);
123
124
125 #endif /* VLC_PICTURE_POOL_H */
126