From 4266129964b8238526936d723de65b419d8069c6 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 31 May 2011 16:27:44 -0300 Subject: [media] DocBook: Move all media docbook stuff into its own directory This patch addresses several issues pointed by Randy Dunlap at changeset ece722c: - In the generated index.html file, "media" is listed first, but it should be listed in alphabetical order, not first. - The generated files are (hidden) in .tmpmedia/ - The link from the top-level index.html file to "media" is to media/index.html, but the file is actually in .tmpmedia/media/index.html - Please build docs with and without using "O=builddir" and test that. - Would it be possible for media to have its own Makefile instead of merging into this one? Due to the way cleandocs target works, I had to rename the media DocBook to media_api, otherwise cleandocs would remove the /media directory. Thanks-to: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/dev-capture.xml | 118 ++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/dev-capture.xml (limited to 'Documentation/DocBook/media/v4l/dev-capture.xml') diff --git a/Documentation/DocBook/media/v4l/dev-capture.xml b/Documentation/DocBook/media/v4l/dev-capture.xml new file mode 100644 index 000000000000..2237c661f26a --- /dev/null +++ b/Documentation/DocBook/media/v4l/dev-capture.xml @@ -0,0 +1,118 @@ + Video Capture Interface + + Video capture devices sample an analog video signal and store +the digitized images in memory. Today nearly all devices can capture +at full 25 or 30 frames/second. With this interface applications can +control the capture process and move images from the driver into user +space. + + Conventionally V4L2 video capture devices are accessed through +character device special files named /dev/video +and /dev/video0 to +/dev/video63 with major number 81 and minor +numbers 0 to 63. /dev/video is typically a +symbolic link to the preferred video device. Note the same device +files are used for video output devices. + +
+ Querying Capabilities + + Devices supporting the video capture interface set the +V4L2_CAP_VIDEO_CAPTURE or +V4L2_CAP_VIDEO_CAPTURE_MPLANE flag in the +capabilities field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions +they may also support the video overlay +(V4L2_CAP_VIDEO_OVERLAY) and the raw VBI capture +(V4L2_CAP_VBI_CAPTURE) interface. At least one of +the read/write or streaming I/O methods must be supported. Tuners and +audio inputs are optional. +
+ +
+ Supplemental Functions + + Video capture devices shall support audio input, tuner, controls, +cropping and scaling and streaming parameter ioctls as needed. +The video input and video standard ioctls must be supported by +all video capture devices. +
+ +
+ Image Format Negotiation + + The result of a capture operation is determined by +cropping and image format parameters. The former select an area of the +video picture to capture, the latter how images are stored in memory, +&ie; in RGB or YUV format, the number of bits per pixel or width and +height. Together they also define how images are scaled in the +process. + + As usual these parameters are not reset +at &func-open; time to permit Unix tool chains, programming a device +and then reading from it as if it was a plain file. Well written V4L2 +applications ensure they really get what they want, including cropping +and scaling. + + Cropping initialization at minimum requires to reset the +parameters to defaults. An example is given in . + + To query the current image format applications set the +type field of a &v4l2-format; to +V4L2_BUF_TYPE_VIDEO_CAPTURE or +V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE and call the +&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill +the &v4l2-pix-format; pix or the +&v4l2-pix-format-mplane; pix_mp member of the +fmt union. + + To request different parameters applications set the +type field of a &v4l2-format; as above and +initialize all fields of the &v4l2-pix-format; +vbi member of the +fmt union, or better just modify the +results of VIDIOC_G_FMT, and call the +&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may +adjust the parameters and finally return the actual parameters as +VIDIOC_G_FMT does. + + Like VIDIOC_S_FMT the +&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations +without disabling I/O or possibly time consuming hardware +preparations. + + The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane; +are discussed in . See also the specification of the +VIDIOC_G_FMT, VIDIOC_S_FMT +and VIDIOC_TRY_FMT ioctls for details. Video +capture devices must implement both the +VIDIOC_G_FMT and +VIDIOC_S_FMT ioctl, even if +VIDIOC_S_FMT ignores all requests and always +returns default parameters as VIDIOC_G_FMT does. +VIDIOC_TRY_FMT is optional. +
+ +
+ Reading Images + + A video capture device may support the read() function and/or streaming (memory mapping or user pointer) I/O. See for details. +
+ + -- cgit v1.2.3