VLC 4.0.0-dev
Loading...
Searching...
No Matches
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#include <vlc_tick.h>
28
32/**
33 * \brief vlc_thumbnailer_cb defines a callback invoked on thumbnailing completion or error
34 *
35 * This callback will always be called, provided vlc_thumbnailer_Request returned
36 * a non NULL request, and provided the request is not cancelled before its
37 * completion.
38 * In case of failure, p_thumbnail will be NULL.
39 * The picture, if any, is owned by the thumbnailer, and must be acquired by using
40 * \link picture_Hold \endlink to use it pass the callback's scope.
41 *
42 * \param data Is the opaque pointer passed as vlc_thumbnailer_Request last parameter
43 * \param thumbnail The generated thumbnail, or NULL in case of failure or timeout
44 */
45typedef void(*vlc_thumbnailer_cb)( void* data, picture_t* thumbnail );
47
48/**
49 * \brief vlc_thumbnailer_Create Creates a thumbnailer object
50 * \param parent A VLC object
51 * \return A thumbnailer object, or NULL in case of failure
52 */
56
59 /** Precise, but potentially slow */
61 /** Fast, but potentially imprecise */
63};
64
65/**
66 * \brief vlc_thumbnailer_RequestByTime Requests a thumbnailer at a given time
67 * \param thumbnailer A thumbnailer object
68 * \param time The time at which the thumbnail should be taken
69 * \param speed The seeking speed \sa{enum vlc_thumbnailer_seek_speed}
70 * \param input_item The input item to generate the thumbnail for
71 * \param timeout A timeout value, or VLC_TICK_INVALID to disable timeout
72 * \param cb A user callback to be called on completion (success & error)
73 * \param user_data An opaque value, provided as pf_cb's first parameter
74 * \return An opaque request object, or NULL in case of failure
75 *
76 * If this function returns a valid request object, the callback is guaranteed
77 * to be called, even in case of later failure (except if destroyed early by
78 * the user).
79 * The returned request object must be freed with
80 * vlc_thumbnailer_DestroyRequest().
81 * The provided input_item will be held by the thumbnailer and can safely be
82 * released safely after calling this function.
83 */
86 vlc_tick_t time,
88 input_item_t *input_item, vlc_tick_t timeout,
89 vlc_thumbnailer_cb cb, void* user_data );
90/**
91 * \brief vlc_thumbnailer_RequestByTime Requests a thumbnailer at a given time
92 * \param thumbnailer A thumbnailer object
93 * \param pos The position at which the thumbnail should be taken
94 * \param speed The seeking speed \sa{enum vlc_thumbnailer_seek_speed}
95 * \param input_item The input item to generate the thumbnail for
96 * \param timeout A timeout value, or VLC_TICK_INVALID to disable timeout
97 * \param cb A user callback to be called on completion (success & error)
98 * \param user_data An opaque value, provided as pf_cb's first parameter
99 * \return An opaque request object, or NULL in case of failure
100 *
101 * If this function returns a valid request object, the callback is guaranteed
102 * to be called, even in case of later failure (except if destroyed early by
103 * the user).
104 * The returned request object must be freed with
105 * vlc_thumbnailer_DestroyRequest().
106 * The provided input_item will be held by the thumbnailer and can safely be
107 * released after calling this function.
108 */
111 double pos,
113 input_item_t *input_item, vlc_tick_t timeout,
114 vlc_thumbnailer_cb cb, void* user_data );
115
116/**
117 * \brief vlc_thumbnailer_DestroyRequest Destroy a thumbnail request
118 * \param thumbnailer A thumbnailer object
119 * \param request An opaque thumbnail request object
120 *
121 * The request can be destroyed before receiving a callback (in that case, the
122 * callback won't be called) or after (to release resources).
123 */
124VLC_API void
126 vlc_thumbnailer_request_t* request );
127
128/**
129 * \brief vlc_thumbnailer_Release releases a thumbnailer and cancel all pending requests
130 * \param thumbnailer A thumbnailer object
131 */
133
134#endif // VLC_THUMBNAILER_H
#define VLC_USED
Definition fourcc_gen.c:32
#define VLC_API
Definition fourcc_gen.c:31
Describes an input and is used to spawn input_thread_t objects.
Definition vlc_input_item.h:98
Video picture.
Definition vlc_picture.h:130
VLC object common members.
Definition vlc_objects.h:53
Definition thumbnailer.c:56
vlc_tick_t timeout
A positive value will be used as the timeout duration VLC_TICK_INVALID means no timeout.
Definition thumbnailer.c:67
vlc_thumbnailer_cb cb
Definition thumbnailer.c:68
vlc_thumbnailer_t * thumbnailer
Definition thumbnailer.c:58
Definition thumbnailer.c:32
This file is a collection of common definitions and types.
void vlc_thumbnailer_Release(vlc_thumbnailer_t *thumbnailer)
vlc_thumbnailer_Release releases a thumbnailer and cancel all pending requests
Definition thumbnailer.c:318
vlc_thumbnailer_request_t * vlc_thumbnailer_RequestByPos(vlc_thumbnailer_t *thumbnailer, double 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:271
void vlc_thumbnailer_DestroyRequest(vlc_thumbnailer_t *thumbnailer, vlc_thumbnailer_request_t *request)
vlc_thumbnailer_DestroyRequest Destroy a thumbnail request
Definition thumbnailer.c:284
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:256
vlc_thumbnailer_t * vlc_thumbnailer_Create(vlc_object_t *parent)
vlc_thumbnailer_Create Creates a thumbnailer object
Definition thumbnailer.c:300
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:46
vlc_thumbnailer_seek_speed
Definition vlc_thumbnailer.h:59
@ VLC_THUMBNAILER_SEEK_PRECISE
Precise, but potentially slow.
Definition vlc_thumbnailer.h:61
@ VLC_THUMBNAILER_SEEK_FAST
Fast, but potentially imprecise.
Definition vlc_thumbnailer.h:63
int64_t vlc_tick_t
High precision date or time interval.
Definition vlc_tick.h:48