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