VLC  4.0.0-dev
vlc_thumbnailer.h
Go to the documentation of this file.
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 
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  */
54 VLC_USED;
55 
57 {
58  /** Precise, but potentially slow */
60  /** Fast, but potentially imprecise */
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  */
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  */
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
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  */
132 
133 #endif // VLC_THUMBNAILER_H
Definition: thumbnailer.c:31
Video picture.
Definition: vlc_picture.h:127
Describes an input and is used to spawn input_thread_t objects.
Definition: vlc_input_item.h:77
vlc_thumbnailer_t * thumbnailer
Definition: thumbnailer.c:62
Definition: thumbnailer.c:60
This file is a collection of common definitions and types.
vlc_thumbnailer_seek_speed
Definition: vlc_thumbnailer.h:57
vlc_thumbnailer_request_t * vlc_thumbnailer_RequestByTime(vlc_thumbnailer_t *thumbnailer, vlc_tick_t time, enum vlc_thumbnailer_seek_speed speed, input_item_t *input_item, vlc_tick_t timeout, vlc_thumbnailer_cb cb, void *user_data)
vlc_thumbnailer_RequestByTime Requests a thumbnailer at a given time
Definition: thumbnailer.c:212
Fast, but potentially imprecise.
Definition: vlc_thumbnailer.h:62
int64_t vlc_tick_t
High precision date or time interval.
Definition: vlc_tick.h:45
vlc_thumbnailer_t * vlc_thumbnailer_Create(vlc_object_t *p_parent)
vlc_thumbnailer_Create Creates a thumbnailer object
Definition: thumbnailer.c:258
void(* vlc_thumbnailer_cb)(void *data, picture_t *thumbnail)
vlc_thumbnailer_cb defines a callback invoked on thumbnailing completion or error ...
Definition: vlc_thumbnailer.h:45
vlc_thumbnailer_request_t * vlc_thumbnailer_RequestByPos(vlc_thumbnailer_t *thumbnailer, float pos, enum vlc_thumbnailer_seek_speed speed, input_item_t *input_item, vlc_tick_t timeout, vlc_thumbnailer_cb cb, void *user_data)
vlc_thumbnailer_RequestByTime Requests a thumbnailer at a given time
Definition: thumbnailer.c:231
void vlc_thumbnailer_Release(vlc_thumbnailer_t *thumbnailer)
vlc_thumbnailer_Release releases a thumbnailer and cancel all pending requests
Definition: thumbnailer.c:282
#define VLC_API
Definition: fourcc_gen.c:31
Precise, but potentially slow.
Definition: vlc_thumbnailer.h:60
VLC object common members.
Definition: vlc_objects.h:43
void vlc_thumbnailer_Cancel(vlc_thumbnailer_t *thumbnailer, vlc_thumbnailer_request_t *request)
vlc_thumbnailer_Cancel Cancel a thumbnail request
Definition: thumbnailer.c:248
#define VLC_USED
Definition: fourcc_gen.c:32