1.\" $OpenBSD: video.4,v 1.9 2011/03/29 20:30:51 jakemsr 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: March 29 2011 $ 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 flags; 66 u_int8_t description[32]; 67 u_int32_t pixelformat; 68 u_int32_t reserved[4]; 69}; 70.Ed 71.It VIDIOC_S_FMT (struct v4l2_format *) 72Set the data format. 73.Bd -literal 74struct v4l2_format { 75 enum v4l2_buf_type type; 76 union { 77 struct v4l2_pix_format pix; 78 struct v4l2_window win; 79 struct v4l2_vbi_format vbi; 80 struct v4l2_sliced_vbi_format sliced; 81 u_int8_t raw_data[200]; 82 } fmt; 83}; 84.Ed 85.It VIDIOC_G_FMT (struct v4l2_format *) 86Get the data format. 87.Pp 88Same structure as for VIDIOC_S_FMT. 89.It VIDIOC_ENUMINPUT (struct v4l2_input *) 90Enumerate video inputs. 91.Bd -literal 92struct v4l2_input { 93 u_int32_t index; 94 u_int8_t name[32]; 95 u_int32_t type; 96 u_int32_t audioset; 97 u_int32_t tuner; 98 v4l2_std_id std; 99 u_int32_t status; 100 u_int32_t reserved[32]; 101}; 102.Ed 103.It VIDIOC_S_INPUT (int *) 104Select the current video input. 105.It VIDIOC_REQBUFS (struct v4l2_requestbuffers *) 106Initiate memory mapping or user pointer I/O. 107.Bd -literal 108struct v4l2_requestbuffers { 109 u_int32_t count; 110 enum v4l2_buf_type type; 111 enum v4l2_memory memory; 112 u_int32_t reserved[2]; 113}; 114.Ed 115.It VIDIOC_QUERYBUF (struct v4l2_buffer *) 116Query the status of a buffer. 117.Bd -literal 118struct v4l2_buffer { 119 u_int32_t index; 120 enum v4l2_buf_type type; 121 u_int32_t bytesused; 122 u_int32_t flags; 123 enum v4l2_field field; 124 struct timeval timestamp; 125 struct v4l2_timecode timecode; 126 u_int32_t sequence; 127 enum v4l2_memory memory; 128 union { 129 u_int32_t offset; 130 unsigned long userptr; 131 } m; 132 u_int32_t length; 133 u_int32_t input; 134 u_int32_t reserved; 135}; 136.Ed 137.It VIDIOC_QBUF (struct v4l2_buffer *) 138Add a buffer to the queue. 139.Pp 140Same structure as for VIDIOC_QUERYBUF. 141.It VIDIOC_DQBUF (struct v4l2_buffer *) 142Remove a buffer from the queue. 143.Pp 144Same structure as for VIDIOC_QUERYBUF. 145.It VIDIOC_STREAMON (int *) 146Start video stream. 147.It Dv VIDIOC_STREAMOFF (int *) 148Stop video stream. 149.It VIDIOC_TRY_FMT (struct v4l2_format *) 150Try a data format. 151.Pp 152Same structure as for VIDIOC_S_FMT. 153.It VIDIOC_ENUM_FRAMEINTERVALS (struct v4l2_frmivalenum *) 154Enumerate frame intervals. 155.Bd -literal 156struct v4l2_frmivalemun { 157 u_int32_t index; 158 u_int32_t pixel_format; 159 u_int32_t width; 160 u_int32_t height; 161 u_int32_t type; 162 union { 163 struct v4l2_fract discrete; 164 struct v4l2_frmival_stepwise stepwise; 165 } un; 166 u_int32_t reserved[2]; 167}; 168 169struct v4l2_frmival_stepwise { 170 struct v4l2_fract min; 171 struct v4l2_fract max; 172 struct v4l2_fract step; 173}; 174.Ed 175.It VIDIOC_S_PARM (struct v4l2_streamparm *) 176Set streaming parameters. 177.Bd -literal 178struct v4l2_streamparm { 179 enum v4l2_buf_type type; 180 union { 181 struct v4l2_captureparm capture; 182 struct v4l2_outputparm output; 183 u_int8_t raw_data[200]; 184 } parm; 185}; 186 187struct v4l2_captureparm { 188 u_int32_t capability; 189 u_int32_t capturemode; 190 struct v4l2_fract timeperframe; 191 u_int32_t extendedmode; 192 u_int32_t readbuffers; 193 u_int32_t reserved[4]; 194}; 195 196struct v4l2_outputparm { 197 u_int32_t capability; 198 u_int32_t outputmode; 199 struct v4l2_fract timeperframe; 200 u_int32_t extendedmode; 201 u_int32_t writebuffers; 202 u_int32_t reserved[4]; 203}; 204.Ed 205.It VIDIOC_G_PARM (struct v4l2_streamparm *) 206Get the streaming parameters. 207.Pp 208Same structures as for VIDIOC_S_PARM. 209.It VIDIOC_QUERYCTRL (struct v4l2_queryctrl *) 210Enumerate control items. 211.Bd -literal 212struct v4l2_queryctrl { 213 u_int32_t id; 214 enum v4l2_ctrl_type type; 215 u_int8_t name[32]; 216 int32_t minimum; 217 int32_t maximum; 218 int32_t step; 219 int32_t default_value; 220 u_int32_t flags; 221 u_int32_t reserved[2]; 222}; 223.Ed 224.El 225.Pp 226Command independent enumerations are: 227.Bd -literal 228enum v4l2_buf_type { 229 V4L2_BUF_TYPE_VIDEO_CAPTURE = 1, 230 V4L2_BUF_TYPE_VIDEO_OUTPUT = 2, 231 V4L2_BUF_TYPE_VIDEO_OVERLAY = 3, 232 V4L2_BUF_TYPE_VBI_CAPTURE = 4, 233 V4L2_BUF_TYPE_VBI_OUTPUT = 5, 234 V4L2_BUF_TYPE_SLICED_VBI_CAPTURE = 6, 235 V4L2_BUF_TYPE_SLICED_VBI_OUTPUT = 7, 236 V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY = 8, 237 V4L2_BUF_TYPE_PRIVATE = 0x80, 238}; 239 240enum v4l2_memory { 241 V4L2_MEMORY_MMAP = 1, 242 V4L2_MEMORY_USERPTR = 2, 243 V4L2_MEMORY_OVERLAY = 3, 244}; 245 246enum v4l2_ctrl_type { 247 V4L2_CTRL_TYPE_INTEGER = 1, 248 V4L2_CTRL_TYPE_BOOLEAN = 2, 249 V4L2_CTRL_TYPE_MENU = 3, 250 V4L2_CTRL_TYPE_BUTTON = 4, 251 V4L2_CTRL_TYPE_INTEGER64 = 5, 252 V4L2_CTRL_TYPE_CTRL_CLASS = 6, 253}; 254 255enum v4l2_frmivaltypes { 256 V4L2_FRMIVAL_TYPE_DISCRETE = 1, 257 V4L2_FRMIVAL_TYPE_CONTINUOUS = 2, 258 V4L2_FRMIVAL_TYPE_STEPWISE = 3, 259}; 260.Ed 261.Pp 262Command independent structures are: 263.Bd -literal 264struct v4l2_pix_format { 265 u_int32_t width; 266 u_int32_t height; 267 u_int32_t pixelformat; 268 enum v4l2_field field; 269 u_int32_t bytesperline; 270 u_int32_t sizeimage; 271 enum v4l2_colorspace colorspace; 272 u_int32_t priv; 273}; 274 275struct v4l2_window { 276 struct v4l2_rect w; 277 enum v4l2_field chromakey; 278 struct v4l2_clip __user *clips; 279 u_int32_t clipcount; 280 void __user *bitmap; 281 u_int8_t global_alpha; 282}; 283 284struct v4l2_vbi_format { 285 u_int32_t sampling_rate; 286 u_int32_t offset; 287 u_int32_t samples_per_line; 288 u_int32_t sample_format; 289 int32_t start[2]; 290 u_int32_t count[2]; 291 u_int32_t flags; 292 u_int32_t reserved[2]; 293}; 294 295struct v4l2_sliced_vbi_format { 296 u_int16_t service_set; 297 u_int16_t service_lines[2][24]; 298 u_int32_t io_size; 299 u_int32_t reserved[2]; 300}; 301 302struct v4l2_fract { 303 u_int32_t numerator; 304 u_int32_t denominator; 305}; 306.Ed 307.Pp 308Command independent typedefs are: 309.Bd -literal 310typedef u_int64_t v4l2_std_id; 311.Ed 312.Sh READ 313Video data can be accessed via the 314.Xr read 2 315system call. 316The main iteration for userland applications occurs as follow: 317.Pp 318.Bl -enum -compact -offset indent 319.It 320Open /dev/video* via the 321.Xr open 2 322system call. 323.It 324Read video data from the device via the 325.Xr read 2 326system call. 327The video stream will be started automatically with the first 328read, which means there is no need to issue a VIDIOC_STREAMON command. 329The read will always return a consistent video frame, if no error occurs. 330.It 331Process video data and start over again with step 2. 332.It 333When finished stop the video stream via the 334.Xr close 2 335system call. 336.El 337.Pp 338The 339.Xr select 2 340and 341.Xr poll 2 342system calls are supported for this access type. 343They will signal when a frame is ready for reading without blocking. 344.Sh MMAP 345Video data can be accessed via the 346.Xr mmap 2 347system call. 348The main iteration for userland applications occurs as follow: 349.Pp 350.Bl -enum -compact -offset indent 351.It 352Open /dev/video* via the 353.Xr open 2 354system call. 355.It 356Request desired number of buffers via the VIDIOC_REQBUFS ioctl command. 357The maximum number of available buffers is normally limited by the hardware 358driver. 359.It 360Get the length and offset for the previously requested buffers via the 361VIDIOC_QUERYBUF ioctl command and map the buffers via the 362.Xr mmap 2 363system call. 364.It 365Initially queue the buffers via the VIDIOC_QBUF ioctl command. 366.It 367Start the video stream via the VIDIOC_STREAMON ioctl command. 368.It 369Dequeue one buffer via the VIDIOC_DQBUF ioctl command. 370If the queue is empty 371the ioctl will block until a buffer gets queued or an error occurs 372(e.g. a timeout). 373.It 374Requeue the buffer via the VIDIOC_QBUF ioctl command. 375.It 376Process video data and start over again with step 6. 377.It 378When finished stop the video stream via the VIDIOC_STREAMOFF ioctl command. 379.El 380.Pp 381The 382.Xr select 2 383and 384.Xr poll 2 385system calls are supported for this access type. 386They will signal when at least one frame is ready for dequeuing, 387allowing to call the VIDIOC_DQBUF ioctl command without blocking. 388.Sh FILES 389.Bl -tag -width /dev/video -compact 390.It Pa /dev/video 391.El 392.Sh SEE ALSO 393.Xr ioctl 2 , 394.Xr uvideo 4 395.Sh HISTORY 396The 397.Nm 398driver first appeared in 399.Ox 4.4 . 400