From dadcdf696e5522645af0ac7f4a34853cdee0092a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 28 May 2011 21:51:59 -0300 Subject: [PATCH] get_media_devices: Add a proper documentation about the library Signed-off-by: Mauro Carvalho Chehab --- utils/libmedia_dev/README | 185 +++++++++++++++++++++++++++++++++ utils/libmedia_dev/get_media_devices.h | 24 ----- 2 files changed, 185 insertions(+), 24 deletions(-) create mode 100644 utils/libmedia_dev/README diff --git a/utils/libmedia_dev/README b/utils/libmedia_dev/README new file mode 100644 index 0000000..b238da0 --- /dev/null +++ b/utils/libmedia_dev/README @@ -0,0 +1,185 @@ +1) Why such library is needed + ========================== + +Media devices can be very complex. It is not trivial how to detect what's the +other devices associated with a video node. + +This API provides the capabilities of getting the associated devices with a +video node. + +It is currently implemented at http://git.linuxtv.org/v4l-utils.git, at the +utils/libmedia_dev/. After validating it, it makes sense to move it to be +part of libv4l. + +2) Provided functions + ================== + +The API defines a macro with its current version. Currently, it is: + + #define GET_MEDIA_DEVICES_VERSION 0x0104 + +Each device type that is known by the API is defined inside enum device_type, +currently defined as: + + enum device_type { + UNKNOWN = 65535, + NONE = 65534, + MEDIA_V4L_VIDEO = 0, + MEDIA_V4L_VBI, + MEDIA_DVB_FRONTEND, + MEDIA_DVB_DEMUX, + MEDIA_DVB_DVR, + MEDIA_DVB_NET, + MEDIA_DVB_CA, + MEDIA_SND_CARD, + MEDIA_SND_CAP, + MEDIA_SND_OUT, + MEDIA_SND_CONTROL, + MEDIA_SND_HW, + }; + +The first function discovers the media devices and stores the information +at an internal representation. Such representation should be opaque to +the userspace applications, as it can change from version to version. + +2.1) Device discover and release functions + ===================================== + +The device discover is done by calling: + + void *discover_media_devices(void); + +In order to release the opaque structure, a free method is provided: + + void free_media_devices(void *opaque); + +2.2) Functions to help printing the discovered devices + ================================================= + +In order to allow printing the device type, a function is provided to +convert from enum device_type into string: + + char *media_device_type(enum device_type type); + +All discovered devices can be displayed by calling: + + void display_media_devices(void *opaque); + +2.3) Functions to get device associations + ==================================== + +The API provides 3 methods to get the associated devices: + +a) get_associated_device: returns the next device associated with another one + + char *get_associated_device(void *opaque, + char *last_seek, + enum device_type desired_type, + char *seek_device, + enum device_type seek_type); +The parameters are: + + opaque: media devices opaque descriptor + last_seek: last seek result. Use NULL to get the first result + desired_type: type of the desired device + seek_device: name of the device with you want to get an association. + seek_type: type of the seek device. Using NONE produces the same + result of using NULL for the seek_device. + +This function seeks inside the media_devices struct for the next device +that it is associated with a seek parameter. +It can be used to get an alsa device associated with a video device. If +the seek_device is NULL or seek_type is NONE, it will just search for +devices of the desired_type. + + +b) fget_associated_device: returns the next device associated with another one + + char *fget_associated_device(void *opaque, + char *last_seek, + enum device_type desired_type, + int fd_seek_device, + enum device_type seek_type); + +The parameters are: + + opaque: media devices opaque descriptor + last_seek: last seek result. Use NULL to get the first result + desired_type: type of the desired device + fd_seek_device: file handler for the device where the association will + be made + seek_type: type of the seek device. Using NONE produces the same + result of using NULL for the seek_device. + +This function seeks inside the media_devices struct for the next device +that it is associated with a seek parameter. +It can be used to get an alsa device associated with an open file descriptor + +c) get_not_associated_device: Returns the next device not associated with + an specific device type. + +char *get_not_associated_device(void *opaque, + char *last_seek, + enum device_type desired_type, + enum device_type not_desired_type); + +The parameters are: + +opaque: media devices opaque descriptor +last_seek: last seek result. Use NULL to get the first result +desired_type: type of the desired device +not_desired_type: type of the seek device + +This function seeks inside the media_devices struct for the next physical +device that doesn't support a non_desired type. +This method is useful for example to return the audio devices that are +provided by the motherboard. + +3) Examples with typical usecases + ============================== + +a) Just displaying all media devices: + + void *md = discover_media_devices(); + display_media_devices(md); + free_media_devices(md); + +The devices will be shown at the order they appear at the computer buses. + +b) For video0, prints the associated alsa capture device(s): + + void *md = discover_media_devices(); + char *devname = NULL, video0 = "/dev/video0"; + do { + devname = get_associated_device(md, devname, MEDIA_SND_CAP, + video0, MEDIA_V4L_VIDEO); + if (devname) + printf("Alsa capture: %s\n", devname); + } while (devname); + free_media_devices(md); + +Note: the video0 string can be declarated as "/dev/video0" or as just "video0", +as the search functions will discard any patch on it. + +c) Get the alsa capture device associated with an opened file descriptor: + + int fd = open("/dev/video0", O_RDWR); + ... + void *md = discover_media_devices(); + vid = fget_associated_device(md, NULL, MEDIA_SND_CAP, fd, + MEDIA_V4L_VIDEO); + printf("\n\nAlsa device = %s\n", vid); + close(fd); + free_media_devices(md); + +d) Get the mainboard alsa playback devices: + + char *devname = NULL; + void *md = discover_media_devices(); + do { + devname = get_not_associated_device(md, devname, MEDIA_SND_OUT, + MEDIA_V4L_VIDEO); + if (devname) + printf("Alsa playback: %s\n", devname); + } while (devname); + free_media_devices(md); diff --git a/utils/libmedia_dev/get_media_devices.h b/utils/libmedia_dev/get_media_devices.h index e8764bb..d21767e 100644 --- a/utils/libmedia_dev/get_media_devices.h +++ b/utils/libmedia_dev/get_media_devices.h @@ -22,30 +22,6 @@ */ #define GET_MEDIA_DEVICES_VERSION 0x0104 -/* - A typical usecase for the above API is: - -void start_alsa(char *video_dev) { - void *md; - char *alsa_playback, *alsa_capture, *p; - - md = discover_media_devices(); - if (!md) - return; - alsa_capture = get_first_alsa_cap_device(md, video_dev); - alsa_playback = get_first_no_video_out_device(md); - if (alsa_capture && alsa_playback) - alsa_handler(alsa_playback, alsa_capture); - free_media_devices(md); -} - -start_alsa("/dev/video0"); - -Where alsa_handler() is some function that will need to handle - both alsa capture and playback devices. -*/ - - /** * enum device_type - Enumerates the type for each device * -- 2.7.4