diff options
Diffstat (limited to 'Documentation/DocBook')
22 files changed, 1378 insertions, 240 deletions
diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 639e7485796..df2962d9e11 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -174,7 +174,7 @@ FILENAME = \ DOCUMENTED = \ -e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \ -e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \ - -e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\) /<link linkend=\"\1\">\1<\/link> /g" \ + -e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\)\(\s\+v4l2_fourcc\)/<link linkend=\"\1\">\1<\/link>\2/g" \ -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \ -e "s/v4l2\-mpeg\-vbi\-ITV0/v4l2-mpeg-vbi-itv0-1/g" diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml index 24c22cabc66..948ddaab592 100644 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -555,10 +555,46 @@ typedef enum fe_delivery_system { </section> <section id="DTV-ISDBT-LAYER-TIME-INTERLEAVING"> <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title> - <para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para> - <para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values - here are referring to what can be found in the TMCC-structure - - independent of the mode.</para> + <para>Valid values: 0, 1, 2, 4, -1 (AUTO)</para> + <para>when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid.</para> + <para>Note: The real time interleaving length depends on the mode (fft-size). The values + here are referring to what can be found in the TMCC-structure, as shown in the table below.</para> + <informaltable id="isdbt-layer-interleaving-table"> + <tgroup cols="4" align="center"> + <tbody> + <row> + <entry>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</entry> + <entry>Mode 1 (2K FFT)</entry> + <entry>Mode 2 (4K FFT)</entry> + <entry>Mode 3 (8K FFT)</entry> + </row> + <row> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + <entry>0</entry> + </row> + <row> + <entry>1</entry> + <entry>4</entry> + <entry>2</entry> + <entry>1</entry> + </row> + <row> + <entry>2</entry> + <entry>8</entry> + <entry>4</entry> + <entry>2</entry> + </row> + <row> + <entry>4</entry> + <entry>16</entry> + <entry>8</entry> + <entry>4</entry> + </row> + </tbody> + </tgroup> + </informaltable> </section> <section id="DTV-ATSCMH-FIC-VER"> <title><constant>DTV_ATSCMH_FIC_VER</constant></title> diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 47198eef75a..9f5ffd85560 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -13,6 +13,19 @@ correctly with any device.</para> <para>All controls are accessed using an ID value. V4L2 defines several IDs for specific purposes. Drivers can also implement their own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant> +<footnote><para>The use of <constant>V4L2_CID_PRIVATE_BASE</constant> +is problematic because different drivers may use the same +<constant>V4L2_CID_PRIVATE_BASE</constant> ID for different controls. +This makes it hard to programatically set such controls since the meaning +of the control with that ID is driver dependent. In order to resolve this +drivers use unique IDs and the <constant>V4L2_CID_PRIVATE_BASE</constant> +IDs are mapped to those unique IDs by the kernel. Consider these +<constant>V4L2_CID_PRIVATE_BASE</constant> IDs as aliases to the real +IDs.</para> +<para>Many applications today still use the <constant>V4L2_CID_PRIVATE_BASE</constant> +IDs instead of using &VIDIOC-QUERYCTRL; with the <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> +flag to enumerate all IDs, so support for <constant>V4L2_CID_PRIVATE_BASE</constant> +is still around.</para></footnote> and higher values. The pre-defined control IDs have the prefix <constant>V4L2_CID_</constant>, and are listed in <xref linkend="control-id" />. The ID is used when querying the attributes of @@ -31,25 +44,22 @@ the current video input or output, tuner or modulator, or audio input or output. Different in the sense of other bounds, another default and current value, step size or other menu items. A control with a certain <emphasis>custom</emphasis> ID can also change name and -type.<footnote> - <para>It will be more convenient for applications if drivers -make use of the <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag, but -that was never required.</para> - </footnote> Control values are stored globally, they do not +type.</para> + + <para>If a control is not applicable to the current configuration +of the device (for example, it doesn't apply to the current video input) +drivers set the <constant>V4L2_CTRL_FLAG_INACTIVE</constant> flag.</para> + + <para>Control values are stored globally, they do not change when switching except to stay within the reported bounds. They also do not change ⪚ when the device is opened or closed, when the tuner radio frequency is changed or generally never without -application request. Since V4L2 specifies no event mechanism, panel -applications intended to cooperate with other panel applications (be -they built into a larger application, as a TV viewer) may need to -regularly poll control values to update their user -interface.<footnote> - <para>Applications could call an ioctl to request events. -After another process called &VIDIOC-S-CTRL; or another ioctl changing -shared properties the &func-select; function would indicate -readability until any ioctl (querying the properties) is -called.</para> - </footnote></para> +application request.</para> + + <para>V4L2 specifies an event mechanism to notify applications +when controls change value (see &VIDIOC-SUBSCRIBE-EVENT;, event +<constant>V4L2_EVENT_CTRL</constant>), panel applications might want to make +use of that in order to always reflect the correct control value.</para> <para> All controls use machine endianness. @@ -398,14 +408,17 @@ to work.</entry> <row id="v4l2-alpha-component"> <entry><constant>V4L2_CID_ALPHA_COMPONENT</constant></entry> <entry>integer</entry> - <entry> Sets the alpha color component on the capture device or on - the capture buffer queue of a mem-to-mem device. When a mem-to-mem - device produces frame format that includes an alpha component + <entry>Sets the alpha color component. When a capture device (or + capture queue of a mem-to-mem device) produces a frame format that + includes an alpha component (e.g. <link linkend="rgb-formats">packed RGB image formats</link>) - and the alpha value is not defined by the mem-to-mem input data - this control lets you select the alpha component value of all - pixels. It is applicable to any pixel format that contains an alpha - component. + and the alpha value is not defined by the device or the mem-to-mem + input data this control lets you select the alpha component value of + all pixels. When an output device (or output queue of a mem-to-mem + device) consumes a frame format that doesn't include an alpha + component and the device supports alpha channel processing this + control lets you set the alpha component value of all pixels for + further processing in the device. </entry> </row> <row> @@ -434,127 +447,152 @@ Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>, controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or more menu type controls.</para> - <example> - <title>Enumerating all controls</title> + <example id="enum_all_controls"> + <title>Enumerating all user controls</title> <programlisting> &v4l2-queryctrl; queryctrl; &v4l2-querymenu; querymenu; -static void -enumerate_menu (void) +static void enumerate_menu(void) { - printf (" Menu items:\n"); + printf(" Menu items:\n"); - memset (&querymenu, 0, sizeof (querymenu)); + memset(&querymenu, 0, sizeof(querymenu)); querymenu.id = queryctrl.id; for (querymenu.index = queryctrl.minimum; querymenu.index <= queryctrl.maximum; - querymenu.index++) { - if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &querymenu)) { - printf (" %s\n", querymenu.name); + querymenu.index++) { + if (0 == ioctl(fd, &VIDIOC-QUERYMENU;, &querymenu)) { + printf(" %s\n", querymenu.name); } } } -memset (&queryctrl, 0, sizeof (queryctrl)); +memset(&queryctrl, 0, sizeof(queryctrl)); for (queryctrl.id = V4L2_CID_BASE; queryctrl.id < V4L2_CID_LASTP1; queryctrl.id++) { - if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { + if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) continue; - printf ("Control %s\n", queryctrl.name); + printf("Control %s\n", queryctrl.name); if (queryctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu (); + enumerate_menu(); } else { if (errno == EINVAL) continue; - perror ("VIDIOC_QUERYCTRL"); - exit (EXIT_FAILURE); + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); } } for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; queryctrl.id++) { - if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { + if (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) continue; - printf ("Control %s\n", queryctrl.name); + printf("Control %s\n", queryctrl.name); if (queryctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu (); + enumerate_menu(); } else { if (errno == EINVAL) break; - perror ("VIDIOC_QUERYCTRL"); - exit (EXIT_FAILURE); + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); } } </programlisting> </example> <example> + <title>Enumerating all user controls (alternative)</title> + <programlisting> +memset(&queryctrl, 0, sizeof(queryctrl)); + +queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL; +while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { + if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER) + break; + if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) + continue; + + printf("Control %s\n", queryctrl.name); + + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu(); + + queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; +} +if (errno != EINVAL) { + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); +} +</programlisting> + </example> + + <example> <title>Changing controls</title> <programlisting> &v4l2-queryctrl; queryctrl; &v4l2-control; control; -memset (&queryctrl, 0, sizeof (queryctrl)); +memset(&queryctrl, 0, sizeof(queryctrl)); queryctrl.id = V4L2_CID_BRIGHTNESS; -if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { +if (-1 == ioctl(fd, &VIDIOC-QUERYCTRL;, &queryctrl)) { if (errno != EINVAL) { - perror ("VIDIOC_QUERYCTRL"); - exit (EXIT_FAILURE); + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); } else { - printf ("V4L2_CID_BRIGHTNESS is not supported\n"); + printf("V4L2_CID_BRIGHTNESS is not supported\n"); } } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { - printf ("V4L2_CID_BRIGHTNESS is not supported\n"); + printf("V4L2_CID_BRIGHTNESS is not supported\n"); } else { - memset (&control, 0, sizeof (control)); + memset(&control, 0, sizeof (control)); control.id = V4L2_CID_BRIGHTNESS; control.value = queryctrl.default_value; - if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control)) { - perror ("VIDIOC_S_CTRL"); - exit (EXIT_FAILURE); + if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &control)) { + perror("VIDIOC_S_CTRL"); + exit(EXIT_FAILURE); } } -memset (&control, 0, sizeof (control)); +memset(&control, 0, sizeof(control)); control.id = V4L2_CID_CONTRAST; -if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &control)) { +if (0 == ioctl(fd, &VIDIOC-G-CTRL;, &control)) { control.value += 1; /* The driver may clamp the value or return ERANGE, ignored here */ - if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control) + if (-1 == ioctl(fd, &VIDIOC-S-CTRL;, &control) && errno != ERANGE) { - perror ("VIDIOC_S_CTRL"); - exit (EXIT_FAILURE); + perror("VIDIOC_S_CTRL"); + exit(EXIT_FAILURE); } /* Ignore if V4L2_CID_CONTRAST is unsupported */ } else if (errno != EINVAL) { - perror ("VIDIOC_G_CTRL"); - exit (EXIT_FAILURE); + perror("VIDIOC_G_CTRL"); + exit(EXIT_FAILURE); } control.id = V4L2_CID_AUDIO_MUTE; -control.value = TRUE; /* silence */ +control.value = 1; /* silence */ /* Errors ignored */ -ioctl (fd, VIDIOC_S_CTRL, &control); +ioctl(fd, VIDIOC_S_CTRL, &control); </programlisting> </example> </section> @@ -625,16 +663,29 @@ supported.</para> &v4l2-control;, except for the fact that it also allows for 64-bit values and pointers to be passed.</para> + <para>Since the &v4l2-ext-control; supports pointers it is now +also possible to have controls with compound types such as N-dimensional arrays +and/or structures. You need to specify the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> +when enumerating controls to actually be able to see such compound controls. +In other words, these controls with compound types should only be used +programmatically.</para> + + <para>Since such compound controls need to expose more information +about themselves than is possible with &VIDIOC-QUERYCTRL; the +&VIDIOC-QUERY-EXT-CTRL; ioctl was added. In particular, this ioctl gives +the dimensions of the N-dimensional array if this control consists of more than +one element.</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 actually is supported in the driver and what the valid range of values -is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to -check this. Also note that it is possible that some of the menu -indices in a control of type <constant>V4L2_CTRL_TYPE_MENU</constant> -may not be supported (<constant>VIDIOC_QUERYMENU</constant> will -return an error). A good example is the list of supported MPEG audio -bitrates. Some drivers only support one or two bitrates, others -support a wider range.</para> +is. So use the &VIDIOC-QUERYCTRL; (or &VIDIOC-QUERY-EXT-CTRL;) and +&VIDIOC-QUERYMENU; ioctls to check this. Also note that it is possible +that some of the menu indices in a control of type +<constant>V4L2_CTRL_TYPE_MENU</constant> may not be supported +(<constant>VIDIOC_QUERYMENU</constant> will return an error). A good +example is the list of supported MPEG audio bitrates. Some drivers only +support one or two bitrates, others support a wider range.</para> <para> All controls use machine endianness. @@ -675,12 +726,12 @@ control class is found:</para> <informalexample> <programlisting> qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL; -while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &qctrl)) { - if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG) +while (0 == ioctl(fd, &VIDIOC-QUERYCTRL;, &qctrl)) { + if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG) break; /* ... */ - qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; - } + qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; +} </programlisting> </informalexample> @@ -700,7 +751,7 @@ ID based on a control ID.</para> <constant>VIDIOC_QUERYCTRL</constant> will fail when used in combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In that case the old method of enumerating control should be used (see -1.8). But if it is supported, then it is guaranteed to enumerate over +<xref linkend="enum_all_controls" />). But if it is supported, then it is guaranteed to enumerate over all controls, including driver-private controls.</para> </section> @@ -4000,6 +4051,68 @@ to find receivers which can scroll strings sized as 32 x N or 64 x N characters. 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_RDS_TX_MONO_STEREO</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Sets the Mono/Stereo bit of the Decoder Identification code. If set, +then the audio was recorded as stereo.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_ARTIFICIAL_HEAD</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Sets the +<ulink url="http://en.wikipedia.org/wiki/Artificial_head">Artificial Head</ulink> bit of the Decoder +Identification code. If set, then the audio was recorded using an artificial head.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_COMPRESSED</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Sets the Compressed bit of the Decoder Identification code. If set, +then the audio is compressed.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_DYNAMIC_PTY</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Sets the Dynamic PTY bit of the Decoder Identification code. If set, +then the PTY code is dynamically switched.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">If set, then a traffic announcement is in progress.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_TRAFFIC_PROGRAM</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">If set, then the tuned programme carries traffic announcements.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_MUSIC_SPEECH</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">If set, then this channel broadcasts music. If cleared, then it +broadcasts speech. If the transmitter doesn't make this distinction, then it should be set.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_ALT_FREQS_ENABLE</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">If set, then transmit alternate frequencies.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_TX_ALT_FREQS</constant> </entry> + <entry>__u32 array</entry> + </row> + <row><entry spanname="descr">The alternate frequencies in kHz units. The RDS standard allows +for up to 25 frequencies to be defined. Drivers may support fewer frequencies so check +the array size.</entry> + </row> + <row> <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant> </entry> <entry>boolean</entry> </row> @@ -4976,6 +5089,57 @@ description of this control class.</entry> </row><row><entry spanname="descr">Enables/disables RDS reception by the radio tuner</entry> </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_RX_PTY</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Gets RDS Programme Type field. +This encodes up to 31 pre-defined programme types.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_RX_PS_NAME</constant> </entry> + <entry>string</entry> + </row> + <row><entry spanname="descr">Gets the Programme Service name (PS_NAME). +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="iec62106" />, 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_RX_RADIO_TEXT</constant> </entry> + <entry>string</entry> + </row> + <row><entry spanname="descr">Gets the Radio Text info. 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 can be used in addition to +<constant>V4L2_CID_RDS_RX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described +in Annex E of <xref linkend="iec62106" />. 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_RDS_RX_TRAFFIC_ANNOUNCEMENT</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">If set, then a traffic announcement is in progress.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_RX_TRAFFIC_PROGRAM</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">If set, then the tuned programme carries traffic announcements.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_RX_MUSIC_SPEECH</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">If set, then this channel broadcasts music. If cleared, then it +broadcasts speech. If the transmitter doesn't make this distinction, then it will be set.</entry> + </row> <row> <entry spanname="id"><constant>V4L2_CID_TUNE_DEEMPHASIS</constant> </entry> <entry>enum v4l2_deemphasis</entry> @@ -5007,6 +5171,102 @@ defines possible values for de-emphasis. Here they are:</entry> </tbody> </tgroup> </table> + </section> + + <section id="detect-controls"> + <title>Detect Control Reference</title> + + <para>The Detect class includes controls for common features of + various motion or object detection capable devices.</para> + + <table pgwide="1" frame="none" id="detect-control-id"> + <title>Detect 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_DETECT_CLASS</constant> </entry> + <entry>class</entry> + </row><row><entry spanname="descr">The Detect 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_DETECT_MD_MODE</constant> </entry> + <entry>menu</entry> + </row><row><entry spanname="descr">Sets the motion detection mode.</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_DETECT_MD_MODE_DISABLED</constant> + </entry><entry>Disable motion detection.</entry> + </row> + <row> + <entry><constant>V4L2_DETECT_MD_MODE_GLOBAL</constant> + </entry><entry>Use a single motion detection threshold.</entry> + </row> + <row> + <entry><constant>V4L2_DETECT_MD_MODE_THRESHOLD_GRID</constant> + </entry><entry>The image is divided into a grid, each cell with its own + motion detection threshold. These thresholds are set through the + <constant>V4L2_CID_DETECT_MD_THRESHOLD_GRID</constant> matrix control.</entry> + </row> + <row> + <entry><constant>V4L2_DETECT_MD_MODE_REGION_GRID</constant> + </entry><entry>The image is divided into a grid, each cell with its own + region value that specifies which per-region motion detection thresholds + should be used. Each region has its own thresholds. How these per-region + thresholds are set up is driver-specific. The region values for the grid are set + through the <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> matrix + control.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Sets the global motion detection threshold to be + used with the <constant>V4L2_DETECT_MD_MODE_GLOBAL</constant> motion detection mode.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_DETECT_MD_THRESHOLD_GRID</constant> </entry> + <entry>__u16 matrix</entry> + </row> + <row><entry spanname="descr">Sets the motion detection thresholds for each cell in the grid. + To be used with the <constant>V4L2_DETECT_MD_MODE_THRESHOLD_GRID</constant> + motion detection mode. Matrix element (0, 0) represents the cell at the top-left of the + grid.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> </entry> + <entry>__u8 matrix</entry> + </row> + <row><entry spanname="descr">Sets the motion detection region value for each cell in the grid. + To be used with the <constant>V4L2_DETECT_MD_MODE_REGION_GRID</constant> + motion detection mode. Matrix element (0, 0) represents the cell at the top-left of the + grid.</entry> + </row> + </tbody> + </tgroup> + </table> </section> diff --git a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml index b788c72c885..f4b61b6ce3c 100644 --- a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml +++ b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml @@ -150,9 +150,15 @@ signal. Drivers shall not convert the sample format by software.</para></entry> <entry>This is the scanning system line number associated with the first line of the VBI image, of the first and the second field respectively. See <xref linkend="vbi-525" /> and -<xref linkend="vbi-625" /> for valid values. VBI input drivers can -return start values 0 if the hardware cannot reliable identify -scanning lines, VBI acquisition may not require this +<xref linkend="vbi-625" /> for valid values. +The <constant>V4L2_VBI_ITU_525_F1_START</constant>, +<constant>V4L2_VBI_ITU_525_F2_START</constant>, +<constant>V4L2_VBI_ITU_625_F1_START</constant> and +<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start line +numbers for each field for each 525 or 625 line format as a convenience. +Don't forget that ITU line numbering starts at 1, not 0. +VBI input drivers can return start values 0 if the hardware cannot +reliable identify scanning lines, VBI acquisition may not require this information.</entry> </row> <row> diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml b/Documentation/DocBook/media/v4l/dev-sdr.xml index dc14804f543..f8903568a24 100644 --- a/Documentation/DocBook/media/v4l/dev-sdr.xml +++ b/Documentation/DocBook/media/v4l/dev-sdr.xml @@ -72,9 +72,12 @@ To use the <link linkend="format">format</link> ioctls applications set the <constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> and use the &v4l2-sdr-format; <structfield>sdr</structfield> member of the <structfield>fmt</structfield> union as needed per the desired operation. -Currently only the <structfield>pixelformat</structfield> field of -&v4l2-sdr-format; is used. The content of that field is the V4L2 fourcc code -of the data format. +Currently there is two fields, <structfield>pixelformat</structfield> and +<structfield>buffersize</structfield>, of struct &v4l2-sdr-format; which are +used. Content of the <structfield>pixelformat</structfield> is V4L2 FourCC +code of the data format. The <structfield>buffersize</structfield> field is +maximum buffer size in bytes required for data transfer, set by the driver in +order to inform application. </para> <table pgwide="1" frame="none" id="v4l2-sdr-format"> @@ -92,8 +95,15 @@ V4L2 defines SDR formats in <xref linkend="sdr-formats" />. </entry> </row> <row> + <entry>__u32</entry> + <entry><structfield>buffersize</structfield></entry> + <entry> +Maximum size in bytes required for data. Value is set by the driver. + </entry> + </row> + <row> <entry>__u8</entry> - <entry><structfield>reserved[28]</structfield></entry> + <entry><structfield>reserved[24]</structfield></entry> <entry>This array is reserved for future extensions. Drivers and applications must set it to zero.</entry> </row> diff --git a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml index 548f8ea28de..7a8bf3011ee 100644 --- a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml +++ b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml @@ -185,7 +185,14 @@ tables, sigh. --></para></entry> <entry></entry> <entry spanname="hspan">Drivers must set <structfield>service_lines</structfield>[0][0] and -<structfield>service_lines</structfield>[1][0] to zero.</entry> +<structfield>service_lines</structfield>[1][0] to zero. +The <constant>V4L2_VBI_ITU_525_F1_START</constant>, +<constant>V4L2_VBI_ITU_525_F2_START</constant>, +<constant>V4L2_VBI_ITU_625_F1_START</constant> and +<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start +line numbers for each field for each 525 or 625 line format as a +convenience. Don't forget that ITU line numbering starts at 1, not 0. +</entry> </row> <row> <entry>__u32</entry> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index a086a5db7a1..e5e8325aa3d 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -870,7 +870,8 @@ should set this to 0.</entry> If the application sets this to 0 for an output stream, then <structfield>bytesused</structfield> will be set to the size of the plane (see the <structfield>length</structfield> field of this struct) - by the driver.</entry> + by the driver. Note that the actual image data starts at + <structfield>data_offset</structfield> which may not be 0.</entry> </row> <row> <entry>__u32</entry> @@ -919,6 +920,10 @@ should set this to 0.</entry> <entry>Offset in bytes to video data in the plane. Drivers must set this field when <structfield>type</structfield> refers to an input stream, applications when it refers to an output stream. + Note that data_offset is included in <structfield>bytesused</structfield>. + So the size of the image in the plane is + <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at + offset <structfield>data_offset</structfield> from the start of the plane. </entry> </row> <row> @@ -1066,7 +1071,7 @@ state, in the application domain so to say.</entry> <entry>Drivers set or clear this flag when calling the <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video capture devices when the buffer contains a compressed image which is a -key frame (or field), &ie; can be decompressed on its own. Also know as +key frame (or field), &ie; can be decompressed on its own. Also known as an I-frame. Applications can set this bit when <structfield>type</structfield> refers to an output stream.</entry> </row> diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml index e1c4f8b4c0b..2aae8e9452a 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml @@ -15,9 +15,6 @@ typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel. These are all packed-pixel formats, meaning all the data for a pixel lie next to each other in memory.</para> - <para>When one of these formats is used, drivers shall report the -colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> - <table pgwide="1" frame="none" id="rgb-formats"> <title>Packed RGB Image Formats</title> <tgroup cols="37" align="center"> @@ -130,9 +127,9 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-PIX-FMT-RGB444"> - <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry> - <entry>'R444'</entry> + <row id="V4L2-PIX-FMT-ARGB444"> + <entry><constant>V4L2_PIX_FMT_ARGB444</constant></entry> + <entry>'AR12'</entry> <entry></entry> <entry>g<subscript>3</subscript></entry> <entry>g<subscript>2</subscript></entry> @@ -152,9 +149,31 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-PIX-FMT-RGB555"> - <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry> - <entry>'RGBO'</entry> + <row id="V4L2-PIX-FMT-XRGB444"> + <entry><constant>V4L2_PIX_FMT_XRGB444</constant></entry> + <entry>'XR12'</entry> + <entry></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + </row> + <row id="V4L2-PIX-FMT-ARGB555"> + <entry><constant>V4L2_PIX_FMT_ARGB555</constant></entry> + <entry>'AR15'</entry> <entry></entry> <entry>g<subscript>2</subscript></entry> <entry>g<subscript>1</subscript></entry> @@ -174,6 +193,28 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> + <row id="V4L2-PIX-FMT-XRGB555"> + <entry><constant>V4L2_PIX_FMT_XRGB555</constant></entry> + <entry>'XR15'</entry> + <entry></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry></entry> + <entry>-</entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + </row> <row id="V4L2-PIX-FMT-RGB565"> <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry> <entry>'RGBP'</entry> @@ -341,9 +382,9 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-PIX-FMT-BGR32"> - <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> - <entry>'BGR4'</entry> + <row id="V4L2-PIX-FMT-ABGR32"> + <entry><constant>V4L2_PIX_FMT_ABGR32</constant></entry> + <entry>'AR24'</entry> <entry></entry> <entry>b<subscript>7</subscript></entry> <entry>b<subscript>6</subscript></entry> @@ -381,9 +422,49 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>a<subscript>1</subscript></entry> <entry>a<subscript>0</subscript></entry> </row> - <row id="V4L2-PIX-FMT-RGB32"> - <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> - <entry>'RGB4'</entry> + <row id="V4L2-PIX-FMT-XBGR32"> + <entry><constant>V4L2_PIX_FMT_XBGR32</constant></entry> + <entry>'XR24'</entry> + <entry></entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></entry> + <entry>b<subscript>5</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry></entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry></entry> + <entry>r<subscript>7</subscript></entry> + <entry>r<subscript>6</subscript></entry> + <entry>r<subscript>5</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + </row> + <row id="V4L2-PIX-FMT-ARGB32"> + <entry><constant>V4L2_PIX_FMT_ARGB32</constant></entry> + <entry>'AX24'</entry> <entry></entry> <entry>a<subscript>7</subscript></entry> <entry>a<subscript>6</subscript></entry> @@ -421,18 +502,76 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> + <row id="V4L2-PIX-FMT-XRGB32"> + <entry><constant>V4L2_PIX_FMT_XRGB32</constant></entry> + <entry>'BX24'</entry> + <entry></entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry>-</entry> + <entry></entry> + <entry>r<subscript>7</subscript></entry> + <entry>r<subscript>6</subscript></entry> + <entry>r<subscript>5</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry></entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry></entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></entry> + <entry>b<subscript>5</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + </row> </tbody> </tgroup> </table> - <para>Bit 7 is the most significant bit. The value of the a = alpha -bits is undefined when reading from the driver, ignored when writing -to the driver, except when alpha blending has been negotiated for a -<link linkend="overlay">Video Overlay</link> or <link linkend="osd"> -Video Output Overlay</link> or when the alpha component has been configured -for a <link linkend="capture">Video Capture</link> by means of <link -linkend="v4l2-alpha-component"> <constant>V4L2_CID_ALPHA_COMPONENT -</constant> </link> control.</para> + <para>Bit 7 is the most significant bit.</para> + + <para>The usage and value of the alpha bits (a) in the ARGB and ABGR formats + (collectively referred to as alpha formats) depend on the device type and + hardware operation. <link linkend="capture">Capture</link> devices + (including capture queues of mem-to-mem devices) fill the alpha component in + memory. When the device outputs an alpha channel the alpha component will + have a meaningful value. Otherwise, when the device doesn't output an alpha + channel but can set the alpha bit to a user-configurable value, the <link + linkend="v4l2-alpha-component"><constant>V4L2_CID_ALPHA_COMPONENT</constant> + </link> control is used to specify that alpha value, and the alpha component + of all pixels will be set to the value specified by that control. Otherwise + a corresponding format without an alpha component (XRGB or XBGR) must be + used instead of an alpha format.</para> + + <para><link linkend="output">Output</link> devices (including output queues + of mem-to-mem devices and <link linkend="osd">video output overlay</link> + devices) read the alpha component from memory. When the device processes the + alpha channel the alpha component must be filled with meaningful values by + applications. Otherwise a corresponding format without an alpha component + (XRGB or XBGR) must be used instead of an alpha format.</para> + + <para>The XRGB and XBGR formats contain undefined bits (-). Applications, + devices and drivers must ignore those bits, for both <link + linkend="capture">capture</link> and <link linkend="output">output</link> + devices.</para> <example> <title><constant>V4L2_PIX_FMT_BGR24</constant> 4 × 4 pixel @@ -512,6 +651,239 @@ image</title> </formalpara> </example> + <para>Formats defined in <xref linkend="rgb-formats-deprecated"/> are + deprecated and must not be used by new drivers. They are documented here for + reference. The meaning of their alpha bits (a) is ill-defined and + interpreted as in either the corresponding ARGB or XRGB format, depending on + the driver.</para> + + <table pgwide="1" frame="none" id="rgb-formats-deprecated"> + <title>Deprecated Packed RGB Image Formats</title> + <tgroup cols="37" align="center"> + <colspec colname="id" align="left" /> + <colspec colname="fourcc" /> + <colspec colname="bit" /> + + <colspec colnum="4" colname="b07" align="center" /> + <colspec colnum="5" colname="b06" align="center" /> + <colspec colnum="6" colname="b05" align="center" /> + <colspec colnum="7" colname="b04" align="center" /> + <colspec colnum="8" colname="b03" align="center" /> + <colspec colnum="9" colname="b02" align="center" /> + <colspec colnum="10" colname="b01" align="center" /> + <colspec colnum="11" colname="b00" align="center" /> + + <colspec colnum="13" colname="b17" align="center" /> + <colspec colnum="14" colname="b16" align="center" /> + <colspec colnum="15" colname="b15" align="center" /> + <colspec colnum="16" colname="b14" align="center" /> + <colspec colnum="17" colname="b13" align="center" /> + <colspec colnum="18" colname="b12" align="center" /> + <colspec colnum="19" colname="b11" align="center" /> + <colspec colnum="20" colname="b10" align="center" /> + + <colspec colnum="22" colname="b27" align="center" /> + <colspec colnum="23" colname="b26" align="center" /> + <colspec colnum="24" colname="b25" align="center" /> + <colspec colnum="25" colname="b24" align="center" /> + <colspec colnum="26" colname="b23" align="center" /> + <colspec colnum="27" colname="b22" align="center" /> + <colspec colnum="28" colname="b21" align="center" /> + <colspec colnum="29" colname="b20" align="center" /> + + <colspec colnum="31" colname="b37" align="center" /> + <colspec colnum="32" colname="b36" align="center" /> + <colspec colnum="33" colname="b35" align="center" /> + <colspec colnum="34" colname="b34" align="center" /> + <colspec colnum="35" colname="b33" align="center" /> + <colspec colnum="36" colname="b32" align="center" /> + <colspec colnum="37" colname="b31" align="center" /> + <colspec colnum="38" colname="b30" align="center" /> + + <spanspec namest="b07" nameend="b00" spanname="b0" /> + <spanspec namest="b17" nameend="b10" spanname="b1" /> + <spanspec namest="b27" nameend="b20" spanname="b2" /> + <spanspec namest="b37" nameend="b30" spanname="b3" /> + <thead> + <row> + <entry>Identifier</entry> + <entry>Code</entry> + <entry> </entry> + <entry spanname="b0">Byte 0 in memory</entry> + <entry spanname="b1">Byte 1</entry> + <entry spanname="b2">Byte 2</entry> + <entry spanname="b3">Byte 3</entry> + </row> + <row> + <entry> </entry> + <entry> </entry> + <entry>Bit</entry> + <entry>7</entry> + <entry>6</entry> + <entry>5</entry> + <entry>4</entry> + <entry>3</entry> + <entry>2</entry> + <entry>1</entry> + <entry>0</entry> + <entry> </entry> + <entry>7</entry> + <entry>6</entry> + <entry>5</entry> + <entry>4</entry> + <entry>3</entry> + <entry>2</entry> + <entry>1</entry> + <entry>0</entry> + <entry> </entry> + <entry>7</entry> + <entry>6</entry> + <entry>5</entry> + <entry>4</entry> + <entry>3</entry> + <entry>2</entry> + <entry>1</entry> + <entry>0</entry> + <entry> </entry> + <entry>7</entry> + <entry>6</entry> + <entry>5</entry> + <entry>4</entry> + <entry>3</entry> + <entry>2</entry> + <entry>1</entry> + <entry>0</entry> + </row> + </thead> + <tbody> + <row id="V4L2-PIX-FMT-RGB444"> + <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry> + <entry>'R444'</entry> + <entry></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry></entry> + <entry>a<subscript>3</subscript></entry> + <entry>a<subscript>2</subscript></entry> + <entry>a<subscript>1</subscript></entry> + <entry>a<subscript>0</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + </row> + <row id="V4L2-PIX-FMT-RGB555"> + <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry> + <entry>'RGBO'</entry> + <entry></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry></entry> + <entry>a</entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + </row> + <row id="V4L2-PIX-FMT-BGR32"> + <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry> + <entry>'BGR4'</entry> + <entry></entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></entry> + <entry>b<subscript>5</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry></entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry></entry> + <entry>r<subscript>7</subscript></entry> + <entry>r<subscript>6</subscript></entry> + <entry>r<subscript>5</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry></entry> + <entry>a<subscript>7</subscript></entry> + <entry>a<subscript>6</subscript></entry> + <entry>a<subscript>5</subscript></entry> + <entry>a<subscript>4</subscript></entry> + <entry>a<subscript>3</subscript></entry> + <entry>a<subscript>2</subscript></entry> + <entry>a<subscript>1</subscript></entry> + <entry>a<subscript>0</subscript></entry> + </row> + <row id="V4L2-PIX-FMT-RGB32"> + <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry> + <entry>'RGB4'</entry> + <entry></entry> + <entry>a<subscript>7</subscript></entry> + <entry>a<subscript>6</subscript></entry> + <entry>a<subscript>5</subscript></entry> + <entry>a<subscript>4</subscript></entry> + <entry>a<subscript>3</subscript></entry> + <entry>a<subscript>2</subscript></entry> + <entry>a<subscript>1</subscript></entry> + <entry>a<subscript>0</subscript></entry> + <entry></entry> + <entry>r<subscript>7</subscript></entry> + <entry>r<subscript>6</subscript></entry> + <entry>r<subscript>5</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry></entry> + <entry>g<subscript>7</subscript></entry> + <entry>g<subscript>6</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry></entry> + <entry>b<subscript>7</subscript></entry> + <entry>b<subscript>6</subscript></entry> + <entry>b<subscript>5</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + </row> + </tbody> + </tgroup> + </table> + <para>A test utility to determine which RGB formats a driver actually supports is available from the LinuxTV v4l-dvb repository. See &v4l-dvb; for access instructions.</para> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml new file mode 100644 index 00000000000..6118d8f7a20 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs08.xml @@ -0,0 +1,44 @@ +<refentry id="V4L2-SDR-FMT-CS08"> + <refmeta> + <refentrytitle>V4L2_SDR_FMT_CS8 ('CS08')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname> + <constant>V4L2_SDR_FMT_CS8</constant> + </refname> + <refpurpose>Complex signed 8-bit IQ sample</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <para> +This format contains sequence of complex number samples. Each complex number +consist two parts, called In-phase and Quadrature (IQ). Both I and Q are +represented as a 8 bit signed number. I value comes first and Q value after +that. + </para> + <example> + <title><constant>V4L2_SDR_FMT_CS8</constant> 1 sample</title> + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="2" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>I'<subscript>0</subscript></entry> + </row> + <row> + <entry>start + 1:</entry> + <entry>Q'<subscript>0</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml new file mode 100644 index 00000000000..e4b494ce136 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-sdr-cs14le.xml @@ -0,0 +1,47 @@ +<refentry id="V4L2-SDR-FMT-CS14LE"> + <refmeta> + <refentrytitle>V4L2_SDR_FMT_CS14LE ('CS14')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname> + <constant>V4L2_SDR_FMT_CS14LE</constant> + </refname> + <refpurpose>Complex signed 14-bit little endian IQ sample</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <para> +This format contains sequence of complex number samples. Each complex number +consist two parts, called In-phase and Quadrature (IQ). Both I and Q are +represented as a 14 bit signed little endian number. I value comes first +and Q value after that. 14 bit value is stored in 16 bit space with unused +high bits padded with 0. + </para> + <example> + <title><constant>V4L2_SDR_FMT_CS14LE</constant> 1 sample</title> + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="3" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>I'<subscript>0[7:0]</subscript></entry> + <entry>I'<subscript>0[13:8]</subscript></entry> + </row> + <row> + <entry>start + 2:</entry> + <entry>Q'<subscript>0[7:0]</subscript></entry> + <entry>Q'<subscript>0[13:8]</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml b/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml new file mode 100644 index 00000000000..3df076b99f9 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-sdr-ru12le.xml @@ -0,0 +1,40 @@ +<refentry id="V4L2-SDR-FMT-RU12LE"> + <refmeta> + <refentrytitle>V4L2_SDR_FMT_RU12LE ('RU12')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname> + <constant>V4L2_SDR_FMT_RU12LE</constant> + </refname> + <refpurpose>Real unsigned 12-bit little endian sample</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <para> +This format contains sequence of real number samples. Each sample is +represented as a 12 bit unsigned little endian number. Sample is stored +in 16 bit space with unused high bits padded with 0. + </para> + <example> + <title><constant>V4L2_SDR_FMT_RU12LE</constant> 1 sample</title> + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="3" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start + 0:</entry> + <entry>I'<subscript>0[7:0]</subscript></entry> + <entry>I'<subscript>0[11:8]</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml index 9ba4fb690bc..96947f17fca 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml @@ -18,7 +18,7 @@ <title>Description</title> <para>The following four pixel formats are raw sRGB / Bayer formats with -12 bits per colour. Each colour component is stored in a 16-bit word, with 6 +12 bits per colour. Each colour component is stored in a 16-bit word, with 4 unused high bits filled with zeros. Each n-pixel row contains n/2 green samples and n/2 blue or red samples, with alternating red and blue rows. Bytes are stored in memory in little endian order. They are conventionally described diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index 91dcbc84f3f..df5b23d4655 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -112,9 +112,34 @@ see <xref linkend="colorspaces" />.</entry> <row> <entry>__u32</entry> <entry><structfield>priv</structfield></entry> - <entry>Reserved for custom (driver defined) additional -information about formats. When not used drivers and applications must -set this field to zero.</entry> + <entry><para>This field indicates whether the remaining fields of the +<structname>v4l2_pix_format</structname> structure, also called the extended +fields, are valid. When set to <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, it +indicates that the extended fields have been correctly initialized. When set to +any other value it indicates that the extended fields contain undefined values. +</para> +<para>Applications that wish to use the pixel format extended fields must first +ensure that the feature is supported by querying the device for the +<link linkend="querycap"><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></link> +capability. If the capability isn't set the pixel format extended fields are not +supported and using the extended fields will lead to undefined results.</para> +<para>To use the extended fields, applications must set the +<structfield>priv</structfield> field to +<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, initialize all the extended fields +and zero the unused bytes of the <structname>v4l2_format</structname> +<structfield>raw_data</structfield> field.</para> +<para>When the <structfield>priv</structfield> field isn't set to +<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> drivers must act as if all the +extended fields were set to zero. On return drivers must set the +<structfield>priv</structfield> field to +<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> and all the extended fields to +applicable values.</para></entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>Flags set by the application or driver, see <xref +linkend="format-flags" />.</entry> </row> </tbody> </tgroup> @@ -201,9 +226,15 @@ codes can be used.</entry> and the number of valid entries in the <structfield>plane_fmt</structfield> array.</entry> </row> + <row> + <entry>__u8</entry> + <entry><structfield>flags</structfield></entry> + <entry>Flags set by the application or driver, see <xref +linkend="format-flags" />.</entry> + </row> <row> <entry>__u8</entry> - <entry><structfield>reserved[11]</structfield></entry> + <entry><structfield>reserved[10]</structfield></entry> <entry>Reserved for future extensions. Should be zeroed by the application.</entry> </row> @@ -248,7 +279,7 @@ has just as many pad bytes after it as the other rows.</para> <para>In V4L2 each format has an identifier which looks like <constant>PIX_FMT_XXX</constant>, defined in the <link -linkend="videodev">videodev.h</link> header file. These identifiers +linkend="videodev">videodev2.h</link> header file. These identifiers represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link> which are also listed below, however they are not the same as those used in the Windows world.</para> @@ -828,6 +859,9 @@ interface only.</para> &sub-sdr-cu08; &sub-sdr-cu16le; + &sub-sdr-cs08; + &sub-sdr-cs14le; + &sub-sdr-ru12le; </section> @@ -1060,4 +1094,21 @@ concatenated to form the JPEG stream. </para> </tbody> </tgroup> </table> + + <table frame="none" pgwide="1" id="format-flags"> + <title>Format Flags</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>V4L2_PIX_FMT_FLAG_PREMUL_ALPHA</constant></entry> + <entry>0x00000001</entry> + <entry>The color values are premultiplied by the alpha channel +value. For example, if a light blue pixel with 50% transparency was described by +RGBA values (128, 192, 255, 128), the same pixel described with premultiplied +colors would be described by RGBA values (64, 96, 128, 128) </entry> + </row> + </tbody> + </tgroup> + </table> </section> diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index 4c238ce068b..28cbded766c 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -86,47 +86,47 @@ selection targets available for a video capture device. It is recommended to configure the cropping targets before to the composing targets.</para> <para>The range of coordinates of the top left corner, width and height of -areas that can be sampled is given by the <constant> V4L2_SEL_TGT_CROP_BOUNDS -</constant> target. It is recommended for the driver developers to put the -top/left corner at position <constant> (0,0) </constant>. The rectangle's +areas that can be sampled is given by the <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant> +target. It is recommended for the driver developers to put the +top/left corner at position <constant>(0,0)</constant>. The rectangle's coordinates are expressed in pixels.</para> <para>The top left corner, width and height of the source rectangle, that is -the area actually sampled, is given by the <constant> V4L2_SEL_TGT_CROP -</constant> target. It uses the same coordinate system as <constant> -V4L2_SEL_TGT_CROP_BOUNDS </constant>. The active cropping area must lie -completely inside the capture boundaries. The driver may further adjust the -requested size and/or position according to hardware limitations.</para> +the area actually sampled, is given by the <constant>V4L2_SEL_TGT_CROP</constant> +target. It uses the same coordinate system as <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>. +The active cropping area must lie completely inside the capture boundaries. The +driver may further adjust the requested size and/or position according to hardware +limitations.</para> <para>Each capture device has a default source rectangle, given by the -<constant> V4L2_SEL_TGT_CROP_DEFAULT </constant> target. This rectangle shall +<constant>V4L2_SEL_TGT_CROP_DEFAULT</constant> target. This rectangle shall over what the driver writer considers the complete picture. Drivers shall set the active crop rectangle to the default when the driver is first loaded, but not later.</para> <para>The composing targets refer to a memory buffer. The limits of composing -coordinates are obtained using <constant> V4L2_SEL_TGT_COMPOSE_BOUNDS -</constant>. All coordinates are expressed in pixels. The rectangle's top/left -corner must be located at position <constant> (0,0) </constant>. The width and -height are equal to the image size set by <constant> VIDIOC_S_FMT </constant>. +coordinates are obtained using <constant>V4L2_SEL_TGT_COMPOSE_BOUNDS</constant>. +All coordinates are expressed in pixels. The rectangle's top/left +corner must be located at position <constant>(0,0)</constant>. The width and +height are equal to the image size set by <constant>VIDIOC_S_FMT</constant>. </para> <para>The part of a buffer into which the image is inserted by the hardware is -controlled by the <constant> V4L2_SEL_TGT_COMPOSE </constant> target. +controlled by the <constant>V4L2_SEL_TGT_COMPOSE</constant> target. The rectangle's coordinates are also expressed in the same coordinate system as the bounds rectangle. The composing rectangle must lie completely inside bounds rectangle. The driver must adjust the composing rectangle to fit to the bounding limits. Moreover, the driver can perform other adjustments according to hardware limitations. The application can control rounding behaviour using -<link linkend="v4l2-selection-flags"> constraint flags </link>.</para> +<link linkend="v4l2-selection-flags"> constraint flags</link>.</para> <para>For capture devices the default composing rectangle is queried using -<constant> V4L2_SEL_TGT_COMPOSE_DEFAULT </constant>. It is usually equal to the +<constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant>. It is usually equal to the bounding rectangle.</para> <para>The part of a buffer that is modified by the hardware is given by -<constant> V4L2_SEL_TGT_COMPOSE_PADDED </constant>. It contains all pixels -defined using <constant> V4L2_SEL_TGT_COMPOSE </constant> plus all +<constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant>. It contains all pixels +defined using <constant>V4L2_SEL_TGT_COMPOSE</constant> plus all padding data modified by hardware during insertion process. All pixels outside this rectangle <emphasis>must not</emphasis> be changed by the hardware. The content of pixels that lie inside the padded area but outside active area is @@ -140,52 +140,51 @@ where the rubbish pixels are located and remove them if needed.</para> <title>Configuration of video output</title> <para>For output devices targets and ioctls are used similarly to the video -capture case. The <emphasis> composing </emphasis> rectangle refers to the +capture case. The <emphasis>composing</emphasis> rectangle refers to the insertion of an image into a video signal. The cropping rectangles refer to a memory buffer. It is recommended to configure the composing targets before to the cropping targets.</para> <para>The cropping targets refer to the memory buffer that contains an image to be inserted into a video signal or graphical screen. The limits of cropping -coordinates are obtained using <constant> V4L2_SEL_TGT_CROP_BOUNDS </constant>. +coordinates are obtained using <constant>V4L2_SEL_TGT_CROP_BOUNDS</constant>. All coordinates are expressed in pixels. The top/left corner is always point -<constant> (0,0) </constant>. The width and height is equal to the image size -specified using <constant> VIDIOC_S_FMT </constant> ioctl.</para> +<constant>(0,0)</constant>. The width and height is equal to the image size +specified using <constant>VIDIOC_S_FMT</constant> ioctl.</para> <para>The top left corner, width and height of the source rectangle, that is the area from which image date are processed by the hardware, is given by the -<constant> V4L2_SEL_TGT_CROP </constant>. Its coordinates are expressed +<constant>V4L2_SEL_TGT_CROP</constant>. Its coordinates are expressed in in the same coordinate system as the bounds rectangle. The active cropping area must lie completely inside the crop boundaries and the driver may further adjust the requested size and/or position according to hardware limitations.</para> <para>For output devices the default cropping rectangle is queried using -<constant> V4L2_SEL_TGT_CROP_DEFAULT </constant>. It is usually equal to the +<constant>V4L2_SEL_TGT_CROP_DEFAULT</constant>. It is usually equal to the bounding rectangle.</para> <para>The part of a video signal or graphics display where the image is -inserted by the hardware is controlled by <constant> -V4L2_SEL_TGT_COMPOSE </constant> target. The rectangle's coordinates -are expressed in pixels. The composing rectangle must lie completely inside the -bounds rectangle. The driver must adjust the area to fit to the bounding -limits. Moreover, the driver can perform other adjustments according to -hardware limitations. </para> - -<para>The device has a default composing rectangle, given by the <constant> -V4L2_SEL_TGT_COMPOSE_DEFAULT </constant> target. This rectangle shall cover what +inserted by the hardware is controlled by <constant>V4L2_SEL_TGT_COMPOSE</constant> +target. The rectangle's coordinates are expressed in pixels. The composing +rectangle must lie completely inside the bounds rectangle. The driver must +adjust the area to fit to the bounding limits. Moreover, the driver can +perform other adjustments according to hardware limitations.</para> + +<para>The device has a default composing rectangle, given by the +<constant>V4L2_SEL_TGT_COMPOSE_DEFAULT</constant> target. This rectangle shall cover what the driver writer considers the complete picture. It is recommended for the -driver developers to put the top/left corner at position <constant> (0,0) -</constant>. Drivers shall set the active composing rectangle to the default +driver developers to put the top/left corner at position <constant>(0,0)</constant>. +Drivers shall set the active composing rectangle to the default one when the driver is first loaded.</para> <para>The devices may introduce additional content to video signal other than an image from memory buffers. It includes borders around an image. However, such a padded area is driver-dependent feature not covered by this document. Driver developers are encouraged to keep padded rectangle equal to active one. -The padded target is accessed by the <constant> V4L2_SEL_TGT_COMPOSE_PADDED -</constant> identifier. It must contain all pixels from the <constant> -V4L2_SEL_TGT_COMPOSE </constant> target.</para> +The padded target is accessed by the <constant>V4L2_SEL_TGT_COMPOSE_PADDED</constant> +identifier. It must contain all pixels from the <constant>V4L2_SEL_TGT_COMPOSE</constant> +target.</para> </section> @@ -194,8 +193,8 @@ V4L2_SEL_TGT_COMPOSE </constant> target.</para> <title>Scaling control</title> <para>An application can detect if scaling is performed by comparing the width -and the height of rectangles obtained using <constant> V4L2_SEL_TGT_CROP -</constant> and <constant> V4L2_SEL_TGT_COMPOSE </constant> targets. If +and the height of rectangles obtained using <constant>V4L2_SEL_TGT_CROP</constant> +and <constant>V4L2_SEL_TGT_COMPOSE</constant> targets. If these are not equal then the scaling is applied. The application can compute the scaling ratios using these values.</para> @@ -208,7 +207,7 @@ the scaling ratios using these values.</para> <title>Comparison with old cropping API</title> <para>The selection API was introduced to cope with deficiencies of previous -<link linkend="crop"> API </link>, that was designed to control simple capture +<link linkend="crop"> API</link>, that was designed to control simple capture devices. Later the cropping API was adopted by video output drivers. The ioctls are used to select a part of the display were the video signal is inserted. It should be considered as an API abuse because the described operation is @@ -220,7 +219,7 @@ part of an image by abusing V4L2 API. Cropping a smaller image from a larger one is achieved by setting the field &v4l2-pix-format;<structfield>::bytesperline</structfield>. Introducing an image offsets could be done by modifying field &v4l2-buffer;<structfield>::m_userptr</structfield> -before calling <constant> VIDIOC_QBUF </constant>. Those +before calling <constant>VIDIOC_QBUF</constant>. Those operations should be avoided because they are not portable (endianness), and do not work for macroblock and Bayer formats and mmap buffers. The selection API deals with configuration of buffer cropping/composing in a clear, intuitive and @@ -229,7 +228,7 @@ and constraints flags are introduced. Finally, &v4l2-crop; and &v4l2-cropcap; have no reserved fields. Therefore there is no way to extend their functionality. The new &v4l2-selection; provides a lot of place for future extensions. Driver developers are encouraged to implement only selection API. -The former cropping API would be simulated using the new one. </para> +The former cropping API would be simulated using the new one.</para> </section> @@ -238,9 +237,9 @@ The former cropping API would be simulated using the new one. </para> <example> <title>Resetting the cropping parameters</title> - <para>(A video capture device is assumed; change <constant> -V4L2_BUF_TYPE_VIDEO_CAPTURE </constant> for other devices; change target to -<constant> V4L2_SEL_TGT_COMPOSE_* </constant> family to configure composing + <para>(A video capture device is assumed; change +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other devices; change target to +<constant>V4L2_SEL_TGT_COMPOSE_*</constant> family to configure composing area)</para> <programlisting> @@ -292,8 +291,8 @@ area)</para> <example> <title>Querying for scaling factors</title> - <para>A video output device is assumed; change <constant> -V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> for other devices</para> + <para>A video output device is assumed; change +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> for other devices</para> <programlisting> &v4l2-selection; compose = { diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index b445161b912..f2f81f06a17 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -152,6 +152,14 @@ structs, ioctls) must be noted in more detail in the history chapter applications. --> <revision> + <revnumber>3.16</revnumber> + <date>2014-05-27</date> + <authorinitials>lp</authorinitials> + <revremark>Extended &v4l2-pix-format;. Added format flags. + </revremark> + </revision> + + <revision> <revnumber>3.15</revnumber> <date>2014-02-03</date> <authorinitials>hv, ap</authorinitials> diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml index 820f86e8744..cb7732582f0 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml @@ -94,6 +94,18 @@ </row> <row> <entry></entry> + <entry>&v4l2-event-motion-det;</entry> + <entry><structfield>motion_det</structfield></entry> + <entry>Event data for event V4L2_EVENT_MOTION_DET.</entry> + </row> + <row> + <entry></entry> + <entry>&v4l2-event-src-change;</entry> + <entry><structfield>src_change</structfield></entry> + <entry>Event data for event V4L2_EVENT_SOURCE_CHANGE.</entry> + </row> + <row> + <entry></entry> <entry>__u8</entry> <entry><structfield>data</structfield>[64]</entry> <entry>Event data. Defined by the event type. The union @@ -258,6 +270,44 @@ </tgroup> </table> + <table frame="none" pgwide="1" id="v4l2-event-motion-det"> + <title>struct <structname>v4l2_event_motion_det</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry> + Currently only one flag is available: if <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant> + is set, then the <structfield>frame_sequence</structfield> field is valid, + otherwise that field should be ignored. + </entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>frame_sequence</structfield></entry> + <entry> + The sequence number of the frame being received. Only valid if the + <constant>V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ</constant> flag was set. + </entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>region_mask</structfield></entry> + <entry> + The bitmask of the regions that reported motion. There is at least one + region. If this field is 0, then no motion was detected at all. + If there is no <constant>V4L2_CID_DETECT_MD_REGION_GRID</constant> control + (see <xref linkend="detect-controls" />) to assign a different region + to each cell in the motion detection grid, then that all cells + are automatically assigned to the default region 0. + </entry> + </row> + </tbody> + </tgroup> + </table> + <table pgwide="1" frame="none" id="changes-flags"> <title>Changes</title> <tgroup cols="3"> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml index e9f6735c082..c5bdbfcc42b 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml @@ -72,23 +72,30 @@ 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> +must also set the <structfield>string</structfield> field. Controls +of compound types (<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set) +must set the <structfield>ptr</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 +memory to this new size and try again. For the string type 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>N-dimensional arrays are set and retrieved row-by-row. You cannot set a partial +array, all elements have to be set or retrieved. The total size is calculated +as <structfield>elems</structfield> * <structfield>elem_size</structfield>. +These values can be obtained by calling &VIDIOC-QUERY-EXT-CTRL;.</para> + <para>To change the value of a set of controls applications initialize the <structfield>id</structfield>, <structfield>size</structfield>, <structfield>reserved2</structfield> and -<structfield>value/string</structfield> fields of each &v4l2-ext-control; and +<structfield>value/value64/string/ptr</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> @@ -96,7 +103,7 @@ valid.</para> <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 +<structfield>value/value64/string/ptr</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> @@ -158,19 +165,47 @@ applications must set the array to zero.</entry> <entry></entry> <entry>__s32</entry> <entry><structfield>value</structfield></entry> - <entry>New value or current value.</entry> + <entry>New value or current value. Valid if this control is not of +type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and +<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry> </row> <row> <entry></entry> <entry>__s64</entry> <entry><structfield>value64</structfield></entry> - <entry>New value or current value.</entry> + <entry>New value or current value. Valid if this control is of +type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and +<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry> </row> <row> <entry></entry> <entry>char *</entry> <entry><structfield>string</structfield></entry> - <entry>A pointer to a string.</entry> + <entry>A pointer to a string. Valid if this control is of +type <constant>V4L2_CTRL_TYPE_STRING</constant>.</entry> + </row> + <row> + <entry></entry> + <entry>__u8 *</entry> + <entry><structfield>p_u8</structfield></entry> + <entry>A pointer to a matrix control of unsigned 8-bit values. +Valid if this control is of type <constant>V4L2_CTRL_TYPE_U8</constant>.</entry> + </row> + <row> + <entry></entry> + <entry>__u16 *</entry> + <entry><structfield>p_u16</structfield></entry> + <entry>A pointer to a matrix control of unsigned 16-bit values. +Valid if this control is of type <constant>V4L2_CTRL_TYPE_U16</constant>.</entry> + </row> + <row> + <entry></entry> + <entry>void *</entry> + <entry><structfield>ptr</structfield></entry> + <entry>A pointer to a compound type which can be an N-dimensional array and/or a +compound type (the control's type is >= <constant>V4L2_CTRL_COMPOUND_TYPES</constant>). +Valid if <constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set for this control. +</entry> </row> </tbody> </tgroup> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml index 7c63815e7af..20460730b02 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml @@ -152,13 +152,10 @@ a valid base address, so applications can find the corresponding Linux framebuffer device (see <xref linkend="osd" />).</entry> </row> <row> - <entry>&v4l2-pix-format;</entry> + <entry>struct</entry> <entry><structfield>fmt</structfield></entry> <entry></entry> - <entry>Layout of the frame buffer. The -<structname>v4l2_pix_format</structname> structure is defined in <xref -linkend="pixfmt" />, for clarification the fields and acceptable values - are listed below:</entry> + <entry>Layout of the frame buffer.</entry> </row> <row> <entry></entry> @@ -276,9 +273,8 @@ see <xref linkend="colorspaces" />.</entry> <entry></entry> <entry>__u32</entry> <entry><structfield>priv</structfield></entry> - <entry>Reserved for additional information about custom -(driver defined) formats. When not used drivers and applications must -set this field to zero.</entry> + <entry>Reserved. Drivers and applications must set this field to +zero.</entry> </row> </tbody> </tgroup> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index b11ec75e21a..9c04ac8661b 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -58,17 +58,16 @@ <para>The ioctls are used to query and configure selection rectangles.</para> -<para> To query the cropping (composing) rectangle set &v4l2-selection; +<para>To query the cropping (composing) rectangle set &v4l2-selection; <structfield> type </structfield> field to the respective buffer type. -Do not use multiplanar buffers. Use <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE -</constant> instead of <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE -</constant>. Use <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> instead of -<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE </constant>. The next step is +Do not use multiplanar buffers. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> +instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. Use +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is setting the value of &v4l2-selection; <structfield>target</structfield> field -to <constant> V4L2_SEL_TGT_CROP </constant> (<constant> -V4L2_SEL_TGT_COMPOSE </constant>). Please refer to table <xref -linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> for additional -targets. The <structfield>flags</structfield> and <structfield>reserved +to <constant>V4L2_SEL_TGT_CROP</constant> (<constant>V4L2_SEL_TGT_COMPOSE</constant>). +Please refer to table <xref linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> +for additional targets. The <structfield>flags</structfield> and <structfield>reserved </structfield> fields of &v4l2-selection; are ignored and they must be filled with zeros. The driver fills the rest of the structure or returns &EINVAL; if incorrect buffer type or target was used. If cropping @@ -77,19 +76,18 @@ always equal to the bounds rectangle. Finally, the &v4l2-rect; <structfield>r</structfield> rectangle is filled with the current cropping (composing) coordinates. The coordinates are expressed in driver-dependent units. The only exception are rectangles for images in raw formats, whose -coordinates are always expressed in pixels. </para> +coordinates are always expressed in pixels.</para> -<para> To change the cropping (composing) rectangle set the &v4l2-selection; +<para>To change the cropping (composing) rectangle set the &v4l2-selection; <structfield>type</structfield> field to the respective buffer type. Do not -use multiplanar buffers. Use <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE -</constant> instead of <constant> V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE -</constant>. Use <constant> V4L2_BUF_TYPE_VIDEO_OUTPUT </constant> instead of -<constant> V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE </constant>. The next step is +use multiplanar buffers. Use <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> +instead of <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. Use +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> instead of +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>. The next step is setting the value of &v4l2-selection; <structfield>target</structfield> to -<constant>V4L2_SEL_TGT_CROP</constant> (<constant> -V4L2_SEL_TGT_COMPOSE </constant>). Please refer to table <xref -linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> for additional -targets. The &v4l2-rect; <structfield>r</structfield> rectangle need to be +<constant>V4L2_SEL_TGT_CROP</constant> (<constant>V4L2_SEL_TGT_COMPOSE</constant>). +Please refer to table <xref linkend="v4l2-selections-common" /> or <xref linkend="selection-api" /> +for additional targets. The &v4l2-rect; <structfield>r</structfield> rectangle need to be set to the desired active area. Field &v4l2-selection; <structfield> reserved </structfield> is ignored and must be filled with zeros. The driver may adjust coordinates of the requested rectangle. An application may @@ -149,8 +147,8 @@ On success the &v4l2-rect; <structfield>r</structfield> field contains the adjusted rectangle. When the parameters are unsuitable the application may modify the cropping (composing) or image parameters and repeat the cycle until satisfactory parameters have been negotiated. If constraints flags have to be -violated at then ERANGE is returned. The error indicates that <emphasis> there -exist no rectangle </emphasis> that satisfies the constraints.</para> +violated at then ERANGE is returned. The error indicates that <emphasis>there +exist no rectangle</emphasis> that satisfies the constraints.</para> <para>Selection targets and flags are documented in <xref linkend="v4l2-selections-common"/>.</para> diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml index 370d49d6fb6..d0c5e604f01 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querycap.xml @@ -302,6 +302,12 @@ modulator programming see <link linkend="sdr">SDR Capture</link> interface.</entry> </row> <row> + <entry><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></entry> + <entry>0x00200000</entry> + <entry>The device supports the &v4l2-pix-format; extended +fields.</entry> + </row> + <row> <entry><constant>V4L2_CAP_READWRITE</constant></entry> <entry>0x01000000</entry> <entry>The device supports the <link diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml index e6645b99655..2bd98fd7a4e 100644 --- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml @@ -1,11 +1,12 @@ <refentry id="vidioc-queryctrl"> <refmeta> - <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</refentrytitle> + <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</refentrytitle> &manvol; </refmeta> <refnamediv> <refname>VIDIOC_QUERYCTRL</refname> + <refname>VIDIOC_QUERY_EXT_CTRL</refname> <refname>VIDIOC_QUERYMENU</refname> <refpurpose>Enumerate controls and menu control items</refpurpose> </refnamediv> @@ -24,6 +25,14 @@ <funcdef>int <function>ioctl</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct v4l2_query_ext_ctrl *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> <paramdef>struct v4l2_querymenu *<parameter>argp</parameter></paramdef> </funcprototype> </funcsynopsis> @@ -42,7 +51,7 @@ <varlistentry> <term><parameter>request</parameter></term> <listitem> - <para>VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</para> + <para>VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU</para> </listitem> </varlistentry> <varlistentry> @@ -67,7 +76,7 @@ structure. The driver fills the rest of the structure or returns an <constant>VIDIOC_QUERYCTRL</constant> with successive <structfield>id</structfield> values starting from <constant>V4L2_CID_BASE</constant> up to and exclusive -<constant>V4L2_CID_BASE_LASTP1</constant>. Drivers may return +<constant>V4L2_CID_LASTP1</constant>. Drivers may return <errorcode>EINVAL</errorcode> if a control in this range is not supported. Further applications can enumerate private controls, which are not defined in this specification, by starting at @@ -89,9 +98,23 @@ prematurely end the enumeration).</para></footnote></para> <para>When the application ORs <structfield>id</structfield> with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the -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> +next supported non-compound control, or <errorcode>EINVAL</errorcode> +if there is none. In addition, the <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> +flag can be specified to enumerate all compound controls (i.e. controls +with type ≥ <constant>V4L2_CTRL_COMPOUND_TYPES</constant>). Specify both +<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> and +<constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> in order to enumerate +all controls, compound or not. Drivers which do not support these flags yet +always return <errorcode>EINVAL</errorcode>.</para> + + <para>The <constant>VIDIOC_QUERY_EXT_CTRL</constant> ioctl was +introduced in order to better support controls that can use compound +types, and to expose additional control information that cannot be +returned in &v4l2-queryctrl; since that structure is full.</para> + + <para><constant>VIDIOC_QUERY_EXT_CTRL</constant> is used in the +same way as <constant>VIDIOC_QUERYCTRL</constant>, except that the +<structfield>reserved</structfield> array must be zeroed as well.</para> <para>Additional information is required for menu controls: the names of the menu items. To query them applications set the @@ -142,38 +165,23 @@ 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 and the -lowest valid index 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> +bound for the control. See &v4l2-ctrl-type; how the minimum value is to +be used for each possible control type. Note that this a signed 32-bit value.</entry> </row> <row> <entry>__s32</entry> <entry><structfield>maximum</structfield></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. For <constant>V4L2_CTRL_TYPE_BITMASK</constant> controls it is the -set of usable bits. -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> +bound for the control. See &v4l2-ctrl-type; how the maximum value is to +be used for each possible control type. Note that this a signed 32-bit 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. 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 + <entry><para>This field gives a step size for the control. +See &v4l2-ctrl-type; how the step value is to be used for each possible +control type. Note that this an unsigned 32-bit value. +</para><para>Generally drivers should not scale hardware control values. It may be necessary for example when the <structfield>name</structfield> or <structfield>id</structfield> imply a particular unit and the hardware actually accepts only multiples of @@ -192,10 +200,11 @@ be always positive.</para></entry> <entry><structfield>default_value</structfield></entry> <entry>The default value of a <constant>V4L2_CTRL_TYPE_INTEGER</constant>, -<constant>_BOOLEAN</constant> or <constant>_MENU</constant> control. -Not valid for other types of controls. Drivers reset controls only -when the driver is loaded, not later, in particular not when the -func-open; is called.</entry> +<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>, +<constant>_MENU</constant> or <constant>_INTEGER_MENU</constant> control. +Not valid for other types of controls. +Note that drivers reset controls to their default value only when the +driver is first loaded, never afterwards.</entry> </row> <row> <entry>__u32</entry> @@ -213,6 +222,126 @@ the array to zero.</entry> </tgroup> </table> + <table pgwide="1" frame="none" id="v4l2-query-ext-ctrl"> + <title>struct <structname>v4l2_query_ext_ctrl</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>id</structfield></entry> + <entry>Identifies the control, set by the application. See +<xref linkend="control-id" /> for predefined IDs. When the ID is ORed +with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver clears the +flag and returns the first non-compound control with a higher ID. When the +ID is ORed with <constant>V4L2_CTRL_FLAG_NEXT_COMPOUND</constant> the driver +clears the flag and returns the first compound control with a higher ID. +Set both to get the first control (compound or not) with a higher ID.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>type</structfield></entry> + <entry>Type of control, see <xref + linkend="v4l2-ctrl-type" />.</entry> + </row> + <row> + <entry>char</entry> + <entry><structfield>name</structfield>[32]</entry> + <entry>Name of the control, a NUL-terminated ASCII +string. This information is intended for the user.</entry> + </row> + <row> + <entry>__s64</entry> + <entry><structfield>minimum</structfield></entry> + <entry>Minimum value, inclusive. This field gives a lower +bound for the control. See &v4l2-ctrl-type; how the minimum value is to +be used for each possible control type. Note that this a signed 64-bit value.</entry> + </row> + <row> + <entry>__s64</entry> + <entry><structfield>maximum</structfield></entry> + <entry>Maximum value, inclusive. This field gives an upper +bound for the control. See &v4l2-ctrl-type; how the maximum value is to +be used for each possible control type. Note that this a signed 64-bit value.</entry> + </row> + <row> + <entry>__u64</entry> + <entry><structfield>step</structfield></entry> + <entry><para>This field gives a step size for the control. +See &v4l2-ctrl-type; how the step value is to be used for each possible +control type. Note that this an unsigned 64-bit value. +</para><para>Generally drivers should not scale hardware +control values. It may be necessary for example when the +<structfield>name</structfield> or <structfield>id</structfield> imply +a particular unit and the hardware actually accepts only multiples of +said unit. If so, drivers must take care values are properly rounded +when scaling, such that errors will not accumulate on repeated +read-write cycles.</para><para>This field gives the smallest change of +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></entry> + </row> + <row> + <entry>__s64</entry> + <entry><structfield>default_value</structfield></entry> + <entry>The default value of a +<constant>V4L2_CTRL_TYPE_INTEGER</constant>, <constant>_INTEGER64</constant>, +<constant>_BOOLEAN</constant>, <constant>_BITMASK</constant>, +<constant>_MENU</constant>, <constant>_INTEGER_MENU</constant>, +<constant>_U8</constant> or <constant>_U16</constant> control. +Not valid for other types of controls. +Note that drivers reset controls to their default value only when the +driver is first loaded, never afterwards. +</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>Control flags, see <xref + linkend="control-flags" />.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>elem_size</structfield></entry> + <entry>The size in bytes of a single element of the array. +Given a char pointer <constant>p</constant> to a 3-dimensional array you can find the +position of cell <constant>(z, y, x)</constant> as follows: +<constant>p + ((z * dims[1] + y) * dims[0] + x) * elem_size</constant>. <structfield>elem_size</structfield> +is always valid, also when the control isn't an array. For string controls +<structfield>elem_size</structfield> is equal to <structfield>maximum + 1</structfield>. +</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>elems</structfield></entry> + <entry>The number of elements in the N-dimensional array. If this control +is not an array, then <structfield>elems</structfield> is 1. The <structfield>elems</structfield> +field can never be 0.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>nr_of_dims</structfield></entry> + <entry>The number of dimension in the N-dimensional array. If this control +is not an array, then this field is 0.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>dims[V4L2_CTRL_MAX_DIMS]</structfield></entry> + <entry>The size of each dimension. The first <structfield>nr_of_dims</structfield> +elements of this array must be non-zero, all remaining elements must be zero.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[32]</entry> + <entry>Reserved for future extensions. Applications and drivers +must set the array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + <table pgwide="1" frame="none" id="v4l2-querymenu"> <title>struct <structname>v4l2_querymenu</structname></title> <tgroup cols="4"> @@ -347,11 +476,14 @@ Drivers must ignore the value passed with </row> <row> <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry> - <entry>n/a</entry> - <entry>n/a</entry> - <entry>n/a</entry> + <entry>any</entry> + <entry>any</entry> + <entry>any</entry> <entry>A 64-bit integer valued control. Minimum, maximum -and step size cannot be queried.</entry> +and step size cannot be queried using <constant>VIDIOC_QUERYCTRL</constant>. +Only <constant>VIDIOC_QUERY_EXT_CTRL</constant> can retrieve the 64-bit +min/max/step values, they should be interpreted as n/a when using +<constant>VIDIOC_QUERYCTRL</constant>.</entry> </row> <row> <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry> @@ -379,6 +511,26 @@ ioctl returns the name of the control class and this control type. Older drivers which do not support this feature return an &EINVAL;.</entry> </row> + <row> + <entry><constant>V4L2_CTRL_TYPE_U8</constant></entry> + <entry>any</entry> + <entry>any</entry> + <entry>any</entry> + <entry>An unsigned 8-bit valued control ranging from minimum to +maximum inclusive. The step value indicates the increment between +values which are actually different on the hardware. +</entry> + </row> + <row> + <entry><constant>V4L2_CTRL_TYPE_U16</constant></entry> + <entry>any</entry> + <entry>any</entry> + <entry>any</entry> + <entry>An unsigned 16-bit valued control ranging from minimum to +maximum inclusive. The step value indicates the increment between +values which are actually different on the hardware. +</entry> + </row> </tbody> </tgroup> </table> @@ -450,6 +602,14 @@ is in auto-gain mode. In such a case the hardware calculates the gain value base the lighting conditions which can change over time. Note that setting a new value for a volatile control will have no effect. The new value will just be ignored.</entry> </row> + <row> + <entry><constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant></entry> + <entry>0x0100</entry> + <entry>This control has a pointer type, so its value has to be accessed +using one of the pointer fields of &v4l2-ext-control;. This flag is set for controls +that are an array, string, or have a compound type. In all cases you have to set a +pointer to memory containing the payload of the control.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml index 17efa870d4d..9f609560883 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml @@ -175,6 +175,14 @@ </entry> </row> <row> + <entry><constant>V4L2_EVENT_MOTION_DET</constant></entry> + <entry>5</entry> + <entry> + <para>Triggered whenever the motion detection state for one or more of the regions + changes. This event has a &v4l2-event-motion-det; associated with it.</para> + </entry> + </row> + <row> <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry> <entry>0x08000000</entry> <entry>Base event number for driver-private events.</entry> |