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