camv(1), nusb(4): add more details on camera operation

2 files changed, 83 insertions, 11 deletions

diff --git a/sys/man/1/camv b/sys/man/1/camv
index 3587d712b..ec6ab4eba 100644
--- 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.
diff --git a/sys/man/4/nusb b/sys/man/4/nusb
index 72ba89cd3..4453cbc6a 100644
--- a/sys/man/4/nusb
+++ b/sys/man/4/nusb
@@ -271,11 +271,34 @@ compatible with
 .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 @@ compatible with
 .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 @@ and
 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.