git.sesse.net Git - vlc/blob - 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     unsigned  picture_count;
  47     picture_t *const *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(unsigned count,
  73                                           picture_t *const *tab) VLC_USED;
  74
  75 /**
  76  * It creates a picture_pool_t creating images using the given format.
  77  *
  78  * Provided for convenience.
  79  */
  80 VLC_API picture_pool_t * picture_pool_NewFromFormat(const video_format_t *,
  81                                                     unsigned count) VLC_USED;
  82
  83 /**
  84  * It destroys a pool created by picture_pool_New.
  85  *
  86  * All pictures must already be released to the pool. The pool will then
  87  * released them.
  88  */
  89 VLC_API void picture_pool_Release( picture_pool_t * );
  90
  91 /**
  92  * It retreives a picture_t from a pool.
  93  *
  94  * The picture must be release by using picture_Release.
  95  */
  96 VLC_API picture_t * picture_pool_Get( picture_pool_t * ) VLC_USED;
  97
  98 /**
  99  * Enumerates all pictures in a pool, both free and allocated.
 100  *
 101  * @param cb callback to invoke once for each picture
 102  * @param data opaque data parameter for the callback (first argument)
 103  *
 104  * @note Allocated pictures may be accessed asynchronously by other threads.
 105  * Therefore, only read-only picture parameters can be read by the callback,
 106  * typically picture_t.p_sys.
 107  */
 108 VLC_API void picture_pool_Enum( picture_pool_t *,
 109                                 void (*cb)(void *, picture_t *), void *data );
 110
 111 /**
 112  * Forcefully return all pictures in the pool to free/unallocated state.
 113  *
 114  * @warning This can only be called when it is known that all pending
 115  * references to the picture pool are stale, e.g. a decoder failed to
 116  * release pictures properly when it terminated.
 117  /
 118  * @return the number of picture references that were freed
 119  */
 120 unsigned picture_pool_Reset( picture_pool_t * );
 121
 122 /**
 123  * It forces the next picture_pool_Get to return a picture even if no
 124  * pictures are free.
 125  *
 126  * It does it by releasing itself the oldest used picture if none is
 127  * available.
 128  * XXX it should be used with great care, the only reason you may need
 129  * it is to workaround a bug.
 130  */
 131 void picture_pool_NonEmpty( picture_pool_t * );
 132
 133 /**
 134  * It reserves picture_count pictures from the given pool and returns
 135  * a new pool with thoses pictures.
 136  *
 137  * The master pool must be full.
 138  * The returned pool must be deleted before the master pool.
 139  * When deleted, all pictures return to the master pool.
 140  */
 141 VLC_API picture_pool_t * picture_pool_Reserve(picture_pool_t *, unsigned count)
 142 VLC_USED;
 143
 144 /**
 145  * It returns the size of the given pool.
 146  */
 147 VLC_API unsigned picture_pool_GetSize(const picture_pool_t *);
 148
 149 bool picture_pool_NeedsLocking(const picture_pool_t *);
 150
 151 #endif /* VLC_PICTURE_POOL_H */
 152