video_if.h revision 1.2
1 /* $NetBSD: video_if.h,v 1.2 2008/09/14 00:26:35 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 VIDEO_FORMAT_RGB24, 188 189 /* compressed frame-based formats */ 190 VIDEO_FORMAT_MJPEG, /* frames of JPEG images */ 191 VIDEO_FORMAT_DV, 192 193 /* stream-based formats */ 194 VIDEO_FORMAT_MPEG 195 }; 196 197 /* interlace_flags bits are allocated like this: 198 7 6 5 4 3 2 1 0 199 \_/ | | |interlaced or progressive 200 | | |packing style of fields (interlaced or planar) 201 | |fields per sample (1 or 2) 202 |pattern (F1 only, F2 only, F12, RND) 203 */ 204 205 /* two bits */ 206 #define VIDEO_INTERLACED(iflags) (iflags & 1) 207 enum video_interlace_presence { 208 VIDEO_INTERLACE_OFF = 0, /* progressive */ 209 VIDEO_INTERLACE_ON = 1, 210 VIDEO_INTERLACE_ANY = 2 /* in requests, accept any interlacing */ 211 }; 212 213 /* one bit, not in UVC */ 214 #define VIDEO_INTERLACE_PACKING(iflags) ((iflags >> 2) & 1) 215 enum video_interlace_packing { 216 VIDEO_INTERLACE_INTERLACED = 0, /* F1 and F2 are interlaced */ 217 VIDEO_INTERLACE_PLANAR = 1 /* entire F1 is followed by F2 */ 218 }; 219 220 /* one bit, not in V4L2; Is this not redundant with PATTERN below? 221 * For now, I'm assuming it describes where the "end-of-frame" markers 222 * appear in the stream data: after every field or after every two 223 * fields. */ 224 #define VIDEO_INTERLACE_FIELDS_PER_SAMPLE(iflags) ((iflags >> 3) & 1) 225 enum video_interlace_fields_per_sample { 226 VIDEO_INTERLACE_TWO_FIELDS_PER_SAMPLE = 0, 227 VIDEO_INTERLACE_ONE_FIELD_PER_SAMPLE = 1 228 }; 229 230 /* two bits */ 231 #define VIDEO_INTERLACE_PATTERN(iflags) ((iflags >> 4) & 3) 232 enum video_interlace_pattern { 233 VIDEO_INTERLACE_PATTERN_F1 = 0, 234 VIDEO_INTERLACE_PATTERN_F2 = 1, 235 VIDEO_INTERLACE_PATTERN_F12 = 2, 236 VIDEO_INTERLACE_PATTERN_RND = 3 237 }; 238 239 enum video_color_primaries { 240 VIDEO_COLOR_PRIMARIES_UNSPECIFIED, 241 VIDEO_COLOR_PRIMARIES_BT709, /* identical to sRGB */ 242 VIDEO_COLOR_PRIMARIES_BT470_2_M, 243 VIDEO_COLOR_PRIMARIES_BT470_2_BG, 244 VIDEO_COLOR_PRIMARIES_SMPTE_170M, 245 VIDEO_COLOR_PRIMARIES_SMPTE_240M, 246 VIDEO_COLOR_PRIMARIES_BT878 /* in V4L2 as broken BT878 chip */ 247 }; 248 249 enum video_gamma_function { 250 VIDEO_GAMMA_FUNCTION_UNSPECIFIED, 251 VIDEO_GAMMA_FUNCTION_BT709, 252 VIDEO_GAMMA_FUNCTION_BT470_2_M, 253 VIDEO_GAMMA_FUNCTION_BT470_2_BG, 254 VIDEO_GAMMA_FUNCTION_SMPTE_170M, 255 VIDEO_GAMMA_FUNCTION_SMPTE_240M, 256 VIDEO_GAMMA_FUNCTION_LINEAR, 257 VIDEO_GAMMA_FUNCTION_sRGB, /* similar but not identical to BT709 */ 258 VIDEO_GAMMA_FUNCTION_BT878 /* in V4L2 as broken BT878 chip */ 259 }; 260 261 /* Matrix coefficients for converting YUV to RGB */ 262 enum video_matrix_coeff { 263 VIDEO_MATRIX_COEFF_UNSPECIFIED, 264 VIDEO_MATRIX_COEFF_BT709, 265 VIDEO_MATRIX_COEFF_FCC, 266 VIDEO_MATRIX_COEFF_BT470_2_BG, 267 VIDEO_MATRIX_COEFF_SMPTE_170M, 268 VIDEO_MATRIX_COEFF_SMPTE_240M, 269 VIDEO_MATRIX_COEFF_BT878 /* in V4L2 as broken BT878 chip */ 270 }; 271 272 /* UVC spec separates these into three categories. V4L2 does not. */ 273 struct video_colorspace { 274 enum video_color_primaries primaries; 275 enum video_gamma_function gamma_function; 276 enum video_matrix_coeff matrix_coeff; 277 }; 278 279 #ifdef undef 280 /* Stucts for future split into format/frame/interval. All functions 281 * interacting with the hardware layer will deal with these structs. 282 * This video layer will handle translating them to V4L2 structs as 283 * necessary. */ 284 285 struct video_format { 286 enum video_pixel_format vfo_pixel_format; 287 uint8_t vfo_aspect_x; /* aspect ratio x and y */ 288 uint8_t vfo_aspect_y; 289 struct video_colorspace vfo_color; 290 uint8_t vfo_interlace_flags; 291 }; 292 293 struct video_frame { 294 uint32_t vfr_width; /* dimensions in pixels */ 295 uint32_t vfr_height; 296 uint32_t vfr_sample_size; /* max sample size */ 297 uint32_t vfr_stride; /* length of one row of pixels in 298 * bytes; uncompressed formats 299 * only */ 300 }; 301 302 enum video_frame_interval_type { 303 VIDEO_FRAME_INTERVAL_TYPE_CONTINUOUS, 304 VIDEO_FRAME_INTERVAL_TYPE_DISCRETE 305 }; 306 307 /* UVC spec frame interval units are 100s of nanoseconds. V4L2 spec 308 * uses a {32/32} bit struct fraction in seconds. We use 100ns units 309 * here. */ 310 #define VIDEO_FRAME_INTERVAL_UNITS_PER_US (10) 311 #define VIDEO_FRAME_INTERVAL_UNITS_PER_MS (10 * 1000) 312 #define VIDEO_FRAME_INTERVAL_UNITS_PER_S (10 * 1000 * 1000) 313 struct video_frame_interval { 314 enum video_frame_interval_type vfi_type; 315 union { 316 struct { 317 uint32_t min; 318 uint32_t max; 319 uint32_t step; 320 } vfi_continuous; 321 322 uint32_t vfi_discrete; 323 }; 324 }; 325 #endif /* undef */ 326 327 /* Describes a video format. For frame based formats, one sample is 328 * equivalent to one frame. For stream based formats such as MPEG, a 329 * sample is logical unit of that streaming format. 330 */ 331 struct video_format { 332 enum video_pixel_format pixel_format; 333 uint32_t width; /* dimensions in pixels */ 334 uint32_t height; 335 uint8_t aspect_x; /* aspect ratio x and y */ 336 uint8_t aspect_y; 337 uint32_t sample_size; /* max sample size */ 338 uint32_t stride; /* length of one row of pixels in 339 * bytes; uncompressed formats 340 * only */ 341 struct video_colorspace color; 342 uint8_t interlace_flags; 343 uint32_t priv; /* For private use by hardware driver. 344 * Must be set to zero if not used. */ 345 }; 346 347 /* A payload is the smallest unit transfered from the hardware driver 348 * to the video layer. Multiple video payloads make up one video 349 * sample. */ 350 struct video_payload { 351 const uint8_t *data; 352 size_t size; /* size in bytes of this payload */ 353 int frameno; /* toggles between 0 and 1 */ 354 bool end_of_frame; /* set if this is the last 355 * payload in the frame. */ 356 }; 357 358 struct video_hw_if { 359 int (*open)(void *, int); /* open hardware */ 360 void (*close)(void *); /* close hardware */ 361 362 const char * (*get_devname)(void *); 363 364 int (*enum_format)(void *, uint32_t, struct video_format *); 365 int (*get_format)(void *, struct video_format *); 366 int (*set_format)(void *, struct video_format *); 367 int (*try_format)(void *, struct video_format *); 368 369 int (*start_transfer)(void *); 370 int (*stop_transfer)(void *); 371 372 int (*control_iter_init)(void *, struct video_control_iter *); 373 int (*control_iter_next)(void *, struct video_control_iter *); 374 int (*get_control_desc_group)(void *, 375 struct video_control_desc_group *); 376 int (*get_control_group)(void *, struct video_control_group *); 377 int (*set_control_group)(void *, const struct video_control_group *); 378 }; 379 380 struct video_attach_args { 381 const struct video_hw_if *hw_if; 382 }; 383 384 device_t video_attach_mi(const struct video_hw_if *, device_t); 385 void video_submit_payload(device_t, const struct video_payload *); 386 387 #endif /* _SYS_DEV_VIDEO_IF_H_ */ 388
Indexes created Thu Sep 25 16:09:42 GMT 2025