Next Video Tool for Linux* OS
	-----------------------------

Copyright (C) 2011--2017 Intel Corporation.
Contact: Tuukka Toivonen <[email protected]>

No license (express or implied, by estoppel or otherwise) to any intellectual
property rights is granted by this document.

Intel disclaims all express and implied warranties, including without
limitation, the implied warranties of merchantability, fitness for a
particular purpose, and non-infringement, as well as any warranty arising from
course of performance, course of dealing, or usage in trade.

This document contains information on products, services and/or processes in
development.  All information provided here is subject to change without
notice. Contact your Intel representative to obtain the latest forecast,
schedule, specifications and roadmaps.

The products and services described may contain defects or errors known as
errata which may cause deviations from published specifications. Current
characterized errata are available on request.

Intel, the Intel logo, and Intel Atom are trademarks of Intel Corporation
in the U.S. and/or other countries.

*Other names and brands may be claimed as the property of others

© 2017 Intel Corporation.

= Introduction =

Next Video Tool for Linux* OS is a simple very low level command line test
tool for Linux V4L2 video and image capture interface developed from scratch.
It allows very precise control of the V4L2 interface and displays detailed
information on exchanged data structures.

It has been developed for Android/x86 but should work on generic Linux
systems once compiled. It is standalone and independent of Android tree
during compilation and usage.

By default, the tool supports some Intel-specific extensions to the V4L2
interface. These can be compile-time disabled. All necessary header
files are included with the package so there are no dependencies to
external V4L2 or AtomISP header files.

The tool can capture images and store them to raw files. The raw files can
be converted to standard pnm files using the companion raw2pnm tool.
The tool also allows setting and querying of V4L2 controls.

The philosophy of Next Video Tool:
- Have everywhere sane default values to simplify usage
- Allow user to control every detail and order of the issued system calls
- Do nothing unless told to do
- Display detailed and complete exchange of structures with the kernel
  when in verbose mode
- Check for all possible errors and abort immediately if one happens

= Requirements =

For compilation, a Linux system with only gcc and static C libraries are
needed. The libraries are linked statically so that there are no dependencies
to Android. To run on Android/x86, only adb is required to be properly
installed. In Windows, adb requires special USB drivers, but on Linux
that is not needed.

= Compilation =

Compilation:
	make

This should create v4l2n which is the main binary and raw2pnm which
converts raw files to pnm.

= Usage =

Run
	./v4l2n --help
to list available options. v4l2n processes options one by one, executing
them while parsing, and displaying results. So, you could use options
several times, for example --capture=30 --waitkey --capture=40 to capture
30 frames, wait enter key, and then capture 40 frames more.
First 100 frames are stored into memory and written to disk files when
v4l2n quits.

Most of the options correspond directly to V4L2 ioctls but without the
VIDIOC_X_ prefix. See
	http://hverkuil.home.xs4all.nl/spec/media.html
for documentation of the interface. The options take structure field
names directly as parameters. For example, you could set the format with
option "--fmt type=1,width=640,height=480,pixelformat=NV12" which corresponds
to VIDIOC_S_FMT and struct v4l2_format. Often both symbolic names and
numeric values are accepted, such as for the "pixelformat" field. All of
the options are listed with "--help" but unfortunately the description of the
fields is incomplete. Please use source code and the links above to check
possible structure field names.

V4L2 controls can be get, set, and queried with the --ctrl command. The
list of supported controls is shown with option --ctrl-list. To set a simple
control values (VIDIOC_S_CTRL) use option "--ctrl=HFLIP=1", for example.
Usually extended controls are preferred and those are selected by adding
a "+" sign after control name, such as "--ctrl=HFLIP+=1". You can get values
by using a question mark, eg. "--ctrl=HFLIP?" or "--ctrl=HFLIP+?" for
VIDIOC_G_EXT_CTRLS. Use a hash character "#" to query control
("--ctrl='HFLIP#'").

== v4l2n.sh ==

Since Next Video Tool is a very low-level tool, the user must specify
exactly what he or she wants to do. This may lead to quite long command lines.
For Linux host users, there is alternatively a script v4l2n.sh designed
to interface with x86-based Android devices with adb. Automatic image
capture can be launched with host Linux command lines:
	export V4L2N_INPUT=X
	./v4l2n.sh -a
where X is 0 or 1, depending whether main or secondary camera is to be
used. Use
	./v4l2n.sh --enuminput
to enumerate device cameras. When run, v4l2n.sh -a
	- Gets settings from environment variables
		* V4L2N_WIDTH, V4L2N_HEIGHT: capture resolution
		* V4L2N_FORMAT: image format, default NV12
		* V4L2N_INPUT: input device, usually 0 or 1
		* V4L2N_VIEWER: program launched for viewing .pnm files
		* V4L2N_DIR: Android directory where to store captured images
	  All of the variables have some default values which hopefully work
	- Remounts /system directory into read-write mode and copies v4l2n
	  binary into that directory
	- Runs v4l2n capturing two images into Android filesystem
	- Transfers images from Android to host using adb and converts them
	  to pnm
	- Finally V4L2N_VIEWER (by default gqview) is launched to display
	  images

Without the -a option, v4l2n.sh does the remounting and copying of v4l2n
into the device but runs v4l2n with command line given to v4l2n.sh. Thus,
you could query the current format with
	./v4l2n.sh "--fmt='?'"
You may need to quote the parameters given to v4l2n.sh.

== Examples ==

Setting exposure (Intel V4L2 extension):
	./v4l2n.sh --exposure=12,34,56,78
where 12 is coarse exposure, 34 is fine exposure, 56 is analog gain,
and 78 is digital gain. These are directly register values.

