diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l')
| -rw-r--r-- | Documentation/DocBook/media/v4l/capture.c.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/compat.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/io.xml | 10 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/v4l2.xml | 10 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-create-bufs.xml | 30 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-enumstd.xml | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml | 28 |
9 files changed, 59 insertions, 29 deletions
diff --git a/Documentation/DocBook/media/v4l/capture.c.xml b/Documentation/DocBook/media/v4l/capture.c.xml index 1c5c49a2de59..22126a991b34 100644 --- a/Documentation/DocBook/media/v4l/capture.c.xml +++ b/Documentation/DocBook/media/v4l/capture.c.xml @@ -5,7 +5,7 @@ * This program can be used and distributed without restrictions. * * This program is provided with the V4L2 API - * see http://linuxtv.org/docs.php for more information + * see https://linuxtv.org/docs.php for more information */ #include <stdio.h> diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 5701a08ed792..5399e8904715 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2666,7 +2666,7 @@ is useful to display images captured with V4L2 devices.</para> <para>V4L2 does not support digital terrestrial, cable or satellite broadcast. A separate project aiming at digital receivers exists. You can find its homepage at <ulink -url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API +url="https://linuxtv.org">https://linuxtv.org</ulink>. The Linux DVB API has no connection to the V4L2 API except that drivers for hybrid hardware may support both.</para> </section> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index da654031ef3f..144158b3a5ac 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -699,7 +699,7 @@ linkend="v4l2-buf-type" /></entry> buffer. It depends on the negotiated data format and may change with each buffer for compressed variable size data like JPEG images. Drivers must set this field when <structfield>type</structfield> -refers to an input stream, applications when it refers to an output stream. +refers to a capture stream, applications when it refers to an output stream. If the application sets this to 0 for an output stream, then <structfield>bytesused</structfield> will be set to the size of the buffer (see the <structfield>length</structfield> field of this struct) by @@ -720,14 +720,14 @@ linkend="buffer-flags" />.</entry> <entry>Indicates the field order of the image in the buffer, see <xref linkend="v4l2-field" />. This field is not used when the buffer contains VBI data. Drivers must set it when -<structfield>type</structfield> refers to an input stream, +<structfield>type</structfield> refers to a capture stream, applications when it refers to an output stream.</entry> </row> <row> <entry>struct timeval</entry> <entry><structfield>timestamp</structfield></entry> <entry></entry> - <entry><para>For input streams this is time when the first data + <entry><para>For capture streams this is time when the first data byte was captured, as returned by the <function>clock_gettime()</function> function for the relevant clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in @@ -866,7 +866,7 @@ must set this to 0.</entry> <entry></entry> <entry>The number of bytes occupied by data in the plane (its payload). Drivers must set this field when <structfield>type</structfield> - refers to an input stream, applications when it refers to an output stream. + refers to a capture stream, applications when it refers to an output stream. 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) @@ -919,7 +919,7 @@ must set this to 0.</entry> <entry></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. + refers to a capture 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 diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 7e61643358de..42e626d6c936 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -152,6 +152,16 @@ structs, ioctls) must be noted in more detail in the history chapter (compat.xml), along with the possible impact on existing drivers and applications. --> <revision> + <revnumber>4.5</revnumber> + <date>2015-10-29</date> + <authorinitials>rr</authorinitials> + <revremark>Extend vidioc-g-ext-ctrls;. Replace ctrl_class with a new +union with ctrl_class and which. Which is used to select the current value of +the control or the default value. + </revremark> + </revision> + + <revision> <revnumber>4.4</revnumber> <date>2015-05-26</date> <authorinitials>ap</authorinitials> diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index 8ffe74f84af1..d81fa0d4016b 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -58,7 +58,7 @@ <para>This ioctl is used to create buffers for <link linkend="mmap">memory mapped</link> or <link linkend="userp">user pointer</link> or <link linkend="dmabuf">DMA buffer</link> I/O. It can be used as an alternative or in -addition to the <constant>VIDIOC_REQBUFS</constant> ioctl, when a tighter +addition to the &VIDIOC-REQBUFS; ioctl, when a tighter control over buffers is required. This ioctl can be called multiple times to create buffers of different sizes.</para> @@ -71,30 +71,28 @@ zeroed.</para> <para>The <structfield>format</structfield> field specifies the image format that the buffers must be able to handle. The application has to fill in this -&v4l2-format;. Usually this will be done using the -<constant>VIDIOC_TRY_FMT</constant> or <constant>VIDIOC_G_FMT</constant> ioctl() -to ensure that the requested format is supported by the driver. Unsupported -formats will result in an error.</para> +&v4l2-format;. Usually this will be done using the &VIDIOC-TRY-FMT; or &VIDIOC-G-FMT; ioctls +to ensure that the requested format is supported by the driver. +Based on the format's <structfield>type</structfield> field the requested buffer +size (for single-planar) or plane sizes (for multi-planar formats) will be +used for the allocated buffers. The driver may return an error if the size(s) +are not supported by the hardware (usually because they are too small).</para> <para>The buffers created by this ioctl will have as minimum size the size -defined by the <structfield>format.pix.sizeimage</structfield> field. If the +defined by the <structfield>format.pix.sizeimage</structfield> field (or the +corresponding fields for other format types). Usually if the <structfield>format.pix.sizeimage</structfield> field is less than the minimum -required for the given format, then <structfield>sizeimage</structfield> will be -increased by the driver to that minimum to allocate the buffers. If it is -larger, then the value will be used as-is. The same applies to the -<structfield>sizeimage</structfield> field of the -<structname>v4l2_plane_pix_format</structname> structure in the case of -multiplanar formats.</para> +required for the given format, then an error will be returned since drivers will +typically not allow this. If it is larger, then the value will be used as-is. +In other words, the driver may reject the requested size, but if it is accepted +the driver will use it unchanged.</para> <para>When the ioctl is called with a pointer to this structure the driver will attempt to allocate up to the requested number of buffers and store the actual number allocated and the starting index in the <structfield>count</structfield> and the <structfield>index</structfield> fields respectively. On return <structfield>count</structfield> can be smaller than -the number requested. The driver may also increase buffer sizes if required, -however, it will not update <structfield>sizeimage</structfield> field values. -The user has to use <constant>VIDIOC_QUERYBUF</constant> to retrieve that -information.</para> +the number requested.</para> <table pgwide="1" frame="none" id="v4l2-create-buffers"> <title>struct <structname>v4l2_create_buffers</structname></title> diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml index 4c4603c135fe..f14a3bb1afaa 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-info.xml @@ -99,7 +99,7 @@ if the driver supports writing registers to the device.</para> <para>We recommended the <application>v4l2-dbg</application> utility over calling this ioctl directly. It is available from the LinuxTV v4l-dvb repository; see <ulink -url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for +url="https://linuxtv.org/repo/">https://linuxtv.org/repo/</ulink> for access instructions.</para> <!-- Note for convenience vidioc-dbg-g-register.sgml diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml index 3d038e75d12b..5877f68a5820 100644 --- a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml +++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml @@ -117,7 +117,7 @@ However when a driver supports these ioctls it must also support <para>We recommended the <application>v4l2-dbg</application> utility over calling these ioctls directly. It is available from the LinuxTV v4l-dvb repository; see <ulink -url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for +url="https://linuxtv.org/repo/">https://linuxtv.org/repo/</ulink> for access instructions.</para> <!-- Note for convenience vidioc-dbg-g-chip-info.sgml diff --git a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml index 8065099401d1..f18454e91752 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml @@ -198,7 +198,7 @@ video4linux-list@redhat.com on 17 Oct 2002 <constant>V4L2_STD_ATSC_16_VSB</constant> are U.S. terrestrial digital TV standards. Presently the V4L2 API does not support digital TV. See also the Linux DVB API at <ulink -url="http://linuxtv.org">http://linuxtv.org</ulink>.</para> +url="https://linuxtv.org">https://linuxtv.org</ulink>.</para> <para><programlisting> #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\ V4L2_STD_PAL_B1 |\ diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml index 842536aae8b4..eb82f7e7d06b 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml @@ -61,7 +61,7 @@ must belong to the same control class.</para> <para>Applications must always fill in the <structfield>count</structfield>, -<structfield>ctrl_class</structfield>, +<structfield>which</structfield>, <structfield>controls</structfield> and <structfield>reserved</structfield> fields of &v4l2-ext-controls;, and initialize the &v4l2-ext-control; array pointed to by the @@ -109,7 +109,7 @@ the driver whether wrong values are automatically adjusted to a valid value or if an error is returned.</para> <para>When the <structfield>id</structfield> or -<structfield>ctrl_class</structfield> is invalid drivers return an +<structfield>which</structfield> is invalid drivers return an &EINVAL;. When the value is out of bounds drivers can choose to take the closest valid value or return an &ERANGE;, whatever seems more appropriate. In the first case the new value is set in @@ -223,7 +223,12 @@ Valid if <constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set for this control <tgroup cols="3"> &cs-str; <tbody valign="top"> + <row> + <entry>union</entry> + <entry>(anonymous)</entry> + </row> <row> + <entry></entry> <entry>__u32</entry> <entry><structfield>ctrl_class</structfield></entry> <entry>The control class to which all controls belong, see @@ -235,6 +240,23 @@ with a <structfield>count</structfield> of 0. If that succeeds, then the driver supports this feature.</entry> </row> <row> + <entry></entry> + <entry>__u32</entry> + <entry><structfield>which</structfield></entry> + <entry><para>Which value of the control to get/set/try. <constant>V4L2_CTRL_WHICH_CUR_VAL</constant> +will return the current value of the control and <constant>V4L2_CTRL_WHICH_DEF_VAL</constant> will +return the default value of the control. Please note that you can only get the default value of the +control, you cannot set or try it.</para> +<para>For backwards compatibility you can also use a control class here (see +<xref linkend="ctrl-class" />). In that case all controls have to belong to that +control class. This usage is deprecated, instead just use <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>. +There are some very old drivers that do not yet support <constant>V4L2_CTRL_WHICH_CUR_VAL</constant> +and that require a control class here. You can test for such drivers by setting ctrl_class to +<constant>V4L2_CTRL_WHICH_CUR_VAL</constant> and calling VIDIOC_TRY_EXT_CTRLS with a count of 0. +If that fails, then the driver does not support <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>.</para> +</entry> + </row> + <row> <entry>__u32</entry> <entry><structfield>count</structfield></entry> <entry>The number of controls in the controls array. May @@ -390,7 +412,7 @@ These controls are described in <xref linkend="rf-tuner-controls" />.</entry> <listitem> <para>The &v4l2-ext-control; <structfield>id</structfield> is invalid, the &v4l2-ext-controls; -<structfield>ctrl_class</structfield> is invalid, or the &v4l2-ext-control; +<structfield>which</structfield> is invalid, or the &v4l2-ext-control; <structfield>value</structfield> was inappropriate (e.g. the given menu index is not supported by the driver). This error code is also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and |