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