9 .Nd "video capture driver interface"
13 driver defined a video capture interface.
16 driver is no longer in the tree, but other devices support this interface
17 so the interface portion is documented here.
18 .Ss Meteor Capture Modes
21 capture driver has three modes of capture operation.
28 This mode is the easiest and slowest to use.
29 This mode is great for
30 capturing a single field at little programming cost.
32 In this mode, the user opens the device, sets the capture mode
39 call to load the data into a buffer.
42 read 400x300 RGB24 into a viewable PPM file
44 #include <sys/fcntl.h>
45 #include <machine/ioctl_meteor.h>
50 #define SIZE (ROWS * COLS * 4)
53 struct meteor_geomet geo;
54 char buf[SIZE],b[4],header[16],*p;
57 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
58 printf("open failed: %d\\n", errno);
61 /* set up the capture type and size */
65 geo.oformat = METEOR_GEO_RGB24 ;
67 if (ioctl(i, METEORSETGEO, &geo) < 0) {
68 printf("ioctl failed: %d\\n", errno);
74 if (ioctl(i, METEORSFMT, &c) < 0) {
75 printf("ioctl failed: %d\\n", errno);
79 c = METEOR_INPUT_DEV0;
81 if (ioctl(i, METEORSINPUT, &c) < 0) {
82 printf("ioctl failed: %d\\n", errno);
86 if ((c=read(i, &buf[0], SIZE)) < SIZE) {
87 printf("read failed %d %d %d\\n", c, i, errno);
93 if ((o = open("rgb24.ppm", O_WRONLY | O_CREAT, 0644)) < 0) {
94 printf("ppm open failed: %d\\n", errno);
98 /* make PPM header and save to file */
99 strcpy(&header[0], "P6 400 300 255 ");
100 header[2] = header[6] = header[10] = header[14] = '\\n';
101 write (o, &header[0], 15);
102 /* save the RGB data to PPM file */
103 for (p = &buf[0]; p < &buf[SIZE]; ) {
104 b[2] = *p++; /* blue */
105 b[1] = *p++; /* green */
106 b[0] = *p++; /* red */
107 *p++; /* NULL byte */
108 write(o,&b[0], 3); /* not very efficient */
115 Memory mapped single capture or unsynchronized continuous capture.
117 The single capture mode is designed for conferencing tools such as
119 These tools need to control the starting of the image capture and also
120 need several frames a second.
121 The continuous capture mode is designed
122 for applications that want free-running data.
124 In this mode, the user opens the device, sets the capture mode
131 memory into the user process space, and issues either the
132 single-capture or the continuous capture call (see:
135 call) to load the data into the memory mapped buffer.
140 call, the single frame capture
142 will block until the capture is complete, the continuous capture
143 will return immediately.
145 .Pa meteor_mmap_single_continuous.c
147 #include <sys/types.h>
148 #include <sys/mman.h>
149 #include <sys/fcntl.h>
150 #include <machine/ioctl_meteor.h>
155 #define SIZE (ROWS * COLS * 2)
158 struct meteor_geomet geo;
163 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
164 printf("open failed\\n");
171 geo.oformat = METEOR_GEO_RGB16 ;
173 if (ioctl(i, METEORSETGEO, &geo) < 0) {
174 printf("ioctl failed: %d\\n", errno);
180 if (ioctl(i, METEORSFMT, &c) < 0) {
181 printf("ioctl failed: %d\\n", errno);
185 c = METEOR_INPUT_DEV0;
187 if (ioctl(i, METEORSINPUT, &c) < 0) {
188 printf("ioctl failed: %d\\n", errno);
192 mmbuf=(char *)mmap((caddr_t)0, SIZE, PROT_READ,
193 MAP_SHARED, i, (off_t)0);
196 /* single frame capture */
197 c = METEOR_CAP_SINGLE ;
198 ioctl(i, METEORCAPTUR, &c); /* wait for the frame */
200 /* directly access the frame buffer array data in mmbuf */
202 /* continuous frame capture */
203 c = METEOR_CAP_CONTINOUS ;
204 ioctl(i, METEORCAPTUR, &c); /* returns immediately */
206 /* directly access the frame buffer array data in mmbuf */
208 c = METEOR_CAP_STOP_CONT ;
209 ioctl(i, METEORCAPTUR, &c); /* close will also stop capture */
217 Memory mapped, multi-frame ring buffer synchronize capture.
219 This continuous capture mode is synchronized with the application that
220 processes up to 32 frames.
221 This gives the advantages of both single and
222 continuous capture modes.
224 The kernel notifies the application of a new data by raising an
225 application defined signal.
226 The driver also shares a structure with
227 the application that allows them to communicate which frame has been
228 written by the kernel and which frame has been read by the application.
230 The shared structure starts on the first page after your data.
232 structure address can be found by calculation:
234 .Dl "(number_rows * number_columns * pixel_depth + 4095) & 0xfffff000"
236 .Dl "((number_rows * number_columns * pixel_depth + 4095)/4096) * 4096"
238 The shared structure is of type
239 .Va struct meteor_mem .
241 important fields are called
246 is a bitmap of frames written by the kernel.
249 a count of frames marked in the
253 in by the driver, the
255 count is tested, if this
256 count is below the threshold of number of active frames (value
260 variable), the bit representing frame
261 number in the buffer is stored in the
265 is incremented, the kernel then raises the specified
266 signal to activate the user application.
267 The user application's
268 responsibility when getting the signal is to check the active bitmap
269 to determine the lowest active frame, use the data as the application
270 desires, clear the bitmap entry for that frame, and decrement the
271 .Va num_active_bufs .
272 If the threshold of number of active frames
274 has been exceeded, no new frames or signal from the kernel will occur
277 is less than or equal to
280 The driver loads the frames in a round-robin fashion.
282 that the user removes them in the same order.
284 check to see if the frame is already active.
288 and number of frames in the buffer are also provided
291 structure, but changing these fields in the
292 application will not change the operation of the driver.
294 In programming for this mode, the user opens the device, sets the
297 the data/common control structure, then starts the
298 continuous capture mode.
299 A special signal catcher is required to
300 process the frames as they are read by the kernel.
302 When specifying the geometry (see:
307 is important that the number of frames is set greater than 1.
309 .Pa skeleton_capture_n.c
311 #include <sys/types.h>
312 #include <sys/mman.h>
313 #include <sys/fcntl.h>
314 #include <sys/signal.h>
315 #include <machine/ioctl_meteor.h>
317 int video; /* made global if you wish to stop capture in signal handler */
319 struct meteor_mem *common_mem;
328 struct meteor_capframe capframe; /* for ioctl */
333 frame = (char *) (data_frames + sig_cnt * common_mem->frame_size) ;
335 /* add frame processing here */
336 /* deactivate frame */
337 common_mem->active &= ~(1 << (sig_cnt % 16));
338 common_mem->num_active_bufs--;
340 /* process next frame on next interrupt */
341 sig_cnt = ((sig_cnt+1) % FRAME_MAX);
344 if (some_condition_requiring_stopping) {
345 capframe.command=METEOR_CAP_STOP_FRAMES;
347 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
348 printf("METEORCAPFRM failed %d\\n", errno);
357 struct meteor_geomet geo;
358 int height, width, depth, frames, size;
359 struct meteor_capframe capframe;
361 if ((i = open("/dev/meteor0", O_RDONLY)) < 0) {
362 printf("open failed\\n");
365 printf("test %d %d\\n", errno, i);
367 height = geo.rows = 120;
368 width= geo.columns = 320;
369 frames = geo.frames = FRAME_MAX;
370 depth = 2; /* 2 bytes per pixel for RGB*/
373 geo.oformat = METEOR_GEO_RGB16;
375 if (ioctl(i, METEORSETGEO, &geo) < 0) {
376 printf("METEORSETGEO failed %d\\n", errno);
382 if (ioctl(i, METEORSFMT, &c) < 0) {
383 printf("ioctl failed: %d\\n", errno);
387 c = METEOR_INPUT_DEV0;
389 if (ioctl(i, METEORSINPUT, &c) < 0) {
390 printf("ioctl failed: %d\\n", errno);
394 size = ((width*height*depth*frames+4095)/4096)*4096;
395 /* add one page after data for meteor_mem */
396 data_frames = mmap((caddr_t)0, size + 4096, PROT_READ | PROT_WRITE,
397 MAP_SHARED, i, (off_t)0);
399 if (data_frames == (caddr_t) MAP_FAILED) return (0);
401 /* common_mem is located at page following data */
402 common_mem = (struct meteor_mem *) (y + size);
404 signal(SIGUSR2, usr2_catcher); /* catch new frame message */
406 capframe.command=METEOR_CAP_N_FRAMES;
407 capframe.signal=SIGUSR2;
408 capframe.lowat=12; /* must be < hiwat */
409 capframe.hiwat=14; /* must be < FRAME_MAX */
411 /* start the sync capture */
412 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
413 printf("METEORCAPFRM failed %d\\n", errno);
417 /* this is the background working area, or you can sleep */
420 /* to stop capture */
421 capframe.command=METEOR_CAP_STOP_FRAMES;
423 if (ioctl(i, METEORCAPFRM, &capframe) < 0) {
424 printf("METEORCAPFRM failed %d\\n", errno);
430 .Ss Meteor IOCTL Call and Parameters
435 requests for capturing, reading card
436 status, for setting and reading the geometry, and for setting and reading the
440 IT IS VERY IMPORTANT TO CHECK FOR ERRORS ON THESE RETURNING IOCTLs.
442 Errors indicate that something is very wrong with the
445 application should not attempt to proceed further with capturing.
448 capture driver still makes attempts to stop the next capture step if
449 an error occurred in a previous step but was ignored by the application
462 are used to set and read the input
463 size, input device, and output format for frame capture.
469 structure that has the
471 .Bl -tag -width columns
473 number of rows (lines high) in output image
475 number of pixels in a row (width) in output image
477 number of frames in buffer.
478 Should be 1, unless using
479 the multi-framed synchronous capture mode
481 which REQUIRES frames to be larger than 1.
488 the existing values are used.
492 you may choose one of the following output format:
493 .Bl -tag -width METEOR_GEO_YUV_PACKED
494 .It Dv METEOR_GEO_RGB16
495 (RGB 16 bits xrrrrrgg gggbbbbb default)
496 .It Dv METEOR_GEO_RGB24
497 (RGB 24 bits packed in 32 bits:
498 00000000 rrrrrrrr gggggggg bbbbbbbb)
499 .It Dv METEOR_GEO_YUV_PACKED
500 (4-2-2 YUV 16 bits packed byte format:
501 u0 y0 v0 y1 u1 y2 v1 y3 ...)
502 .It Dv METEOR_GEO_YUV_PLANER
503 (4-2-2 YUV 16 bits planer format:
504 rows * columns bytes of y
505 rows * column / 4 bytes of even u
506 rows * column / 4 bytes of even v
507 rows * column / 4 bytes of odd u
508 rows * column / 4 bytes of odd v)
515 will fail if more than one entry from a category
517 It is highly recommended that a
520 before capturing data because you cannot guarantee the initial mode
525 will also attempt to reallocate a new contiguous
526 kernel buffer if the new geometry exceeds the old geometry.
528 other hand, if the new geometry will fit in the existing buffer,
529 the existing buffer is used.
535 will return a value of -1 and the
544 .Va rows , columns , frames
547 could not allocate the contiguous block.
559 are used to set and read the camera input
562 Possible formats are:
564 .Bl -tag -width METEOR_FMT_AUTOMODE -compact
565 .It Dv METEOR_FMT_NTSC
567 .It Dv METEOR_FMT_PAL
569 .It Dv METEOR_FMT_SECAM
571 .It Dv METEOR_FMT_AUTOMODE
584 are used to set and read the camera
586 Using the DB9 connector on the
589 devices can be connected and an input camera can be selected with this
592 Possible formats are:
594 .Bl -tag -width METEOR_INPUT_DEV_SVIDEO -compact
595 .It Dv METEOR_INPUT_DEV0
596 (default if none specified)
597 .It Dv METEOR_INPUT_DEV_RCA
598 (same as METEOR_INPUT_DEV0)
599 .It Dv METEOR_INPUT_DEV1
600 .It Dv METEOR_INPUT_DEV2
601 .It Dv METEOR_INPUT_DEV_SVIDEO
602 (same as METEOR_INPUT_DEV2)
610 is used to read the status of the
613 and returns the following information:
614 .Bl -column "METEOR_STATUS_ID_MASK" "\&"
615 .It Dv METEOR_STATUS_ID_MASK " 4 bit ID of the SAA7196 scaler chip."
617 .It Dv METEOR_STATUS_DIR " 0 = scaler uses internal source."
618 .It " 1 = scaler uses external data of expansion bus."
620 .It Dv METEOR_STATUS_OEF " 0 = even field detected."
621 .It " 1 = odd field detected."
623 .It Dv METEOR_STATUS_SVP " VRAM Port state:"
624 .It " 0 = inputs HFL and INCADDR inactive."
625 .It " 1 = inputs HFL and INCADDR active."
627 .It Dv METEOR_STATUS_STTC " 0 = TV horizontal time constant (slow)."
628 .It " 1 = VCR horizontal time constant (fast)."
630 .It Dv METEOR_STATUS_HCLK " 0 = Horizontal Phase Lock Loop locked."
631 .It " 1 = Horizontal Phase Lock Loop unlocked."
633 .It Dv METEOR_STATUS_FIDT " 0 = 50 Hz Field detected."
634 .It " 1 = 60 Hz Field detected."
636 .It Dv METEOR_STATUS_ALTD " 0 = no line alternating color burst detected."
637 .It " 1 = line alternating color burst detected (PAL/SECAM)."
639 .It Dv METEOR_STATUS_CODE " 0 = no color information detected."
640 .It " 1 = color information detected."
648 is used to single frame capture or unsynchronized
651 The single frame capture
653 request will return only after a
654 frame has been captured and transferred to the frame buffer.
656 The unsynchronized continuous capture will return immediately and
657 data is directly deposited into the buffer when it is available.
658 Since this is unsynchronized, it is possible the data is being
659 written by the kernel while being read by the application.
663 routines use the following settings:
665 .Bl -tag -width METEOR_CAP_CONTINOUS -compact
666 .It Dv METEOR_CAP_SINGLE
668 .It Dv METEOR_CAP_CONTINOUS
669 unsynchronized continuous capture
670 .It Dv METEOR_CAP_STOP_CONT
671 stop the unsynchronized continuous
679 will return a value of -1 and the
685 invalid capture command value
687 there is not internal buffer to hold the frame.
688 This indicates the previous set geometry
692 card is already capturing.
700 is used for synchronous capture of multiple frames.
706 structure that has the
708 .Bl -tag -width command
713 .Bl -tag -width METEOR_CAP_STOP_FRAMES
714 .It Dv METEOR_CAP_STOP_FRAMES
715 stop the capture; does not use the
716 other variable in structure.
717 .It Dv METEOR_CAP_N_FRAMES
718 start the capture using the other
719 variables in the structure as inputs
722 signal to send to application when a new
723 frame has been captured.
725 only be raised if the captured frame is saved.
732 When a new frame is completed, the driver checks the current unread
733 frame count stored in shared variable (the shared variable is stored
738 if the count is larger
741 the driver will not store any new frames and will not
742 send capture signal to the user application until the
751 will return a value of -1 and the
757 invalid meteor_geomet structure pointer or bad command.
759 there is not internal buffer to hold the frame.
760 This indicates the previous set geometry
764 card is already capturing.
776 are used to set and get the chrominance
777 gain control and effects the UV output amplitude.
786 of -1 and the external variable
791 invalid unsigned char pointer.
803 are used to get and set the hue.
805 signed character has legal values are from +127 which represent
806 +178.6 degrees to -128 which represents -180 degrees.
814 will return a value of
815 -1 and the external variable
820 invalid signed char pointer.
830 is used to get the count of frame errors, DMA errors and
831 count of the number of frames captured that have occurred since
832 the device was opened.
834 can be used to reinitialize the
841 structure that has the
843 .Bl -tag -width frame_count
845 number of FIFO errors since device was opened.
847 number of DMA errors since device was opened.
849 number of frames captured since device was opened.
859 of -1 and the external variable
864 invalid meteor_counts structure pointer.
868 .An Jim Lowe Aq james@miller.cs.uwm.edu ,
869 .An Mark Tinguely Aq tinguely@plains.nodak.edu
873 driver no longer works at all.