1.\" $OpenBSD: video.4,v 1.10 2013/09/28 17:50:07 jmc Exp $ 2.\" 3.\" Copyright (c) 2008 Marcus Glocker <mglocker@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 28 2013 $ 18.Dt VIDEO 4 19.Os 20.Sh NAME 21.Nm video 22.Nd device-independent video driver layer 23.Sh SYNOPSIS 24.Cd "video* at uvideo?" 25.Pp 26.Fd #include <sys/types.h> 27.Fd #include <sys/ioctl.h> 28.Fd #include <sys/videoio.h> 29.Sh DESCRIPTION 30The 31.Nm 32driver provides support for various video devices. 33It provides a uniform programming interface layer 34above different underlying video hardware drivers. 35The 36.Nm 37driver uses the V4L2 (Video for Linux Two) API which is widely used by video 38applications. 39Therefore this document mainly describes the V4L2 API parts 40which are supported by the 41.Nm 42driver. 43.Sh IOCTLS 44The following 45.Xr ioctl 2 46commands are supported: 47.Bl -tag -width Ds 48.It VIDIOC_QUERYCAP (struct v4l2_capability *) 49Query device capabilities. 50.Bd -literal 51struct v4l2_capability { 52 u_int8_t driver[16]; 53 u_int8_t card[32]; 54 u_int8_t bus_info[32]; 55 u_int32_t version; 56 u_int32_t capabilities; 57 u_int32_t reserved[4]; 58}; 59.Ed 60.It VIDIOC_ENUM_FMT (struct v4l2_fmtdesc *) 61Enumerate image formats. 62.Bd -literal 63struct v4l2_fmtdesc { 64 u_int32_t index; 65 enum v4l2_buf_type type; 66 u_int32_t flags; 67 u_int8_t description[32]; 68 u_int32_t pixelformat; 69 u_int32_t reserved[4]; 70}; 71.Ed 72.It VIDIOC_S_FMT (struct v4l2_format *) 73Set the data format. 74.Bd -literal 75struct v4l2_format { 76 enum v4l2_buf_type type; 77 union { 78 struct v4l2_pix_format pix; 79 struct v4l2_window win; 80 struct v4l2_vbi_format vbi; 81 struct v4l2_sliced_vbi_format sliced; 82 u_int8_t raw_data[200]; 83 } fmt; 84}; 85.Ed 86.It VIDIOC_G_FMT (struct v4l2_format *) 87Get the data format. 88.Pp 89Same structure as for VIDIOC_S_FMT. 90.It VIDIOC_ENUMINPUT (struct v4l2_input *) 91Enumerate video inputs. 92.Bd -literal 93struct v4l2_input { 94 u_int32_t index; 95 u_int8_t name[32]; 96 u_int32_t type; 97 u_int32_t audioset; 98 u_int32_t tuner; 99 v4l2_std_id std; 100 u_int32_t status; 101 u_int32_t reserved[32]; 102}; 103.Ed 104.It VIDIOC_S_INPUT (int *) 105Select the current video input. 106.It VIDIOC_REQBUFS (struct v4l2_requestbuffers *) 107Initiate memory mapping or user pointer I/O. 108.Bd -literal 109struct v4l2_requestbuffers { 110 u_int32_t count; 111 enum v4l2_buf_type type; 112 enum v4l2_memory memory; 113 u_int32_t reserved[2]; 114}; 115.Ed 116.It VIDIOC_QUERYBUF (struct v4l2_buffer *) 117Query the status of a buffer. 118.Bd -literal 119struct v4l2_buffer { 120 u_int32_t index; 121 enum v4l2_buf_type type; 122 u_int32_t bytesused; 123 u_int32_t flags; 124 enum v4l2_field field; 125 struct timeval timestamp; 126 struct v4l2_timecode timecode; 127 u_int32_t sequence; 128 enum v4l2_memory memory; 129 union { 130 u_int32_t offset; 131 unsigned long userptr; 132 } m; 133 u_int32_t length; 134 u_int32_t input; 135 u_int32_t reserved; 136}; 137.Ed 138.It VIDIOC_QBUF (struct v4l2_buffer *) 139Add a buffer to the queue. 140.Pp 141Same structure as for VIDIOC_QUERYBUF. 142.It VIDIOC_DQBUF (struct v4l2_buffer *) 143Remove a buffer from the queue. 144.Pp 145Same structure as for VIDIOC_QUERYBUF. 146.It VIDIOC_STREAMON (int *) 147Start video stream. 148.It Dv VIDIOC_STREAMOFF (int *) 149Stop video stream. 150.It VIDIOC_TRY_FMT (struct v4l2_format *) 151Try a data format. 152.Pp 153Same structure as for VIDIOC_S_FMT. 154.It VIDIOC_ENUM_FRAMEINTERVALS (struct v4l2_frmivalenum *) 155Enumerate frame intervals. 156.Bd -literal 157struct v4l2_frmivalemun { 158 u_int32_t index; 159 u_int32_t pixel_format; 160 u_int32_t width; 161 u_int32_t height; 162 u_int32_t type; 163 union { 164 struct v4l2_fract discrete; 165 struct v4l2_frmival_stepwise stepwise; 166 } un; 167 u_int32_t reserved[2]; 168}; 169 170struct v4l2_frmival_stepwise { 171 struct v4l2_fract min; 172 struct v4l2_fract max; 173 struct v4l2_fract step; 174}; 175.Ed 176.It VIDIOC_S_PARM (struct v4l2_streamparm *) 177Set streaming parameters. 178.Bd -literal 179struct v4l2_streamparm { 180 enum v4l2_buf_type type; 181 union { 182 struct v4l2_captureparm capture; 183 struct v4l2_outputparm output; 184 u_int8_t raw_data[200]; 185 } parm; 186}; 187 188struct v4l2_captureparm { 189 u_int32_t capability; 190 u_int32_t capturemode; 191 struct v4l2_fract timeperframe; 192 u_int32_t extendedmode; 193 u_int32_t readbuffers; 194 u_int32_t reserved[4]; 195}; 196 197struct v4l2_outputparm { 198 u_int32_t capability; 199 u_int32_t outputmode; 200 struct v4l2_fract timeperframe; 201 u_int32_t extendedmode; 202 u_int32_t writebuffers; 203 u_int32_t reserved[4]; 204}; 205.Ed 206.It VIDIOC_G_PARM (struct v4l2_streamparm *) 207Get the streaming parameters. 208.Pp 209Same structures as for VIDIOC_S_PARM. 210.It VIDIOC_QUERYCTRL (struct v4l2_queryctrl *) 211Enumerate control items. 212.Bd -literal 213struct v4l2_queryctrl { 214 u_int32_t id; 215 enum v4l2_ctrl_type type; 216 u_int8_t name[32]; 217 int32_t minimum; 218 int32_t maximum; 219 int32_t step; 220 int32_t default_value; 221 u_int32_t flags; 222 u_int32_t reserved[2]; 223}; 224.Ed 225.El 226.Pp 227Command independent enumerations are: 228.Bd -literal 229enum v4l2_buf_type { 230 V4L2_BUF_TYPE_VIDEO_CAPTURE = 1, 231 V4L2_BUF_TYPE_VIDEO_OUTPUT = 2, 232 V4L2_BUF_TYPE_VIDEO_OVERLAY = 3, 233 V4L2_BUF_TYPE_VBI_CAPTURE = 4, 234 V4L2_BUF_TYPE_VBI_OUTPUT = 5, 235 V4L2_BUF_TYPE_SLICED_VBI_CAPTURE = 6, 236 V4L2_BUF_TYPE_SLICED_VBI_OUTPUT = 7, 237 V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY = 8, 238 V4L2_BUF_TYPE_PRIVATE = 0x80, 239}; 240 241enum v4l2_memory { 242 V4L2_MEMORY_MMAP = 1, 243 V4L2_MEMORY_USERPTR = 2, 244 V4L2_MEMORY_OVERLAY = 3, 245}; 246 247enum v4l2_ctrl_type { 248 V4L2_CTRL_TYPE_INTEGER = 1, 249 V4L2_CTRL_TYPE_BOOLEAN = 2, 250 V4L2_CTRL_TYPE_MENU = 3, 251 V4L2_CTRL_TYPE_BUTTON = 4, 252 V4L2_CTRL_TYPE_INTEGER64 = 5, 253 V4L2_CTRL_TYPE_CTRL_CLASS = 6, 254}; 255 256enum v4l2_frmivaltypes { 257 V4L2_FRMIVAL_TYPE_DISCRETE = 1, 258 V4L2_FRMIVAL_TYPE_CONTINUOUS = 2, 259 V4L2_FRMIVAL_TYPE_STEPWISE = 3, 260}; 261.Ed 262.Pp 263Command independent structures are: 264.Bd -literal 265struct v4l2_pix_format { 266 u_int32_t width; 267 u_int32_t height; 268 u_int32_t pixelformat; 269 enum v4l2_field field; 270 u_int32_t bytesperline; 271 u_int32_t sizeimage; 272 enum v4l2_colorspace colorspace; 273 u_int32_t priv; 274}; 275 276struct v4l2_window { 277 struct v4l2_rect w; 278 enum v4l2_field chromakey; 279 struct v4l2_clip __user *clips; 280 u_int32_t clipcount; 281 void __user *bitmap; 282 u_int8_t global_alpha; 283}; 284 285struct v4l2_vbi_format { 286 u_int32_t sampling_rate; 287 u_int32_t offset; 288 u_int32_t samples_per_line; 289 u_int32_t sample_format; 290 int32_t start[2]; 291 u_int32_t count[2]; 292 u_int32_t flags; 293 u_int32_t reserved[2]; 294}; 295 296struct v4l2_sliced_vbi_format { 297 u_int16_t service_set; 298 u_int16_t service_lines[2][24]; 299 u_int32_t io_size; 300 u_int32_t reserved[2]; 301}; 302 303struct v4l2_fract { 304 u_int32_t numerator; 305 u_int32_t denominator; 306}; 307.Ed 308.Pp 309Command independent typedefs are: 310.Bd -literal 311typedef u_int64_t v4l2_std_id; 312.Ed 313.Sh READ 314Video data can be accessed via the 315.Xr read 2 316system call. 317The main iteration for userland applications occurs as follow: 318.Pp 319.Bl -enum -compact -offset indent 320.It 321Open /dev/video* via the 322.Xr open 2 323system call. 324.It 325Read video data from the device via the 326.Xr read 2 327system call. 328The video stream will be started automatically with the first 329read, which means there is no need to issue a VIDIOC_STREAMON command. 330The read will always return a consistent video frame, if no error occurs. 331.It 332Process video data and start over again with step 2. 333.It 334When finished stop the video stream via the 335.Xr close 2 336system call. 337.El 338.Pp 339The 340.Xr select 2 341and 342.Xr poll 2 343system calls are supported for this access type. 344They will signal when a frame is ready for reading without blocking. 345.Sh MMAP 346Video data can be accessed via the 347.Xr mmap 2 348system call. 349The main iteration for userland applications occurs as follow: 350.Pp 351.Bl -enum -compact -offset indent 352.It 353Open /dev/video* via the 354.Xr open 2 355system call. 356.It 357Request desired number of buffers via the VIDIOC_REQBUFS ioctl command. 358The maximum number of available buffers is normally limited by the hardware 359driver. 360.It 361Get the length and offset for the previously requested buffers via the 362VIDIOC_QUERYBUF ioctl command and map the buffers via the 363.Xr mmap 2 364system call. 365.It 366Initially queue the buffers via the VIDIOC_QBUF ioctl command. 367.It 368Start the video stream via the VIDIOC_STREAMON ioctl command. 369.It 370Dequeue one buffer via the VIDIOC_DQBUF ioctl command. 371If the queue is empty 372the ioctl will block until a buffer gets queued or an error occurs 373(e.g. a timeout). 374.It 375Requeue the buffer via the VIDIOC_QBUF ioctl command. 376.It 377Process video data and start over again with step 6. 378.It 379When finished stop the video stream via the VIDIOC_STREAMOFF ioctl command. 380.El 381.Pp 382The 383.Xr select 2 384and 385.Xr poll 2 386system calls are supported for this access type. 387They will signal when at least one frame is ready for dequeuing, 388allowing to call the VIDIOC_DQBUF ioctl command without blocking. 389.Sh FILES 390.Bl -tag -width /dev/video -compact 391.It Pa /dev/video 392.El 393.Sh SEE ALSO 394.Xr ioctl 2 , 395.Xr uvideo 4 396.Sh HISTORY 397The 398.Nm 399driver first appeared in 400.Ox 4.4 . 401