include/vlc_thumbnailer.h

   1 /*****************************************************************************
   2  * vlc_thumbnailer.h: Thumbnailing 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_THUMBNAILER_H
  24 #define VLC_THUMBNAILER_H
  25
  26 #include <vlc_common.h>
  27
  28 typedef struct vlc_thumbnailer_t vlc_thumbnailer_t;
  29 typedef struct vlc_thumbnailer_request_t vlc_thumbnailer_request_t;
  30
  31 /**
  32  * \brief vlc_thumbnailer_cb defines a callback invoked on thumbnailing completion or error
  33  *
  34  * This callback will always be called, provided vlc_thumbnailer_Request returned
  35  * a non NULL request, and provided the request is not cancelled before its
  36  * completion.
  37  * In case of failure, p_thumbnail will be NULL.
  38  * The picture, if any, is owned by the thumbnailer, and must be acquired by using
  39  * \link picture_Hold \endlink to use it pass the callback's scope.
  40  *
  41  * \param data Is the opaque pointer passed as vlc_thumbnailer_Request last parameter
  42  * \param thumbnail The generated thumbnail, or NULL in case of failure or timeout
  43  */
  44 typedef void(*vlc_thumbnailer_cb)( void* data, picture_t* thumbnail );
  45
  46
  47 /**
  48  * \brief vlc_thumbnailer_Create Creates a thumbnailer object
  49  * \param parent A VLC object
  50  * \return A thumbnailer object, or NULL in case of failure
  51  */
  52 VLC_API vlc_thumbnailer_t*
  53 vlc_thumbnailer_Create( vlc_object_t* p_parent )
  54 VLC_USED;
  55
  56 enum vlc_thumbnailer_seek_speed
  57 {
  58     /** Precise, but potentially slow */
  59     VLC_THUMBNAILER_SEEK_PRECISE,
  60     /** Fast, but potentially imprecise */
  61     VLC_THUMBNAILER_SEEK_FAST,
  62 };
  63
  64 /**
  65  * \brief vlc_thumbnailer_RequestByTime Requests a thumbnailer at a given time
  66  * \param thumbnailer A thumbnailer object
  67  * \param time The time at which the thumbnail should be taken
  68  * \param speed The seeking speed \sa{enum vlc_thumbnailer_seek_speed}
  69  * \param input_item The input item to generate the thumbnail for
  70  * \param timeout A timeout value, or VLC_TICK_INVALID to disable timeout
  71  * \param cb A user callback to be called on completion (success & error)
  72  * \param user_data An opaque value, provided as pf_cb's first parameter
  73  * \return An opaque request object, or NULL in case of failure
  74  *
  75  * If this function returns a valid request object, the callback is guaranteed
  76  * to be called, even in case of later failure.
  77  * The returned request object must not be used after the callback has been
  78  * invoked. That request object is owned by the thumbnailer, and must not be
  79  * released.
  80  * The provided input_item will be held by the thumbnailer and can safely be
  81  * released safely after calling this function.
  82  */
  83 VLC_API vlc_thumbnailer_request_t*
  84 vlc_thumbnailer_RequestByTime( vlc_thumbnailer_t *thumbnailer,
  85                                vlc_tick_t time,
  86                                enum vlc_thumbnailer_seek_speed speed,
  87                                input_item_t *input_item, vlc_tick_t timeout,
  88                                vlc_thumbnailer_cb cb, void* user_data );
  89 /**
  90  * \brief vlc_thumbnailer_RequestByTime Requests a thumbnailer at a given time
  91  * \param thumbnailer A thumbnailer object
  92  * \param pos The position at which the thumbnail should be taken
  93  * \param speed The seeking speed \sa{enum vlc_thumbnailer_seek_speed}
  94  * \param input_item The input item to generate the thumbnail for
  95  * \param timeout A timeout value, or VLC_TICK_INVALID to disable timeout
  96  * \param cb A user callback to be called on completion (success & error)
  97  * \param user_data An opaque value, provided as pf_cb's first parameter
  98  * \return An opaque request object, or NULL in case of failure
  99  *
 100  * If this function returns a valid request object, the callback is guaranteed
 101  * to be called, even in case of later failure.
 102  * The returned request object must not be used after the callback has been
 103  * invoked. That request object is owned by the thumbnailer, and must not be
 104  * released.
 105  * The provided input_item will be held by the thumbnailer and can safely be
 106  * released after calling this function.
 107  */
 108 VLC_API vlc_thumbnailer_request_t*
 109 vlc_thumbnailer_RequestByPos( vlc_thumbnailer_t *thumbnailer,
 110                               float pos,
 111                               enum vlc_thumbnailer_seek_speed speed,
 112                               input_item_t *input_item, vlc_tick_t timeout,
 113                               vlc_thumbnailer_cb cb, void* user_data );
 114
 115 /**
 116  * \brief vlc_thumbnailer_Cancel Cancel a thumbnail request
 117  * \param thumbnailer A thumbnailer object
 118  * \param request An opaque thumbnail request object
 119  *
 120  * Cancelling a request will *not* invoke the completion callback.
 121  * The behavior is undefined if the request is cancelled after its completion.
 122  */
 123 VLC_API void
 124 vlc_thumbnailer_Cancel( vlc_thumbnailer_t* thumbnailer,
 125                         vlc_thumbnailer_request_t* request );
 126
 127 /**
 128  * \brief vlc_thumbnailer_Release releases a thumbnailer and cancel all pending requests
 129  * \param thumbnailer A thumbnailer object
 130  */
 131 VLC_API void vlc_thumbnailer_Release( vlc_thumbnailer_t* thumbnailer );
 132
 133 #endif // VLC_THUMBNAILER_H