share/man/man4/meteor.4

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