diff options
Diffstat (limited to 'v4l2-spec')
| -rw-r--r-- | v4l2-spec/Makefile | 23 | ||||
| -rw-r--r-- | v4l2-spec/README | 3 | ||||
| -rw-r--r-- | v4l2-spec/V4L1_API.html | 401 | ||||
| -rw-r--r-- | v4l2-spec/biblio.sgml | 65 | ||||
| -rw-r--r-- | v4l2-spec/common.sgml | 2 | ||||
| -rw-r--r-- | v4l2-spec/compat.sgml | 29 | ||||
| -rw-r--r-- | v4l2-spec/controls.sgml | 226 | ||||
| -rw-r--r-- | v4l2-spec/dev-radio.sgml | 14 | ||||
| -rw-r--r-- | v4l2-spec/dev-rds.sgml | 182 | ||||
| -rw-r--r-- | v4l2-spec/dev-sliced-vbi.sgml | 315 | ||||
| -rw-r--r-- | v4l2-spec/libv4l.sgml | 168 | ||||
| -rw-r--r-- | v4l2-spec/pixfmt-sgrbg8.sgml | 75 | ||||
| -rw-r--r-- | v4l2-spec/pixfmt.sgml | 21 | ||||
| -rw-r--r-- | v4l2-spec/v4l2.sgml | 73 | ||||
| -rw-r--r-- | v4l2-spec/vidioc-enuminput.sgml | 19 | ||||
| -rw-r--r-- | v4l2-spec/vidioc-g-ext-ctrls.sgml | 79 | ||||
| -rw-r--r-- | v4l2-spec/vidioc-g-modulator.sgml | 18 | ||||
| -rw-r--r-- | v4l2-spec/vidioc-g-tuner.sgml | 21 | ||||
| -rw-r--r-- | v4l2-spec/vidioc-querycap.sgml | 16 | ||||
| -rw-r--r-- | v4l2-spec/vidioc-queryctrl.sgml | 42 |
20 files changed, 1659 insertions, 133 deletions
diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile index d0dde12f4..a88420286 100644 --- a/v4l2-spec/Makefile +++ b/v4l2-spec/Makefile @@ -1,9 +1,11 @@ # Also update in v4l2.sgml! -VERSION = 0.25 +VERSION = 0.26 +SHELL=/bin/bash SGMLS = \ biblio.sgml \ capture.c.sgml \ + v4l2grab.c.sgml \ common.sgml \ compat.sgml \ controls.sgml \ @@ -19,6 +21,7 @@ SGMLS = \ dev-sliced-vbi.sgml \ dev-teletext.sgml \ driver.sgml \ + libv4l.sgml \ entities.sgml \ fdl-appendix.sgml \ func-close.sgml \ @@ -40,6 +43,7 @@ SGMLS = \ pixfmt-sbggr16.sgml \ pixfmt-sbggr8.sgml \ pixfmt-sgbrg8.sgml \ + pixfmt-sgrbg8.sgml \ pixfmt-uyvy.sgml \ pixfmt-vyuy.sgml \ pixfmt-y16.sgml \ @@ -241,6 +245,7 @@ ENUMS = \ v4l2_power_line_frequency \ v4l2_priority \ v4l2_tuner_type \ + v4l2_preemphasis \ STRUCTS = \ v4l2_audio \ @@ -274,6 +279,7 @@ STRUCTS = \ v4l2_input \ v4l2_jpegcompression \ v4l2_modulator \ + v4l2_mpeg_vbi_fmt_ivtv \ v4l2_output \ v4l2_outputparm \ v4l2_pix_format \ @@ -302,6 +308,7 @@ ERRORS = \ EINVAL \ ENFILE \ ENOMEM \ + ENOSPC \ ENOTTY \ ENXIO \ EMFILE \ @@ -320,6 +327,12 @@ DOCUMENTED = \ -e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\) /<link linkend=\"\1\">\1<\/link> /g" \ -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" +libv4l-fmt.sgml: + cat ../v4l2-apps/libv4l/libv4lconvert/*.c| \ + perl -ne 'if (m/(V4L2_PIX_FMT_[^\s\;\\)\,:]+)/) { printf "<link linkend=\"$$1\"><constant>$$1</constant></link>,\n"; };' \ + |sort|uniq| \ + sed -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" > $@ + capture.c.sgml: ../v4l2-apps/test/capture-example.c Makefile echo "<programlisting>" > $@ expand --tabs=8 < $< | \ @@ -327,6 +340,13 @@ capture.c.sgml: ../v4l2-apps/test/capture-example.c Makefile sed 's/i\.e\./&ie;/' >> $@ echo "</programlisting>" >> $@ +v4l2grab.c.sgml: ../v4l2-apps/test/v4l2grab.c Makefile + echo "<programlisting>" > $@ + expand --tabs=8 < $< | \ + sed $(ESCAPE) $(DOCUMENTED) | \ + sed 's/i\.e\./&ie;/' >> $@ + echo "</programlisting>" >> $@ + videodev2.h.sgml: ../linux/include/linux/videodev2.h Makefile echo "<programlisting>" > $@ expand --tabs=8 < $< | \ @@ -485,6 +505,7 @@ distclean clean: rm -f *.stamp rm -f videodev2.h.sgml rm -f capture.c.sgml + rm -f v4l2grab.c.sgml rm -f capture rm -f indices.sgml entities.sgml rm -rf v4l2 v4l2-single v4l2.pdf diff --git a/v4l2-spec/README b/v4l2-spec/README index 6b0a3d0f1..9fe129642 100644 --- a/v4l2-spec/README +++ b/v4l2-spec/README @@ -15,3 +15,6 @@ html-single A single HTML file (default) html Tree of HTML files pdf A PDF file coffeebreak All of the above + +Note: the V4L1_API.html is here just for reference. The V4L2 API replaces +V4L1. diff --git a/v4l2-spec/V4L1_API.html b/v4l2-spec/V4L1_API.html new file mode 100644 index 000000000..9f717fd50 --- /dev/null +++ b/v4l2-spec/V4L1_API.html @@ -0,0 +1,401 @@ +<HTML><HEAD> +<TITLE>Video4Linux Kernel API Reference v0.1:19990430 - OBSOLETE - USE V4L2 API INSTEAD.</TITLE> +</HEAD> +<! Revision History: > +<! 4/30/1999 - Fred Gleason (fredg@wava.com)> +<! Documented extensions for the Radio Data System (RDS) extensions > +<BODY bgcolor="#ffffff"> +<H1>Obsoleted by V4L2 API</H1> + +<H3>Devices</H3> +Video4Linux provides the following sets of device files. These live on the +character device formerly known as "/dev/bttv". /dev/bttv should be a +symlink to /dev/video0 for most people. +<P> +<TABLE> +<TR><TH>Device Name</TH><TH>Minor Range</TH><TH>Function</TH> +<TR><TD>/dev/video</TD><TD>0-63</TD><TD>Video Capture Interface</TD> +<TR><TD>/dev/radio</TD><TD>64-127</TD><TD>AM/FM Radio Devices</TD> +<TR><TD>/dev/vtx</TD><TD>192-223</TD><TD>Teletext Interface Chips</TD> +<TR><TD>/dev/vbi</TD><TD>224-239</TD><TD>Raw VBI Data (Intercast/teletext)</TD> +</TABLE> +<P> +Video4Linux programs open and scan the devices to find what they are looking +for. Capability queries define what each interface supports. The +described API is only defined for video capture cards. The relevant subset +applies to radio cards. Teletext interfaces talk the existing VTX API. +<P> +<H3>Capability Query Ioctl</H3> +The <B>VIDIOCGCAP</B> ioctl call is used to obtain the capability +information for a video device. The <b>struct video_capability</b> object +passed to the ioctl is completed and returned. It contains the following +information +<P> +<TABLE> +<TR><TD><b>name[32]</b><TD>Canonical name for this interface</TD> +<TR><TD><b>type</b><TD>Type of interface</TD> +<TR><TD><b>channels</b><TD>Number of radio/tv channels if appropriate</TD> +<TR><TD><b>audios</b><TD>Number of audio devices if appropriate</TD> +<TR><TD><b>maxwidth</b><TD>Maximum capture width in pixels</TD> +<TR><TD><b>maxheight</b><TD>Maximum capture height in pixels</TD> +<TR><TD><b>minwidth</b><TD>Minimum capture width in pixels</TD> +<TR><TD><b>minheight</b><TD>Minimum capture height in pixels</TD> +</TABLE> +<P> +The type field lists the capability flags for the device. These are +as follows +<P> +<TABLE> +<TR><TH>Name</TH><TH>Description</TH> +<TR><TD><b>VID_TYPE_CAPTURE</b><TD>Can capture to memory</TD> +<TR><TD><b>VID_TYPE_TUNER</b><TD>Has a tuner of some form</TD> +<TR><TD><b>VID_TYPE_TELETEXT</b><TD>Has teletext capability</TD> +<TR><TD><b>VID_TYPE_OVERLAY</b><TD>Can overlay its image onto the frame buffer</TD> +<TR><TD><b>VID_TYPE_CHROMAKEY</b><TD>Overlay is Chromakeyed</TD> +<TR><TD><b>VID_TYPE_CLIPPING</b><TD>Overlay clipping is supported</TD> +<TR><TD><b>VID_TYPE_FRAMERAM</b><TD>Overlay overwrites frame buffer memory</TD> +<TR><TD><b>VID_TYPE_SCALES</b><TD>The hardware supports image scaling</TD> +<TR><TD><b>VID_TYPE_MONOCHROME</b><TD>Image capture is grey scale only</TD> +<TR><TD><b>VID_TYPE_SUBCAPTURE</b><TD>Capture can be of only part of the image</TD> +</TABLE> +<P> +The minimum and maximum sizes listed for a capture device do not imply all +that all height/width ratios or sizes within the range are possible. A +request to set a size will be honoured by the largest available capture +size whose capture is no large than the requested rectangle in either +direction. For example the quickcam has 3 fixed settings. +<P> +<H3>Frame Buffer</H3> +Capture cards that drop data directly onto the frame buffer must be told the +base address of the frame buffer, its size and organisation. This is a +privileged ioctl and one that eventually X itself should set. +<P> +The <b>VIDIOCSFBUF</b> ioctl sets the frame buffer parameters for a capture +card. If the card does not do direct writes to the frame buffer then this +ioctl will be unsupported. The <b>VIDIOCGFBUF</b> ioctl returns the +currently used parameters. The structure used in both cases is a +<b>struct video_buffer</b>. +<P> +<TABLE> +<TR><TD><b>void *base</b></TD><TD>Base physical address of the buffer</TD> +<TR><TD><b>int height</b></TD><TD>Height of the frame buffer</TD> +<TR><TD><b>int width</b></TD><TD>Width of the frame buffer</TD> +<TR><TD><b>int depth</b></TD><TD>Depth of the frame buffer</TD> +<TR><TD><b>int bytesperline</b></TD><TD>Number of bytes of memory between the start of two adjacent lines</TD> +</TABLE> +<P> +Note that these values reflect the physical layout of the frame buffer. +The visible area may be smaller. In fact under XFree86 this is commonly the +case. XFree86 DGA can provide the parameters required to set up this ioctl. +Setting the base address to NULL indicates there is no physical frame buffer +access. +<P> +<H3>Capture Windows</H3> +The capture area is described by a <b>struct video_window</b>. This defines +a capture area and the clipping information if relevant. The +<b>VIDIOCGWIN</b> ioctl recovers the current settings and the +<b>VIDIOCSWIN</b> sets new values. A successful call to <b>VIDIOCSWIN</b> +indicates that a suitable set of parameters have been chosen. They do not +indicate that exactly what was requested was granted. The program should +call <b>VIDIOCGWIN</b> to check if the nearest match was suitable. The +<b>struct video_window</b> contains the following fields. +<P> +<TABLE> +<TR><TD><b>x</b><TD>The X co-ordinate specified in X windows format.</TD> +<TR><TD><b>y</b><TD>The Y co-ordinate specified in X windows format.</TD> +<TR><TD><b>width</b><TD>The width of the image capture.</TD> +<TR><TD><b>height</b><TD>The height of the image capture.</TD> +<TR><TD><b>chromakey</b><TD>A host order RGB32 value for the chroma key.</TD> +<TR><TD><b>flags</b><TD>Additional capture flags.</TD> +<TR><TD><b>clips</b><TD>A list of clipping rectangles. <em>(Set only)</em></TD> +<TR><TD><b>clipcount</b><TD>The number of clipping rectangles. <em>(Set only)</em></TD> +</TABLE> +<P> +Clipping rectangles are passed as an array. Each clip consists of the following +fields available to the user. +<P> +<TABLE> +<TR><TD><b>x</b></TD><TD>X co-ordinate of rectangle to skip</TD> +<TR><TD><b>y</b></TD><TD>Y co-ordinate of rectangle to skip</TD> +<TR><TD><b>width</b></TD><TD>Width of rectangle to skip</TD> +<TR><TD><b>height</b></TD><TD>Height of rectangle to skip</TD> +</TABLE> +<P> +Merely setting the window does not enable capturing. Overlay capturing +(i.e. PCI-PCI transfer to the frame buffer of the video card) +is activated by passing the <b>VIDIOCCAPTURE</b> ioctl a value of 1, and +disabled by passing it a value of 0. +<P> +Some capture devices can capture a subfield of the image they actually see. +This is indicated when VIDEO_TYPE_SUBCAPTURE is defined. +The video_capture describes the time and special subfields to capture. +The video_capture structure contains the following fields. +<P> +<TABLE> +<TR><TD><b>x</b></TD><TD>X co-ordinate of source rectangle to grab</TD> +<TR><TD><b>y</b></TD><TD>Y co-ordinate of source rectangle to grab</TD> +<TR><TD><b>width</b></TD><TD>Width of source rectangle to grab</TD> +<TR><TD><b>height</b></TD><TD>Height of source rectangle to grab</TD> +<TR><TD><b>decimation</b></TD><TD>Decimation to apply</TD> +<TR><TD><b>flags</b></TD><TD>Flag settings for grabbing</TD> +</TABLE> +The available flags are +<P> +<TABLE> +<TR><TH>Name</TH><TH>Description</TH> +<TR><TD><b>VIDEO_CAPTURE_ODD</b><TD>Capture only odd frames</TD> +<TR><TD><b>VIDEO_CAPTURE_EVEN</b><TD>Capture only even frames</TD> +</TABLE> +<P> +<H3>Video Sources</H3> +Each video4linux video or audio device captures from one or more +source <b>channels</b>. Each channel can be queries with the +<b>VDIOCGCHAN</b> ioctl call. Before invoking this function the caller +must set the channel field to the channel that is being queried. On return +the <b>struct video_channel</b> is filled in with information about the +nature of the channel itself. +<P> +The <b>VIDIOCSCHAN</b> ioctl takes an integer argument and switches the +capture to this input. It is not defined whether parameters such as colour +settings or tuning are maintained across a channel switch. The caller should +maintain settings as desired for each channel. (This is reasonable as +different video inputs may have different properties). +<P> +The <b>struct video_channel</b> consists of the following +<P> +<TABLE> +<TR><TD><b>channel</b></TD><TD>The channel number</TD> +<TR><TD><b>name</b></TD><TD>The input name - preferably reflecting the label +on the card input itself</TD> +<TR><TD><b>tuners</b></TD><TD>Number of tuners for this input</TD> +<TR><TD><b>flags</b></TD><TD>Properties the tuner has</TD> +<TR><TD><b>type</b></TD><TD>Input type (if known)</TD> +<TR><TD><b>norm</b><TD>The norm for this channel</TD> +</TABLE> +<P> +The flags defined are +<P> +<TABLE> +<TR><TD><b>VIDEO_VC_TUNER</b><TD>Channel has tuners.</TD> +<TR><TD><b>VIDEO_VC_AUDIO</b><TD>Channel has audio.</TD> +<TR><TD><b>VIDEO_VC_NORM</b><TD>Channel has norm setting.</TD> +</TABLE> +<P> +The types defined are +<P> +<TABLE> +<TR><TD><b>VIDEO_TYPE_TV</b><TD>The input is a TV input.</TD> +<TR><TD><b>VIDEO_TYPE_CAMERA</b><TD>The input is a camera.</TD> +</TABLE> +<P> +<H3>Image Properties</H3> +The image properties of the picture can be queried with the <b>VIDIOCGPICT</b> +ioctl which fills in a <b>struct video_picture</b>. The <b>VIDIOCSPICT</b> +ioctl allows values to be changed. All values except for the palette type +are scaled between 0-65535. +<P> +The <b>struct video_picture</b> consists of the following fields +<P> +<TABLE> +<TR><TD><b>brightness</b><TD>Picture brightness</TD> +<TR><TD><b>hue</b><TD>Picture hue (colour only)</TD> +<TR><TD><b>colour</b><TD>Picture colour (colour only)</TD> +<TR><TD><b>contrast</b><TD>Picture contrast</TD> +<TR><TD><b>whiteness</b><TD>The whiteness (greyscale only)</TD> +<TR><TD><b>depth</b><TD>The capture depth (may need to match the frame buffer depth)</TD> +<TR><TD><b>palette</b><TD>Reports the palette that should be used for this image</TD> +</TABLE> +<P> +The following palettes are defined +<P> +<TABLE> +<TR><TD><b>VIDEO_PALETTE_GREY</b><TD>Linear intensity grey scale (255 is brightest).</TD> +<TR><TD><b>VIDEO_PALETTE_HI240</b><TD>The BT848 8bit colour cube.</TD> +<TR><TD><b>VIDEO_PALETTE_RGB565</b><TD>RGB565 packed into 16 bit words.</TD> +<TR><TD><b>VIDEO_PALETTE_RGB555</b><TD>RGV555 packed into 16 bit words, top bit undefined.</TD> +<TR><TD><b>VIDEO_PALETTE_RGB24</b><TD>RGB888 packed into 24bit words.</TD> +<TR><TD><b>VIDEO_PALETTE_RGB32</b><TD>RGB888 packed into the low 3 bytes of 32bit words. The top 8bits are undefined.</TD> +<TR><TD><b>VIDEO_PALETTE_YUV422</b><TD>Video style YUV422 - 8bits packed 4bits Y 2bits U 2bits V</TD> +<TR><TD><b>VIDEO_PALETTE_YUYV</b><TD>Describe me</TD> +<TR><TD><b>VIDEO_PALETTE_UYVY</b><TD>Describe me</TD> +<TR><TD><b>VIDEO_PALETTE_YUV420</b><TD>YUV420 capture</TD> +<TR><TD><b>VIDEO_PALETTE_YUV411</b><TD>YUV411 capture</TD> +<TR><TD><b>VIDEO_PALETTE_RAW</b><TD>RAW capture (BT848)</TD> +<TR><TD><b>VIDEO_PALETTE_YUV422P</b><TD>YUV 4:2:2 Planar</TD> +<TR><TD><b>VIDEO_PALETTE_YUV411P</b><TD>YUV 4:1:1 Planar</TD> +</TABLE> +<P> +<H3>Tuning</H3> +Each video input channel can have one or more tuners associated with it. Many +devices will not have tuners. TV cards and radio cards will have one or more +tuners attached. +<P> +Tuners are described by a <b>struct video_tuner</b> which can be obtained by +the <b>VIDIOCGTUNER</b> ioctl. Fill in the tuner number in the structure +then pass the structure to the ioctl to have the data filled in. The +tuner can be switched using <b>VIDIOCSTUNER</b> which takes an integer argument +giving the tuner to use. A struct tuner has the following fields +<P> +<TABLE> +<TR><TD><b>tuner</b><TD>Number of the tuner</TD> +<TR><TD><b>name</b><TD>Canonical name for this tuner (eg FM/AM/TV)</TD> +<TR><TD><b>rangelow</b><TD>Lowest tunable frequency</TD> +<TR><TD><b>rangehigh</b><TD>Highest tunable frequency</TD> +<TR><TD><b>flags</b><TD>Flags describing the tuner</TD> +<TR><TD><b>mode</b><TD>The video signal mode if relevant</TD> +<TR><TD><b>signal</b><TD>Signal strength if known - between 0-65535</TD> +</TABLE> +<P> +The following flags exist +<P> +<TABLE> +<TR><TD><b>VIDEO_TUNER_PAL</b><TD>PAL tuning is supported</TD> +<TR><TD><b>VIDEO_TUNER_NTSC</b><TD>NTSC tuning is supported</TD> +<TR><TD><b>VIDEO_TUNER_SECAM</b><TD>SECAM tuning is supported</TD> +<TR><TD><b>VIDEO_TUNER_LOW</b><TD>Frequency is in a lower range</TD> +<TR><TD><b>VIDEO_TUNER_NORM</b><TD>The norm for this tuner is settable</TD> +<TR><TD><b>VIDEO_TUNER_STEREO_ON</b><TD>The tuner is seeing stereo audio</TD> +<TR><TD><b>VIDEO_TUNER_RDS_ON</b><TD>The tuner is seeing a RDS datastream</TD> +<TR><TD><b>VIDEO_TUNER_MBS_ON</b><TD>The tuner is seeing a MBS datastream</TD> +</TABLE> +<P> +The following modes are defined +<P> +<TABLE> +<TR><TD><b>VIDEO_MODE_PAL</b><TD>The tuner is in PAL mode</TD> +<TR><TD><b>VIDEO_MODE_NTSC</b><TD>The tuner is in NTSC mode</TD> +<TR><TD><b>VIDEO_MODE_SECAM</b><TD>The tuner is in SECAM mode</TD> +<TR><TD><b>VIDEO_MODE_AUTO</b><TD>The tuner auto switches, or mode does not apply</TD> +</TABLE> +<P> +Tuning frequencies are an unsigned 32bit value in 1/16th MHz or if the +<b>VIDEO_TUNER_LOW</b> flag is set they are in 1/16th KHz. The current +frequency is obtained as an unsigned long via the <b>VIDIOCGFREQ</b> ioctl and +set by the <b>VIDIOCSFREQ</b> ioctl. +<P> +<H3>Audio</H3> +TV and Radio devices have one or more audio inputs that may be selected. +The audio properties are queried by passing a <b>struct video_audio</b> to <b>VIDIOCGAUDIO</b> ioctl. The +<b>VIDIOCSAUDIO</b> ioctl sets audio properties. +<P> +The structure contains the following fields +<P> +<TABLE> +<TR><TD><b>audio</b><TD>The channel number</TD> +<TR><TD><b>volume</b><TD>The volume level</TD> +<TR><TD><b>bass</b><TD>The bass level</TD> +<TR><TD><b>treble</b><TD>The treble level</TD> +<TR><TD><b>flags</b><TD>Flags describing the audio channel</TD> +<TR><TD><b>name</b><TD>Canonical name for the audio input</TD> +<TR><TD><b>mode</b><TD>The mode the audio input is in</TD> +<TR><TD><b>balance</b><TD>The left/right balance</TD> +<TR><TD><b>step</b><TD>Actual step used by the hardware</TD> +</TABLE> +<P> +The following flags are defined +<P> +<TABLE> +<TR><TD><b>VIDEO_AUDIO_MUTE</b><TD>The audio is muted</TD> +<TR><TD><b>VIDEO_AUDIO_MUTABLE</b><TD>Audio muting is supported</TD> +<TR><TD><b>VIDEO_AUDIO_VOLUME</b><TD>The volume is controllable</TD> +<TR><TD><b>VIDEO_AUDIO_BASS</b><TD>The bass is controllable</TD> +<TR><TD><b>VIDEO_AUDIO_TREBLE</b><TD>The treble is controllable</TD> +<TR><TD><b>VIDEO_AUDIO_BALANCE</b><TD>The balance is controllable</TD> +</TABLE> +<P> +The following decoding modes are defined +<P> +<TABLE> +<TR><TD><b>VIDEO_SOUND_MONO</b><TD>Mono signal</TD> +<TR><TD><b>VIDEO_SOUND_STEREO</b><TD>Stereo signal (NICAM for TV)</TD> +<TR><TD><b>VIDEO_SOUND_LANG1</b><TD>European TV alternate language 1</TD> +<TR><TD><b>VIDEO_SOUND_LANG2</b><TD>European TV alternate language 2</TD> +</TABLE> +<P> +<H3>Reading Images</H3> +Each call to the <b>read</b> syscall returns the next available image +from the device. It is up to the caller to set format and size (using +the VIDIOCSPICT and VIDIOCSWIN ioctls) and then to pass a suitable +size buffer and length to the function. Not all devices will support +read operations. +<P> +A second way to handle image capture is via the mmap interface if supported. +To use the mmap interface a user first sets the desired image size and depth +properties. Next the VIDIOCGMBUF ioctl is issued. This reports the size +of buffer to mmap and the offset within the buffer for each frame. The +number of frames supported is device dependent and may only be one. +<P> +The video_mbuf structure contains the following fields +<P> +<TABLE> +<TR><TD><b>size</b><TD>The number of bytes to map</TD> +<TR><TD><b>frames</b><TD>The number of frames</TD> +<TR><TD><b>offsets</b><TD>The offset of each frame</TD> +</TABLE> +<P> +Once the mmap has been made the VIDIOCMCAPTURE ioctl starts the +capture to a frame using the format and image size specified in the +video_mmap (which should match or be below the initial query size). +When the VIDIOCMCAPTURE ioctl returns the frame is <em>not</em> +captured yet, the driver just instructed the hardware to start the +capture. The application has to use the VIDIOCSYNC ioctl to wait +until the capture of a frame is finished. VIDIOCSYNC takes the frame +number you want to wait for as argument. +<p> +It is allowed to call VIDIOCMCAPTURE multiple times (with different +frame numbers in video_mmap->frame of course) and thus have multiple +outstanding capture requests. A simple way do to double-buffering +using this feature looks like this: +<pre> +/* setup everything */ +VIDIOCMCAPTURE(0) +while (whatever) { + VIDIOCMCAPTURE(1) + VIDIOCSYNC(0) + /* process frame 0 while the hardware captures frame 1 */ + VIDIOCMCAPTURE(0) + VIDIOCSYNC(1) + /* process frame 1 while the hardware captures frame 0 */ +} +</pre> +Note that you are <em>not</em> limited to only two frames. The API +allows up to 32 frames, the VIDIOCGMBUF ioctl returns the number of +frames the driver granted. Thus it is possible to build deeper queues +to avoid loosing frames on load peaks. +<p> +While capturing to memory the driver will make a "best effort" attempt +to capture to screen as well if requested. This normally means all +frames that "miss" memory mapped capture will go to the display. +<P> +A final ioctl exists to allow a device to obtain related devices if a +driver has multiple components (for example video0 may not be associated +with vbi0 which would cause an intercast display program to make a bad +mistake). The VIDIOCGUNIT ioctl reports the unit numbers of the associated +devices if any exist. The video_unit structure has the following fields. +<P> +<TABLE> +<TR><TD><b>video</b><TD>Video capture device</TD> +<TR><TD><b>vbi</b><TD>VBI capture device</TD> +<TR><TD><b>radio</b><TD>Radio device</TD> +<TR><TD><b>audio</b><TD>Audio mixer</TD> +<TR><TD><b>teletext</b><TD>Teletext device</TD> +</TABLE> +<P> +<H3>RDS Datastreams</H3> +For radio devices that support it, it is possible to receive Radio Data +System (RDS) data by means of a read() on the device. The data is packed in +groups of three, as follows: +<TABLE> +<TR><TD>First Octet</TD><TD>Least Significant Byte of RDS Block</TD></TR> +<TR><TD>Second Octet</TD><TD>Most Significant Byte of RDS Block +<TR><TD>Third Octet</TD><TD>Bit 7:</TD><TD>Error bit. Indicates that +an uncorrectable error occurred during reception of this block.</TD></TR> +<TR><TD> </TD><TD>Bit 6:</TD><TD>Corrected bit. Indicates that +an error was corrected for this data block.</TD></TR> +<TR><TD> </TD><TD>Bits 5-3:</TD><TD>Received Offset. Indicates the +offset received by the sync system.</TD></TR> +<TR><TD> </TD><TD>Bits 2-0:</TD><TD>Offset Name. Indicates the +offset applied to this data.</TD></TR> +</TABLE> +</BODY> +</HTML> diff --git a/v4l2-spec/biblio.sgml b/v4l2-spec/biblio.sgml index b013ece1d..afc8a0dd2 100644 --- a/v4l2-spec/biblio.sgml +++ b/v4l2-spec/biblio.sgml @@ -158,54 +158,23 @@ Signal - NTSC for Studio Applications"</title> 1125-Line High-Definition Production"</title> </biblioentry> - <biblioentry id="v4l"> - <abbrev>V4L</abbrev> - <authorgroup> - <author> - <firstname>Alan</firstname> - <surname>Cox</surname> - <affiliation> - <orgname>Red Hat, Inc.</orgname> - <address> - <email>alan@redhat.com</email> - </address> - </affiliation> - </author> - </authorgroup> - <title>Video4Linux API Specification</title> - <abstract> - <para>This file is part of the Linux kernel sources under -<filename>Documentation/video4linux</filename>.</para> - </abstract> - </biblioentry> - - <biblioentry id="v4lprog"> - <abbrev>V4LPROG</abbrev> - <authorgroup> - <author> - <firstname>Alan</firstname> - <surname>Cox</surname> - <affiliation> - <orgname>Red Hat, Inc.</orgname> - <address> - <email>alan@redhat.com</email> - </address> - </affiliation> - </author> - </authorgroup> - <title>Video4Linux Programming (a.k.a. The Video4Linux -Book)</title> - <abstract> - <para>About V4L <emphasis>driver</emphasis> programming. This -book is part of the Linux kernel DocBook documentation, for example at -<ulink url="http://kernelnewbies.org/documents/"> -http://kernelnewbies.org/documents/</ulink>. SGML sources are included -in the kernel sources.</para> - </abstract> - <copyright> - <year>2000</year> - <holder>Alan Cox</holder> - </copyright> + <biblioentry id="en50067"> + <abbrev>EN 50067</abbrev> + <authorgroup> + <corpauthor>European Committee for Electrotechnical Standardization +(<ulink url="http://www.cenelec.eu">http://www.cenelec.eu</ulink>)</corpauthor> + </authorgroup> + <title>Specification of the radio data system (RDS) for VHF/FM sound broadcasting +in the frequency range from 87,5 to 108,0 MHz</title> + </biblioentry> + + <biblioentry id="nrsc4"> + <abbrev>NRSC-4</abbrev> + <authorgroup> + <corpauthor>National Radio Systems Committee +(<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor> + </authorgroup> + <title>NTSC-4: United States RBDS Standard</title> </biblioentry> </bibliography> diff --git a/v4l2-spec/common.sgml b/v4l2-spec/common.sgml index ff595960b..75c7141e3 100644 --- a/v4l2-spec/common.sgml +++ b/v4l2-spec/common.sgml @@ -491,7 +491,7 @@ the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that <constant>VIDIOC_S_MODULATOR</constant> does not switch the current modulator, when there is more than one at all. The modulator is solely determined by the current video output. Drivers must support both -ioctls and set the <constant>V4L2_CAP_TUNER</constant> (sic) flag in +ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or more modulators.</para> </section> diff --git a/v4l2-spec/compat.sgml b/v4l2-spec/compat.sgml index 94713023d..07b3b4058 100644 --- a/v4l2-spec/compat.sgml +++ b/v4l2-spec/compat.sgml @@ -1273,9 +1273,8 @@ also the size of the structure changed, which is encoded in the ioctl request code, thus older V4L2 devices will respond with an &EINVAL; to the new &VIDIOC-QUERYCAP; ioctl.</para> - <para>There are new fields to identify the driver, a new (as -of yet unspecified) device function -<constant>V4L2_CAP_RDS_CAPTURE</constant>, the + <para>There are new fields to identify the driver, a new RDS +device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the <constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has any audio connectors, another I/O capability <constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to @@ -2294,6 +2293,30 @@ was renamed to <structname id=v4l2-chip-ident-old>v4l2_chip_ident_old</structnam </listitem> </orderedlist> </section> + <section> + <title>V4L2 in Linux 2.6.32</title> + <orderedlist> + <listitem> + <para>Finalized the RDS capture API. See <xref linkend="rds"> for +more information.</para> + </listitem> + <listitem> + <para>Added new capabilities for modulators and RDS encoders.</para> + </listitem> + <listitem> + <para>Add description for libv4l API.</para> + </listitem> + <listitem> + <para>Added support for string controls via new type <constant>V4L2_CTRL_TYPE_STRING</constant>.</para> + </listitem> + <listitem> + <para>Added <constant>V4L2_CID_BAND_STOP_FILTER</constant> documentation.</para> + </listitem> + <listitem> + <para>Added FM Modulator (FM TX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_TX</constant> and their Control IDs.</para> + </listitem> + </orderedlist> + </section> </section> <section id="other"> diff --git a/v4l2-spec/controls.sgml b/v4l2-spec/controls.sgml index 477a97077..869198601 100644 --- a/v4l2-spec/controls.sgml +++ b/v4l2-spec/controls.sgml @@ -458,6 +458,12 @@ video is actually encoded into that format.</para> <para>Unfortunately, the original control API lacked some features needed for these new uses and so it was extended into the (not terribly originally named) extended control API.</para> + + <para>Even though the MPEG encoding API was the first effort +to use the Extended Control API, nowadays there are also other classes +of Extended Controls, such as Camera Controls and FM Transmitter Controls. +The Extended Controls API as well as all Extended Controls classes are +described in the following text.</para> </section> <section> @@ -492,8 +498,7 @@ supported.</para> <para>The control array is a &v4l2-ext-control; array. The <structname>v4l2_ext_control</structname> structure is very similar to &v4l2-control;, except for the fact that it also allows for 64-bit -values and pointers to be passed (although the latter is not yet used -anywhere).</para> +values and pointers to be passed.</para> <para>It is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set @@ -1811,11 +1816,228 @@ mechanical obturation of the sensor and firmware image processing, but the device is not restricted to these methods. Devices that implement the privacy control must support read access and may support write access.</entry> </row> + + <row> + <entry spanname="id"><constant>V4L2_CID_BAND_STOP_FILTER</constant> </entry> + <entry>integer</entry> + </row><row><entry spanname="descr">Switch the band-stop filter of a +camera sensor on or off, or specify its strength. Such band-stop filters can +be used, for example, to filter out the fluorescent light component.</entry> + </row> <row><entry></entry></row> </tbody> </tgroup> </table> </section> + + <section id="fm-tx-controls"> + <title>FM Transmitter Control Reference</title> + + <para>The FM Transmitter (FM_TX) class includes controls for common features of +FM transmissions capable devices. Currently this class includes parameters for audio +compression, pilot tone generation, audio deviation limiter, RDS transmission and +tuning power features.</para> + + <table pgwide="1" frame="none" id="fm-tx-control-id"> + <title>FM_TX Control IDs</title> + + <tgroup cols="4"> + <colspec colname="c1" colwidth="1*"> + <colspec colname="c2" colwidth="6*"> + <colspec colname="c3" colwidth="2*"> + <colspec colname="c4" colwidth="6*"> + <spanspec namest="c1" nameend="c2" spanname="id"> + <spanspec namest="c2" nameend="c4" spanname="descr"> + <thead> + <row> + <entry spanname="id" align="left">ID</entry> + <entry align="left">Type</entry> + </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> + </row> + </thead> + <tbody valign="top"> + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_FM_TX_CLASS</constant> </entry> + <entry>class</entry> + </row><row><entry spanname="descr">The FM_TX class +descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a +description of this control class.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_DEVIATION</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Configures RDS signal frequency deviation level in Hz. +The range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_PI</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Sets the RDS Programme Identification field +for transmission.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_PTY</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Sets the RDS Programme Type field for transmission. +This encodes up to 31 pre-defined programme types.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_PS_NAME</constant> </entry> + <entry>string</entry> + </row> + <row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission. +It is intended for static display on a receiver. It is the primary aid to listeners in programme service +identification and selection. In Annex E of <xref linkend="en50067">, the RDS specification, +there is a full description of the correct character encoding for Programme Service name strings. +Also from RDS specification, PS is usually a single eight character text. However, it is also possible +to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured +with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_RADIO_TEXT</constant> </entry> + <entry>string</entry> + </row> + <row><entry spanname="descr">Sets the Radio Text info for transmission. It is a textual description of +what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names, +programme-related information or any other text. In these cases, RadioText should be used in addition to +<constant>V4L2_CID_RDS_TX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described +in Annex E of <xref linkend="en50067">. The length of Radio Text strings depends on which RDS Block is being +used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible +to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured +with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Enables or disables the audio deviation limiter feature. +The limiter is useful when trying to maximize the audio volume, minimize receiver-generated +distortion and prevent overmodulation. +</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_RELEASE_TIME</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Sets the audio deviation limiter feature release time. +Unit is in useconds. Step and range are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_DEVIATION</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Configures audio frequency deviation level in Hz. +The range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ENABLED</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Enables or disables the audio compression feature. +This feature amplifies signals below the threshold by a fixed gain and compresses audio +signals above the threshold by the ratio of Threshold/(Gain + Threshold).</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_GAIN</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Sets the gain for audio compression feature. It is +a dB value. The range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_THRESHOLD</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Sets the threshold level for audio compression freature. +It is a dB value. The range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Sets the attack time for audio compression feature. +It is a useconds value. The range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Sets the release time for audio compression feature. +It is a useconds value. The range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_ENABLED</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Enables or disables the pilot tone generation feature.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_DEVIATION</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Configures pilot tone frequency deviation level. Unit is +in Hz. The range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_FREQUENCY</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Configures pilot tone frequency value. Unit is +in Hz. The range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant> </entry> + <entry>integer</entry> + </row> + <row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting. +A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies. +Depending on the region, a time constant of either 50 or 75 useconds is used. The enum v4l2_preemphasis +defines possible values for pre-emphasis. Here they are:</entry> + </row><row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_PREEMPHASIS_DISABLED</constant> </entry> + <entry>No pre-emphasis is applied.</entry> + </row> + <row> + <entry><constant>V4L2_PREEMPHASIS_50_uS</constant> </entry> + <entry>A pre-emphasis of 50 uS is used.</entry> + </row> + <row> + <entry><constant>V4L2_PREEMPHASIS_75_uS</constant> </entry> + <entry>A pre-emphasis of 75 uS is used.</entry> + </row> + </tbody> + </entrytbl> + + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_TUNE_POWER_LEVEL</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Sets the output power level for signal transmission. +Unit is in dBuV. Range and step are driver-specific.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_TUNE_ANTENNA_CAPACITOR</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">This selects the value of antenna tuning capacitor +manually or automatically if set to zero. Unit, range and step are driver-specific.</entry> + </row> + <row><entry></entry></row> + </tbody> + </tgroup> + </table> + +<para>For more details about RDS specification, refer to +<xref linkend="en50067"> document, from CENELEC.</para> + </section> </section> <!-- diff --git a/v4l2-spec/dev-radio.sgml b/v4l2-spec/dev-radio.sgml index ae8367219..4d521d2a8 100644 --- a/v4l2-spec/dev-radio.sgml +++ b/v4l2-spec/dev-radio.sgml @@ -1,7 +1,7 @@ <title>Radio Interface</title> <para>This interface is intended for AM and FM (analog) radio -receivers.</para> +receivers and transmitters.</para> <para>Conventionally V4L2 radio devices are accessed through character device special files named <filename>/dev/radio</filename> @@ -14,7 +14,8 @@ numbers 64 to 127.</para> <para>Devices supporting the radio interface set the <constant>V4L2_CAP_RADIO</constant> and -<constant>V4L2_CAP_TUNER</constant> flag in the +<constant>V4L2_CAP_TUNER</constant> or +<constant>V4L2_CAP_MODULATOR</constant> flag in the <structfield>capabilities</structfield> field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl. Other combinations of capability flags are reserved for future extensions.</para> @@ -25,7 +26,7 @@ capability flags are reserved for future extensions.</para> <para>Radio devices can support <link linkend="control">controls</link>, and must support the <link -linkend="tuner">tuner</link> ioctls.</para> +linkend="tuner">tuner or modulator</link> ioctls.</para> <para>They do not support the video input or output, audio input or output, video standard, cropping and scaling, compression and @@ -38,11 +39,12 @@ methods are reserved for future extensions.</para> <para>Radio devices may have a couple audio controls (as discussed in <xref linkend="control">) such as a volume control, possibly custom -controls. Further all radio devices have one tuner (these are +controls. Further all radio devices have one tuner or modulator (these are discussed in <xref linkend="tuner">) with index number zero to select the radio frequency and to determine if a monaural or FM stereo -program is received. Drivers switch automatically between AM and FM -depending on the selected frequency. The &VIDIOC-G-TUNER; ioctl +program is received/emitted. Drivers switch automatically between AM and FM +depending on the selected frequency. The &VIDIOC-G-TUNER; or +&VIDIOC-G-MODULATOR; ioctl reports the supported frequency range.</para> </section> diff --git a/v4l2-spec/dev-rds.sgml b/v4l2-spec/dev-rds.sgml index 07bfd4c65..9d59d0cb0 100644 --- a/v4l2-spec/dev-rds.sgml +++ b/v4l2-spec/dev-rds.sgml @@ -2,38 +2,162 @@ <para>The Radio Data System transmits supplementary information in binary format, for example the station name or travel -information, on a inaudible audio subcarrier of a radio program. This -interface aims at devices capable of receiving and decoding RDS +information, on an inaudible audio subcarrier of a radio program. This +interface is aimed at devices capable of receiving and decoding RDS information.</para> - <para>The V4L API defines its RDS API as follows.</para> - - <para>From radio devices supporting it, RDS data can be read -with the &func-read; function. The data is packed in groups of three, -as follows:<orderedlist> - <listitem> - <para>First Octet Least Significant Byte of RDS Block</para> - </listitem> - <listitem> - <para>Second Octet Most Significant Byte of RDS Block</para> - </listitem> - <listitem> - <para>Third Octet Bit 7: Error bit. Indicates that an -uncorrectable error occurred during reception of this block. Bit 6: -Corrected bit. Indicates that an error was corrected for this data -block. Bits 5-3: Received Offset. Indicates the offset received by the -sync system. Bits 2-0: Offset Name. Indicates the offset applied to -this data.</para> - </listitem> - </orderedlist></para> - - <para>It was argued <!-- video4linux-list@redhat.com -on 12 Nov 2002, subject "RDS/RBDS" --> the RDS API should be -extended before integration into V4L2, no new API has been devised yet. -Please write to the linux-media mailing list for discussion: &v4l-ml;. -Meanwhile no V4L2 driver should set the -<constant>V4L2_CAP_RDS_CAPTURE</constant> capability flag.</para> + <para>For more information see the core RDS standard <xref linkend="en50067"> +and the RBDS standard <xref linkend="nrsc4">.</para> + <para>Note that the RBDS standard as is used in the USA is almost identical +to the RDS standard. Any RDS decoder can also handle RBDS. Only some of the fields +have slightly different meanings. See the RBDS standard for more information.</para> + + <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search). +This is a proprietary format which seems to be discontinued. The RDS interface does not +support this format. Should support for MMBS (or the so-called 'E blocks' in general) +be needed, then please contact the linux-media mailing list: &v4l-ml;.</para> + + <section> + <title>Querying Capabilities</title> + + <para>Devices supporting the RDS capturing API +set the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in +the <structfield>capabilities</structfield> field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl. +Any tuner that supports RDS will set the +<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield> +field of &v4l2-tuner;. +Whether an RDS signal is present can be detected by looking at +the <structfield>rxsubchans</structfield> field of &v4l2-tuner;: the +<constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data was detected.</para> + + <para>Devices supporting the RDS output API +set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in +the <structfield>capabilities</structfield> field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl. +Any modulator that supports RDS will set the +<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield> +field of &v4l2-modulator;. +In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant> +bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.</para> + + </section> + + <section> + <title>Reading RDS data</title> + + <para>RDS data can be read from the radio device +with the &func-read; function. The data is packed in groups of three bytes, +as follows:</para> + <table frame="none" pgwide="1" id="v4l2-rds-data"> + <title>struct +<structname>v4l2_rds_data</structname></title> + <tgroup cols="3"> + <colspec colname="c1" colwidth="1*"> + <colspec colname="c2" colwidth="1*"> + <colspec colname="c3" colwidth="5*"> + <tbody valign="top"> + <row> + <entry>__u8</entry> + <entry><structfield>lsb</structfield></entry> + <entry>Least Significant Byte of RDS Block</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>msb</structfield></entry> + <entry>Most Significant Byte of RDS Block</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>block</structfield></entry> + <entry>Block description</entry> + </row> + </tbody> + </tgroup> + </table> + <table frame="none" pgwide="1" id="v4l2-rds-block"> + <title>Block description</title> + <tgroup cols="2"> + <colspec colname="c1" colwidth="1*"> + <colspec colname="c2" colwidth="5*"> + <tbody valign="top"> + <row> + <entry>Bits 0-2</entry> + <entry>Block (aka offset) of the received data.</entry> + </row> + <row> + <entry>Bits 3-5</entry> + <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry> + </row> + <row> + <entry>Bit 6</entry> + <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry> + </row> + <row> + <entry>Bit 7</entry> + <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="v4l2-rds-block-codes"> + <title>Block defines</title> + <tgroup cols="3"> + <colspec colname="c1" colwidth="1*"> + <colspec colname="c2" colwidth="1*"> + <colspec colname="c3" colwidth="5*"> + <tbody valign="top"> + <row> + <entry>V4L2_RDS_BLOCK_MSK</entry> + <entry>7</entry> + <entry>Mask for bits 0-2 to get the block ID.</entry> + </row> + <row> + <entry>V4L2_RDS_BLOCK_A</entry> + <entry>0</entry> + <entry>Block A.</entry> + </row> + <row> + <entry>V4L2_RDS_BLOCK_B</entry> + <entry>1</entry> + <entry>Block B.</entry> + </row> + <row> + <entry>V4L2_RDS_BLOCK_C</entry> + <entry>2</entry> + <entry>Block C.</entry> + </row> + <row> + <entry>V4L2_RDS_BLOCK_D</entry> + <entry>3</entry> + <entry>Block D.</entry> + </row> + <row> + <entry>V4L2_RDS_BLOCK_C_ALT</entry> + <entry>4</entry> + <entry>Block C'.</entry> + </row> + <row> + <entry>V4L2_RDS_BLOCK_INVALID</entry> + <entry>7</entry> + <entry>An invalid block.</entry> + </row> + <row> + <entry>V4L2_RDS_BLOCK_CORRECTED</entry> + <entry>0x40</entry> + <entry>A bit error was detected but corrected.</entry> + </row> + <row> + <entry>V4L2_RDS_BLOCK_ERROR</entry> + <entry>0x80</entry> + <entry>An incorrectable error occurred.</entry> + </row> + </tbody> + </tgroup> + </table> + </section> <!-- Local Variables: diff --git a/v4l2-spec/dev-sliced-vbi.sgml b/v4l2-spec/dev-sliced-vbi.sgml index 5560650a6..3c260e3e3 100644 --- a/v4l2-spec/dev-sliced-vbi.sgml +++ b/v4l2-spec/dev-sliced-vbi.sgml @@ -48,7 +48,7 @@ vital to program a sliced VBI device, therefore must be supported.</para> </section> - <section> + <section id="sliced-vbi-format-negotitation"> <title>Sliced VBI Format Negotiation</title> <para>To find out which data services are supported by the @@ -386,6 +386,319 @@ video and VBI data by using buffer timestamps.</para> </section> + <section> + <title>Sliced VBI Data in MPEG Streams</title> + + <para>If a device can produce an MPEG output stream, it may be +capable of providing <link +linkend="sliced-vbi-format-negotitation">negotiated sliced VBI +services</link> as data embedded in the MPEG stream. Users or +applications control this sliced VBI data insertion with the <link +linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> +control.</para> + + <para>If the driver does not provide the <link +linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> +control, or only allows that control to be set to <link +linkend="v4l2-mpeg-stream-vbi-fmt"><constant> +V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device +cannot embed sliced VBI data in the MPEG stream.</para> + + <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"> +V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set +the device driver to capture nor cease capturing sliced VBI data. The +control only indicates to embed sliced VBI data in the MPEG stream, if +an application has negotiated sliced VBI service be captured.</para> + + <para>It may also be the case that a device can embed sliced VBI +data in only certain types of MPEG streams: for example in an MPEG-2 +PS but not an MPEG-2 TS. In this situation, if sliced VBI data +insertion is requested, the sliced VBI data will be embedded in MPEG +stream types when supported, and silently omitted from MPEG stream +types where sliced VBI data insertion is not supported by the device. +</para> + + <para>The following subsections specify the format of the +embedded sliced VBI data.</para> + + <section> + <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title> + <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> +V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI +format shall be interpreted by drivers as a control to cease +embedding sliced VBI data in MPEG streams. Neither the device nor +driver shall insert "empty" embedded sliced VBI data packets in the +MPEG stream when this format is set. No MPEG stream data structures +are specified for this format.</para> + </section> + + <section> + <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title> + <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> +V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI +format, when supported, indicates to the driver to embed up to 36 +lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private +Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis> +Program Pack</emphasis> in the MPEG stream.</para> + + <para><emphasis>Historical context</emphasis>: This format +specification originates from a custom, embedded, sliced VBI data +format used by the <filename>ivtv</filename> driver. This format +has already been informally specified in the kernel sources in the +file <filename>Documentation/video4linux/cx2341x/README.vbi</filename> +. The maximum size of the payload and other aspects of this format +are driven by the CX23415 MPEG decoder's capabilities and limitations +with respect to extracting, decoding, and displaying sliced VBI data +embedded within an MPEG stream.</para> + + <para>This format's use is <emphasis>not</emphasis> exclusive to +the <filename>ivtv</filename> driver <emphasis>nor</emphasis> +exclusive to CX2341x devices, as the sliced VBI data packet insertion +into the MPEG stream is implemented in driver software. At least the +<filename>cx18</filename> driver provides sliced VBI data insertion +into an MPEG-2 PS in this format as well.</para> + + <para>The following definitions specify the payload of the +MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain +sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt"> +<constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set. +(The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header +and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are +not detailed here. Please refer to the MPEG-2 specifications for +details on those packet headers.)</para> + + <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES +</emphasis> packets that contain sliced VBI data is specified by +&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable +length, depending on the actual number of lines of sliced VBI data +present in a video frame. The payload may be padded at the end with +unspecified fill bytes to align the end of the payload to a 4-byte +boundary. The payload shall never exceed 1552 bytes (2 fields with +18 lines/field with 43 bytes of data/line and a 4 byte magic number). +</para> + + <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv"> + <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname> + </title> + <tgroup cols="4"> + &cs-ustr; + <tbody valign="top"> + <row> + <entry>__u8</entry> + <entry><structfield>magic</structfield>[4]</entry> + <entry></entry> + <entry>A "magic" constant from <xref + linkend="v4l2-mpeg-vbi-fmt-ivtv-magic"> that indicates +this is a valid sliced VBI data payload and also indicates which +member of the anonymous union, <structfield>itv0</structfield> or +<structfield>ITV0</structfield>, to use for the payload data.</entry> + </row> + <row> + <entry>union</entry> + <entry>(anonymous)</entry> + </row> + <row> + <entry></entry> + <entry>struct <link linkend="v4l2-mpeg-vbi-itv0"> + <structname>v4l2_mpeg_vbi_itv0</structname></link> + </entry> + <entry><structfield>itv0</structfield></entry> + <entry>The primary form of the sliced VBI data payload +that contains anywhere from 1 to 35 lines of sliced VBI data. +Line masks are provided in this form of the payload indicating +which VBI lines are provided.</entry> + </row> + <row> + <entry></entry> + <entry>struct <link linkend="v4l2-mpeg-vbi-ITV0-1"> + <structname>v4l2_mpeg_vbi_ITV0</structname></link> + </entry> + <entry><structfield>ITV0</structfield></entry> + <entry>An alternate form of the sliced VBI data payload +used when 36 lines of sliced VBI data are present. No line masks are +provided in this form of the payload; all valid line mask bits are +implcitly set.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic"> + <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv; + <structfield>magic</structfield> field</title> + <tgroup cols="3"> + &cs-def; + <thead> + <row> + <entry align="left">Defined Symbol</entry> + <entry align="left">Value</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant> + </entry> + <entry>"itv0"</entry> + <entry>Indicates the <structfield>itv0</structfield> +member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant> + </entry> + <entry>"ITV0"</entry> + <entry>Indicates the <structfield>ITV0</structfield> +member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and +that 36 lines of sliced VBI data are present.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0"> + <title>struct <structname>v4l2_mpeg_vbi_itv0</structname> + </title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__le32</entry> + <entry><structfield>linemask</structfield>[2]</entry> + <entry><para>Bitmasks indicating the VBI service lines +present. These <structfield>linemask</structfield> values are stored +in little endian byte order in the MPEG stream. Some reference +<structfield>linemask</structfield> bit positions with their +corresponding VBI line number and video field are given below. +b<subscript>0</subscript> indicates the least significant bit of a +<structfield>linemask</structfield> value:<screen> +<structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field +<structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field +<structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field +<structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field +<structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field +<structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field +<structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry> + </row> + <row> + <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> + <structname>v4l2_mpeg_vbi_itv0_line</structname></link> + </entry> + <entry><structfield>line</structfield>[35]</entry> + <entry>This is a variable length array that holds from 1 +to 35 lines of sliced VBI data. The sliced VBI data lines present +correspond to the bits set in the <structfield>linemask</structfield> +array, starting from b<subscript>0</subscript> of <structfield> +linemask</structfield>[0] up through b<subscript>31</subscript> of +<structfield>linemask</structfield>[0], and from b<subscript>0 +</subscript> of <structfield>linemask</structfield>[1] up through b +<subscript>3</subscript> of <structfield>linemask</structfield>[1]. +<structfield>line</structfield>[0] corresponds to the first bit +found set in the <structfield>linemask</structfield> array, +<structfield>line</structfield>[1] corresponds to the second bit +found set in the <structfield>linemask</structfield> array, etc. +If no <structfield>linemask</structfield> array bits are set, then +<structfield>line</structfield>[0] may contain one line of +unspecified data that should be ignored by applications.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-ITV0-1"> + <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname> + </title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> + <structname>v4l2_mpeg_vbi_itv0_line</structname></link> + </entry> + <entry><structfield>line</structfield>[36]</entry> + <entry>A fixed length array of 36 lines of sliced VBI +data. <structfield>line</structfield>[0] through <structfield>line +</structfield>[17] correspond to lines 6 through 23 of the +first field. <structfield>line</structfield>[18] through +<structfield>line</structfield>[35] corresponds to lines 6 +through 23 of the second field.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line"> + <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname> + </title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u8</entry> + <entry><structfield>id</structfield></entry> + <entry>A line identifier value from +<xref linkend="ITV0-Line-Identifier-Constants"> that indicates +the type of sliced VBI data stored on this line.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>data</structfield>[42]</entry> + <entry>The sliced VBI data for the line.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants"> + <title>Line Identifiers for struct <link + linkend="v4l2-mpeg-vbi-itv0-line"><structname> +v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id +</structfield> field</title> + <tgroup cols="3"> + &cs-def; + <thead> + <row> + <entry align="left">Defined Symbol</entry> + <entry align="left">Value</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant> + </entry> + <entry>1</entry> + <entry>Refer to <link linkend="vbi-services2"> +Sliced VBI services</link> for a description of the line payload.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant> + </entry> + <entry>4</entry> + <entry>Refer to <link linkend="vbi-services2"> +Sliced VBI services</link> for a description of the line payload.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant> + </entry> + <entry>5</entry> + <entry>Refer to <link linkend="vbi-services2"> +Sliced VBI services</link> for a description of the line payload.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant> + </entry> + <entry>7</entry> + <entry>Refer to <link linkend="vbi-services2"> +Sliced VBI services</link> for a description of the line payload.</entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + </section> + + <!-- Local Variables: mode: sgml diff --git a/v4l2-spec/libv4l.sgml b/v4l2-spec/libv4l.sgml new file mode 100644 index 000000000..ec1f8b6fe --- /dev/null +++ b/v4l2-spec/libv4l.sgml @@ -0,0 +1,168 @@ +<title>Libv4l Userspace Library</title> +<section id="libv4l-introduction"> + <title>Introduction</title> + + <para>libv4l is a collection of libraries which adds a thin abstraction +layer on top of video4linux2 devices. The purpose of this (thin) layer +is to make it easy for application writers to support a wide variety of +devices without having to write separate code for different devices in the +same class.</para> +<para>An example of using libv4l is provided by +<link linkend='v4l2grab-example'>v4l2grab</link>. +</para> + + <para>libv4l consists of 3 different libraries:</para> + <section> + <title>libv4lconvert</title> + + <para>libv4lconvert is a library that converts several +different pixelformats found in V4L2 drivers into a few common RGB and +YUY formats.</para> + <para>It currently accepts the following V4L2 driver formats: +<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>, +<link linkend="V4L2-PIX-FMT-HM12"><constant>V4L2_PIX_FMT_HM12</constant></link>, +<link linkend="V4L2-PIX-FMT-JPEG"><constant>V4L2_PIX_FMT_JPEG</constant></link>, +<link linkend="V4L2-PIX-FMT-MJPEG"><constant>V4L2_PIX_FMT_MJPEG</constant></link>, +<link linkend="V4L2-PIX-FMT-MR97310A"><constant>V4L2_PIX_FMT_MR97310A</constant></link>, +<link linkend="V4L2-PIX-FMT-OV511"><constant>V4L2_PIX_FMT_OV511</constant></link>, +<link linkend="V4L2-PIX-FMT-OV518"><constant>V4L2_PIX_FMT_OV518</constant></link>, +<link linkend="V4L2-PIX-FMT-PAC207"><constant>V4L2_PIX_FMT_PAC207</constant></link>, +<link linkend="V4L2-PIX-FMT-PJPG"><constant>V4L2_PIX_FMT_PJPG</constant></link>, +<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>, +<link linkend="V4L2-PIX-FMT-SBGGR8"><constant>V4L2_PIX_FMT_SBGGR8</constant></link>, +<link linkend="V4L2-PIX-FMT-SGBRG8"><constant>V4L2_PIX_FMT_SGBRG8</constant></link>, +<link linkend="V4L2-PIX-FMT-SGRBG8"><constant>V4L2_PIX_FMT_SGRBG8</constant></link>, +<link linkend="V4L2-PIX-FMT-SN9C10X"><constant>V4L2_PIX_FMT_SN9C10X</constant></link>, +<link linkend="V4L2-PIX-FMT-SN9C20X-I420"><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></link>, +<link linkend="V4L2-PIX-FMT-SPCA501"><constant>V4L2_PIX_FMT_SPCA501</constant></link>, +<link linkend="V4L2-PIX-FMT-SPCA505"><constant>V4L2_PIX_FMT_SPCA505</constant></link>, +<link linkend="V4L2-PIX-FMT-SPCA508"><constant>V4L2_PIX_FMT_SPCA508</constant></link>, +<link linkend="V4L2-PIX-FMT-SPCA561"><constant>V4L2_PIX_FMT_SPCA561</constant></link>, +<link linkend="V4L2-PIX-FMT-SQ905C"><constant>V4L2_PIX_FMT_SQ905C</constant></link>, +<constant>V4L2_PIX_FMT_SRGGB8</constant>, +<link linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link>, +<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>, +<link linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link>, +<link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>, +and <link linkend="V4L2-PIX-FMT-YVYU"><constant>V4L2_PIX_FMT_YVYU</constant></link>. +</para> + <para>Later on libv4lconvert was expanded to also be able to do +various video processing functions to improve webcam video quality. +The video processing is split in to 2 parts: libv4lconvert/control and +libv4lconvert/processing.</para> + + <para>The control part is used to offer video controls which can +be used to control the video processing functions made available by + libv4lconvert/processing. These controls are stored application wide +(until reboot) by using a persistent shared memory object.</para> + + <para>libv4lconvert/processing offers the actual video +processing functionality.</para> + </section> + <section> + <title>libv4l1</title> + <para>This library offers functions that can be used to quickly +make v4l1 applications work with v4l2 devices. These functions work exactly +like the normal open/close/etc, except that libv4l1 does full emulation of +the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it +will just pass calls through.</para> + <para>Since those functions are emulations of the old V4L1 API, +it shouldn't be used for new applications.</para> + </section> + <section> + <title>libv4l2</title> + <para>This library should be used for all modern V4L2 +applications.</para> + <para>It provides handles to call V4L2 open/ioctl/close/poll +methods. Instead of just providing the raw output of the device, it enhances +the calls in the sense that it will use libv4lconvert to provide more video +formats and to enhance the image quality.</para> + <para>In most cases, libv4l2 just passes the calls directly +through to the v4l2 driver, intercepting the calls to +<link linkend='VIDIOC-G-FMT'><constant>VIDIOC_TRY_FMT</constant></link>, +<link linkend='VIDIOC-G-FMT'><constant>VIDIOC_G_FMT</constant></link> +<link linkend='VIDIOC-G-FMT'><constant>VIDIOC_S_FMT</constant></link> +<link linkend='VIDIOC-ENUM-FRAMESIZES'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link> +and +<link linkend='VIDIOC-ENUM-FRAMEINTERVALS'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link> +in order to emulate the formats +<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>, +<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>, +<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>, +and <link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>, +if they aren't available in the driver. +<link linkend='VIDIOC-ENUM-FMT'><constant>VIDIOC_ENUM_FMT</constant></link> +keeps enumerating the hardware supported formats, plus the emulated formats +offered by libv4l at the end. +</para> + <section id="libv4l-ops"> + <title>Libv4l device control functions</title> + <para>The common file operation methods are provided by +libv4l.</para> + <para>Those functions operate just like glibc +open/close/dup/ioctl/read/mmap/munmap:</para> +<itemizedlist><listitem> + <para>int v4l2_open(const char *file, int oflag, +...) - +operates like the standard <link linkend='func-open'>open()</link> function. +</para></listitem><listitem> + <para>int v4l2_close(int fd) - +operates like the standard <link linkend='func-close'>close()</link> function. +</para></listitem><listitem> + <para>int v4l2_dup(int fd) - +operates like the standard dup() function, duplicating a file handler. +</para></listitem><listitem> + <para>int v4l2_ioctl (int fd, unsigned long int request, ...) - +operates like the standard <link linkend='func-ioctl'>ioctl()</link> function. +</para></listitem><listitem> + <para>int v4l2_read (int fd, void* buffer, size_t n) - +operates like the standard <link linkend='func-read'>read()</link> function. +</para></listitem><listitem> + <para>void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - +operates like the standard <link linkend='func-mmap'>mmap()</link> function. +</para></listitem><listitem> + <para>int v4l2_munmap(void *_start, size_t length); - +operates like the standard <link linkend='func-munmap'>munmap()</link> function. +</para></listitem> +</itemizedlist> + <para>Those functions provide additional control:</para> +<itemizedlist><listitem> + <para>int v4l2_fd_open(int fd, int v4l2_flags) - +opens an already opened fd for further use through v4l2lib and possibly +modify libv4l2's default behavior through the v4l2_flags argument. +Currently, v4l2_flags can be <constant>V4L2_DISABLE_CONVERSION</constant>, +to disable format conversion. +</para></listitem><listitem> + <para>int v4l2_set_control(int fd, int cid, int value) - +This function takes a value of 0 - 65535, and then scales that range to +the actual range of the given v4l control id, and then if the cid exists +and is not locked sets the cid to the scaled value. +</para></listitem><listitem> + <para>int v4l2_get_control(int fd, int cid) - +This function returns a value of 0 - 65535, scaled to from the actual range +of the given v4l control id. when the cid does not exist, could not be +accessed for some reason, or some error occured 0 is returned. +</para></listitem> +</itemizedlist> + </section> + </section> + <section> + + <title>v4l1compat.so wrapper library</title> + + <para>This library intercepts calls to +open/close/ioctl/mmap/mmunmap operations and redirects them to the libv4l +counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also +emulates V4L1 calls via V4L2 API.</para> + <para>It allows usage of binary legacy applications that +still don't use libv4l.</para> + </section> + +</section> +<!-- +Local Variables: +mode: sgml +sgml-parent-document: "v4l2.sgml" +indent-tabs-mode: nil +End: +--> diff --git a/v4l2-spec/pixfmt-sgrbg8.sgml b/v4l2-spec/pixfmt-sgrbg8.sgml new file mode 100644 index 000000000..553c5264a --- /dev/null +++ b/v4l2-spec/pixfmt-sgrbg8.sgml @@ -0,0 +1,75 @@ + <refentry id="V4L2-PIX-FMT-SGRBG8"> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_SGRBG8 ('GRBG')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname><constant>V4L2_PIX_FMT_SGRBG8</constant></refname> + <refpurpose>Bayer RGB format</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>This is commonly the native format of digital cameras, +reflecting the arrangement of sensors on the CCD device. Only one red, +green or blue value is given for each pixel. Missing components must +be interpolated from neighbouring pixels. From left to right the first +row consists of a green and blue value, the second row of a red and +green value. This scheme repeats to the right and down for every two +columns and rows.</para> + + <example> + <title><constant>V4L2_PIX_FMT_SGRBG8</constant> 4 × +4 pixel image</title> + + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="5" align="center"> + <colspec align="left" colwidth="2*"> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>G<subscript>00</subscript></entry> + <entry>R<subscript>01</subscript></entry> + <entry>G<subscript>02</subscript></entry> + <entry>R<subscript>03</subscript></entry> + </row> + <row> + <entry>start + 4:</entry> + <entry>R<subscript>10</subscript></entry> + <entry>B<subscript>11</subscript></entry> + <entry>R<subscript>12</subscript></entry> + <entry>B<subscript>13</subscript></entry> + </row> + <row> + <entry>start + 8:</entry> + <entry>G<subscript>20</subscript></entry> + <entry>R<subscript>21</subscript></entry> + <entry>G<subscript>22</subscript></entry> + <entry>R<subscript>23</subscript></entry> + </row> + <row> + <entry>start + 12:</entry> + <entry>R<subscript>30</subscript></entry> + <entry>B<subscript>31</subscript></entry> + <entry>R<subscript>32</subscript></entry> + <entry>B<subscript>33</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> + </refentry> + + <!-- +Local Variables: +mode: sgml +sgml-parent-document: "pixfmt.sgml" +indent-tabs-mode: nil +End: + --> diff --git a/v4l2-spec/pixfmt.sgml b/v4l2-spec/pixfmt.sgml index f1a36d396..9e6bebeb4 100644 --- a/v4l2-spec/pixfmt.sgml +++ b/v4l2-spec/pixfmt.sgml @@ -565,6 +565,7 @@ access the palette, this must be done with ioctls of the Linux framebuffer API.< &sub-packed-rgb; &sub-sbggr8; &sub-sgbrg8; + &sub-sgrbg8 &sub-sbggr16; </section> @@ -724,11 +725,26 @@ kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm <entry>'M310'</entry> <entry>Compressed BGGR Bayer format used by the gspca driver.</entry> </row> + <row id="V4L2-PIX-FMT-OV511"> + <entry><constant>V4L2_PIX_FMT_OV511</constant></entry> + <entry>'O511'</entry> + <entry>OV511 JPEG format used by the gspca driver.</entry> + </row> + <row id="V4L2-PIX-FMT-OV518"> + <entry><constant>V4L2_PIX_FMT_OV518</constant></entry> + <entry>'O518'</entry> + <entry>OV518 JPEG format used by the gspca driver.</entry> + </row> <row id="V4L2-PIX-FMT-PJPG"> <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry> <entry>'PJPG'</entry> <entry>Pixart 73xx JPEG format used by the gspca driver.</entry> </row> + <row id="V4L2-PIX-FMT-SQ905C"> + <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry> + <entry>'905C'</entry> + <entry>Compressed RGGB bayer format used by the gspca driver.</entry> + </row> <row id="V4L2-PIX-FMT-MJPEG"> <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry> <entry>'MJPG'</entry> @@ -749,6 +765,11 @@ kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm <entry>'S910'</entry> <entry>Compressed format of the SN9C102 driver.</entry> </row> + <row id="V4L2-PIX-FMT-SN9C20X-I420"> + <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry> + <entry>'S920'</entry> + <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry> + </row> <row id="V4L2-PIX-FMT-WNVA"> <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry> <entry>'WNVA'</entry> diff --git a/v4l2-spec/v4l2.sgml b/v4l2-spec/v4l2.sgml index 9f43b6d1e..f274ab95b 100644 --- a/v4l2-spec/v4l2.sgml +++ b/v4l2-spec/v4l2.sgml @@ -25,7 +25,7 @@ <book id="v4l2spec"> <bookinfo> <title>Video for Linux Two API Specification</title> - <subtitle>Revision 0.25</subtitle> + <subtitle>Revision 0.29</subtitle> <authorgroup> <author> @@ -77,8 +77,33 @@ API.</contrib> <contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib> </author> + + <author> + <firstname>Andy</firstname> + <surname>Walls</surname> + <contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV +MPEG stream embedded, sliced VBI data format in this specification. +</contrib> + <affiliation> + <address> + <email>awalls@radix.net</email> + </address> + </affiliation> + </author> </authorgroup> + <author> + <firstname>Mauro</firstname> + <surname>Carvalho Chehab</surname> + <contrib>Documented libv4l, designed and added v4l2grab example + </contrib> + <affiliation> + <address> + <email>mchehab@redhat.com</email> + </address> + </affiliation> + </author> + <copyright> <year>1999</year> <year>2000</year> @@ -92,12 +117,13 @@ and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib> <year>2008</year> <year>2009</year> <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin -Rubli</holder> +Rubli, Andy Walls, Mauro Carvalho Chehab</holder> </copyright> <legalnotice> <para>This document is copyrighted © 1999-2009 by Bill -Dirks, Michael H. Schimek, Hans Verkuil and Martin Rubli.</para> +Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls and +Mauro Carvalho Chehab.</para> <para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -118,6 +144,35 @@ structs, ioctls) must be noted in more detail in the history chapter applications. --> <revision> + <revnumber>0.29</revnumber> + <date>2009-08-26</date> + <authorinitials>ev</authorinitials> + <revremark>Added documentation for string controls and for FM Transmitter controls.</revremark> + </revision> + + <revision> + <revnumber>0.28</revnumber> + <date>2009-08-26</date> + <authorinitials>gl</authorinitials> + <revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark> + </revision> + + <revision> + <revnumber>0.27</revnumber> + <date>2009-08-15</date> + <authorinitials>mcc</authorinitials> + <revremark>Added libv4l documentation and v4l2grab example.</revremark> + </revision> + + <revision> + <revnumber>0.26</revnumber> + <date>2009-07-23</date> + <authorinitials>hv</authorinitials> + <revremark>Finalized the RDS capture API. Added modulator and RDS encoder +capabilities. Added support for string controls.</revremark> + </revision> + + <revision> <revnumber>0.25</revnumber> <date>2009-01-18</date> <authorinitials>hv</authorinitials> @@ -450,6 +505,10 @@ available here: <ulink url="http://linuxtv.org/downloads/video4linux/API/V4L2_AP &sub-driver; </chapter> + <chapter id="libv4l"> + &sub-libv4l; + </chapter> + <chapter id="compat"> &sub-compat; </chapter> @@ -464,6 +523,14 @@ available here: <ulink url="http://linuxtv.org/downloads/video4linux/API/V4L2_AP &sub-capture-c; </appendix> + <appendix id="v4l2grab-example"> + <title>Video Grabber example using libv4l</title> + <para>This program demonstrates how to grab V4L2 images in ppm format by +using libv4l handlers. The advantage is that this grabber can potentially work +with any V4L2 driver.</para> + &sub-v4l2grab-c; + </appendix> + &sub-fdl-appendix; &sub-indices; diff --git a/v4l2-spec/vidioc-enuminput.sgml b/v4l2-spec/vidioc-enuminput.sgml index 1c1486b43..824b47e5f 100644 --- a/v4l2-spec/vidioc-enuminput.sgml +++ b/v4l2-spec/vidioc-enuminput.sgml @@ -119,7 +119,7 @@ linkend="standard">.</entry> <entry><structfield>status</structfield></entry> <entry>This field provides status information about the input. See <xref linkend="input-status"> for flags. -<structfield>status</structfield> is only valid when this is the +With the exception of the sensor orientation bits <structfield>status</structfield> is only valid when this is the current input.</entry> </row> <row> @@ -188,6 +188,23 @@ is OK." --> detect color modulation in the signal.</entry> </row> <row> + <entry spanname="hspan">Sensor Orientation</entry> + </row> + <row> + <entry><constant>V4L2_IN_ST_HFLIP</constant></entry> + <entry>0x00000010</entry> + <entry>The input is connected to a device that produces a signal +that is flipped horizontally and does not correct this before passing the +signal to userspace.</entry> + </row> + <row> + <entry><constant>V4L2_IN_ST_VFLIP</constant></entry> + <entry>0x00000020</entry> + <entry>The input is connected to a device that produces a signal +that is flipped vertically and does not correct this before passing the +signal to userspace. Note that a 180 degree rotation is the same as HFLIP | VFLIP</entry> + </row> + <row> <entry spanname="hspan">Analog Video</entry> </row> <row> diff --git a/v4l2-spec/vidioc-g-ext-ctrls.sgml b/v4l2-spec/vidioc-g-ext-ctrls.sgml index 510520254..352f24cbf 100644 --- a/v4l2-spec/vidioc-g-ext-ctrls.sgml +++ b/v4l2-spec/vidioc-g-ext-ctrls.sgml @@ -68,20 +68,35 @@ initialize the &v4l2-ext-control; array pointed to by the <structfield>controls</structfield> fields.</para> <para>To get the current value of a set of controls applications -initialize the <structfield>id</structfield> field of each -&v4l2-ext-control; and call the -<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl.</para> +initialize the <structfield>id</structfield>, +<structfield>size</structfield> and <structfield>reserved2</structfield> fields +of each &v4l2-ext-control; and call the +<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls +must also set the <structfield>string</structfield> field.</para> + + <para>If the <structfield>size</structfield> is too small to +receive the control result (only relevant for pointer-type controls +like strings), then the driver will set <structfield>size</structfield> +to a valid value and return an &ENOSPC;. You should re-allocate the +string memory to this new size and try again. It is possible that the +same issue occurs again if the string has grown in the meantime. It is +recommended to call &VIDIOC-QUERYCTRL; first and use +<structfield>maximum</structfield>+1 as the new <structfield>size</structfield> +value. It is guaranteed that that is sufficient memory. +</para> <para>To change the value of a set of controls applications -initialize the <structfield>id</structfield> and -<structfield>value</structfield> fields of a &v4l2-ext-control; and +initialize the <structfield>id</structfield>, <structfield>size</structfield>, +<structfield>reserved2</structfield> and +<structfield>value/string</structfield> fields of each &v4l2-ext-control; and call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls will only be set if <emphasis>all</emphasis> control values are valid.</para> - <para>To check if the a set of controls have correct values -applications initialize the <structfield>id</structfield> and -<structfield>value</structfield> fields of a &v4l2-ext-control; and + <para>To check if a set of controls have correct values applications +initialize the <structfield>id</structfield>, <structfield>size</structfield>, +<structfield>reserved2</structfield> and +<structfield>value/string</structfield> fields of each &v4l2-ext-control; and call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to the driver whether wrong values are automatically adjusted to a valid value or if an error is returned.</para> @@ -112,7 +127,23 @@ application.</entry> </row> <row> <entry>__u32</entry> - <entry><structfield>reserved2</structfield>[2]</entry> + <entry><structfield>size</structfield></entry> + <entry></entry> + <entry>The total size in bytes of the payload of this +control. This is normally 0, but for pointer controls this should be +set to the size of the memory containing the payload, or that will +receive the payload. If <constant>VIDIOC_G_EXT_CTRLS</constant> finds +that this value is less than is required to store +the payload result, then it is set to a value large enough to store the +payload result and ENOSPC is returned. Note that for string controls +this <structfield>size</structfield> field should not be confused with the length of the string. +This field refers to the size of the memory that contains the string. +The actual <emphasis>length</emphasis> of the string may well be much smaller. +</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved2</structfield>[1]</entry> <entry></entry> <entry>Reserved for future extensions. Drivers and applications must set the array to zero.</entry> @@ -135,9 +166,9 @@ applications must set the array to zero.</entry> </row> <row> <entry></entry> - <entry>void *</entry> - <entry><structfield>reserved</structfield></entry> - <entry>Reserved for future pointer-type controls. Currently unused.</entry> + <entry>char *</entry> + <entry><structfield>string</structfield></entry> + <entry>A pointer to a string.</entry> </row> </tbody> </tgroup> @@ -202,9 +233,23 @@ class.</entry> <entry><constant>V4L2_CTRL_CLASS_MPEG</constant></entry> <entry>0x990000</entry> <entry>The class containing MPEG compression controls. -These controls are described in section <xref +These controls are described in <xref linkend="mpeg-controls">.</entry> </row> + <row> + <entry><constant>V4L2_CTRL_CLASS_CAMERA</constant></entry> + <entry>0x9a0000</entry> + <entry>The class containing camera controls. +These controls are described in <xref + linkend="camera-controls">.</entry> + </row> + <row> + <entry><constant>V4L2_CTRL_CLASS_FM_TX</constant></entry> + <entry>0x9b0000</entry> + <entry>The class containing FM Transmitter (FM TX) controls. +These controls are described in <xref + linkend="fm-tx-controls">.</entry> + </row> </tbody> </tgroup> </table> @@ -241,6 +286,14 @@ because another applications took over control of the device function this control belongs to.</para> </listitem> </varlistentry> + <varlistentry> + <term><errorcode>ENOSPC</errorcode></term> + <listitem> + <para>The space reserved for the control's payload is insufficient. +The field <structfield>size</structfield> is set to a value that is enough +to store the payload and this error code is returned.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> </refentry> diff --git a/v4l2-spec/vidioc-g-modulator.sgml b/v4l2-spec/vidioc-g-modulator.sgml index e5d4a3f24..945147f90 100644 --- a/v4l2-spec/vidioc-g-modulator.sgml +++ b/v4l2-spec/vidioc-g-modulator.sgml @@ -166,7 +166,7 @@ combine with <constant>V4L2_TUNER_SUB_STEREO</constant> or channel of a stereo audio signal. When the input has only one channel or two channels and <constant>V4L2_TUNER_SUB_SAP</constant> is also set, channel 1 is encoded as left and right channel. This flag does -not combine with <constant>V4L2_TUNER_SUB_MONO </constant> or +not combine with <constant>V4L2_TUNER_SUB_MONO</constant> or <constant>V4L2_TUNER_SUB_LANG1</constant>. When the driver does not support stereo audio it shall fall back to mono.</entry> </row> @@ -177,8 +177,9 @@ support stereo audio it shall fall back to mono.</entry> language of a bilingual audio signal. When the input has only one channel it is used for both languages. It is not possible to encode the primary or secondary language only. This flag does not combine -with <constant>V4L2_TUNER_SUB_MONO </constant> or -<constant>V4L2_TUNER_SUB_STEREO</constant>. If the hardware does not +with <constant>V4L2_TUNER_SUB_MONO</constant>, +<constant>V4L2_TUNER_SUB_STEREO</constant> or +<constant>V4L2_TUNER_SUB_SAP</constant>. If the hardware does not support the respective audio matrix, or the current video standard does not permit bilingual audio the <constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL; @@ -188,7 +189,7 @@ and the driver shall fall back to mono or stereo mode.</entry> <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry> <entry>0x0004</entry> <entry>Same effect as -<constant>V4L2_TUNER_SUB_LANG1</constant>.</entry> +<constant>V4L2_TUNER_SUB_SAP</constant>.</entry> </row> <row> <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry> @@ -198,7 +199,7 @@ and the driver shall fall back to mono or stereo mode.</entry> channel as Second Audio Program. When the input has only one channel it is used for both audio tracks. When the input has three channels the mono track is a down-mix of channel 1 and 2. When combined with -<constant>V4L2_TUNER_SUB_STEREO </constant> channel 1 and 2 are +<constant>V4L2_TUNER_SUB_STEREO</constant> channel 1 and 2 are encoded as left and right stereo audio, channel 3 as Second Audio Program. When the input has only two channels, the first is encoded as left and right channel and the second as SAP. When the input has only @@ -207,10 +208,15 @@ encode a Second Audio Program only. This flag must combine with <constant>V4L2_TUNER_SUB_MONO</constant> or <constant>V4L2_TUNER_SUB_STEREO</constant>. If the hardware does not support the respective audio matrix, or the current video standard -does not permit SAP the <constant> VIDIOC_S_MODULATOR</constant> ioctl +does not permit SAP the <constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL; and driver shall fall back to mono or stereo mode.</entry> </row> + <row> + <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> + <entry>0x0010</entry> + <entry>Enable the RDS encoder for a radio FM transmitter.</entry> + </row> </tbody> </tgroup> </table> diff --git a/v4l2-spec/vidioc-g-tuner.sgml b/v4l2-spec/vidioc-g-tuner.sgml index 6285c18de..eb0b89e9a 100644 --- a/v4l2-spec/vidioc-g-tuner.sgml +++ b/v4l2-spec/vidioc-g-tuner.sgml @@ -120,9 +120,9 @@ field is not quite clear.--></para></entry> to decode audio subprograms. They will <emphasis>not</emphasis> change, for example with the current video standard.</para><para>When the structure refers to a radio tuner only the -<constant>V4L2_TUNER_CAP_LOW</constant> and -<constant>V4L2_TUNER_CAP_STEREO</constant> flags can be -set.</para></entry> +<constant>V4L2_TUNER_CAP_LOW</constant>, +<constant>V4L2_TUNER_CAP_STEREO</constant> and +<constant>V4L2_TUNER_CAP_RDS</constant> flags can be set.</para></entry> </row> <row> <entry>__u32</entry> @@ -312,6 +312,12 @@ carrier for a monaural secondary language. Only supports the <constant>V4L2_STD_NTSC_M</constant> video standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry> </row> + <row> + <entry><constant>V4L2_TUNER_CAP_RDS</constant></entry> + <entry>0x0080</entry> + <entry>RDS capture is supported. This capability is only valid for +radio tuners.</entry> + </row> </tbody> </tgroup> </table> @@ -353,6 +359,11 @@ bilingual audio signal (or a second audio program).</entry> <constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry> </row> + <row> + <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> + <entry>0x0010</entry> + <entry>The tuner receives an RDS channel.</entry> + </row> </tbody> </tgroup> </table> @@ -375,8 +386,8 @@ language.</entry> <entry>1</entry> <entry><para>Play stereo audio. When the tuner receives bilingual audio it may play different languages on the left and right -channel or the primary language on both channels. behave as in mono -mode.</para><para>Playing different languages in this mode is +channel or the primary language is played on both channels.</para><para>Playing +different languages in this mode is deprecated. New drivers should do this only in <constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner receives no stereo signal or does not support stereo reception the diff --git a/v4l2-spec/vidioc-querycap.sgml b/v4l2-spec/vidioc-querycap.sgml index 2715289d8..fa12ae738 100644 --- a/v4l2-spec/vidioc-querycap.sgml +++ b/v4l2-spec/vidioc-querycap.sgml @@ -184,7 +184,7 @@ data.</entry> <row> <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry> <entry>0x00000100</entry> - <entry>[to be defined]</entry> + <entry>The device supports the <link linkend="rds">RDS</link> interface.</entry> </row> <row> <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry> @@ -208,9 +208,9 @@ hardware frequency seeking.</entry> <row> <entry><constant>V4L2_CAP_TUNER</constant></entry> <entry>0x00010000</entry> - <entry>The device has some sort of tuner or modulator to -receive or emit RF-modulated video signals. For more information about -tuner and modulator programming see + <entry>The device has some sort of tuner to +receive RF-modulated video signals. For more information about +tuner programming see <xref linkend="tuner">.</entry> </row> <row> @@ -228,6 +228,14 @@ interface. For more information on audio inputs and outputs see <xref <entry>This is a radio receiver.</entry> </row> <row> + <entry><constant>V4L2_CAP_MODULATOR</constant></entry> + <entry>0x00080000</entry> + <entry>The device has some sort of modulator to +emit RF-modulated video/audio signals. For more information about +modulator programming see +<xref linkend="tuner">.</entry> + </row> + <row> <entry><constant>V4L2_CAP_READWRITE</constant></entry> <entry>0x01000000</entry> <entry>The device supports the <link diff --git a/v4l2-spec/vidioc-queryctrl.sgml b/v4l2-spec/vidioc-queryctrl.sgml index 9908a964d..abf56b22e 100644 --- a/v4l2-spec/vidioc-queryctrl.sgml +++ b/v4l2-spec/vidioc-queryctrl.sgml @@ -93,8 +93,8 @@ next supported control, or <errorcode>EINVAL</errorcode> if there is none. Drivers which do not support this flag yet always return <errorcode>EINVAL</errorcode>.</para> - <para>Additional information is required for menu controls, the -name of menu items. To query them applications set the + <para>Additional information is required for menu controls: the +names of the menu items. To query them applications set the <structfield>id</structfield> and <structfield>index</structfield> fields of &v4l2-querymenu; and call the <constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this @@ -138,9 +138,12 @@ string. This information is intended for the user.</entry> <entry>__s32</entry> <entry><structfield>minimum</structfield></entry> <entry>Minimum value, inclusive. This field gives a lower -bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. It may -not be valid for any other type of control, including -<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note this is a +bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the +lowest valid index (always 0) for <constant>V4L2_CTRL_TYPE_MENU</constant> controls. +For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value +gives the minimum length of the string. This length <emphasis>does not include the terminating +zero</emphasis>. It may not be valid for any other type of control, including +<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a signed value.</entry> </row> <row> @@ -149,16 +152,21 @@ signed value.</entry> <entry>Maximum value, inclusive. This field gives an upper bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> -controls. It may not be valid for any other type of control, including -<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note this is a +controls. +For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value +gives the maximum length of the string. This length <emphasis>does not include the terminating +zero</emphasis>. It may not be valid for any other type of control, including +<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a signed value.</entry> </row> <row> <entry>__s32</entry> <entry><structfield>step</structfield></entry> <entry><para>This field gives a step size for -<constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. It may not be -valid for any other type of control, including +<constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. For +<constant>V4L2_CTRL_TYPE_STRING</constant> controls this field refers to +the string length that has to be a multiple of this step size. +It may not be valid for any other type of control, including <constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls.</para><para>Generally drivers should not scale hardware control values. It may be necessary for example when the @@ -171,7 +179,7 @@ an integer control actually affecting hardware. Often the information is needed when the user can change controls by keyboard or GUI buttons, rather than a slider. When for example a hardware register accepts values 0-511 and the driver reports 0-65535, step should be -128.</para><para>Note although signed, the step value is supposed to +128.</para><para>Note that although signed, the step value is supposed to be always positive.</para></entry> </row> <row> @@ -297,6 +305,20 @@ Drivers must ignore the value passed with and step size cannot be queried.</entry> </row> <row> + <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry> + <entry>≥ 0</entry> + <entry>≥ 1</entry> + <entry>≥ 0</entry> + <entry>The minimum and maximum string lengths. The step size +means that the string must be (minimum + N * step) characters long for +N ≥ 0. These lengths do not include the terminating zero, so in order to +pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the +<structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can +set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1. +Which character encoding is used will depend on the string control itself and +should be part of the control documentation.</entry> + </row> + <row> <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry> <entry>n/a</entry> <entry>n/a</entry> |