Additional documentation and corrections

examples/README.md

@@ -10,12 +10,12 @@
 * [simplecam](./simplecam/) A functional webcam program that streams video to web page.
 * [webcam](./webcam) - Builds on simplecam and adds image control, format control, and face detection.
 
-## Building your code
+## Building the example code
 
-There are three ways to build the example.
+There are three ways to build the code in the example directories.
 
-### On device builds
-One of the easiest ways to get started is to setup your Linux workstation, or device, with Go to build your source code directly there.
+### On-device build
+One of the easiest ways to get started is to setup your Linux workstation (with camera attached), or device (such as Raspberry Pi), with Go to build your source code directly there.
 
 Install the `build-essential` package to install required C compilers:
 ```shell
@@ -29,15 +29,18 @@ sudo apt full-upgrade
 ```
 
 ### Cross-compile with Zig toolchain
-The Zig language comes with a full C/C++ cross-compiler including flag compatibility with gcc and clang. It can be used as a drop-in replacement for those compilers allowing easy cross-compilation of source code.
+If you would rather cross-compile the code from a different location (i.e. your MacOS laptop or x86 Linux machine), then
+you will need tooling to do the CGo-enabled cross-compilation of the C code generated for the code.  One easy way to do this is with the [Zig language](https://ziglang.org/) toolchain.
 
-Zig cross-compilers can be used for building CGo-enabled Go code with little fuss. Assuming you have the Zig build tools installed, you can cross-compile the code in this directory as shown below:
+Zig comes with a full C/C++ cross-compiler including flag compatibility with `gcc` and `clang`. It can be used as a drop-in replacement for those compilers allowing easy cross-compilation of C source code. Zig cross-compilers can be used for building CGo-enabled Go code with little fuss. Assuming you have the Zig build tools installed, you can easily cross-compile the code in this directory.
+
+For instance, the following cross-compiles the [./simplecam](./simplecam/) example into a static binary:
 
 ```
 CGO_ENABLED=1 GOOS=linux GOARCH=arm GOARM=7 CC="zig cc -target arm-linux-musleabihf" CXX="zig c++ -target arm-linux-musleabihf" go build -o simple-cam ./simplecam
 ```
 
-The previous build command will create a static binary that can run on Linux for the Arm/v7 architecture.
+The previous build command will create a static binary that can run on Linux/Arm/v7 architecture.
 
 ### Cross-compile with Docker
-There are some Docker images that you can use to properly cross-compile your code. Example [./simplecam](./simplecam/Dockerfile) includes a Dockerfile that uses image `crazymax/goxx` to cross-compile go4vl code.
+Another way you can achieve cross compilation is with Docker. If you already have Docker as part of your workflow, you will find some images that you can use to cross-compile the code in this directory. For instance, the simplecam example includes a [./simplecam/Dockerfile](./simplecam/Dockerfile) that uses image `crazymax/goxx` to cross-compile the go4vl code.

examples/ext_ctrls/README.md

@@ -1,3 +1,32 @@
 # Extended controls
 
-This example shows go4vl support for extended controls. The API allows users to query and set control values.
+This example shows go4vl support for V4L2 extended controls. The API allows users to query and set control values.
+For instance, the following snippet shows how to retrieve all extended controls for a given device.
+
+```go
+func main() {
+	devName := "/dev/video0"
+	flag.StringVar(&devName, "d", devName, "device name (path)")
+	flag.Parse()
+
+	device, err := dev.Open(devName)
+	if err != nil {
+		log.Fatalf("failed to open device: %s", err)
+	}
+	defer device.Close()
+
+	ctrls, err := v4l2.QueryAllExtControls(device.Fd())
+	if err != nil {
+		log.Fatalf("failed to get ext controls: %s", err)
+	}
+	if len(ctrls) == 0 {
+		log.Println("Device does not have extended controls")
+		os.Exit(0)
+	}
+	for _, ctrl := range ctrls {
+		printControl(ctrl)
+	}
+}
+```
+
+> See full example [source code](./extctrls.go).

examples/snapshot/README.md

@@ -0,0 +1,49 @@
+# Snapshot
+
+This program is a simple example that shows how to use the go4vl API to capture a single frame, from an attached camera device, and save it to a file. The example assumes the attached camera device supports JPEG (MJPEG) format inherently.
+
+First, the `device` package is used to open a device with name `/dev/vide0`. If the device is not available or cant be opened (with the default configuration), the driver will return an error.
+
+```go
+func main() {
+	dev, err := device.Open("/dev/video0")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer dev.Close()
+
+    ...
+}
+```
+
+Next, the device is started, with a context, and if no error is returned, it is ready to capture video data.
+
+```go
+func main() {
+    ...
+	if err := dev.Start(context.TODO()); err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+Next, the source code use variable `dev` to capture the frame and save the binary data to a file.
+
+```go
+func main() {
+    ...
+	frame := <-dev.GetOutput()
+
+	file, err := os.Create("pic.jpg")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer file.Close()
+
+	if _, err := file.Write(frame); err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+> See the full [source code](./snap.go).

examples/user_ctrl/README.md

@@ -1 +1,27 @@
-# Device user control
+# Device user control
+
+The go4vl API has support for querying and setting values for device user control as demonstrated in this example.
+For instance, the two functions below uses the go4vl API to set a user control and retrieve all user controls respectively.
+
+```go
+func setUserControlValue(device *dev.Device, ctrlID v4l2.CtrlID, val int) error {
+	if ctrlID == 0 {
+		return fmt.Errorf("invalid control specified")
+	}
+	return device.SetControlValue(ctrlID, v4l2.CtrlValue(val))
+}
+
+func listUserControls(device *dev.Device) {
+	ctrls, err := device.QueryAllControls()
+	if err != nil {
+		log.Fatalf("query controls: %s", err)
+	}
+
+	for _, ctrl := range ctrls {
+		printUserControl(ctrl)
+	}
+}
+```
+
+> See complete [source code](./ctrl.go).
+

examples/webcam/README.md

@@ -5,22 +5,20 @@ The webcam examples shows how the `go4vl` API can be used to create a webcam tha
 * go4vl device control API
 * go4vl format description API
 * go4vl capture API
-
-The example also includes code that shows how to do face detection using the captured image.
-
-The code sets up a web server that returns a web page with an image element that continuously stream the captured video from the camera.
+* Using (third-party) package for face detection
 
 ## Building the source code
+Follow these instructions if you want to build the code for your device.
 
-### Fix face detection modules 
+### 1. Fix face detection modules 
 The project uses an external package for face detection. For it to build properly, some Go modules must be specically pulled. This is done by running shell script file [./fix-mods.sh](./fix-mods.sh).
 
-### Compile the code
-See instructions for on-device compilation or off-device cross-compilation [here](../README.md).
+### 2. Compile the code
+See instructions for on-device compilation or off-device cross-compilation [here](../README.md). Once you have compiled the code, return here to find out how to run the example.
 
-### Run
+## Run
 
-Once built, run the binary on a target machine (a Raspberry Pi for instance) that has a camera capture device attached:
+Run the binary on a target machine (a Raspberry Pi for instance) that has a camera device attached:
 
 ```
  ./webcam
@@ -33,11 +31,15 @@ Once built, run the binary on a target machine (a Raspberry Pi for instance) tha
 2022/05/21 09:04:31 use url path /webcam
 ```
 
-Next, point your browser to your machine's address and shown port (i.e. `http://198.162.100.20:9090`). 
+By default, the program will attempt to  use format `Motion-JPEG` (or related format). If your camera does not support that format, the example will not work properly.
+
+### View the webcam stream
+Next, point your browser to your device's IP address and port (i.e. `http://198.162.100.20:9090`). 
 You should see a webpage with the streaming video (see below.)
 
 ![](./screenshot.png)
 
+### CLI options
 The webcam program offers several CLI arguments that you can use to configure the webcam:
 
 ```