← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-ti-omap4/precise-security

« back to all changes in this revision

Viewing changes to Documentation/DocBook/media/v4l/vidioc-g-fmt.xml

  • Committer: Package Import Robot
  • Author(s): Paolo Pisati, Paolo Pisati
  • Date: 2011-12-06 15:56:07 UTC
  • Revision ID: package-import@ubuntu.com-20111206155607-pcf44kv5fmhk564f
Tags: 3.2.0-1401.1
[ Paolo Pisati ]

* Rebased on top of Ubuntu-3.2.0-3.8
* Tilt-tracking @ ef2487af4bb15bdd0689631774b5a5e3a59f74e2
* Delete debian.ti-omap4/control, it shoudln't be tracked
* Fix architecture spelling (s/armel/armhf/)
* [Config] Update configs following 3.2 import
* [Config] Fix compilation: disable CODA and ARCH_OMAP3
* [Config] Fix compilation: disable Ethernet Faraday
* Update series to precise

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
 
1
<refentry id="vidioc-g-fmt">
 
2
  <refmeta>
 
3
    <refentrytitle>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT,
 
4
VIDIOC_TRY_FMT</refentrytitle>
 
5
    &manvol;
 
6
  </refmeta>
 
7
 
 
8
  <refnamediv>
 
9
    <refname>VIDIOC_G_FMT</refname>
 
10
    <refname>VIDIOC_S_FMT</refname>
 
11
    <refname>VIDIOC_TRY_FMT</refname>
 
12
    <refpurpose>Get or set the data format, try a format</refpurpose>
 
13
  </refnamediv>
 
14
 
 
15
  <refsynopsisdiv>
 
16
    <funcsynopsis>
 
17
      <funcprototype>
 
18
        <funcdef>int <function>ioctl</function></funcdef>
 
19
        <paramdef>int <parameter>fd</parameter></paramdef>
 
20
        <paramdef>int <parameter>request</parameter></paramdef>
 
21
        <paramdef>struct v4l2_format
 
22
*<parameter>argp</parameter></paramdef>
 
23
      </funcprototype>
 
24
    </funcsynopsis>
 
25
  </refsynopsisdiv>
 
26
 
 
27
  <refsect1>
 
28
    <title>Arguments</title>
 
29
 
 
30
    <variablelist>
 
31
      <varlistentry>
 
32
        <term><parameter>fd</parameter></term>
 
33
        <listitem>
 
34
          <para>&fd;</para>
 
35
        </listitem>
 
36
      </varlistentry>
 
37
      <varlistentry>
 
38
        <term><parameter>request</parameter></term>
 
39
        <listitem>
 
40
          <para>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</para>
 
41
        </listitem>
 
42
      </varlistentry>
 
43
      <varlistentry>
 
44
        <term><parameter>argp</parameter></term>
 
45
        <listitem>
 
46
          <para></para>
 
47
        </listitem>
 
48
      </varlistentry>
 
49
    </variablelist>
 
50
  </refsect1>
 
51
 
 
52
  <refsect1>
 
53
    <title>Description</title>
 
54
 
 
55
    <para>These ioctls are used to negotiate the format of data
 
56
(typically image format) exchanged between driver and
 
57
application.</para>
 
58
 
 
59
    <para>To query the current parameters applications set the
 
60
<structfield>type</structfield> field of a struct
 
61
<structname>v4l2_format</structname> to the respective buffer (stream)
 
62
type. For example video capture devices use
 
63
<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
 
64
<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. When the application
 
65
calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to
 
66
this structure the driver fills the respective member of the
 
67
<structfield>fmt</structfield> union. In case of video capture devices
 
68
that is either the &v4l2-pix-format; <structfield>pix</structfield> or
 
69
the &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member.
 
70
When the requested buffer type is not supported drivers return an
 
71
&EINVAL;.</para>
 
72
 
 
73
    <para>To change the current format parameters applications
 
74
initialize the <structfield>type</structfield> field and all
 
75
fields of the respective <structfield>fmt</structfield>
 
76
union member. For details see the documentation of the various devices
 
77
types in <xref linkend="devices" />. Good practice is to query the
 
78
current parameters first, and to
 
79
modify only those parameters not suitable for the application. When
 
80
the application calls the <constant>VIDIOC_S_FMT</constant> ioctl
 
81
with a pointer to a <structname>v4l2_format</structname> structure
 
82
the driver checks
 
83
and adjusts the parameters against hardware abilities. Drivers
 
84
should not return an error code unless the input is ambiguous, this is
 
85
a mechanism to fathom device capabilities and to approach parameters
 
86
acceptable for both the application and driver. On success the driver
 
87
may program the hardware, allocate resources and generally prepare for
 
88
data exchange.
 
