ref: 8237f8c583281e8575c7f67f4d044b43aef82920
parent: 00d06ac617f27e7e63f70612698a7ff5dc7a9a1a
author: qwx <qwx@sciops.net>
date: Sat Oct 1 23:30:43 EDT 2022
camv(1), nusb(4): add more details on camera operation
--- a/sys/man/1/camv
+++ b/sys/man/1/camv
@@ -1,16 +1,55 @@
.TH CAMV 1
.SH NAME
-camv, camera display
+camv \- USB camera display
.SH SYNOPSIS
-.B camv cam-device
+.B camv
+.I cam-device
.SH DESCRIPTION
.I Camv
-uses the underlying
+uses the
.I cam-device
-file system to start a graphical camera display stream.
+file tree provided by
+.IR nusb (4)
+to use and control a USB camera.
+It opens the tree's
+.I video
+file to play the video stream directly in the window.
.PP
-The file system is initialized using nusb/cam (see nusb(4)).
+The middle mouse button menu shows and allows editing the current picture settings.
+While it lists resolution, format and framerate per second,
+those must be set manually before starting
+.IR camv (1).
+One can quit the program from the right mouse button menu.
+.SH EXAMPLES
+Initialize and configure a camera before starting
+.I camv
+in its own window.
+.IP
+.EX
+% nusb/cam 5
+% window -dx 320 -dy 240 \\
+ 'label cam
+ cat <<EOF >/dev/cam5.1/ctl
+format 320x240
+fps 30
+backlight-compensation 1
+brightness 20
+contrast 95
+saturation 40
+sharpness 7
+gamma 200
+EOF
+ camv /dev/cam5.1
+\'
+.EE
.SH SOURCE
.B /sys/src/cmd/camv.c
-.SH SEE ALSO
+.SH "SEE ALSO"
.IR nusb (4)
+.SH HISTORY
+.I Camv
+first appeared in 9front (March, 2018).
+.SH BUGS
+Not all available picture settings can be set while
+.IR camv (1)
+is running, some possibly not at all.
--- a/sys/man/4/nusb
+++ b/sys/man/4/nusb
@@ -271,11 +271,34 @@
.IR audio (3).
.SS Camera devices
.I Cam
-configures and manages a USB camera device.
-It implements a file system (normally seen under
-.BR /dev ),
-compatible with
-.IR camv (1).
+configures and exposes a USB camera device's capabilities,
+implementing a file system compatible with
+.IR camv (1),
+under a directory named
+.BI cam N [. M ].
+It provides the following files:
+.BR desc ,
+showing all of the device's internal descriptors and their values;
+.BR format ,
+listing admissible image resolutions and framerates;
+.BR ctl ,
+the picture settings control file;
+.BR frame ,
+which captures and outputs a single video frame as an
+.IR image (6)
+file;
+and
+.IR video ,
+streaming video in a preset format, resolution and framerate.
+In particular, reading from the
+.B ctl
+file yields a space-separated list of parameter settings,
+where the second and third columns correspond to key-value pairs,
+and an optional fourth column corresponds to the range of possible numerical values
+(formatted as
+.IR minimum / increment / maximum ).
+The same pairs can be written to the file to configure the camera.
+Currently, only the YUY2 video format is supported.
.SH SOURCE
.B /sys/src/cmd/nusb
.SH "SEE ALSO"
@@ -288,11 +311,15 @@
.IR uart (3),
.IR usb (3),
.IR shr (3),
+.IR image (6),
.IR nusbrc (8),
.IR kbdfs (8)
.SH HISTORY
.I Joy
first appeared in 9front (March, 2014).
+.br
+.I Cam
+first appeared in 9front (March, 2018).
.SH BUGS
The various device drivers are generic USB drivers and
may work only for certain devices of each class.
@@ -307,3 +334,9 @@
signals and some of the extra features are not implemented.
For Ftdi, only the Sheevaplug and Guruplug have been tried.
There is support for the EHCI debug port, but it loses bytes.
+.PP
+USB video format settings cannot be changed while
+.IR camv (1)
+is running, and must be set manually by writing them to
+.IR cam (4)'s ctl
+file before starting the viewer.