| <refentry id="vidioc-querycap"> |
| <refmeta> |
| <refentrytitle>ioctl VIDIOC_QUERYCAP</refentrytitle> |
| &manvol; |
| </refmeta> |
| |
| <refnamediv> |
| <refname>VIDIOC_QUERYCAP</refname> |
| <refpurpose>Query device capabilities</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <funcsynopsis> |
| <funcprototype> |
| <funcdef>int <function>ioctl</function></funcdef> |
| <paramdef>int <parameter>fd</parameter></paramdef> |
| <paramdef>int <parameter>request</parameter></paramdef> |
| <paramdef>struct v4l2_capability *<parameter>argp</parameter></paramdef> |
| </funcprototype> |
| </funcsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Arguments</title> |
| |
| <variablelist> |
| <varlistentry> |
| <term><parameter>fd</parameter></term> |
| <listitem> |
| <para>&fd;</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>request</parameter></term> |
| <listitem> |
| <para>VIDIOC_QUERYCAP</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>argp</parameter></term> |
| <listitem> |
| <para></para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para>All V4L2 devices support the |
| <constant>VIDIOC_QUERYCAP</constant> ioctl. It is used to identify |
| kernel devices compatible with this specification and to obtain |
| information about driver and hardware capabilities. The ioctl takes a |
| pointer to a &v4l2-capability; which is filled by the driver. When the |
| driver is not compatible with this specification the ioctl returns an |
| &EINVAL;.</para> |
| |
| <table pgwide="1" frame="none" id="v4l2-capability"> |
| <title>struct <structname>v4l2_capability</structname></title> |
| <tgroup cols="3"> |
| &cs-str; |
| <tbody valign="top"> |
| <row> |
| <entry>__u8</entry> |
| <entry><structfield>driver</structfield>[16]</entry> |
| <entry><para>Name of the driver, a unique NUL-terminated |
| ASCII string. For example: "bttv". Driver specific applications can |
| use this information to verify the driver identity. It is also useful |
| to work around known bugs, or to identify drivers in error reports.</para> |
| <para>Storing strings in fixed sized arrays is bad |
| practice but unavoidable here. Drivers and applications should take |
| precautions to never read or write beyond the end of the array and to |
| make sure the strings are properly NUL-terminated.</para></entry> |
| </row> |
| <row> |
| <entry>__u8</entry> |
| <entry><structfield>card</structfield>[32]</entry> |
| <entry>Name of the device, a NUL-terminated UTF-8 string. |
| For example: "Yoyodyne TV/FM". One driver may support different brands |
| or models of video hardware. This information is intended for users, |
| for example in a menu of available devices. Since multiple TV cards of |
| the same brand may be installed which are supported by the same |
| driver, this name should be combined with the character device file |
| name (⪚ <filename>/dev/video2</filename>) or the |
| <structfield>bus_info</structfield> string to avoid |
| ambiguities.</entry> |
| </row> |
| <row> |
| <entry>__u8</entry> |
| <entry><structfield>bus_info</structfield>[32]</entry> |
| <entry>Location of the device in the system, a |
| NUL-terminated ASCII string. For example: "PCI:0000:05:06.0". This |
| information is intended for users, to distinguish multiple |
| identical devices. If no such information is available the field must |
| simply count the devices controlled by the driver ("platform:vivi-000"). |
| The bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI Express boards, |
| "usb-" for USB devices, "I2C:" for i2c devices, "ISA:" for ISA devices, |
| "parport" for parallel port devices and "platform:" for platform devices.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>version</structfield></entry> |
| <entry><para>Version number of the driver.</para> |
| <para>Starting on kernel 3.1, the version reported is provided per |
| V4L2 subsystem, following the same Kernel numberation scheme. However, it |
| should not always return the same version as the kernel, if, for example, |
| an stable or distribution-modified kernel uses the V4L2 stack from a |
| newer kernel.</para> |
| <para>The version number is formatted using the |
| <constant>KERNEL_VERSION()</constant> macro:</para></entry> |
| </row> |
| <row> |
| <entry spanname="hspan"><para> |
| <programlisting> |
| #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) |
| |
| __u32 version = KERNEL_VERSION(0, 8, 1); |
| |
| printf ("Version: %u.%u.%u\n", |
| (version >> 16) & 0xFF, |
| (version >> 8) & 0xFF, |
| version & 0xFF); |
| </programlisting></para></entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>capabilities</structfield></entry> |
| <entry>Available capabilities of the physical device as a whole, see <xref |
| linkend="device-capabilities" />. The same physical device can export |
| multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and /dev/radioZ). |
| The <structfield>capabilities</structfield> field should contain a union |
| of all capabilities available around the several V4L2 devices exported |
| to userspace. |
| For all those devices the <structfield>capabilities</structfield> field |
| returns the same set of capabilities. This allows applications to open |
| just one of the devices (typically the video device) and discover whether |
| video, vbi and/or radio are also supported. |
| </entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>device_caps</structfield></entry> |
| <entry>Device capabilities of the opened device, see <xref |
| linkend="device-capabilities" />. Should contain the available capabilities |
| of that specific device node. So, for example, <structfield>device_caps</structfield> |
| of a radio device will only contain radio related capabilities and |
| no video or vbi capabilities. This field is only set if the <structfield>capabilities</structfield> |
| field contains the <constant>V4L2_CAP_DEVICE_CAPS</constant> capability. |
| Only the <structfield>capabilities</structfield> field can have the |
| <constant>V4L2_CAP_DEVICE_CAPS</constant> capability, <structfield>device_caps</structfield> |
| will never set <constant>V4L2_CAP_DEVICE_CAPS</constant>. |
| </entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>reserved</structfield>[3]</entry> |
| <entry>Reserved for future extensions. Drivers must set |
| this array to zero.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="none" id="device-capabilities"> |
| <title>Device Capabilities Flags</title> |
| <tgroup cols="3"> |
| &cs-def; |
| <tbody valign="top"> |
| <row> |
| <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry> |
| <entry>0x00000001</entry> |
| <entry>The device supports the single-planar API through the <link |
| linkend="capture">Video Capture</link> interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant></entry> |
| <entry>0x00001000</entry> |
| <entry>The device supports the |
| <link linkend="planar-apis">multi-planar API</link> through the |
| <link linkend="capture">Video Capture</link> interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry> |
| <entry>0x00000002</entry> |
| <entry>The device supports the single-planar API through the <link |
| linkend="output">Video Output</link> interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant></entry> |
| <entry>0x00002000</entry> |
| <entry>The device supports the |
| <link linkend="planar-apis">multi-planar API</link> through the |
| <link linkend="output">Video Output</link> interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_VIDEO_M2M</constant></entry> |
| <entry>0x00004000</entry> |
| <entry>The device supports the single-planar API through the |
| Video Memory-To-Memory interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_VIDEO_M2M_MPLANE</constant></entry> |
| <entry>0x00008000</entry> |
| <entry>The device supports the |
| <link linkend="planar-apis">multi-planar API</link> through the |
| Video Memory-To-Memory interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry> |
| <entry>0x00000004</entry> |
| <entry>The device supports the <link |
| linkend="overlay">Video Overlay</link> interface. A video overlay device |
| typically stores captured images directly in the video memory of a |
| graphics card, with hardware clipping and scaling.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry> |
| <entry>0x00000010</entry> |
| <entry>The device supports the <link linkend="raw-vbi">Raw |
| VBI Capture</link> interface, providing Teletext and Closed Caption |
| data.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_VBI_OUTPUT</constant></entry> |
| <entry>0x00000020</entry> |
| <entry>The device supports the <link linkend="raw-vbi">Raw VBI Output</link> interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant></entry> |
| <entry>0x00000040</entry> |
| <entry>The device supports the <link linkend="sliced">Sliced VBI Capture</link> interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant></entry> |
| <entry>0x00000080</entry> |
| <entry>The device supports the <link linkend="sliced">Sliced VBI Output</link> interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry> |
| <entry>0x00000100</entry> |
| <entry>The device supports the <link linkend="rds">RDS</link> capture interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry> |
| <entry>0x00000200</entry> |
| <entry>The device supports the <link linkend="osd">Video |
| Output Overlay</link> (OSD) interface. Unlike the <wordasword>Video |
| Overlay</wordasword> interface, this is a secondary function of video |
| output devices and overlays an image onto an outgoing video signal. |
| When the driver sets this flag, it must clear the |
| <constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag and vice |
| versa.<footnote><para>The &v4l2-framebuffer; lacks an |
| &v4l2-buf-type; field, therefore the type of overlay is implied by the |
| driver capabilities.</para></footnote></entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_HW_FREQ_SEEK</constant></entry> |
| <entry>0x00000400</entry> |
| <entry>The device supports the &VIDIOC-S-HW-FREQ-SEEK; ioctl for |
| hardware frequency seeking.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_RDS_OUTPUT</constant></entry> |
| <entry>0x00000800</entry> |
| <entry>The device supports the <link linkend="rds">RDS</link> output interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_TUNER</constant></entry> |
| <entry>0x00010000</entry> |
| <entry>The device has some sort of tuner to |
| receive RF-modulated video signals. For more information about |
| tuner programming see |
| <xref linkend="tuner" />.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_AUDIO</constant></entry> |
| <entry>0x00020000</entry> |
| <entry>The device has audio inputs or outputs. It may or |
| may not support audio recording or playback, in PCM or compressed |
| formats. PCM audio support must be implemented as ALSA or OSS |
| interface. For more information on audio inputs and outputs see <xref |
| linkend="audio" />.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_RADIO</constant></entry> |
| <entry>0x00040000</entry> |
| <entry>This is a radio receiver.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_MODULATOR</constant></entry> |
| <entry>0x00080000</entry> |
| <entry>The device has some sort of modulator to |
| emit RF-modulated video/audio signals. For more information about |
| modulator programming see |
| <xref linkend="tuner" />.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_SDR_CAPTURE</constant></entry> |
| <entry>0x00100000</entry> |
| <entry>The device supports the |
| <link linkend="sdr">SDR Capture</link> interface.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_READWRITE</constant></entry> |
| <entry>0x01000000</entry> |
| <entry>The device supports the <link |
| linkend="rw">read()</link> and/or <link linkend="rw">write()</link> |
| I/O methods.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_ASYNCIO</constant></entry> |
| <entry>0x02000000</entry> |
| <entry>The device supports the <link |
| linkend="async">asynchronous</link> I/O methods.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_STREAMING</constant></entry> |
| <entry>0x04000000</entry> |
| <entry>The device supports the <link |
| linkend="mmap">streaming</link> I/O method.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_CAP_DEVICE_CAPS</constant></entry> |
| <entry>0x80000000</entry> |
| <entry>The driver fills the <structfield>device_caps</structfield> |
| field. This capability can only appear in the <structfield>capabilities</structfield> |
| field and never in the <structfield>device_caps</structfield> field.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| </refsect1> |
| |
| <refsect1> |
| &return-value; |
| </refsect1> |
| </refentry> |
