path: root/libavdevice/avdevice.h (plain)
blob: ee9462480e2cddf00a3abe6a4d219d799391af5c

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
22	#include "version.h"
23
24	/**
25	* @file
26	* @ingroup lavd
27	* Main libavdevice API header
28	*/
29
30	/**
31	* @defgroup lavd libavdevice
32	* Special devices muxing/demuxing library.
33	*
34	* Libavdevice is a complementary library to @ref libavf "libavformat". It
35	* provides various "special" platform-specific muxers and demuxers, e.g. for
36	* grabbing devices, audio capture and playback etc. As a consequence, the
37	* (de)muxers in libavdevice are of the AVFMT_NOFILE type (they use their own
38	* I/O functions). The filename passed to avformat_open_input() often does not
39	* refer to an actually existing file, but has some special device-specific
40	* meaning - e.g. for xcbgrab it is the display name.
41	*
42	* To use libavdevice, simply call avdevice_register_all() to register all
43	* compiled muxers and demuxers. They all use standard libavformat API.
44	*
45	* @{
46	*/
47
48	#include "libavutil/log.h"
49	#include "libavutil/opt.h"
50	#include "libavutil/dict.h"
51	#include "libavformat/avformat.h"
52
53	/**
54	* Return the LIBAVDEVICE_VERSION_INT constant.
55	*/
56	unsigned avdevice_version(void);
57
58	/**
59	* Return the libavdevice build-time configuration.
60	*/
61	const char *avdevice_configuration(void);
62
63	/**
64	* Return the libavdevice license.
65	*/
66	const char *avdevice_license(void);
67
68	/**
69	* Initialize libavdevice and register all the input and output devices.
70	*/
71	void avdevice_register_all(void);
72
73	/**
74	* Audio input devices iterator.
75	*
76	* If d is NULL, returns the first registered input audio/video device,
77	* if d is non-NULL, returns the next registered input audio/video device after d
78	* or NULL if d is the last one.
79	*/
80	AVInputFormat *av_input_audio_device_next(AVInputFormat *d);
81
82	/**
83	* Video input devices iterator.
84	*
85	* If d is NULL, returns the first registered input audio/video device,
86	* if d is non-NULL, returns the next registered input audio/video device after d
87	* or NULL if d is the last one.
88	*/
89	AVInputFormat *av_input_video_device_next(AVInputFormat *d);
90
91	/**
92	* Audio output devices iterator.
93	*
94	* If d is NULL, returns the first registered output audio/video device,
95	* if d is non-NULL, returns the next registered output audio/video device after d
96	* or NULL if d is the last one.
97	*/
98	AVOutputFormat *av_output_audio_device_next(AVOutputFormat *d);
99
100	/**
101	* Video output devices iterator.
102	*
103	* If d is NULL, returns the first registered output audio/video device,
104	* if d is non-NULL, returns the next registered output audio/video device after d
105	* or NULL if d is the last one.
106	*/
107	AVOutputFormat *av_output_video_device_next(AVOutputFormat *d);
108
109	typedef struct AVDeviceRect {
110	int x; /**< x coordinate of top left corner */
111	int y; /**< y coordinate of top left corner */
112	int width; /**< width */
113	int height; /**< height */
114	} AVDeviceRect;
115
116	/**
117	* Message types used by avdevice_app_to_dev_control_message().
118	*/
119	enum AVAppToDevMessageType {
120	/**
121	* Dummy message.
122	*/
123	AV_APP_TO_DEV_NONE = MKBETAG('N','O','N','E'),
124
125	/**
126	* Window size change message.
127	*
128	* Message is sent to the device every time the application changes the size
129	* of the window device renders to.
130	* Message should also be sent right after window is created.
131	*
132	* data: AVDeviceRect: new window size.
133	*/
134	AV_APP_TO_DEV_WINDOW_SIZE = MKBETAG('G','E','O','M'),
135
136	/**
137	* Repaint request message.
138	*
139	* Message is sent to the device when window has to be repainted.
140	*
141	* data: AVDeviceRect: area required to be repainted.
142	* NULL: whole area is required to be repainted.
143	*/
144	AV_APP_TO_DEV_WINDOW_REPAINT = MKBETAG('R','E','P','A'),
145
146	/**
147	* Request pause/play.
148	*
149	* Application requests pause/unpause playback.
150	* Mostly usable with devices that have internal buffer.
151	* By default devices are not paused.
152	*
153	* data: NULL
154	*/
155	AV_APP_TO_DEV_PAUSE = MKBETAG('P', 'A', 'U', ' '),
156	AV_APP_TO_DEV_PLAY = MKBETAG('P', 'L', 'A', 'Y'),
157	AV_APP_TO_DEV_TOGGLE_PAUSE = MKBETAG('P', 'A', 'U', 'T'),
158
159	/**
160	* Volume control message.
161	*
162	* Set volume level. It may be device-dependent if volume
163	* is changed per stream or system wide. Per stream volume
164	* change is expected when possible.
165	*
166	* data: double: new volume with range of 0.0 - 1.0.
167	*/
168	AV_APP_TO_DEV_SET_VOLUME = MKBETAG('S', 'V', 'O', 'L'),
169
170	/**
171	* Mute control messages.
172	*
173	* Change mute state. It may be device-dependent if mute status
174	* is changed per stream or system wide. Per stream mute status
175	* change is expected when possible.
176	*
177	* data: NULL.
178	*/
179	AV_APP_TO_DEV_MUTE = MKBETAG(' ', 'M', 'U', 'T'),
180	AV_APP_TO_DEV_UNMUTE = MKBETAG('U', 'M', 'U', 'T'),
181	AV_APP_TO_DEV_TOGGLE_MUTE = MKBETAG('T', 'M', 'U', 'T'),
182
183	/**
184	* Get volume/mute messages.
185	*
186	* Force the device to send AV_DEV_TO_APP_VOLUME_LEVEL_CHANGED or
187	* AV_DEV_TO_APP_MUTE_STATE_CHANGED command respectively.
188	*
189	* data: NULL.
190	*/
191	AV_APP_TO_DEV_GET_VOLUME = MKBETAG('G', 'V', 'O', 'L'),
192	AV_APP_TO_DEV_GET_MUTE = MKBETAG('G', 'M', 'U', 'T'),
193	};
194
195	/**
196	* Message types used by avdevice_dev_to_app_control_message().
197	*/
198	enum AVDevToAppMessageType {
199	/**
200	* Dummy message.
201	*/
202	AV_DEV_TO_APP_NONE = MKBETAG('N','O','N','E'),
203
204	/**
205	* Create window buffer message.
206	*
207	* Device requests to create a window buffer. Exact meaning is device-
208	* and application-dependent. Message is sent before rendering first
209	* frame and all one-shot initializations should be done here.
210	* Application is allowed to ignore preferred window buffer size.
211	*
212	* @note: Application is obligated to inform about window buffer size
213	* with AV_APP_TO_DEV_WINDOW_SIZE message.
214	*
215	* data: AVDeviceRect: preferred size of the window buffer.
216	* NULL: no preferred size of the window buffer.
217	*/
218	AV_DEV_TO_APP_CREATE_WINDOW_BUFFER = MKBETAG('B','C','R','E'),
219
220	/**
221	* Prepare window buffer message.
222	*
223	* Device requests to prepare a window buffer for rendering.
224	* Exact meaning is device- and application-dependent.
225	* Message is sent before rendering of each frame.
226	*
227	* data: NULL.
228	*/
229	AV_DEV_TO_APP_PREPARE_WINDOW_BUFFER = MKBETAG('B','P','R','E'),
230
231	/**
232	* Display window buffer message.
233	*
234	* Device requests to display a window buffer.
235	* Message is sent when new frame is ready to be displayed.
236	* Usually buffers need to be swapped in handler of this message.
237	*
238	* data: NULL.
239	*/
240	AV_DEV_TO_APP_DISPLAY_WINDOW_BUFFER = MKBETAG('B','D','I','S'),
241
242	/**
243	* Destroy window buffer message.
244	*
245	* Device requests to destroy a window buffer.
246	* Message is sent when device is about to be destroyed and window
247	* buffer is not required anymore.
248	*
249	* data: NULL.
250	*/
251	AV_DEV_TO_APP_DESTROY_WINDOW_BUFFER = MKBETAG('B','D','E','S'),
252
253	/**
254	* Buffer fullness status messages.
255	*
256	* Device signals buffer overflow/underflow.
257	*
258	* data: NULL.
259	*/
260	AV_DEV_TO_APP_BUFFER_OVERFLOW = MKBETAG('B','O','F','L'),
261	AV_DEV_TO_APP_BUFFER_UNDERFLOW = MKBETAG('B','U','F','L'),
262
263	/**
264	* Buffer readable/writable.
265	*
266	* Device informs that buffer is readable/writable.
267	* When possible, device informs how many bytes can be read/write.
268	*
269	* @warning Device may not inform when number of bytes than can be read/write changes.
270	*
271	* data: int64_t: amount of bytes available to read/write.
272	* NULL: amount of bytes available to read/write is not known.
273	*/
274	AV_DEV_TO_APP_BUFFER_READABLE = MKBETAG('B','R','D',' '),
275	AV_DEV_TO_APP_BUFFER_WRITABLE = MKBETAG('B','W','R',' '),
276
277	/**
278	* Mute state change message.
279	*
280	* Device informs that mute state has changed.
281	*
282	* data: int: 0 for not muted state, non-zero for muted state.
283	*/
284	AV_DEV_TO_APP_MUTE_STATE_CHANGED = MKBETAG('C','M','U','T'),
285
286	/**
287	* Volume level change message.
288	*
289	* Device informs that volume level has changed.
290	*
291	* data: double: new volume with range of 0.0 - 1.0.
292	*/
293	AV_DEV_TO_APP_VOLUME_LEVEL_CHANGED = MKBETAG('C','V','O','L'),
294	};
295
296	/**
297	* Send control message from application to device.
298	*
299	* @param s device context.
300	* @param type message type.
301	* @param data message data. Exact type depends on message type.
302	* @param data_size size of message data.
303	* @return >= 0 on success, negative on error.
304	* AVERROR(ENOSYS) when device doesn't implement handler of the message.
305	*/
306	int avdevice_app_to_dev_control_message(struct AVFormatContext *s,
307	enum AVAppToDevMessageType type,
308	void *data, size_t data_size);
309
310	/**
311	* Send control message from device to application.
312	*
313	* @param s device context.
314	* @param type message type.
315	* @param data message data. Can be NULL.
316	* @param data_size size of message data.
317	* @return >= 0 on success, negative on error.
318	* AVERROR(ENOSYS) when application doesn't implement handler of the message.
319	*/
320	int avdevice_dev_to_app_control_message(struct AVFormatContext *s,
321	enum AVDevToAppMessageType type,
322	void *data, size_t data_size);
323
324	/**
325	* Following API allows user to probe device capabilities (supported codecs,
326	* pixel formats, sample formats, resolutions, channel counts, etc).
327	* It is build on top op AVOption API.
328	* Queried capabilities make it possible to set up converters of video or audio
329	* parameters that fit to the device.
330	*
331	* List of capabilities that can be queried:
332	* - Capabilities valid for both audio and video devices:
333	* - codec: supported audio/video codecs.
334	* type: AV_OPT_TYPE_INT (AVCodecID value)
335	* - Capabilities valid for audio devices:
336	* - sample_format: supported sample formats.
337	* type: AV_OPT_TYPE_INT (AVSampleFormat value)
338	* - sample_rate: supported sample rates.
339	* type: AV_OPT_TYPE_INT
340	* - channels: supported number of channels.
341	* type: AV_OPT_TYPE_INT
342	* - channel_layout: supported channel layouts.
343	* type: AV_OPT_TYPE_INT64
344	* - Capabilities valid for video devices:
345	* - pixel_format: supported pixel formats.
346	* type: AV_OPT_TYPE_INT (AVPixelFormat value)
347	* - window_size: supported window sizes (describes size of the window size presented to the user).
348	* type: AV_OPT_TYPE_IMAGE_SIZE
349	* - frame_size: supported frame sizes (describes size of provided video frames).
350	* type: AV_OPT_TYPE_IMAGE_SIZE
351	* - fps: supported fps values
352	* type: AV_OPT_TYPE_RATIONAL
353	*
354	* Value of the capability may be set by user using av_opt_set() function
355	* and AVDeviceCapabilitiesQuery object. Following queries will
356	* limit results to the values matching already set capabilities.
357	* For example, setting a codec may impact number of formats or fps values
358	* returned during next query. Setting invalid value may limit results to zero.
359	*
360	* Example of the usage basing on opengl output device:
361	*
362	* @code
363	* AVFormatContext *oc = NULL;
364	* AVDeviceCapabilitiesQuery *caps = NULL;
365	* AVOptionRanges *ranges;
366	* int ret;
367	*
368	* if ((ret = avformat_alloc_output_context2(&oc, NULL, "opengl", NULL)) < 0)
369	* goto fail;
370	* if (avdevice_capabilities_create(&caps, oc, NULL) < 0)
371	* goto fail;
372	*
373	* //query codecs
374	* if (av_opt_query_ranges(&ranges, caps, "codec", AV_OPT_MULTI_COMPONENT_RANGE)) < 0)
375	* goto fail;
376	* //pick codec here and set it
377	* av_opt_set(caps, "codec", AV_CODEC_ID_RAWVIDEO, 0);
378	*
379	* //query format
380	* if (av_opt_query_ranges(&ranges, caps, "pixel_format", AV_OPT_MULTI_COMPONENT_RANGE)) < 0)
381	* goto fail;
382	* //pick format here and set it
383	* av_opt_set(caps, "pixel_format", AV_PIX_FMT_YUV420P, 0);
384	*
385	* //query and set more capabilities
386	*
387	* fail:
388	* //clean up code
389	* avdevice_capabilities_free(&query, oc);
390	* avformat_free_context(oc);
391	* @endcode
392	*/
393
394	/**
395	* Structure describes device capabilities.
396	*
397	* It is used by devices in conjunction with av_device_capabilities AVOption table
398	* to implement capabilities probing API based on AVOption API. Should not be used directly.
399	*/
400	typedef struct AVDeviceCapabilitiesQuery {
401	const AVClass *av_class;
402	AVFormatContext *device_context;
403	enum AVCodecID codec;
404	enum AVSampleFormat sample_format;
405	enum AVPixelFormat pixel_format;
406	int sample_rate;
407	int channels;
408	int64_t channel_layout;
409	int window_width;
410	int window_height;
411	int frame_width;
412	int frame_height;
413	AVRational fps;
414	} AVDeviceCapabilitiesQuery;
415
416	/**
417	* AVOption table used by devices to implement device capabilities API. Should not be used by a user.
418	*/
419	extern const AVOption av_device_capabilities[];
420
421	/**
422	* Initialize capabilities probing API based on AVOption API.
423	*
424	* avdevice_capabilities_free() must be called when query capabilities API is
425	* not used anymore.
426	*
427	* @param[out] caps Device capabilities data. Pointer to a NULL pointer must be passed.
428	* @param s Context of the device.
429	* @param device_options An AVDictionary filled with device-private options.
430	* On return this parameter will be destroyed and replaced with a dict
431	* containing options that were not found. May be NULL.
432	* The same options must be passed later to avformat_write_header() for output
433	* devices or avformat_open_input() for input devices, or at any other place
434	* that affects device-private options.
435	*
436	* @return >= 0 on success, negative otherwise.
437	*/
438	int avdevice_capabilities_create(AVDeviceCapabilitiesQuery **caps, AVFormatContext *s,
439	AVDictionary **device_options);
440
441	/**
442	* Free resources created by avdevice_capabilities_create()
443	*
444	* @param caps Device capabilities data to be freed.
445	* @param s Context of the device.
446	*/
447	void avdevice_capabilities_free(AVDeviceCapabilitiesQuery **caps, AVFormatContext *s);
448
449	/**
450	* Structure describes basic parameters of the device.
451	*/
452	typedef struct AVDeviceInfo {
453	char *device_name; /**< device name, format depends on device */
454	char *device_description; /**< human friendly name */
455	} AVDeviceInfo;
456
457	/**
458	* List of devices.
459	*/
460	typedef struct AVDeviceInfoList {
461	AVDeviceInfo **devices; /**< list of autodetected devices */
462	int nb_devices; /**< number of autodetected devices */
463	int default_device; /**< index of default device or -1 if no default */
464	} AVDeviceInfoList;
465
466	/**
467	* List devices.
468	*
469	* Returns available device names and their parameters.
470	*
471	* @note: Some devices may accept system-dependent device names that cannot be
472	* autodetected. The list returned by this function cannot be assumed to
473	* be always completed.
474	*
475	* @param s device context.
476	* @param[out] device_list list of autodetected devices.
477	* @return count of autodetected devices, negative on error.
478	*/
479	int avdevice_list_devices(struct AVFormatContext *s, AVDeviceInfoList **device_list);
480
481	/**
482	* Convenient function to free result of avdevice_list_devices().
483	*
484	* @param devices device list to be freed.
485	*/
486	void avdevice_free_list_devices(AVDeviceInfoList **device_list);
487
488	/**
489	* List devices.
490	*
491	* Returns available device names and their parameters.
492	* These are convinient wrappers for avdevice_list_devices().
493	* Device context is allocated and deallocated internally.
494	*
495	* @param device device format. May be NULL if device name is set.
496	* @param device_name device name. May be NULL if device format is set.
497	* @param device_options An AVDictionary filled with device-private options. May be NULL.
498	* The same options must be passed later to avformat_write_header() for output
499	* devices or avformat_open_input() for input devices, or at any other place
500	* that affects device-private options.
501	* @param[out] device_list list of autodetected devices
502	* @return count of autodetected devices, negative on error.
503	* @note device argument takes precedence over device_name when both are set.
504	*/
505	int avdevice_list_input_sources(struct AVInputFormat *device, const char *device_name,
506	AVDictionary *device_options, AVDeviceInfoList **device_list);
507	int avdevice_list_output_sinks(struct AVOutputFormat *device, const char *device_name,
508	AVDictionary *device_options, AVDeviceInfoList **device_list);
509
510	/**
511	* @}
512	*/
513
514	#endif /* AVDEVICE_AVDEVICE_H */
515