89
Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the
 
90
current format parameters as <constant>VIDIOC_G_FMT</constant> does.
 
91
Very simple, inflexible devices may even ignore all input and always
 
92
return the default parameters. However all V4L2 devices exchanging
 
93
data with the application must implement the
 
94
<constant>VIDIOC_G_FMT</constant> and
 
95
<constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer
 
96
type is not supported drivers return an &EINVAL; on a
 
97
<constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in
 
98
progress or the resource is not available for other reasons drivers
 
99
return the &EBUSY;.</para>
 
100
 
 
101
    <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent
 
102
to <constant>VIDIOC_S_FMT</constant> with one exception: it does not
 
103
change driver state. It can also be called at any time, never
 
104
returning <errorcode>EBUSY</errorcode>. This function is provided to
 
105
negotiate parameters, to learn about hardware limitations, without
 
106
disabling I/O or possibly time consuming hardware preparations.
 
107
Although strongly recommended drivers are not required to implement
 
108
this ioctl.</para>
 
109
 
 
110
    <table pgwide="1" frame="none" id="v4l2-format">
 
111
      <title>struct <structname>v4l2_format</structname></title>
 
112
      <tgroup cols="4">
 
113
        <colspec colname="c1" />
 
114
        <colspec colname="c2" />
 
115
        <colspec colname="c3" />
 
116
        <colspec colname="c4" />
 
117
        <tbody valign="top">
 
118
          <row>
 
119
            <entry>&v4l2-buf-type;</entry>
 
120
            <entry><structfield>type</structfield></entry>
 
121
            <entry></entry>
 
122
            <entry>Type of the data stream, see <xref
 
123
                linkend="v4l2-buf-type" />.</entry>
 
124
          </row>
 
125
          <row>
 
126
            <entry>union</entry>
 
127
            <entry><structfield>fmt</structfield></entry>
 
128
          </row>
 
129
          <row>
 
130
            <entry></entry>
 
131
            <entry>&v4l2-pix-format;</entry>
 
132
            <entry><structfield>pix</structfield></entry>
 
133
            <entry>Definition of an image format, see <xref
 
134
                linkend="pixfmt" />, used by video capture and output
 
135
devices.</entry>
 
136
          </row>
 
137
          <row>
 
138
            <entry></entry>
 
139
            <entry>&v4l2-pix-format-mplane;</entry>
 
140
            <entry><structfield>pix_mp</structfield></entry>
 
141
            <entry>Definition of an image format, see <xref
 
142
                linkend="pixfmt" />, used by video capture and output
 
143
devices that support the <link linkend="planar-apis">multi-planar
 
144
version of the API</link>.</entry>
 
145
          </row>
 
146
          <row>
 
147
            <entry></entry>
 
148
            <entry>&v4l2-window;</entry>
 
149
            <entry><structfield>win</structfield></entry>
 
150
            <entry>Definition of an overlaid image, see <xref
 
151
            linkend="overlay" />, used by video overlay devices.</entry>
 
152
          </row>
 
153
          <row>
 
154
            <entry></entry>
 
155
            <entry>&v4l2-vbi-format;</entry>
 
156
            <entry><structfield>vbi</structfield></entry>
 
157
            <entry>Raw VBI capture or output parameters. This is
 
158
discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI
 
159
capture and output devices.</entry>
 
160
          </row>
 
161
          <row>
 
162
            <entry></entry>
 
163
            <entry>&v4l2-sliced-vbi-format;</entry>
 
164
            <entry><structfield>sliced</structfield></entry>
 
165
            <entry>Sliced VBI capture or output parameters. See
 
166
<xref linkend="sliced" /> for details. Used by sliced VBI
 
167
capture and output devices.</entry>
 
168
          </row>
 
169
          <row>
 
170
            <entry></entry>
 
171
            <entry>__u8</entry>
 
172
            <entry><structfield>raw_data</structfield>[200]</entry>
 
173
            <entry>Place holder for future extensions and custom
 
174
(driver defined) formats with <structfield>type</structfield>
 
175
<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry>
 
176
          </row>
 
177
        </tbody>
 
178
      </tgroup>
 
179
    </table>
 
180
  </refsect1>
 
181
 
 
182
  <refsect1>
 
183
    &return-value;
 
184
 
 
185
    <variablelist>
 
186
      <varlistentry>
 
187
        <term><errorcode>EINVAL</errorcode></term>
 
188
        <listitem>
 
189
          <para>The &v4l2-format; <structfield>type</structfield>
 
190
field is invalid, the requested buffer type not supported, or the
 
191
format is not supported with this buffer type.</para>
 
192
        </listitem>
 
193
      </varlistentry>
 
194
    </variablelist>
 
195
  </refsect1>
 
196
</refentry>