Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_ENCODER_CMD: |
5377d91f MH |
4 | |
5 | ************************************************ | |
6 | ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD | |
7 | ************************************************ | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
41d80465 MCC |
18 | .. c:function:: int ioctl( int fd, VIDIOC_ENCODER_CMD, struct v4l2_encoder_cmd *argp ) |
19 | :name: VIDIOC_ENCODER_CMD | |
20 | ||
21 | .. c:function:: int ioctl( int fd, VIDIOC_TRY_ENCODER_CMD, struct v4l2_encoder_cmd *argp ) | |
22 | :name: VIDIOC_TRY_ENCODER_CMD | |
5377d91f | 23 | |
586027ce | 24 | |
15e7d615 | 25 | Arguments |
5377d91f MH |
26 | ========= |
27 | ||
28 | ``fd`` | |
29 | File descriptor returned by :ref:`open() <func-open>`. | |
30 | ||
5377d91f MH |
31 | ``argp`` |
32 | ||
33 | ||
15e7d615 | 34 | Description |
5377d91f MH |
35 | =========== |
36 | ||
37 | These ioctls control an audio/video (usually MPEG-) encoder. | |
38 | ``VIDIOC_ENCODER_CMD`` sends a command to the encoder, | |
39 | ``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually | |
40 | executing it. | |
41 | ||
42 | To send a command applications must initialize all fields of a struct | |
43 | :ref:`v4l2_encoder_cmd <v4l2-encoder-cmd>` and call | |
44 | ``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to | |
45 | this structure. | |
46 | ||
47 | The ``cmd`` field must contain the command code. The ``flags`` field is | |
48 | currently only used by the STOP command and contains one bit: If the | |
49 | ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue | |
50 | until the end of the current *Group Of Pictures*, otherwise it will stop | |
51 | immediately. | |
52 | ||
760c7010 | 53 | A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` |
5377d91f | 54 | call sends an implicit START command to the encoder if it has not been |
760c7010 | 55 | started yet. After a STOP command, :ref:`read() <func-read>` calls will read |
5377d91f | 56 | the remaining data buffered by the driver. When the buffer is empty, |
760c7010 | 57 | :ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>` |
5377d91f MH |
58 | call will restart the encoder. |
59 | ||
760c7010 | 60 | A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` |
5377d91f MH |
61 | call of a streaming file descriptor sends an implicit immediate STOP to |
62 | the encoder, and all buffered data is discarded. | |
63 | ||
64 | These ioctls are optional, not all drivers may support them. They were | |
65 | introduced in Linux 2.6.21. | |
66 | ||
67 | ||
5bd4bb78 MCC |
68 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
69 | ||
fa92b04d MCC |
70 | .. _v4l2-encoder-cmd: |
71 | ||
5377d91f MH |
72 | .. flat-table:: struct v4l2_encoder_cmd |
73 | :header-rows: 0 | |
74 | :stub-columns: 0 | |
75 | :widths: 1 1 2 | |
76 | ||
77 | ||
78 | - .. row 1 | |
79 | ||
80 | - __u32 | |
81 | ||
82 | - ``cmd`` | |
83 | ||
84 | - The encoder command, see :ref:`encoder-cmds`. | |
85 | ||
86 | - .. row 2 | |
87 | ||
88 | - __u32 | |
89 | ||
90 | - ``flags`` | |
91 | ||
92 | - Flags to go with the command, see :ref:`encoder-flags`. If no | |
0579e6e3 MCC |
93 | flags are defined for this command, drivers and applications must |
94 | set this field to zero. | |
5377d91f MH |
95 | |
96 | - .. row 3 | |
97 | ||
98 | - __u32 | |
99 | ||
8968da9b | 100 | - ``data``\ [8] |
5377d91f MH |
101 | |
102 | - Reserved for future extensions. Drivers and applications must set | |
0579e6e3 | 103 | the array to zero. |
5377d91f MH |
104 | |
105 | ||
106 | ||
5bd4bb78 MCC |
107 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
108 | ||
fa92b04d MCC |
109 | .. _encoder-cmds: |
110 | ||
5377d91f MH |
111 | .. flat-table:: Encoder Commands |
112 | :header-rows: 0 | |
113 | :stub-columns: 0 | |
114 | :widths: 3 1 4 | |
115 | ||
116 | ||
117 | - .. row 1 | |
118 | ||
119 | - ``V4L2_ENC_CMD_START`` | |
120 | ||
121 | - 0 | |
122 | ||
123 | - Start the encoder. When the encoder is already running or paused, | |
0579e6e3 | 124 | this command does nothing. No flags are defined for this command. |
5377d91f MH |
125 | |
126 | - .. row 2 | |
127 | ||
128 | - ``V4L2_ENC_CMD_STOP`` | |
129 | ||
130 | - 1 | |
131 | ||
132 | - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag | |
0579e6e3 MCC |
133 | is set, encoding will continue until the end of the current *Group |
134 | Of Pictures*, otherwise encoding will stop immediately. When the | |
135 | encoder is already stopped, this command does nothing. mem2mem | |
136 | encoders will send a ``V4L2_EVENT_EOS`` event when the last frame | |
137 | has been encoded and all frames are ready to be dequeued and will | |
138 | set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of | |
139 | the capture queue to indicate there will be no new buffers | |
140 | produced to dequeue. This buffer may be empty, indicated by the | |
141 | driver setting the ``bytesused`` field to 0. Once the | |
142 | ``V4L2_BUF_FLAG_LAST`` flag was set, the | |
143 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, | |
144 | but return an ``EPIPE`` error code. | |
5377d91f MH |
145 | |
146 | - .. row 3 | |
147 | ||
148 | - ``V4L2_ENC_CMD_PAUSE`` | |
149 | ||
150 | - 2 | |
151 | ||
152 | - Pause the encoder. When the encoder has not been started yet, the | |
0579e6e3 MCC |
153 | driver will return an ``EPERM`` error code. When the encoder is |
154 | already paused, this command does nothing. No flags are defined | |
155 | for this command. | |
5377d91f MH |
156 | |
157 | - .. row 4 | |
158 | ||
159 | - ``V4L2_ENC_CMD_RESUME`` | |
160 | ||
161 | - 3 | |
162 | ||
163 | - Resume encoding after a PAUSE command. When the encoder has not | |
0579e6e3 MCC |
164 | been started yet, the driver will return an ``EPERM`` error code. When |
165 | the encoder is already running, this command does nothing. No | |
166 | flags are defined for this command. | |
5377d91f MH |
167 | |
168 | ||
fa92b04d | 169 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
5377d91f MH |
170 | |
171 | .. _encoder-flags: | |
172 | ||
173 | .. flat-table:: Encoder Command Flags | |
174 | :header-rows: 0 | |
175 | :stub-columns: 0 | |
176 | :widths: 3 1 4 | |
177 | ||
178 | ||
179 | - .. row 1 | |
180 | ||
181 | - ``V4L2_ENC_CMD_STOP_AT_GOP_END`` | |
182 | ||
183 | - 0x0001 | |
184 | ||
185 | - Stop encoding at the end of the current *Group Of Pictures*, | |
0579e6e3 | 186 | rather than immediately. |
5377d91f MH |
187 | |
188 | ||
15e7d615 | 189 | Return Value |
5377d91f MH |
190 | ============ |
191 | ||
192 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
193 | appropriately. The generic error codes are described at the | |
194 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
195 | ||
196 | EINVAL | |
197 | The ``cmd`` field is invalid. | |
198 | ||
199 | EPERM | |
200 | The application sent a PAUSE or RESUME command when the encoder was | |
201 | not running. |