video_if.h revision 1.1
1 /* $NetBSD: video_if.h,v 1.1 2008/09/06 19:00:54 jmcneill Exp $ */ 2 3 /* 4 * Copyright (c) 2008 Patrick Mahoney <pat (at) polycrystal.org> 5 * All rights reserved. 6 * 7 * This code was written by Patrick Mahoney (pat (at) polycrystal.org) as 8 * part of Google Summer of Code 2008. 9 * 10 * Redistribution and use in source and binary forms, with or without 11 * modification, are permitted provided that the following conditions 12 * are met: 13 * 1. Redistributions of source code must retain the above copyright 14 * notice, this list of conditions and the following disclaimer. 15 * 2. Redistributions in binary form must reproduce the above copyright 16 * notice, this list of conditions and the following disclaimer in the 17 * documentation and/or other materials provided with the distribution. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 * POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 /* 33 * This ia a Video4Linux 2 compatible /dev/video driver for NetBSD 34 * 35 * See http://v4l2spec.bytesex.org/ for Video4Linux 2 specifications 36 */ 37 38 #ifndef _SYS_DEV_VIDEO_IF_H_ 39 #define _SYS_DEV_VIDEO_IF_H_ 40 41 #include <sys/types.h> 42 #include <sys/videoio.h> 43 44 #if defined(_KERNEL_OPT) 45 #include "video.h" 46 47 #if (NVIDEO == 0) 48 #error "No 'video* at videobus?' configured" 49 #endif 50 51 #endif /* _KERNEL_OPT */ 52 53 struct video_softc; 54 55 /* Controls provide a way to query and set controls in the camera 56 * hardware. The control structure is the primitive unit. Control 57 * groups are arrays of controls that must be set together (e.g. pan 58 * direction and pan speed). Control descriptors describe a control 59 * including minimum and maximum values, read-only state, etc. A 60 * control group descriptor is an array of control descriptors 61 * corresponding to a control group array of controls. 62 * 63 * A control_group is made up of multiple controls meant to be set 64 * together and is identified by a 16 bit group_id. Each control is 65 * identified by a group_id and a control_id. Controls that are the 66 * sole member of a control_group may ignore the control_id or 67 * redundantly have the control_id equal to the group_id. 68 * 69 * The hardware driver only handles control_group's, many of which 70 * will only have a single control. 71 * 72 * Some id's are defined here (closely following the USB Video Class 73 * controls) with room for unspecified extended controls. These id's 74 * may be used for group_id's or control_id's as appropriate. 75 */ 76 77 enum video_control_id { 78 VIDEO_CONTROL_UNDEFINED, 79 /* camera hardware */ 80 VIDEO_CONTROL_SCANNING_MODE, 81 VIDEO_CONTROL_AE_MODE, 82 VIDEO_CONTROL_EXPOSURE_TIME_ABSOLUTE, 83 VIDEO_CONTROL_EXPOSURE_TIME_RELATIVE, 84 VIDEO_CONTROL_FOCUS_ABSOLUTE, 85 VIDEO_CONTROL_FOCUS_RELATIVE, 86 VIDEO_CONTROL_IRIS_ABSOLUTE, 87 VIDEO_CONTROL_IRIS_RELATIVE, 88 VIDEO_CONTROL_ZOOM_ABSOLUTE, 89 VIDEO_CONTROL_ZOOM_RELATIVE, 90 VIDEO_CONTROL_PANTILT_ABSOLUTE, 91 VIDEO_CONTROL_PANTILT_RELATIVE, 92 VIDEO_CONTROL_ROLL_ABSOLUTE, 93 VIDEO_CONTROL_ROLL_RELATIVE, 94 VIDEO_CONTROL_PRIVACY, 95 /* video processing */ 96 VIDEO_CONTROL_BACKLIGHT_COMPENSATION, 97 VIDEO_CONTROL_BRIGHTNESS, 98 VIDEO_CONTROL_CONTRAST, 99 VIDEO_CONTROL_GAIN, 100 VIDEO_CONTROL_GAIN_AUTO, /* not in UVC */ 101 VIDEO_CONTROL_POWER_LINE_FREQUENCY, 102 VIDEO_CONTROL_HUE, 103 VIDEO_CONTROL_SATURATION, 104 VIDEO_CONTROL_SHARPNESS, 105 VIDEO_CONTROL_GAMMA, 106 /* Generic WHITE_BALANCE controls applies to whichever type of 107 * white balance the hardware implements to either perform one 108 * white balance action or enable auto white balance. */ 109 VIDEO_CONTROL_WHITE_BALANCE_ACTION, 110 VIDEO_CONTROL_WHITE_BALANCE_AUTO, 111 VIDEO_CONTROL_WHITE_BALANCE_TEMPERATURE, 112 VIDEO_CONTROL_WHITE_BALANCE_TEMPERATURE_AUTO, 113 VIDEO_CONTROL_WHITE_BALANCE_COMPONENT, 114 VIDEO_CONTROL_WHITE_BALANCE_COMPONENT_AUTO, 115 VIDEO_CONTROL_DIGITAL_MULTIPLIER, 116 VIDEO_CONTROL_DIGITAL_MULTIPLIER_LIMIT, 117 VIDEO_CONTROL_HUE_AUTO, 118 VIDEO_CONTROL_ANALOG_VIDEO_STANDARD, 119 VIDEO_CONTROL_ANALOG_LOCK_STATUS, 120 /* video stream */ 121 VIDEO_CONTROL_GENERATE_KEY_FRAME, 122 VIDEO_CONTROL_UPDATE_FRAME_SEGMENT, 123 /* misc, not in UVC */ 124 VIDEO_CONTROL_HFLIP, 125 VIDEO_CONTROL_VFLIP, 126 /* Custom controls start here; any controls beyond this are 127 * valid and condsidered "extended". */ 128 VIDEO_CONTROL_EXTENDED 129 }; 130 131 enum video_control_type { 132 VIDEO_CONTROL_TYPE_INT, /* signed 32 bit integer */ 133 VIDEO_CONTROL_TYPE_BOOL, 134 VIDEO_CONTROL_TYPE_LIST, /* V4L2 MENU */ 135 VIDEO_CONTROL_TYPE_ACTION /* V4L2 BUTTON */ 136 }; 137 138 #define VIDEO_CONTROL_FLAG_READ (1<<0) 139 #define VIDEO_CONTROL_FLAG_WRITE (1<<1) 140 #define VIDEO_CONTROL_FLAG_DISABLED (1<<2) /* V4L2 INACTIVE */ 141 #define VIDEO_CONTROL_FLAG_AUTOUPDATE (1<<3) 142 #define VIDEO_CONTROL_FLAG_ASYNC (1<<4) 143 144 struct video_control_desc { 145 uint16_t group_id; 146 uint16_t control_id; 147 uint8_t name[32]; 148 uint32_t flags; 149 enum video_control_type type; 150 int32_t min; 151 int32_t max; 152 int32_t step; 153 int32_t def; 154 }; 155 156 /* array of struct video_control_value_info belonging to the same control */ 157 struct video_control_desc_group { 158 uint16_t group_id; 159 uint8_t length; 160 struct video_control_desc *desc; 161 }; 162 163 struct video_control { 164 uint16_t group_id; 165 uint16_t control_id; 166 int32_t value; 167 }; 168 169 /* array of struct video_control_value belonging to the same control */ 170 struct video_control_group { 171 uint16_t group_id; 172 uint8_t length; 173 struct video_control *control; 174 }; 175 176 struct video_control_iter { 177 struct video_control_desc *desc; 178 }; 179 180 /* format of video data in a video sample */ 181 enum video_pixel_format { 182 VIDEO_FORMAT_UNDEFINED, 183 184 /* uncompressed frame-based formats */ 185 VIDEO_FORMAT_YUY2, /* packed 4:2:2 */ 186 VIDEO_FORMAT_NV12, /* planar 4:2:0 */ 187 188 /* compressed frame-based formats */ 189 VIDEO_FORMAT_MJPEG, /* frames of JPEG images */ 190 VIDEO_FORMAT_DV, 191 192 /* stream-based formats */ 193 VIDEO_FORMAT_MPEG 194 }; 195 196 /* interlace_flags bits are allocated like this: 197 7 6 5 4 3 2 1 0 198 \_/ | | |interlaced or progressive 199 | | |packing style of fields (interlaced or planar) 200 | |fields per sample (1 or 2) 201 |pattern (F1 only, F2 only, F12, RND) 202 */ 203 204 /* two bits */ 205 #define VIDEO_INTERLACED(iflags) (iflags & 1) 206 enum video_interlace_presence { 207 VIDEO_INTERLACE_OFF = 0, /* progressive */ 208 VIDEO_INTERLACE_ON = 1, 209 VIDEO_INTERLACE_ANY = 2 /* in requests, accept any interlacing */ 210 }; 211 212 /* one bit, not in UVC */ 213 #define VIDEO_INTERLACE_PACKING(iflags) ((iflags >> 2) & 1) 214 enum video_interlace_packing { 215 VIDEO_INTERLACE_INTERLACED = 0, /* F1 and F2 are interlaced */ 216 VIDEO_INTERLACE_PLANAR = 1 /* entire F1 is followed by F2 */ 217 }; 218 219 /* one bit, not in V4L2; Is this not redundant with PATTERN below? 220 * For now, I'm assuming it describes where the "end-of-frame" markers 221 * appear in the stream data: after every field or after every two 222 * fields. */ 223 #define VIDEO_INTERLACE_FIELDS_PER_SAMPLE(iflags) ((iflags >> 3) & 1) 224 enum video_interlace_fields_per_sample { 225 VIDEO_INTERLACE_TWO_FIELDS_PER_SAMPLE = 0, 226 VIDEO_INTERLACE_ONE_FIELD_PER_SAMPLE = 1 227 }; 228 229 /* two bits */ 230 #define VIDEO_INTERLACE_PATTERN(iflags) ((iflags >> 4) & 3) 231 enum video_interlace_pattern { 232 VIDEO_INTERLACE_PATTERN_F1 = 0, 233 VIDEO_INTERLACE_PATTERN_F2 = 1, 234 VIDEO_INTERLACE_PATTERN_F12 = 2, 235 VIDEO_INTERLACE_PATTERN_RND = 3 236 }; 237 238 enum video_color_primaries { 239 VIDEO_COLOR_PRIMARIES_UNSPECIFIED, 240 VIDEO_COLOR_PRIMARIES_BT709, /* identical to sRGB */ 241 VIDEO_COLOR_PRIMARIES_BT470_2_M, 242 VIDEO_COLOR_PRIMARIES_BT470_2_BG, 243 VIDEO_COLOR_PRIMARIES_SMPTE_170M, 244 VIDEO_COLOR_PRIMARIES_SMPTE_240M, 245 VIDEO_COLOR_PRIMARIES_BT878 /* in V4L2 as broken BT878 chip */ 246 }; 247 248 enum video_gamma_function { 249 VIDEO_GAMMA_FUNCTION_UNSPECIFIED, 250 VIDEO_GAMMA_FUNCTION_BT709, 251 VIDEO_GAMMA_FUNCTION_BT470_2_M, 252 VIDEO_GAMMA_FUNCTION_BT470_2_BG, 253 VIDEO_GAMMA_FUNCTION_SMPTE_170M, 254 VIDEO_GAMMA_FUNCTION_SMPTE_240M, 255 VIDEO_GAMMA_FUNCTION_LINEAR, 256 VIDEO_GAMMA_FUNCTION_sRGB, /* similar but not identical to BT709 */ 257 VIDEO_GAMMA_FUNCTION_BT878 /* in V4L2 as broken BT878 chip */ 258 }; 259 260 /* Matrix coefficients for converting YUV to RGB */ 261 enum video_matrix_coeff { 262 VIDEO_MATRIX_COEFF_UNSPECIFIED, 263 VIDEO_MATRIX_COEFF_BT709, 264 VIDEO_MATRIX_COEFF_FCC, 265 VIDEO_MATRIX_COEFF_BT470_2_BG, 266 VIDEO_MATRIX_COEFF_SMPTE_170M, 267 VIDEO_MATRIX_COEFF_SMPTE_240M, 268 VIDEO_MATRIX_COEFF_BT878 /* in V4L2 as broken BT878 chip */ 269 }; 270 271 /* UVC spec separates these into three categories. V4L2 does not. */ 272 struct video_colorspace { 273 enum video_color_primaries primaries; 274 enum video_gamma_function gamma_function; 275 enum video_matrix_coeff matrix_coeff; 276 }; 277 278 #ifdef undef 279 /* Stucts for future split into format/frame/interval. All functions 280 * interacting with the hardware layer will deal with these structs. 281 * This video layer will handle translating them to V4L2 structs as 282 * necessary. */ 283 284 struct video_format { 285 enum video_pixel_format vfo_pixel_format; 286 uint8_t vfo_aspect_x; /* aspect ratio x and y */ 287 uint8_t vfo_aspect_y; 288 struct video_colorspace vfo_color; 289 uint8_t vfo_interlace_flags; 290 }; 291 292 struct video_frame { 293 uint32_t vfr_width; /* dimensions in pixels */ 294 uint32_t vfr_height; 295 uint32_t vfr_sample_size; /* max sample size */ 296 uint32_t vfr_stride; /* length of one row of pixels in 297 * bytes; uncompressed formats 298 * only */ 299 }; 300 301 enum video_frame_interval_type { 302 VIDEO_FRAME_INTERVAL_TYPE_CONTINUOUS, 303 VIDEO_FRAME_INTERVAL_TYPE_DISCRETE 304 }; 305 306 /* UVC spec frame interval units are 100s of nanoseconds. V4L2 spec 307 * uses a {32/32} bit struct fraction in seconds. We use 100ns units 308 * here. */ 309 #define VIDEO_FRAME_INTERVAL_UNITS_PER_US (10) 310 #define VIDEO_FRAME_INTERVAL_UNITS_PER_MS (10 * 1000) 311 #define VIDEO_FRAME_INTERVAL_UNITS_PER_S (10 * 1000 * 1000) 312 struct video_frame_interval { 313 enum video_frame_interval_type vfi_type; 314 union { 315 struct { 316 uint32_t min; 317 uint32_t max; 318 uint32_t step; 319 } vfi_continuous; 320 321 uint32_t vfi_discrete; 322 }; 323 }; 324 #endif /* undef */ 325 326 /* Describes a video format. For frame based formats, one sample is 327 * equivalent to one frame. For stream based formats such as MPEG, a 328 * sample is logical unit of that streaming format. 329 */ 330 struct video_format { 331 enum video_pixel_format pixel_format; 332 uint32_t width; /* dimensions in pixels */ 333 uint32_t height; 334 uint8_t aspect_x; /* aspect ratio x and y */ 335 uint8_t aspect_y; 336 uint32_t sample_size; /* max sample size */ 337 uint32_t stride; /* length of one row of pixels in 338 * bytes; uncompressed formats 339 * only */ 340 struct video_colorspace color; 341 uint8_t interlace_flags; 342 uint32_t priv; /* For private use by hardware driver. 343 * Must be set to zero if not used. */ 344 }; 345 346 /* A payload is the smallest unit transfered from the hardware driver 347 * to the video layer. Multiple video payloads make up one video 348 * sample. */ 349 struct video_payload { 350 const uint8_t *data; 351 size_t size; /* size in bytes of this payload */ 352 int frameno; /* toggles between 0 and 1 */ 353 bool end_of_frame; /* set if this is the last 354 * payload in the frame. */ 355 }; 356 357 struct video_hw_if { 358 int (*open)(void *, int); /* open hardware */ 359 void (*close)(void *); /* close hardware */ 360 361 const char * (*get_devname)(void *); 362 363 int (*enum_format)(void *, uint32_t, struct video_format *); 364 int (*get_format)(void *, struct video_format *); 365 int (*set_format)(void *, struct video_format *); 366 int (*try_format)(void *, struct video_format *); 367 368 int (*start_transfer)(void *); 369 int (*stop_transfer)(void *); 370 371 int (*control_iter_init)(void *, struct video_control_iter *); 372 int (*control_iter_next)(void *, struct video_control_iter *); 373 int (*get_control_desc_group)(void *, 374 struct video_control_desc_group *); 375 int (*get_control_group)(void *, struct video_control_group *); 376 int (*set_control_group)(void *, const struct video_control_group *); 377 }; 378 379 struct video_attach_args { 380 const struct video_hw_if *hw_if; 381 }; 382 383 device_t video_attach_mi(const struct video_hw_if *, device_t); 384 void video_submit_payload(device_t, const struct video_payload *); 385 386 #endif /* _SYS_DEV_VIDEO_IF_H_ */ 387
Indexes created Mon Sep 22 21:09:42 GMT 2025