playlist demuxer: remove tabs
[vlc.git] / include / vlc_thumbnailer.h
blob39c23cd727ec285d527e982121e87740ccf94b87
1 /*****************************************************************************
2 * vlc_thumbnailer.h: Thumbnailing API
3 *****************************************************************************
4 * Copyright (C) 2018 VLC authors and VideoLAN
6 * Authors: Hugo Beauzée-Luyssen <hugo@beauzee.fr>
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.
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.
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 *****************************************************************************/
23 #ifndef VLC_THUMBNAILER_H
24 #define VLC_THUMBNAILER_H
26 #include <vlc_common.h>
28 typedef struct vlc_thumbnailer_t vlc_thumbnailer_t;
29 typedef struct vlc_thumbnailer_request_t vlc_thumbnailer_request_t;
31 /**
32 * \brief vlc_thumbnailer_cb defines a callback invoked on thumbnailing completion or error
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.
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
44 typedef void(*vlc_thumbnailer_cb)( void* data, picture_t* thumbnail );
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
52 VLC_API vlc_thumbnailer_t*
53 vlc_thumbnailer_Create( vlc_object_t* p_parent )
54 VLC_USED;
56 enum vlc_thumbnailer_seek_speed
58 /** Precise, but potentially slow */
59 VLC_THUMBNAILER_SEEK_PRECISE,
60 /** Fast, but potentially imprecise */
61 VLC_THUMBNAILER_SEEK_FAST,
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
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.
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
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.
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 );
116 * \brief vlc_thumbnailer_Cancel Cancel a thumbnail request
117 * \param thumbnailer A thumbnailer object
118 * \param request An opaque thumbnail request object
120 * Cancelling a request will *not* invoke the completion callback.
121 * The behavior is undefined if the request is cancelled after its completion.
123 VLC_API void
124 vlc_thumbnailer_Cancel( vlc_thumbnailer_t* thumbnailer,
125 vlc_thumbnailer_request_t* request );
128 * \brief vlc_thumbnailer_Release releases a thumbnailer and cancel all pending requests
129 * \param thumbnailer A thumbnailer object
131 VLC_API void vlc_thumbnailer_Release( vlc_thumbnailer_t* thumbnailer );
133 #endif // VLC_THUMBNAILER_H