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 $
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 .Ss Meteor Capture Modes
58 capture driver has three modes of capture operation.
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.
69 In this mode, the user opens the device, sets the capture mode
76 call to load the data into a buffer.
79 read 400x300 RGB24 into a viewable PPM file
81 #include <sys/fcntl.h>
82 #include <machine/ioctl_meteor.h>
87 #define SIZE (ROWS * COLS * 4)
90 struct meteor_geomet geo;
91 char buf[SIZE],b[4],header[16],*p;
94 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
95 printf("open failed: %d\\n", errno);
98 /* set up the capture type and size */
102 geo.oformat = METEOR_GEO_RGB24 ;
104 if (ioctl(i, METEORSETGEO, &geo) < 0) {
105 printf("ioctl failed: %d\\n", errno);
111 if (ioctl(i, METEORSFMT, &c) < 0) {
112 printf("ioctl failed: %d\\n", errno);
116 c = METEOR_INPUT_DEV0;
118 if (ioctl(i, METEORSINPUT, &c) < 0) {
119 printf("ioctl failed: %d\\n", errno);
123 if ((c=read(i, &buf[0], SIZE)) < SIZE) {
124 printf("read failed %d %d %d\\n", c, i, errno);
130 if ((o = open("rgb24.ppm", O_WRONLY | O_CREAT, 0644)) < 0) {
131 printf("ppm open failed: %d\\n", errno);
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 */
152 Memory mapped single capture or unsynchronized continuous capture.
154 The single capture mode is designed for conferencing tools such as
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.
161 In this mode, the user opens the device, sets the capture mode
168 memory into the user process space, and issues either the
169 single-capture or the continuous capture call (see:
172 call) to load the data into the memory mapped buffer.
177 call, the single frame capture
179 will block until the capture is complete, the continuous capture
180 will return immediately.
182 .Pa meteor_mmap_single_continuous.c
184 #include <sys/types.h>
185 #include <sys/mman.h>
186 #include <sys/fcntl.h>
187 #include <machine/ioctl_meteor.h>
192 #define SIZE (ROWS * COLS * 2)
195 struct meteor_geomet geo;
200 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
201 printf("open failed\\n");
208 geo.oformat = METEOR_GEO_RGB16 ;
210 if (ioctl(i, METEORSETGEO, &geo) < 0) {
211 printf("ioctl failed: %d\\n", errno);
217 if (ioctl(i, METEORSFMT, &c) < 0) {
218 printf("ioctl failed: %d\\n", errno);
222 c = METEOR_INPUT_DEV0;
224 if (ioctl(i, METEORSINPUT, &c) < 0) {
225 printf("ioctl failed: %d\\n", errno);
229 mmbuf=(char *)mmap((caddr_t)0, SIZE, PROT_READ,
230 MAP_SHARED, i, (off_t)0);
233 /* single frame capture */
234 c = METEOR_CAP_SINGLE ;
235 ioctl(i, METEORCAPTUR, &c); /* wait for the frame */
237 /* directly access the frame buffer array data in mmbuf */
239 /* continuous frame capture */
240 c = METEOR_CAP_CONTINOUS ;
241 ioctl(i, METEORCAPTUR, &c); /* returns immediately */
243 /* directly access the frame buffer array data in mmbuf */
245 c = METEOR_CAP_STOP_CONT ;
246 ioctl(i, METEORCAPTUR, &c); /* close will also stop capture */
254 Memory mapped, multi-frame ring buffer synchronize capture.
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.
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.
267 The shared structure starts on the first page after your data.
269 structure address can be found by calculation:
271 .Dl "(number_rows * number_columns * pixel_depth + 4095) & 0xfffff000"
273 .Dl "((number_rows * number_columns * pixel_depth + 4095)/4096) * 4096"
275 The shared structure is of type
276 .Va struct meteor_mem .
278 important fields are called
283 is a bitmap of frames written by the kernel.
286 a count of frames marked in the
290 in by the driver, the
292 count is tested, if this
293 count is below the threshold of number of active frames (value
297 variable), the bit representing frame
298 number in the buffer is stored in the
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
311 has been exceeded, no new frames or signal from the kernel will occur
314 is less than or equal to
317 The driver loads the frames in a round-robin fashion.
319 that the user removes them in the same order.
321 check to see if the frame is already active.
325 and number of frames in the buffer are also provided
328 structure, but changing these fields in the
329 application will not change the operation of the driver.
331 In programming for this mode, the user opens the device, sets the
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.
339 When specifying the geometry (see:
344 is important that the number of frames is set greater than 1.
346 .Pa skeleton_capture_n.c
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>
354 int video; /* made global if you wish to stop capture in signal handler */
356 struct meteor_mem *common_mem;
365 struct meteor_capframe capframe; /* for ioctl */
370 frame = (char *) (data_frames + sig_cnt * common_mem->frame_size) ;
372 /* add frame processing here */
373 /* deactivate frame */
374 common_mem->active &= ~(1 << (sig_cnt % 16));
375 common_mem->num_active_bufs--;
377 /* process next frame on next interrupt */
378 sig_cnt = ((sig_cnt+1) % FRAME_MAX);
381 if (some_condition_requiring_stopping) {
382 capframe.command=METEOR_CAP_STOP_FRAMES;
384 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
385 printf("METEORCAPFRM failed %d\\n", errno);
394 struct meteor_geomet geo;
395 int height, width, depth, frames, size;
396 struct meteor_capframe capframe;
398 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
399 printf("open failed\\n");
402 printf("test %d %d\\n", errno, i);
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*/
410 geo.oformat = METEOR_GEO_RGB16;
412 if (ioctl(i, METEORSETGEO, &geo) < 0) {
413 printf("METEORSETGEO failed %d\\n", errno);
419 if (ioctl(i, METEORSFMT, &c) < 0) {
420 printf("ioctl failed: %d\\n", errno);
424 c = METEOR_INPUT_DEV0;
426 if (ioctl(i, METEORSINPUT, &c) < 0) {
427 printf("ioctl failed: %d\\n", errno);
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);
436 if (data_frames == (caddr_t) MAP_FAILED) return (0);
438 /* common_mem is located at page following data */
439 common_mem = (struct meteor_mem *) (y + size);
441 signal(SIGUSR2, usr2_catcher); /* catch new frame message */
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 */
448 /* start the sync capture */
449 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
450 printf("METEORCAPFRM failed %d\\n", errno);
454 /* this is the background working area, or you can sleep */
457 /* to stop capture */
458 capframe.command=METEOR_CAP_STOP_FRAMES;
460 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
461 printf("METEORCAPFRM failed %d\\n", errno);
467 .Ss Meteor IOCTL Call and Parameters
472 requests for capturing, reading card
473 status, for setting and reading the geometry, and for setting and reading the
477 IT IS VERY IMPORTANT TO CHECK FOR ERRORS ON THESE RETURNING IOCTLs.
479 Errors indicate that something is very wrong with the
482 application should not attempt to proceed further with capturing.
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
499 are used to set and read the input
500 size, input device, and output format for frame capture.
506 structure that has the
508 .Bl -tag -width columns
510 number of rows (lines high) in output image
512 number of pixels in a row (width) in output image
514 number of frames in buffer.
515 Should be 1, unless using
516 the multi-framed synchronous capture mode
518 which REQUIRES frames to be larger than 1.
525 the existing values are used.
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)
552 will fail if more than one entry from a category
554 It is highly recommended that a
557 before capturing data because you cannot guarantee the initial mode
562 will also attempt to reallocate a new contiguous
563 kernel buffer if the new geometry exceeds the old geometry.
565 other hand, if the new geometry will fit in the existing buffer,
566 the existing buffer is used.
572 will return a value of -1 and the
581 .Va rows , columns , frames
584 could not allocate the contiguous block.
596 are used to set and read the camera input
599 Possible formats are:
601 .Bl -tag -width METEOR_FMT_AUTOMODE -compact
602 .It Dv METEOR_FMT_NTSC
604 .It Dv METEOR_FMT_PAL
606 .It Dv METEOR_FMT_SECAM
608 .It Dv METEOR_FMT_AUTOMODE
621 are used to set and read the camera
623 Using the DB9 connector on the
626 devices can be connected and an input camera can be selected with this
629 Possible formats are:
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)
647 is used to read the status of the
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."
654 .It Dv METEOR_STATUS_DIR " 0 = scaler uses internal source."
655 .It " 1 = scaler uses external data of expansion bus."
657 .It Dv METEOR_STATUS_OEF " 0 = even field detected."
658 .It " 1 = odd field detected."
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."
664 .It Dv METEOR_STATUS_STTC " 0 = TV horizontal time constant (slow)."
665 .It " 1 = VCR horizontal time constant (fast)."
667 .It Dv METEOR_STATUS_HCLK " 0 = Horizontal Phase Lock Loop locked."
668 .It " 1 = Horizontal Phase Lock Loop unlocked."
670 .It Dv METEOR_STATUS_FIDT " 0 = 50 Hz Field detected."
671 .It " 1 = 60 Hz Field detected."
673 .It Dv METEOR_STATUS_ALTD " 0 = no line alternating color burst detected."
674 .It " 1 = line alternating color burst detected (PAL/SECAM)."
676 .It Dv METEOR_STATUS_CODE " 0 = no color information detected."
677 .It " 1 = color information detected."
685 is used to single frame capture or unsynchronized
688 The single frame capture
690 request will return only after a
691 frame has been captured and transferred to the frame buffer.
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.
700 routines use the following settings:
702 .Bl -tag -width METEOR_CAP_CONTINOUS -compact
703 .It Dv METEOR_CAP_SINGLE
705 .It Dv METEOR_CAP_CONTINOUS
706 unsynchronized continuous capture
707 .It Dv METEOR_CAP_STOP_CONT
708 stop the unsynchronized continuous
716 will return a value of -1 and the
722 invalid capture command value
724 there is not internal buffer to hold the frame.
725 This indicates the previous set geometry
729 card is already capturing.
737 is used for synchronous capture of multiple frames.
743 structure that has the
745 .Bl -tag -width command
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
759 signal to send to application when a new
760 frame has been captured.
762 only be raised if the captured frame is saved.
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
775 if the count is larger
778 the driver will not store any new frames and will not
779 send capture signal to the user application until the
788 will return a value of -1 and the
794 invalid meteor_geomet structure pointer or bad command.
796 there is not internal buffer to hold the frame.
797 This indicates the previous set geometry
801 card is already capturing.
813 are used to set and get the chrominance
814 gain control and affects the UV output amplitude.
823 of -1 and the external variable
828 invalid unsigned char pointer.
840 are used to get and set the hue.
842 signed character has legal values are from +127 which represent
843 +178.6 degrees to -128 which represents -180 degrees.
851 will return a value of
852 -1 and the external variable
857 invalid signed char pointer.
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.
871 can be used to reinitialize the
878 structure that has the
880 .Bl -tag -width frame_count
882 number of FIFO errors since device was opened.
884 number of DMA errors since device was opened.
886 number of frames captured since device was opened.
896 of -1 and the external variable
901 invalid meteor_counts structure pointer.
908 .An Jim Lowe Aq james@miller.cs.uwm.edu ,
909 .An Mark Tinguely Aq tinguely@plains.nodak.edu
913 IIC register is difficult to set.
914 We got around that by adding a long
915 wait at each IIC register write.
917 We had difficulties getting the
919 capture card to work on systems
920 that used NCR chipset SCSI cards.
921 It is possible that the
925 could work together using the newer TRITON motherboards.