share/man/man4/man4.i386/meteor.4

   1 .\"
   2 .\" $FreeBSD: src/share/man/man4/man4.i386/meteor.4,v 1.10.2.4 2001/08/17 13:08:45 ru Exp $
   3 .\" $DragonFly: src/share/man/man4/man4.i386/meteor.4,v 1.8 2006/10/23 07:45:47 swildner Exp $
   4 .\"
   5 .Dd August 15, 1995
   6 .Dt METEOR 4 i386
   7 .Os
   8 .Sh NAME
   9 .Nm meteor
  10 .Nd "video capture driver"
  11 .Sh SYNOPSIS
  12 .Cd "device meteor"
  13 .Sh DESCRIPTION
  14 The
  15 .Nm
  16 driver provides support for a PCI
  17 .Em video
  18 capture.
  19 It allows the capture of 24 bit RGB, 16 bit RGB and 16 bit YUV
  20 output formats.
  21 .Ss Meteor Driver Configuration
  22 To use the
  23 .Tn "Matrox Meteor"
  24 card in your system, you need a computer
  25 that supports the PCI (preferably the Type 2 or better) interface bus.
  26 It is recommended that the system has more than 16 MB of RAM since this
  27 capture card directly deposits the image to system RAM.
  28 .Bl -enum
  29 .It
  30 In the configuration file, add the line:
  31 .Pp
  32 .Cd "device meteor"
  33 .It
  34 There is also a couple of optional parameters you may use:
  35 .Bl -tag -width indent
  36 .It Cd "options ""METEOR_ALLOC_PAGES=xxx"""
  37 Specifies the number of contiguous pages to allocate when successfully
  38 probed.
  39 The default number of pages allocated by the kernel is 151.
  40 This means that there are (151*4096) bytes available for use.
  41 .It Cd "options METEOR_DEALLOC_PAGES"
  42 Deallocate all pages when closing the device.
  43 Note, the chances of
  44 contiguously re-allocating new pages are very small.
  45 The default
  46 behavior is to not deallocate pages.
  47 .It Cd "options ""METEOR_DEALLOC_ABOVE=xxx"""
  48 Deallocate all pages above the specified number.
  49 The default action is
  50 to not deallocate above any pages.
  51 .El
  52 .It
  53 Make and install the kernel.
  54 .It
  55 Make the special file name:
  56 .Pp
  57 .Dl "# cd /dev; ./MAKEDEV meteor0"
  58 .Pp
  59 The major number is determined by the placement of the device in
  60 .Pa conf.c .
  61 The patch supplied with the driver will make the major number 67.
  62 .El
  63 .Ss Meteor Capture Modes
  64 The
  65 .Nm
  66 capture driver has three modes of capture operation.
  67 .Bl -enum
  68 .It
  69 Conventional
  70 .Xr read 2
  71 interface.
  72 .Pp
  73 This mode is the easiest and slowest to use.
  74 This mode is great for
  75 capturing a single field at little programming cost.
  76 .Pp
  77 In this mode, the user opens the device, sets the capture mode
  78 and size (see:
  79 .Dv METEORSETGEO
  80 .Xr ioctl 2
  81 call), and uses the
  82 .Xr read 2
  83 system
  84 call to load the data into a buffer.
  85 .Pp
  86 .Pa meteor_read.c ;
  87 read 400x300 RGB24 into a viewable PPM file
  88 .Bd -literal
  89 #include <sys/fcntl.h>
  90 #include <machine/ioctl_meteor.h>
  91
  92 extern int errno;
  93 #define ROWS 300
  94 #define COLS 400
  95 #define SIZE (ROWS * COLS * 4)
  96 main()
  97 {
  98         struct meteor_geomet geo;
  99         char buf[SIZE],b[4],header[16],*p;
 100         int i,o,c;
 101
 102         if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
 103                 printf("open failed: %d\\n", errno);
 104                 exit(1);
 105         }
 106         /* set up the capture type and size */
 107         geo.rows = ROWS;
 108         geo.columns = COLS;
 109         geo.frames = 1;
 110         geo.oformat = METEOR_GEO_RGB24 ;
 111
 112         if (ioctl(i, METEORSETGEO, &geo) < 0) {
 113                 printf("ioctl failed: %d\\n", errno);
 114                 exit(1);
 115         }
 116
 117         c = METEOR_FMT_NTSC;
 118
 119         if (ioctl(i, METEORSFMT, &c) < 0) {
 120                 printf("ioctl failed: %d\\n", errno);
 121                 exit(1);
 122         }
 123
 124         c = METEOR_INPUT_DEV0;
 125
 126         if (ioctl(i, METEORSINPUT, &c) < 0) {
 127                 printf("ioctl failed: %d\\n", errno);
 128                 exit(1);
 129         }
 130
 131         if ((c=read(i, &buf[0], SIZE)) < SIZE) {
 132                 printf("read failed %d %d %d\\n", c, i, errno);
 133                 close(i);
 134                 exit(1);
 135         }
 136         close(i);
 137
 138         if ((o = open("rgb24.ppm", O_WRONLY | O_CREAT, 0644)) < 0) {
 139                 printf("ppm open failed: %d\\n", errno);
 140                 exit(1);
 141         }
 142
 143         /* make PPM header and save to file */
 144         strcpy(&header[0], "P6 400 300 255 ");
 145         header[2] = header[6]  = header[10] = header[14] = '\\n';
 146         write (o, &header[0], 15);
 147         /* save the RGB data to PPM file */
 148         for (p = &buf[0]; p < &buf[SIZE]; ) {
 149                 b[2] = *p++;            /* blue */
 150                 b[1] = *p++;            /* green */
 151                 b[0] = *p++;            /* red */
 152                 *p++;                   /* NULL byte */
 153                 write(o,&b[0], 3);      /* not very efficient */
 154         }
 155         close(o);
 156         exit(0);
 157 }
 158 .Ed
 159 .It
 160 Memory mapped single capture or unsynchronized continuous capture.
 161 .Pp
 162 The single capture mode is designed for conferencing tools such as
 163 .Nm nv .
 164 These tools need to control the starting of the image capture and also
 165 need several frames a second.
 166 The continuous capture mode is designed
 167 for applications that want free-running data.
 168 .Pp
 169 In this mode, the user opens the device, sets the capture mode
 170 and size (see:
 171 .Dv METEORSETGEO
 172 .Xr ioctl 2
 173 call),
 174 .Xr mmap 2 Ns s
 175 the frame buffer
 176 memory into the user process space, and issues either the
 177 single-capture or the continuous capture call (see:
 178 .Dv METEORCAPTUR
 179 .Xr ioctl 2
 180 call) to load the data into the memory mapped buffer.
 181 .Pp
 182 As explained in the
 183 .Dv METEORCAPTUR
 184 .Xr ioctl 2
 185 call, the single frame capture
 186 .Xr ioctl 2
 187 will block until the capture is complete, the continuous capture
 188 will return immediately.
 189 .Pp
 190 .Pa meteor_mmap_single_continuous.c
 191 .Bd -literal
 192 #include <sys/types.h>
 193 #include <sys/mman.h>
 194 #include <sys/fcntl.h>
 195 #include <machine/ioctl_meteor.h>
 196
 197 extern int errno;
 198 #define ROWS 480
 199 #define COLS 640
 200 #define SIZE (ROWS * COLS * 2)
 201 main()
 202 {
 203         struct meteor_geomet geo;
 204         char buf[SIZE];
 205         char *mmbuf;
 206         int i,c;
 207
 208         if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
 209                 printf("open failed\\n");
 210                 exit(1);
 211         }
 212
 213         geo.rows = ROWS;
 214         geo.columns = COLS;
 215         geo.frames = 1;
 216         geo.oformat = METEOR_GEO_RGB16 ;
 217
 218         if (ioctl(i, METEORSETGEO, &geo) < 0) {
 219                 printf("ioctl failed: %d\\n", errno);
 220                 exit(1);
 221         }
 222
 223         c = METEOR_FMT_NTSC;
 224
 225         if (ioctl(i, METEORSFMT, &c) < 0) {
 226                 printf("ioctl failed: %d\\n", errno);
 227                 exit(1);
 228         }
 229
 230         c = METEOR_INPUT_DEV0;
 231
 232         if (ioctl(i, METEORSINPUT, &c) < 0) {
 233                 printf("ioctl failed: %d\\n", errno);
 234                 exit(1);
 235         }
 236
 237         mmbuf=(char *)mmap((caddr_t)0, SIZE, PROT_READ,
 238                 MAP_SHARED, i, (off_t)0);
 239
 240 #ifdef SINGLE_MODE
 241         /* single frame capture */
 242         c = METEOR_CAP_SINGLE ;
 243         ioctl(i, METEORCAPTUR, &c);     /* wait for the frame */
 244
 245         /* directly access the frame buffer array data in mmbuf */
 246 #else
 247         /* continuous frame capture */
 248         c = METEOR_CAP_CONTINOUS ;
 249         ioctl(i, METEORCAPTUR, &c);     /* returns immediately */
 250
 251         /* directly access the frame buffer array data in mmbuf */
 252
 253         c = METEOR_CAP_STOP_CONT ;
 254         ioctl(i, METEORCAPTUR, &c);     /* close will also stop capture */
 255 #endif
 256
 257         close(i);
 258         exit(0);
 259 }
 260 .Ed
 261 .It
 262 Memory mapped, multi-frame ring buffer synchronize capture.
 263 .Pp
 264 This continuous capture mode is synchronized with the application that
 265 processes up to 32 frames.
 266 This gives the advantages of both single and
 267 continuous capture modes.
 268 .Pp
 269 The kernel notifies the application of a new data by raising an
 270 application defined signal.
 271 The driver also shares a structure with
 272 the application that allows them to communicate which frame has been
 273 written by the kernel and which frame has been read by the application.
 274 .Pp
 275 The shared structure starts on the first page after your data.
 276 The
 277 structure address can be found by calculation:
 278 .Pp
 279 .Dl "(number_rows * number_columns * pixel_depth + 4095) & 0xfffff000"
 280 or
 281 .Dl "((number_rows * number_columns * pixel_depth + 4095)/4096) * 4096"
 282 .Pp
 283 The shared structure is of type
 284 .Va struct meteor_mem .
 285 The two most
 286 important fields are called
 287 .Va active
 288 and
 289 .Va num_active_buf .
 290 .Va active
 291 is a bitmap of frames written by the kernel.
 292 .Va num_active_bufs
 293 is
 294 a count of frames marked in the
 295 .Va active
 296 field.
 297 When a frame is read
 298 in by the driver, the
 299 .Va num_active_bufs
 300 count is tested, if this
 301 count is below the threshold of number of active frames (value
 302 in
 303 .Va meteor_mem Ns 's
 304 .Va hiwat
 305 variable), the bit representing frame
 306 number in the buffer is stored in the
 307 .Va active
 308 variable, the
 309 .Va num_active_bufs
 310 is incremented, the kernel then raises the specified
 311 signal to activate the user application.
 312 The user application's
 313 responsibility when getting the signal is to check the active bitmap
 314 to determine the lowest active frame, use the data as the application
 315 desires, clear the bitmap entry for that frame, and decrement the
 316 .Va num_active_bufs .
 317 If the threshold of number of active frames
 318 .Pq Va hiwat
 319 has been exceeded, no new frames or signal from the kernel will occur
 320 until the
 321 .Va num_active_bufs
 322 is less than or equal to
 323 .Va lowat .
 324 .Pp
 325 The driver loads the frames in a round-robin fashion.
 326 It is expected
 327 that the user removes them in the same order.
 328 The driver does not
 329 check to see if the frame is already active.
 330 .Pp
 331 The
 332 .Va frame_size
 333 and number of frames in the buffer are also provided
 334 to the
 335 .Va meteor_mem
 336 structure, but changing these fields in the
 337 application will not change the operation of the driver.
 338 .Pp
 339 In programming for this mode, the user opens the device, sets the
 340 geometry,
 341 .Xr mmap 2 Ns s
 342 the data/common control structure, then starts the
 343 continuous capture mode.
 344 A special signal catcher is required to
 345 process the frames as they are read by the kernel.
 346 .Pp
 347 When specifying the geometry (see:
 348 .Dv METEORSETGEO
 349 .Xr ioctl 2
 350 call),
 351 it
 352 is important that the number of frames is set greater than 1.
 353 .Pp
 354 .Pa skeleton_capture_n.c
 355 .Bd -literal
 356 #include <sys/types.h>
 357 #include <sys/mman.h>
 358 #include <sys/fcntl.h>
 359 #include <sys/signal.h>
 360 #include <machine/ioctl_meteor.h>
 361
 362 int video;  /* made global if you wish to stop capture in signal handler */
 363 caddr_t data_frames;
 364 struct meteor_mem *common_mem;
 365 extern int errno;
 366
 367 #define FRAME_MAX
 368
 369 void
 370 usr2_catcher()
 371 {
 372 #ifdef SIGNAL_STOP
 373         struct meteor_capframe capframe;        /* for ioctl */
 374 #endif
 375         char *frame;
 376
 377         /* find frame */
 378         frame = (char *) (data_frames + sig_cnt * common_mem->frame_size) ;
 379
 380         /* add frame processing here */
 381         /* deactivate frame */
 382         common_mem->active &= ~(1 << (sig_cnt % 16));
 383         common_mem->num_active_bufs--;
 384
 385         /* process next frame on next interrupt */
 386         sig_cnt = ((sig_cnt+1) % FRAME_MAX);
 387
 388 #ifdef SIGNAL_STOP
 389         if (some_condition_requiring_stopping) {
 390                 capframe.command=METEOR_CAP_STOP_FRAMES;
 391
 392                 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
 393                         printf("METEORCAPFRM failed %d\\n", errno);
 394                         exit(1);
 395                 }
 396         }
 397 #endif
 398 }
 399
 400 main()
 401 {
 402         struct meteor_geomet geo;
 403         int height, width, depth, frames, size;
 404         struct meteor_capframe capframe;
 405
 406         if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
 407                 printf("open failed\\n");
 408                 exit(1);
 409         }
 410         printf("test %d %d\\n", errno, i);
 411
 412         height = geo.rows = 120;
 413         width= geo.columns = 320;
 414         frames = geo.frames = FRAME_MAX;
 415         depth = 2;      /* 2 bytes per pixel for RGB*/
 416
 417
 418         geo.oformat = METEOR_GEO_RGB16;
 419
 420         if (ioctl(i, METEORSETGEO, &geo) < 0) {
 421                 printf("METEORSETGEO failed %d\\n", errno);
 422                 exit(1);
 423         }
 424
 425         c = METEOR_FMT_NTSC;
 426
 427         if (ioctl(i, METEORSFMT, &c) < 0) {
 428                 printf("ioctl failed: %d\\n", errno);
 429                 exit(1);
 430         }
 431
 432         c = METEOR_INPUT_DEV0;
 433
 434         if (ioctl(i, METEORSINPUT, &c) < 0) {
 435                 printf("ioctl failed: %d\\n", errno);
 436                 exit(1);
 437         }
 438
 439         size = ((width*height*depth*frames+4095)/4096)*4096;
 440         /* add one page after data for meteor_mem */
 441         data_frames = mmap((caddr_t)0, size + 4096, PROT_READ | PROT_WRITE,
 442                                                 MAP_SHARED, i, (off_t)0);
 443
 444         if (data_frames == (caddr_t) MAP_FAILED) return (0);
 445
 446         /* common_mem is located at page following data */
 447         common_mem = (struct meteor_mem *) (y + size);
 448
 449         signal(SIGUSR2, usr2_catcher);  /* catch new frame message */
 450
 451         capframe.command=METEOR_CAP_N_FRAMES;
 452         capframe.signal=SIGUSR2;
 453         capframe.lowat=12;              /* must be < hiwat */
 454         capframe.hiwat=14;              /* must be < FRAME_MAX */
 455
 456                                         /* start the sync capture */
 457         if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
 458                 printf("METEORCAPFRM failed %d\\n", errno);
 459                 exit(1);
 460         }
 461
 462         /* this is the background working area, or you can sleep */
 463
 464
 465         /* to stop capture */
 466         capframe.command=METEOR_CAP_STOP_FRAMES;
 467
 468         if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
 469                 printf("METEORCAPFRM failed %d\\n", errno);
 470                 exit(1);
 471         }
 472 }
 473 .Ed
 474 .El
 475 .Ss Meteor IOCTL Call and Parameters
 476 The
 477 .Nm
 478 capture driver has
 479 .Xr ioctl 2
 480 requests for capturing, reading card
 481 status, for setting and reading the geometry, and for setting and reading the
 482 attributes.
 483 .Pp
 484 .Bf -symbolic
 485 IT IS VERY IMPORTANT TO CHECK FOR ERRORS ON THESE RETURNING IOCTLs.
 486 .Ef
 487 Errors indicate that something is very wrong with the
 488 .Xr ioctl 2
 489 and the
 490 application should not attempt to proceed further with capturing.
 491 The
 492 .Nm
 493 capture driver still makes attempts to stop the next capture step if
 494 an error occurred in a previous step but was ignored by the application
 495 programmer.
 496 .Bl -enum
 497 .It
 498 .Xr ioctl 2
 499 requests
 500 .Dv METEORSETGEO
 501 and
 502 .Dv METEORGETGEO
 503 .Pp
 504 .Dv METEORSETGEO
 505 and
 506 .Dv METEORGETGEO
 507 are used to set and read the input
 508 size, input device, and output format for frame capture.
 509 .Pp
 510 These
 511 .Xr ioctl 2
 512 routines use the
 513 .Va meteor_geomet
 514 structure that has the
 515 following entries:
 516 .Pp
 517 .Bl -tag -width columns
 518 .It Va rows
 519 number of rows (lines high) in output image
 520 .It Va columns
 521 number of pixels in a row (width) in output image
 522 .It Va frames
 523 number of frames in buffer.
 524 Should be 1, unless using
 525 the multi-framed synchronous capture mode
 526 .Pq Dv METEORCAPFRM
 527 which REQUIRES frames to be larger than 1.
 528 .Pp
 529 Note: if
 530 .Va rows , columns
 531 or
 532 .Va frames
 533 is not changed, then
 534 the existing values are used.
 535 The system defaults
 536 is 640x480x1.
 537 .It Va oformat
 538 you may choose one of the following output format:
 539 .Bl -tag -width METEOR_GEO_YUV_PACKED
 540 .It Dv METEOR_GEO_RGB16
 541 (RGB 16 bits xrrrrrgg gggbbbbb default)
 542 .It Dv METEOR_GEO_RGB24
 543 (RGB 24 bits packed in 32 bits:
 544 00000000 rrrrrrrr gggggggg bbbbbbbb)
 545 .It Dv METEOR_GEO_YUV_PACKED
 546 (4-2-2 YUV 16 bits packed byte format:
 547 u0 y0 v0 y1 u1 y2 v1 y3 ...)
 548 .It Dv METEOR_GEO_YUV_PLANER
 549 (4-2-2 YUV 16 bits planer format:
 550 rows * columns bytes of y
 551 rows * column / 4 bytes of even u
 552 rows * column / 4 bytes of even v
 553 rows * column / 4 bytes of odd  u
 554 rows * column / 4 bytes of odd  v)
 555 .El
 556 .El
 557 .Pp
 558 The
 559 .Dv METEORSETGEO
 560 .Xr ioctl 2
 561 will fail if more than one entry from a category
 562 is selected.
 563 It is highly recommended that a
 564 .Dv METEORSETGEO
 565 is done
 566 before capturing data because you cannot guarantee the initial mode
 567 the card.
 568 .Pp
 569 The
 570 .Dv METEORSETGEO
 571 will also attempt to reallocate a new contiguous
 572 kernel buffer if the new geometry exceeds the old geometry.
 573 On
 574 other hand, if the new geometry will fit in the existing buffer,
 575 the existing buffer is used.
 576 .Pp
 577 If
 578 .Dv METEORSETGEO
 579 fails the
 580 .Xr ioctl 2
 581 will return a value of -1 and the
 582 external variable
 583 .Va errno
 584 will be set to:
 585 .Bl -tag -width Er
 586 .It Bq Er EINVAL
 587 invalid
 588 .Va meteor_geomet
 589 structure pointer,
 590 .Va rows , columns , frames
 591 were invalid.
 592 .It Bq Er ENOMEM
 593 could not allocate the contiguous block.
 594 .El
 595 .It
 596 .Xr ioctl 2
 597 requests
 598 .Dv METEORSFMT
 599 and
 600 .Dv METEORGFMT
 601 .Pp
 602 .Dv METEORSFMT
 603 and
 604 .Dv METEORGFMT
 605 are used to set and read the camera input
 606 standard format.
 607 .Pp
 608 Possible formats are:
 609 .Pp
 610 .Bl -tag -width METEOR_FMT_AUTOMODE -compact
 611 .It Dv METEOR_FMT_NTSC
 612 NTSC (default mode)
 613 .It Dv METEOR_FMT_PAL
 614 PAL
 615 .It Dv METEOR_FMT_SECAM
 616 SECAM
 617 .It Dv METEOR_FMT_AUTOMODE
 618 Autodetect.
 619 .El
 620 .It
 621 .Xr ioctl 2
 622 requests
 623 .Dv METEORSINPUT
 624 and
 625 .Dv METEORGINPUT
 626 .Pp
 627 .Dv METEORSINPUT
 628 and
 629 .Dv METEORGINPUT
 630 are used to set and read the camera
 631 input device.
 632 Using the DB9 connector on the
 633 .Tn Meteor
 634 card, 4 input
 635 devices can be connected and an input camera can be selected with this
 636 .Xr ioctl 2 .
 637 .Pp
 638 Possible formats are:
 639 .Pp
 640 .Bl -tag -width METEOR_INPUT_DEV_SVIDEO -compact
 641 .It Dv METEOR_INPUT_DEV0
 642 (default if none specified)
 643 .It Dv METEOR_INPUT_DEV_RCA
 644 (same as METEOR_INPUT_DEV0)
 645 .It Dv METEOR_INPUT_DEV1
 646 .It Dv METEOR_INPUT_DEV2
 647 .It Dv METEOR_INPUT_DEV_SVIDEO
 648 (same as METEOR_INPUT_DEV2)
 649 .El
 650 .It
 651 .Xr ioctl 2
 652 request
 653 .Dv METEORSTATUS
 654 .Pp
 655 .Dv METEORSTATUS
 656 is used to read the status of the
 657 .Tn Meteor
 658 capture card
 659 and returns the following information:
 660 .Bl -column "METEOR_STATUS_ID_MASK" "\&"
 661 .It Dv METEOR_STATUS_ID_MASK "  4 bit ID of the SAA7196 scaler chip."
 662 .Pp
 663 .It Dv METEOR_STATUS_DIR "      0 =     scaler uses internal source."
 664 .It "   1 =     scaler uses external data of expansion bus."
 665 .Pp
 666 .It Dv METEOR_STATUS_OEF "      0 =     even field detected."
 667 .It "   1 =     odd field detected."
 668 .Pp
 669 .It Dv METEOR_STATUS_SVP "      VRAM Port state:"
 670 .It "   0 =     inputs HFL and INCADDR inactive."
 671 .It "   1 =     inputs HFL and INCADDR active."
 672 .Pp
 673 .It Dv METEOR_STATUS_STTC "     0 =     TV horizontal time constant (slow)."
 674 .It "   1 =     VCR horizontal time constant (fast)."
 675 .Pp
 676 .It Dv METEOR_STATUS_HCLK "     0 =     Horizontal Phase Lock Loop locked."
 677 .It "   1 =     Horizontal Phase Lock Loop unlocked."
 678 .Pp
 679 .It Dv METEOR_STATUS_FIDT "     0 =     50 Hz Field detected."
 680 .It "   1 =     60 Hz Field detected."
 681 .Pp
 682 .It Dv METEOR_STATUS_ALTD "     0 =     no line alternating color burst detected."
 683 .It "   1 =     line alternating color burst detected (PAL/SECAM)."
 684 .Pp
 685 .It Dv METEOR_STATUS_CODE "     0 =     no color information detected."
 686 .It "   1 =     color information detected."
 687 .El
 688 .It
 689 .Xr ioctl 2
 690 request
 691 .Dv METEORCAPTUR
 692 .Pp
 693 .Dv METEORCAPTUR
 694 is used to single frame capture or unsynchronized
 695 continuous capture.
 696 .Pp
 697 The single frame capture
 698 .Xr ioctl 2
 699 request will return only after a
 700 frame has been captured and transfered to the frame buffer.
 701 .Pp
 702 The unsynchronized continuous capture will return immediately and
 703 data is directly deposited into the buffer when it is available.
 704 Since this is unsynchronized, it is possible the data is being
 705 written by the kernel while being read by the application.
 706 .Pp
 707 These
 708 .Xr ioctl 2
 709 routines use the following settings:
 710 .Pp
 711 .Bl -tag -width METEOR_CAP_CONTINOUS -compact
 712 .It Dv METEOR_CAP_SINGLE
 713 capture one frame
 714 .It Dv METEOR_CAP_CONTINOUS
 715 unsynchronized continuous capture
 716 .It Dv METEOR_CAP_STOP_CONT
 717 stop the unsynchronized continuous
 718 capture
 719 .El
 720 .Pp
 721 If
 722 .Dv METEORCAPTUR
 723 fails the
 724 .Xr ioctl 2
 725 will return a value of -1 and the
 726 external variable
 727 .Va errno
 728 will be set to:
 729 .Bl -tag -width Er
 730 .It Bq Er EINVAL
 731 invalid capture command value
 732 .It Bq Er ENXIO
 733 there is not internal buffer to hold the frame.
 734 This indicates the previous set geometry
 735 .Xr ioctl 2
 736 failed.
 737 .It Bq Er EIO
 738 card is already capturing.
 739 .El
 740 .It
 741 .Xr ioctl 2
 742 request
 743 .Dv METEORCAPFRM
 744 .Pp
 745 .Dv METEORCAPFRM
 746 is used for synchronous capture of multiple frames.
 747 .Pp
 748 This
 749 .Xr ioctl 2
 750 routine uses the
 751 .Va meteor_capture
 752 structure that has the
 753 following entries:
 754 .Bl -tag -width command
 755 .It Va command
 756 possible values for
 757 .Va command
 758 are:
 759 .Bl -tag -width METEOR_CAP_STOP_FRAMES
 760 .It Dv METEOR_CAP_STOP_FRAMES
 761 stop the capture; does not use the
 762 other variable in structure.
 763 .It Dv METEOR_CAP_N_FRAMES
 764 start the capture using the other
 765 variables in the structure as inputs
 766 .El
 767 .It Va signal
 768 signal to send to application when a new
 769 frame has been captured.
 770 This signal will
 771 only be raised if the captured frame is saved.
 772 .It Va lowat
 773 see below
 774 .It Va hiwat
 775 see below
 776 .El
 777 .Pp
 778 When a new frame is completed, the driver checks the current unread
 779 frame count stored in shared variable (the shared variable is stored
 780 in the
 781 .Va meteor_mem
 782 structure)
 783 .Va num_active_buf ;
 784 if the count is larger
 785 than
 786 .Va hiwat ,
 787 the driver will not store any new frames and will not
 788 send capture signal to the user application until the
 789 .Va num_active_buf
 790 is lower than
 791 .Va lowat .
 792 .Pp
 793 If
 794 .Dv METEORCAPFRM
 795 fails the
 796 .Xr ioctl 2
 797 will return a value of -1 and the
 798 external variable
 799 .Va errno
 800 will be set to:
 801 .Bl -tag -width Er
 802 .It Bq Er EINVAL
 803 invalid meteor_geomet structure pointer or bad command.
 804 .It Bq Er ENXIO
 805 there is not internal buffer to hold the frame.
 806 This indicates the previous set geometry
 807 .Xr ioctl 2
 808 failed.
 809 .It Bq Er EIO
 810 card is already capturing.
 811 .El
 812 .It
 813 .Xr ioctl 2
 814 requests
 815 .Dv METEORSCHCV
 816 and
 817 .Dv METEORGCHCV
 818 .Pp
 819 .Dv METEORSCHCV
 820 and
 821 .Dv METEORGCHCV
 822 are used to set and get the chrominance
 823 gain control and effects the UV output amplitude.
 824 .Pp
 825 If
 826 .Dv METEORSCHCV
 827 or
 828 .Dv METEORGCHCV
 829 fails the
 830 .Xr ioctl 2
 831 will return a value
 832 of -1 and the external variable
 833 .Va errno
 834 will be set to:
 835 .Bl -tag -width Er
 836 .It Bq Er EINVAL
 837 invalid unsigned char pointer.
 838 .El
 839 .It
 840 .Xr ioctl 2
 841 requests
 842 .Dv METEORGHUE
 843 and
 844 .Dv METEORSHUE
 845 .Pp
 846 .Dv METEORGHUE
 847 and
 848 .Dv METEORSHUE
 849 are used to get and set the hue.
 850 The
 851 signed character has legal values are from +127 which represent
 852 +178.6 degrees to -128 which represents -180 degrees.
 853 .Pp
 854 If
 855 .Dv METEORGHUE
 856 or
 857 .Dv METEORSHUE
 858 fails the
 859 .Xr ioctl 2
 860 will return a value of
 861 -1 and the external variable
 862 .Va errno
 863 will be set to:
 864 .Bl -tag -width Er
 865 .It Bq Er EINVAL
 866 invalid signed char pointer.
 867 .El
 868 .It
 869 .Xr ioctl 2
 870 requests
 871 .Dv METEORSCOUNT
 872 and
 873 .Dv METEORGCOUNT
 874 .Pp
 875 .Dv METEORGCOUNT
 876 is used to get the count of frame errors, DMA errors and
 877 count of the number of frames captured that have occurred since
 878 the device was opened.
 879 .Dv METEORSCOUNT
 880 can be used to reinitialize the
 881 counters.
 882 .Pp
 883 This
 884 .Xr ioctl 2
 885 routines use the
 886 .Va meteor_counts
 887 structure that has the
 888 following entries:
 889 .Bl -tag -width frame_count
 890 .It Va fifo_errors
 891 number of FIFO errors since device was opened.
 892 .It Va dma_errors
 893 number of DMA errors since device was opened.
 894 .It Va frame_count
 895 number of frames captured since device was opened.
 896 .El
 897 .Pp
 898 If
 899 .Dv METEORSCOUNT
 900 or
 901 .Dv METEORGCOUNT
 902 fails the
 903 .Xr ioctl 2
 904 will return a value
 905 of -1 and the external variable
 906 .Va errno
 907 will be set to:
 908 .Bl -tag -width Er
 909 .It Bq Er EINVAL
 910 invalid meteor_counts structure pointer.
 911 .El
 912 .El
 913 .Sh AUTHORS
 914 .An Jim Lowe Aq james@miller.cs.uwm.edu ,
 915 .An Mark Tinguely Aq tinguely@plains.nodak.edu
 916 .Sh BUGS
 917 .Bl -enum
 918 .It
 919 IIC register is difficult to set.
 920 We got around that by adding a long
 921 wait at each IIC register write.
 922 .It
 923 We had difficulties getting the
 924 .Tn Meteor
 925 capture card to work on systems
 926 that used NCR chipset SCSI cards.
 927 It is possible that the
 928 .Tn Meteor
 929 and
 930 .Tn "NCR SCSI"
 931 could work together using the newer TRITON motherboards.
 932 .El