1 /*
2 * This file is part of FFmpeg.
3 *
4 * FFmpeg is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * FFmpeg is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with FFmpeg; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17 */
18
19 #ifndef AVDEVICE_AVDEVICE_H
20 #define AVDEVICE_AVDEVICE_H
21
23 #ifndef HAVE_AV_CONFIG_H
24 /* When included as part of the ffmpeg build, only include the major version
25 * to avoid unnecessary rebuilds. When included externally, keep including
26 * the full version information. */
27 #include "version.h"
28 #endif
29
30 /**
31 * @file
32 * @ingroup lavd
33 * Main libavdevice API header
34 */
35
36 /**
37 * @defgroup lavd libavdevice
38 * Special devices muxing/demuxing library.
39 *
40 * Libavdevice is a complementary library to @ref libavf "libavformat". It
41 * provides various "special" platform-specific muxers and demuxers, e.g. for
42 * grabbing devices, audio capture and playback etc. As a consequence, the
43 * (de)muxers in libavdevice are of the AVFMT_NOFILE type (they use their own
44 * I/O functions). The filename passed to avformat_open_input() often does not
45 * refer to an actually existing file, but has some special device-specific
46 * meaning - e.g. for xcbgrab it is the display name.
47 *
48 * To use libavdevice, simply call avdevice_register_all() to register all
49 * compiled muxers and demuxers. They all use standard libavformat API.
50 *
51 * @{
52 */
53
58
59 /**
60 * Return the LIBAVDEVICE_VERSION_INT constant.
61 */
63
64 /**
65 * Return the libavdevice build-time configuration.
66 */
68
69 /**
70 * Return the libavdevice license.
71 */
73
74 /**
75 * Initialize libavdevice and register all the input and output devices.
76 */
78
79 /**
80 * Audio input devices iterator.
81 *
82 * If d is NULL, returns the first registered input audio/video device,
83 * if d is non-NULL, returns the next registered input audio/video device after d
84 * or NULL if d is the last one.
85 */
87
88 /**
89 * Video input devices iterator.
90 *
91 * If d is NULL, returns the first registered input audio/video device,
92 * if d is non-NULL, returns the next registered input audio/video device after d
93 * or NULL if d is the last one.
94 */
96
97 /**
98 * Audio output devices iterator.
99 *
100 * If d is NULL, returns the first registered output audio/video device,
101 * if d is non-NULL, returns the next registered output audio/video device after d
102 * or NULL if d is the last one.
103 */
105
106 /**
107 * Video output devices iterator.
108 *
109 * If d is NULL, returns the first registered output audio/video device,
110 * if d is non-NULL, returns the next registered output audio/video device after d
111 * or NULL if d is the last one.
112 */
114
116 int x;
/**< x coordinate of top left corner */
117 int y;
/**< y coordinate of top left corner */
121
122 /**
123 * Message types used by avdevice_app_to_dev_control_message().
124 */
126 /**
127 * Dummy message.
128 */
130
131 /**
132 * Window size change message.
133 *
134 * Message is sent to the device every time the application changes the size
135 * of the window device renders to.
136 * Message should also be sent right after window is created.
137 *
138 * data: AVDeviceRect: new window size.
139 */
141
142 /**
143 * Repaint request message.
144 *
145 * Message is sent to the device when window has to be repainted.
146 *
147 * data: AVDeviceRect: area required to be repainted.
148 * NULL: whole area is required to be repainted.
149 */
151
152 /**
153 * Request pause/play.
154 *
155 * Application requests pause/unpause playback.
156 * Mostly usable with devices that have internal buffer.
157 * By default devices are not paused.
158 *
159 * data: NULL
160 */
164
165 /**
166 * Volume control message.
167 *
168 * Set volume level. It may be device-dependent if volume
169 * is changed per stream or system wide. Per stream volume
170 * change is expected when possible.
171 *
172 * data: double: new volume with range of 0.0 - 1.0.
173 */
175
176 /**
177 * Mute control messages.
178 *
179 * Change mute state. It may be device-dependent if mute status
180 * is changed per stream or system wide. Per stream mute status
181 * change is expected when possible.
182 *
183 * data: NULL.
184 */
188
189 /**
190 * Get volume/mute messages.
191 *
192 * Force the device to send AV_DEV_TO_APP_VOLUME_LEVEL_CHANGED or
193 * AV_DEV_TO_APP_MUTE_STATE_CHANGED command respectively.
194 *
195 * data: NULL.
196 */
199 };
200
201 /**
202 * Message types used by avdevice_dev_to_app_control_message().
203 */
205 /**
206 * Dummy message.
207 */
209
210 /**
211 * Create window buffer message.
212 *
213 * Device requests to create a window buffer. Exact meaning is device-
214 * and application-dependent. Message is sent before rendering first
215 * frame and all one-shot initializations should be done here.
216 * Application is allowed to ignore preferred window buffer size.
217 *
218 * @note: Application is obligated to inform about window buffer size
219 * with AV_APP_TO_DEV_WINDOW_SIZE message.
220 *
221 * data: AVDeviceRect: preferred size of the window buffer.
222 * NULL: no preferred size of the window buffer.
223 */
225
226 /**
227 * Prepare window buffer message.
228 *
229 * Device requests to prepare a window buffer for rendering.
230 * Exact meaning is device- and application-dependent.
231 * Message is sent before rendering of each frame.
232 *
233 * data: NULL.
234 */
236
237 /**
238 * Display window buffer message.
239 *
240 * Device requests to display a window buffer.
241 * Message is sent when new frame is ready to be displayed.
242 * Usually buffers need to be swapped in handler of this message.
243 *
244 * data: NULL.
245 */
247
248 /**
249 * Destroy window buffer message.
250 *
251 * Device requests to destroy a window buffer.
252 * Message is sent when device is about to be destroyed and window
253 * buffer is not required anymore.
254 *
255 * data: NULL.
256 */
258
259 /**
260 * Buffer fullness status messages.
261 *
262 * Device signals buffer overflow/underflow.
263 *
264 * data: NULL.
265 */
268
269 /**
270 * Buffer readable/writable.
271 *
272 * Device informs that buffer is readable/writable.
273 * When possible, device informs how many bytes can be read/write.
274 *
275 * @warning Device may not inform when number of bytes than can be read/write changes.
276 *
277 * data: int64_t: amount of bytes available to read/write.
278 * NULL: amount of bytes available to read/write is not known.
279 */
282
283 /**
284 * Mute state change message.
285 *
286 * Device informs that mute state has changed.
287 *
288 * data: int: 0 for not muted state, non-zero for muted state.
289 */
291
292 /**
293 * Volume level change message.
294 *
295 * Device informs that volume level has changed.
296 *
297 * data: double: new volume with range of 0.0 - 1.0.
298 */
300 };
301
302 /**
303 * Send control message from application to device.
304 *
305 * @param s device context.
306 * @param type message type.
307 * @param data message data. Exact type depends on message type.
308 * @param data_size size of message data.
309 * @return >= 0 on success, negative on error.
310 * AVERROR(ENOSYS) when device doesn't implement handler of the message.
311 */
314 void *
data,
size_t data_size);
315
316 /**
317 * Send control message from device to application.
318 *
319 * @param s device context.
320 * @param type message type.
321 * @param data message data. Can be NULL.
322 * @param data_size size of message data.
323 * @return >= 0 on success, negative on error.
324 * AVERROR(ENOSYS) when application doesn't implement handler of the message.
325 */
328 void *
data,
size_t data_size);
329
330 /**
331 * Structure describes basic parameters of the device.
332 */
336 enum AVMediaType *
media_types;
/**< array indicating what media types(s), if any, a device can provide. If null, cannot provide any */
337 int nb_media_types;
/**< length of media_types array, 0 if device cannot provide any media types */
339
340 /**
341 * List of devices.
342 */
348
349 /**
350 * List devices.
351 *
352 * Returns available device names and their parameters.
353 *
354 * @note: Some devices may accept system-dependent device names that cannot be
355 * autodetected. The list returned by this function cannot be assumed to
356 * be always completed.
357 *
358 * @param s device context.
359 * @param[out] device_list list of autodetected devices.
360 * @return count of autodetected devices, negative on error.
361 */
363
364 /**
365 * Convenient function to free result of avdevice_list_devices().
366 *
367 * @param device_list device list to be freed.
368 */
370
371 /**
372 * List devices.
373 *
374 * Returns available device names and their parameters.
375 * These are convinient wrappers for avdevice_list_devices().
376 * Device context is allocated and deallocated internally.
377 *
378 * @param device device format. May be NULL if device name is set.
379 * @param device_name device name. May be NULL if device format is set.
380 * @param device_options An AVDictionary filled with device-private options. May be NULL.
381 * The same options must be passed later to avformat_write_header() for output
382 * devices or avformat_open_input() for input devices, or at any other place
383 * that affects device-private options.
384 * @param[out] device_list list of autodetected devices
385 * @return count of autodetected devices, negative on error.
386 * @note device argument takes precedence over device_name when both are set.
387 */
392
393 /**
394 * @}
395 */
396
397 #endif /* AVDEVICE_AVDEVICE_H */