This example runs eternal viewfinder with adb (works from Windows prompt too),
the parameters are for Clovertrail:
	adb root
	adb remount
	adb push v4l2n /system/
	adb shell /system/v4l2n -o /cache/[email protected] --input 1
		--parm type=1 --fmt type=1,width=800,height=600,pixelformat=NV12
		--reqbufs count=3,memory=USERPTR --capture=999999
Only 100 first frames are saved to memory, the rest are discarded. Since v4l2n
in practice will run eternally, the captured images are never saved to disk.

This example captures one frame, pulls it from the phone, and converts to PNM
file:
	./v4l2n.sh -o /cache/[email protected] --device /dev/video2 --input 0
	--parm type=1,capturemode=CI_MODE_PREVIEW
	--fmt type=1,width=1920,height=1080,pixelformat=NV12 --reqbufs
	count=2,memory=USERPTR --exposure=5400,0,0,256 --capture=2
	adb pull /cache/testimage_001.raw .
	./raw2pnm -x1920 -y1080 -fNV12 testimage_001.raw testimage_001.pnm

Merrifield and Moorefield enable offline mode by default for still
capture. This requires configuring two video pipes. To avoid that, you can
use option --cvf_parm=0,0,0 to switch to online mode. Then you could capture
raw images in still mode using this command:

	./v4l2n.sh -o /cache/[email protected] --device /dev/video0 --input 0
	--parm type=1,capturemode=CI_MODE_STILL_CAPTURE --cvf_parm=0,0,0
	--fmt type=1,width=4192,height=3104,pixelformat=SGRBG10 --reqbufs
	count=2,memory=USERPTR --exposure=5400,0,0,256 --capture=2
	adb pull /cache/testimage_001.raw .
	./raw2pnm -x4224 -y3104 -fSGRBG10 testimage_001.raw testimage_001.pnm
This example was from Saltbay, where extra padding is added to raw captured
images. The "@" character in file name is replaced with frame number.

Here is raw capture command for secondary camera of Moorefield PR1:
	./v4l2n.sh  -o /cache/[email protected] \
	--device /dev/video0 --input 0 \
	--parm type=1,capturemode=CI_MODE_STILL_CAPTURE \
	--cvf_parm=0,0,0 --exposure=1102,0,140,256 \
	--fmt type=1,width=1936,height=1200,pixelformat=SRGGB10 \
	--reqbufs count=1,memory=USERPTR \
	--capture=2

	./raw2pnm -x2048 -y1200 -fSRGGB10 testimage_001.raw testimage_001.pnm

The default gains give a greenish image. You may adjust white balance by
changing red, green, and blue gains as follows:

	./v4l2n.sh -o /cache/[email protected] --device /dev/video2 --input 1 \
	--parm type=1,capturemode=CI_MODE_PREVIEW \
	--fmt type=1,width=1920,height=1080,pixelformat=NV12 \
	--reqbufs count=2,memory=USERPTR --exposure=5400,0,0,256 --stream=0 \
	--parameters=wb_config.r=32768,wb_config.gr=21043,wb_config.gb=21043,wb_config.b=30863 \
	--stream=2
	for i in 0 1;do \
		adb pull /cache/testimage_00$i.raw .; \
		./raw2pnm -x1920 -y1080 -fNV12 testimage_00$i.raw testimage_00$i.pnm;\
	done 

This example was from Moorefield and illustrates the usage of Intel-specific
VIDIOC_S_PARAMETERS (--parameters) call. The call requires that streaming
has been first started, which is done with --stream=0 option.

Video capture is another use case which requires simultaneous configuration
of two pipes, for video stream and preview stream. This command works on
Moorefield PR2 and captures 1920x1080 video with 1280x720 preview:

	./v4l2n.sh --pipe=2 -o /cache/[email protected] --device=/dev/video2 \
	--input=1 --ctrl=ATOMISP_VIDEO_STABLIZATION=0 --exposure=2000,0,0,256 \
	--pipe=3 -o /cache/[email protected] --device=/dev/video3 \
	--parm type=1,capturemode=CI_MODE_VIDEO \
	--fmt type=1,width=1920,height=1080,pixelformat=NV12 \
	--pipe=2 --fmt=type=1,width=1280,height=720,pixelformat=NV12 \
	--pipe=3 --reqbufs count=9,memory=USERPTR \
	--pipe=2 --reqbufs count=9,memory=USERPTR --pipe 2,3 --capture=2
	for i in /cache/testimage2_001.raw /cache/testimage3_001.raw;do adb pull $i .;done
	./raw2pnm -x1280 -y720 -fNV12 testimage2_001.raw testimage2_001.pnm
	./raw2pnm -x1920 -y1080 -fNV12 testimage3_001.raw testimage3_001.pnm

Display list of image formats supported by v4l2n:
	./v4l2n --fmt-list
Note that neither AtomISP driver nor raw2pnm supports all of these. Use
SGRBG10 or its variant to capture raw Bayer images and NV12 or NV21 to capture
images in YUV colorspace. 

Convert raw NV12 file into pnm file:
	./raw2pnm -x640 -y480 -fNV12 testimage_001.raw testimage_001.pnm
Remember to check the resolution, it should match with what v4l2n tells
that the driver uses ie. what the VIDIOC_S_FMT ioctl returns. If the buffer
has padding, you can use -s BPL option where BPL is the same value
as bytesperline returned from VIDIOC_S_FMT.

== References ==
	http://hverkuil.home.xs4all.nl/spec/media.html
	http://git.ideasonboard.org/yavta.git
		(yet another simple V4L2 testing tool)

---