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