avdevice.h (13506B)
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_major.h" 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 54 #include "libavutil/log.h" 55 #include "libavutil/opt.h" 56 #include "libavutil/dict.h" 57 #include "libavformat/avformat.h" 58 59 /** 60 * Return the LIBAVDEVICE_VERSION_INT constant. 61 */ 62 unsigned avdevice_version(void); 63 64 /** 65 * Return the libavdevice build-time configuration. 66 */ 67 const char *avdevice_configuration(void); 68 69 /** 70 * Return the libavdevice license. 71 */ 72 const char *avdevice_license(void); 73 74 /** 75 * Initialize libavdevice and register all the input and output devices. 76 */ 77 void avdevice_register_all(void); 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 */ 86 const AVInputFormat *av_input_audio_device_next(const AVInputFormat *d); 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 */ 95 const AVInputFormat *av_input_video_device_next(const AVInputFormat *d); 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 */ 104 const AVOutputFormat *av_output_audio_device_next(const AVOutputFormat *d); 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 */ 113 const AVOutputFormat *av_output_video_device_next(const AVOutputFormat *d); 114 115 typedef struct AVDeviceRect { 116 int x; /**< x coordinate of top left corner */ 117 int y; /**< y coordinate of top left corner */ 118 int width; /**< width */ 119 int height; /**< height */ 120 } AVDeviceRect; 121 122 /** 123 * Message types used by avdevice_app_to_dev_control_message(). 124 */ 125 enum AVAppToDevMessageType { 126 /** 127 * Dummy message. 128 */ 129 AV_APP_TO_DEV_NONE = MKBETAG('N','O','N','E'), 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 */ 140 AV_APP_TO_DEV_WINDOW_SIZE = MKBETAG('G','E','O','M'), 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 */ 150 AV_APP_TO_DEV_WINDOW_REPAINT = MKBETAG('R','E','P','A'), 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 */ 161 AV_APP_TO_DEV_PAUSE = MKBETAG('P', 'A', 'U', ' '), 162 AV_APP_TO_DEV_PLAY = MKBETAG('P', 'L', 'A', 'Y'), 163 AV_APP_TO_DEV_TOGGLE_PAUSE = MKBETAG('P', 'A', 'U', 'T'), 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 */ 174 AV_APP_TO_DEV_SET_VOLUME = MKBETAG('S', 'V', 'O', 'L'), 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 */ 185 AV_APP_TO_DEV_MUTE = MKBETAG(' ', 'M', 'U', 'T'), 186 AV_APP_TO_DEV_UNMUTE = MKBETAG('U', 'M', 'U', 'T'), 187 AV_APP_TO_DEV_TOGGLE_MUTE = MKBETAG('T', 'M', 'U', 'T'), 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 */ 197 AV_APP_TO_DEV_GET_VOLUME = MKBETAG('G', 'V', 'O', 'L'), 198 AV_APP_TO_DEV_GET_MUTE = MKBETAG('G', 'M', 'U', 'T'), 199 }; 200 201 /** 202 * Message types used by avdevice_dev_to_app_control_message(). 203 */ 204 enum AVDevToAppMessageType { 205 /** 206 * Dummy message. 207 */ 208 AV_DEV_TO_APP_NONE = MKBETAG('N','O','N','E'), 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 */ 224 AV_DEV_TO_APP_CREATE_WINDOW_BUFFER = MKBETAG('B','C','R','E'), 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 */ 235 AV_DEV_TO_APP_PREPARE_WINDOW_BUFFER = MKBETAG('B','P','R','E'), 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 */ 246 AV_DEV_TO_APP_DISPLAY_WINDOW_BUFFER = MKBETAG('B','D','I','S'), 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 */ 257 AV_DEV_TO_APP_DESTROY_WINDOW_BUFFER = MKBETAG('B','D','E','S'), 258 259 /** 260 * Buffer fullness status messages. 261 * 262 * Device signals buffer overflow/underflow. 263 * 264 * data: NULL. 265 */ 266 AV_DEV_TO_APP_BUFFER_OVERFLOW = MKBETAG('B','O','F','L'), 267 AV_DEV_TO_APP_BUFFER_UNDERFLOW = MKBETAG('B','U','F','L'), 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 */ 280 AV_DEV_TO_APP_BUFFER_READABLE = MKBETAG('B','R','D',' '), 281 AV_DEV_TO_APP_BUFFER_WRITABLE = MKBETAG('B','W','R',' '), 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 */ 290 AV_DEV_TO_APP_MUTE_STATE_CHANGED = MKBETAG('C','M','U','T'), 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 */ 299 AV_DEV_TO_APP_VOLUME_LEVEL_CHANGED = MKBETAG('C','V','O','L'), 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 */ 312 int avdevice_app_to_dev_control_message(struct AVFormatContext *s, 313 enum AVAppToDevMessageType type, 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 */ 326 int avdevice_dev_to_app_control_message(struct AVFormatContext *s, 327 enum AVDevToAppMessageType type, 328 void *data, size_t data_size); 329 330 /** 331 * Structure describes basic parameters of the device. 332 */ 333 typedef struct AVDeviceInfo { 334 char *device_name; /**< device name, format depends on device */ 335 char *device_description; /**< human friendly name */ 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 */ 338 } AVDeviceInfo; 339 340 /** 341 * List of devices. 342 */ 343 typedef struct AVDeviceInfoList { 344 AVDeviceInfo **devices; /**< list of autodetected devices */ 345 int nb_devices; /**< number of autodetected devices */ 346 int default_device; /**< index of default device or -1 if no default */ 347 } AVDeviceInfoList; 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 */ 362 int avdevice_list_devices(struct AVFormatContext *s, AVDeviceInfoList **device_list); 363 364 /** 365 * Convenient function to free result of avdevice_list_devices(). 366 * 367 * @param device_list device list to be freed. 368 */ 369 void avdevice_free_list_devices(AVDeviceInfoList **device_list); 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 */ 388 int avdevice_list_input_sources(const AVInputFormat *device, const char *device_name, 389 AVDictionary *device_options, AVDeviceInfoList **device_list); 390 int avdevice_list_output_sinks(const AVOutputFormat *device, const char *device_name, 391 AVDictionary *device_options, AVDeviceInfoList **device_list); 392 393 /** 394 * @} 395 */ 396 397 #endif /* AVDEVICE_AVDEVICE_H */