2 .\" $FreeBSD: src/share/man/man4/man4.i386/meteor.4,v 1.10.2.4 2001/08/17 13:08:45 ru Exp $
3 .\" $DragonFly: src/share/man/man4/man4.i386/meteor.4,v 1.8 2006/10/23 07:45:47 swildner Exp $
10 .Nd "video capture driver"
16 driver provides support for a PCI
19 It allows the capture of 24 bit RGB, 16 bit RGB and 16 bit YUV
21 .Ss Meteor Driver Configuration
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.
30 In the configuration file, add the line:
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
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.
44 contiguously re-allocating new pages are very small.
46 behavior is to not deallocate pages.
47 .It Cd "options ""METEOR_DEALLOC_ABOVE=xxx"""
48 Deallocate all pages above the specified number.
50 to not deallocate above any pages.
53 Make and install the kernel.
55 Make the special file name:
57 .Dl "# cd /dev; ./MAKEDEV meteor0"
59 The major number is determined by the placement of the device in
61 The patch supplied with the driver will make the major number 67.
63 .Ss Meteor Capture Modes
66 capture driver has three modes of capture operation.
73 This mode is the easiest and slowest to use.
74 This mode is great for
75 capturing a single field at little programming cost.
77 In this mode, the user opens the device, sets the capture mode
84 call to load the data into a buffer.
87 read 400x300 RGB24 into a viewable PPM file
89 #include <sys/fcntl.h>
90 #include <machine/ioctl_meteor.h>
95 #define SIZE (ROWS * COLS * 4)
98 struct meteor_geomet geo;
99 char buf[SIZE],b[4],header[16],*p;
102 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
103 printf("open failed: %d\\n", errno);
106 /* set up the capture type and size */
110 geo.oformat = METEOR_GEO_RGB24 ;
112 if (ioctl(i, METEORSETGEO, &geo) < 0) {
113 printf("ioctl failed: %d\\n", errno);
119 if (ioctl(i, METEORSFMT, &c) < 0) {
120 printf("ioctl failed: %d\\n", errno);
124 c = METEOR_INPUT_DEV0;
126 if (ioctl(i, METEORSINPUT, &c) < 0) {
127 printf("ioctl failed: %d\\n", errno);
131 if ((c=read(i, &buf[0], SIZE)) < SIZE) {
132 printf("read failed %d %d %d\\n", c, i, errno);
138 if ((o = open("rgb24.ppm", O_WRONLY | O_CREAT, 0644)) < 0) {
139 printf("ppm open failed: %d\\n", errno);
143 /* make PPM header and save to file */
144 strcpy(&header[0], "P6 400 300 255 ");
145 header[2] = header[6] = header[10] = header[14] = '\\n';
146 write (o, &header[0], 15);
147 /* save the RGB data to PPM file */
148 for (p = &buf[0]; p < &buf[SIZE]; ) {
149 b[2] = *p++; /* blue */
150 b[1] = *p++; /* green */
151 b[0] = *p++; /* red */
152 *p++; /* NULL byte */
153 write(o,&b[0], 3); /* not very efficient */
160 Memory mapped single capture or unsynchronized continuous capture.
162 The single capture mode is designed for conferencing tools such as
164 These tools need to control the starting of the image capture and also
165 need several frames a second.
166 The continuous capture mode is designed
167 for applications that want free-running data.
169 In this mode, the user opens the device, sets the capture mode
176 memory into the user process space, and issues either the
177 single-capture or the continuous capture call (see:
180 call) to load the data into the memory mapped buffer.
185 call, the single frame capture
187 will block until the capture is complete, the continuous capture
188 will return immediately.
190 .Pa meteor_mmap_single_continuous.c
192 #include <sys/types.h>
193 #include <sys/mman.h>
194 #include <sys/fcntl.h>
195 #include <machine/ioctl_meteor.h>
200 #define SIZE (ROWS * COLS * 2)
203 struct meteor_geomet geo;
208 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
209 printf("open failed\\n");
216 geo.oformat = METEOR_GEO_RGB16 ;
218 if (ioctl(i, METEORSETGEO, &geo) < 0) {
219 printf("ioctl failed: %d\\n", errno);
225 if (ioctl(i, METEORSFMT, &c) < 0) {
226 printf("ioctl failed: %d\\n", errno);
230 c = METEOR_INPUT_DEV0;
232 if (ioctl(i, METEORSINPUT, &c) < 0) {
233 printf("ioctl failed: %d\\n", errno);
237 mmbuf=(char *)mmap((caddr_t)0, SIZE, PROT_READ,
238 MAP_SHARED, i, (off_t)0);
241 /* single frame capture */
242 c = METEOR_CAP_SINGLE ;
243 ioctl(i, METEORCAPTUR, &c); /* wait for the frame */
245 /* directly access the frame buffer array data in mmbuf */
247 /* continuous frame capture */
248 c = METEOR_CAP_CONTINOUS ;
249 ioctl(i, METEORCAPTUR, &c); /* returns immediately */
251 /* directly access the frame buffer array data in mmbuf */
253 c = METEOR_CAP_STOP_CONT ;
254 ioctl(i, METEORCAPTUR, &c); /* close will also stop capture */
262 Memory mapped, multi-frame ring buffer synchronize capture.
264 This continuous capture mode is synchronized with the application that
265 processes up to 32 frames.
266 This gives the advantages of both single and
267 continuous capture modes.
269 The kernel notifies the application of a new data by raising an
270 application defined signal.
271 The driver also shares a structure with
272 the application that allows them to communicate which frame has been
273 written by the kernel and which frame has been read by the application.
275 The shared structure starts on the first page after your data.
277 structure address can be found by calculation:
279 .Dl "(number_rows * number_columns * pixel_depth + 4095) & 0xfffff000"
281 .Dl "((number_rows * number_columns * pixel_depth + 4095)/4096) * 4096"
283 The shared structure is of type
284 .Va struct meteor_mem .
286 important fields are called
291 is a bitmap of frames written by the kernel.
294 a count of frames marked in the
298 in by the driver, the
300 count is tested, if this
301 count is below the threshold of number of active frames (value
305 variable), the bit representing frame
306 number in the buffer is stored in the
310 is incremented, the kernel then raises the specified
311 signal to activate the user application.
312 The user application's
313 responsibility when getting the signal is to check the active bitmap
314 to determine the lowest active frame, use the data as the application
315 desires, clear the bitmap entry for that frame, and decrement the
316 .Va num_active_bufs .
317 If the threshold of number of active frames
319 has been exceeded, no new frames or signal from the kernel will occur
322 is less than or equal to
325 The driver loads the frames in a round-robin fashion.
327 that the user removes them in the same order.
329 check to see if the frame is already active.
333 and number of frames in the buffer are also provided
336 structure, but changing these fields in the
337 application will not change the operation of the driver.
339 In programming for this mode, the user opens the device, sets the
342 the data/common control structure, then starts the
343 continuous capture mode.
344 A special signal catcher is required to
345 process the frames as they are read by the kernel.
347 When specifying the geometry (see:
352 is important that the number of frames is set greater than 1.
354 .Pa skeleton_capture_n.c
356 #include <sys/types.h>
357 #include <sys/mman.h>
358 #include <sys/fcntl.h>
359 #include <sys/signal.h>
360 #include <machine/ioctl_meteor.h>
362 int video; /* made global if you wish to stop capture in signal handler */
364 struct meteor_mem *common_mem;
373 struct meteor_capframe capframe; /* for ioctl */
378 frame = (char *) (data_frames + sig_cnt * common_mem->frame_size) ;
380 /* add frame processing here */
381 /* deactivate frame */
382 common_mem->active &= ~(1 << (sig_cnt % 16));
383 common_mem->num_active_bufs--;
385 /* process next frame on next interrupt */
386 sig_cnt = ((sig_cnt+1) % FRAME_MAX);
389 if (some_condition_requiring_stopping) {
390 capframe.command=METEOR_CAP_STOP_FRAMES;
392 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
393 printf("METEORCAPFRM failed %d\\n", errno);
402 struct meteor_geomet geo;
403 int height, width, depth, frames, size;
404 struct meteor_capframe capframe;
406 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
407 printf("open failed\\n");
410 printf("test %d %d\\n", errno, i);
412 height = geo.rows = 120;
413 width= geo.columns = 320;
414 frames = geo.frames = FRAME_MAX;
415 depth = 2; /* 2 bytes per pixel for RGB*/
418 geo.oformat = METEOR_GEO_RGB16;
420 if (ioctl(i, METEORSETGEO, &geo) < 0) {
421 printf("METEORSETGEO failed %d\\n", errno);
427 if (ioctl(i, METEORSFMT, &c) < 0) {
428 printf("ioctl failed: %d\\n", errno);
432 c = METEOR_INPUT_DEV0;
434 if (ioctl(i, METEORSINPUT, &c) < 0) {
435 printf("ioctl failed: %d\\n", errno);
439 size = ((width*height*depth*frames+4095)/4096)*4096;
440 /* add one page after data for meteor_mem */
441 data_frames = mmap((caddr_t)0, size + 4096, PROT_READ | PROT_WRITE,
442 MAP_SHARED, i, (off_t)0);
444 if (data_frames == (caddr_t) MAP_FAILED) return (0);
446 /* common_mem is located at page following data */
447 common_mem = (struct meteor_mem *) (y + size);
449 signal(SIGUSR2, usr2_catcher); /* catch new frame message */
451 capframe.command=METEOR_CAP_N_FRAMES;
452 capframe.signal=SIGUSR2;
453 capframe.lowat=12; /* must be < hiwat */
454 capframe.hiwat=14; /* must be < FRAME_MAX */
456 /* start the sync capture */
457 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
458 printf("METEORCAPFRM failed %d\\n", errno);
462 /* this is the background working area, or you can sleep */
465 /* to stop capture */
466 capframe.command=METEOR_CAP_STOP_FRAMES;
468 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
469 printf("METEORCAPFRM failed %d\\n", errno);
475 .Ss Meteor IOCTL Call and Parameters
480 requests for capturing, reading card
481 status, for setting and reading the geometry, and for setting and reading the
485 IT IS VERY IMPORTANT TO CHECK FOR ERRORS ON THESE RETURNING IOCTLs.
487 Errors indicate that something is very wrong with the
490 application should not attempt to proceed further with capturing.
493 capture driver still makes attempts to stop the next capture step if
494 an error occurred in a previous step but was ignored by the application
507 are used to set and read the input
508 size, input device, and output format for frame capture.
514 structure that has the
517 .Bl -tag -width columns
519 number of rows (lines high) in output image
521 number of pixels in a row (width) in output image
523 number of frames in buffer.
524 Should be 1, unless using
525 the multi-framed synchronous capture mode
527 which REQUIRES frames to be larger than 1.
534 the existing values are used.
538 you may choose one of the following output format:
539 .Bl -tag -width METEOR_GEO_YUV_PACKED
540 .It Dv METEOR_GEO_RGB16
541 (RGB 16 bits xrrrrrgg gggbbbbb default)
542 .It Dv METEOR_GEO_RGB24
543 (RGB 24 bits packed in 32 bits:
544 00000000 rrrrrrrr gggggggg bbbbbbbb)
545 .It Dv METEOR_GEO_YUV_PACKED
546 (4-2-2 YUV 16 bits packed byte format:
547 u0 y0 v0 y1 u1 y2 v1 y3 ...)
548 .It Dv METEOR_GEO_YUV_PLANER
549 (4-2-2 YUV 16 bits planer format:
550 rows * columns bytes of y
551 rows * column / 4 bytes of even u
552 rows * column / 4 bytes of even v
553 rows * column / 4 bytes of odd u
554 rows * column / 4 bytes of odd v)
561 will fail if more than one entry from a category
563 It is highly recommended that a
566 before capturing data because you cannot guarantee the initial mode
571 will also attempt to reallocate a new contiguous
572 kernel buffer if the new geometry exceeds the old geometry.
574 other hand, if the new geometry will fit in the existing buffer,
575 the existing buffer is used.
581 will return a value of -1 and the
590 .Va rows , columns , frames
593 could not allocate the contiguous block.
605 are used to set and read the camera input
608 Possible formats are:
610 .Bl -tag -width METEOR_FMT_AUTOMODE -compact
611 .It Dv METEOR_FMT_NTSC
613 .It Dv METEOR_FMT_PAL
615 .It Dv METEOR_FMT_SECAM
617 .It Dv METEOR_FMT_AUTOMODE
630 are used to set and read the camera
632 Using the DB9 connector on the
635 devices can be connected and an input camera can be selected with this
638 Possible formats are:
640 .Bl -tag -width METEOR_INPUT_DEV_SVIDEO -compact
641 .It Dv METEOR_INPUT_DEV0
642 (default if none specified)
643 .It Dv METEOR_INPUT_DEV_RCA
644 (same as METEOR_INPUT_DEV0)
645 .It Dv METEOR_INPUT_DEV1
646 .It Dv METEOR_INPUT_DEV2
647 .It Dv METEOR_INPUT_DEV_SVIDEO
648 (same as METEOR_INPUT_DEV2)
656 is used to read the status of the
659 and returns the following information:
660 .Bl -column "METEOR_STATUS_ID_MASK" "\&"
661 .It Dv METEOR_STATUS_ID_MASK " 4 bit ID of the SAA7196 scaler chip."
663 .It Dv METEOR_STATUS_DIR " 0 = scaler uses internal source."
664 .It " 1 = scaler uses external data of expansion bus."
666 .It Dv METEOR_STATUS_OEF " 0 = even field detected."
667 .It " 1 = odd field detected."
669 .It Dv METEOR_STATUS_SVP " VRAM Port state:"
670 .It " 0 = inputs HFL and INCADDR inactive."
671 .It " 1 = inputs HFL and INCADDR active."
673 .It Dv METEOR_STATUS_STTC " 0 = TV horizontal time constant (slow)."
674 .It " 1 = VCR horizontal time constant (fast)."
676 .It Dv METEOR_STATUS_HCLK " 0 = Horizontal Phase Lock Loop locked."
677 .It " 1 = Horizontal Phase Lock Loop unlocked."
679 .It Dv METEOR_STATUS_FIDT " 0 = 50 Hz Field detected."
680 .It " 1 = 60 Hz Field detected."
682 .It Dv METEOR_STATUS_ALTD " 0 = no line alternating color burst detected."
683 .It " 1 = line alternating color burst detected (PAL/SECAM)."
685 .It Dv METEOR_STATUS_CODE " 0 = no color information detected."
686 .It " 1 = color information detected."
694 is used to single frame capture or unsynchronized
697 The single frame capture
699 request will return only after a
700 frame has been captured and transfered to the frame buffer.
702 The unsynchronized continuous capture will return immediately and
703 data is directly deposited into the buffer when it is available.
704 Since this is unsynchronized, it is possible the data is being
705 written by the kernel while being read by the application.
709 routines use the following settings:
711 .Bl -tag -width METEOR_CAP_CONTINOUS -compact
712 .It Dv METEOR_CAP_SINGLE
714 .It Dv METEOR_CAP_CONTINOUS
715 unsynchronized continuous capture
716 .It Dv METEOR_CAP_STOP_CONT
717 stop the unsynchronized continuous
725 will return a value of -1 and the
731 invalid capture command value
733 there is not internal buffer to hold the frame.
734 This indicates the previous set geometry
738 card is already capturing.
746 is used for synchronous capture of multiple frames.
752 structure that has the
754 .Bl -tag -width command
759 .Bl -tag -width METEOR_CAP_STOP_FRAMES
760 .It Dv METEOR_CAP_STOP_FRAMES
761 stop the capture; does not use the
762 other variable in structure.
763 .It Dv METEOR_CAP_N_FRAMES
764 start the capture using the other
765 variables in the structure as inputs
768 signal to send to application when a new
769 frame has been captured.
771 only be raised if the captured frame is saved.
778 When a new frame is completed, the driver checks the current unread
779 frame count stored in shared variable (the shared variable is stored
784 if the count is larger
787 the driver will not store any new frames and will not
788 send capture signal to the user application until the
797 will return a value of -1 and the
803 invalid meteor_geomet structure pointer or bad command.
805 there is not internal buffer to hold the frame.
806 This indicates the previous set geometry
810 card is already capturing.
822 are used to set and get the chrominance
823 gain control and effects the UV output amplitude.
832 of -1 and the external variable
837 invalid unsigned char pointer.
849 are used to get and set the hue.
851 signed character has legal values are from +127 which represent
852 +178.6 degrees to -128 which represents -180 degrees.
860 will return a value of
861 -1 and the external variable
866 invalid signed char pointer.
876 is used to get the count of frame errors, DMA errors and
877 count of the number of frames captured that have occurred since
878 the device was opened.
880 can be used to reinitialize the
887 structure that has the
889 .Bl -tag -width frame_count
891 number of FIFO errors since device was opened.
893 number of DMA errors since device was opened.
895 number of frames captured since device was opened.
905 of -1 and the external variable
910 invalid meteor_counts structure pointer.
914 .An Jim Lowe Aq james@miller.cs.uwm.edu ,
915 .An Mark Tinguely Aq tinguely@plains.nodak.edu
919 IIC register is difficult to set.
920 We got around that by adding a long
921 wait at each IIC register write.
923 We had difficulties getting the
925 capture card to work on systems
926 that used NCR chipset SCSI cards.
927 It is possible that the
931 could work together using the newer TRITON motherboards.