Remove outdated documentation

README.md

@@ -14,54 +14,6 @@ $ ninja
 $ sudo ninja install
 ```
 
-# Config
-
-Megapixels checks multiple locations for its configuration file and uses the first one it finds.
-As a first step it will get the first compatible name in the device tree, in the case of a PinePhone
-this might be `pine64,pinephone-1.2`. Then that dtname will be used as the filename in the search
-path in this order:
-
-* `$XDG_CONFIG_DIR/megapixels/config/$dtname.ini`
-* `~/.config/megapixels/config/$dtname.ini`
-* `/etc/megapixels/config/$dtname.ini`
-* `/usr/share/megapixels/config/$dtname.ini`
-
-The files in `/usr/share/megapixels` should be the config files distributed in this repository. The other
-locations allow the user or distribution to override config.
-
-## Config file format
-
-Configuration files are INI format files. 
-
-### [device]
-
-This provides global info, currently only the `make` and `model` keys exist, which is metadata added to the
-generated pictures.
-
-### All other sections
-
-These are the sections describing the sensors.
-
-* `driver=ov5640` the name of the media node that provides the sensor and its `/dev/v4l-subdev*` node.
-* `media-driver=sun6i-csi` the name of the media node that has this camera in it.
-* `rotate=90` the rotation angle to make the sensor match the screen
-* `mirrored=true` whether the output is mirrored, useful for front-facing cameras
-* `colormatrix=` the DNG colormatrix1 attribute as 9 comma seperated floats
-* `forwardmatrix=` the DNG forwardmatrix1 attribute as 9 comma seperated floats
-* `blacklevel=10` The DNG blacklevel attribute for this camera
-* `whitelevel=255` The DNG whitelevel attribute for this camera
-* `focallength=3.33` The focal length of the camera, for EXIF
-* `cropfactor=10.81` The cropfactor for the sensor in the camera, for EXIF
-* `fnumber=3.0` The aperture size of the sensor, for EXIF
-
-These sections have two possibly prefixes: `capture-` and `preview-`. Both sets
-are required. Capture is used when a picture is taken, whereas preview is used
-when previewing.
-
-* `width=640` and `height=480` the resolution to use for the sensor
-* `rate=15` the refresh rate in fps to use for the sensor
-* `fmt=BGGR8` sets the pixel and bus formats used when capturing from the sensor.
-
 # Post processing
 
 Megapixels only captures raw frames and stores .dng files. It captures a 5 frame burst and saves it to a temporary
@@ -85,11 +37,10 @@ see `postprocess.sh` in this repository.
 
 # Developing
 
-Megapixels is developed at: https://gitlab.com/postmarketOS/megapixels
+Megapixels is developed at: https://gitlab.com/megapixels-org/megapixels
 
 ## Source code organization
 
-* `ini.c` contains a INI file format parser.
 * `camera_config.c` describes how cameras are configured. Contains no state.
 * `main.c` contains the entry point and UI portion of the application.
 * `quickpreview.c` implements fast preview functionality, including debayering, color correction, rotation, etc.
@@ -105,280 +56,4 @@ which in turn talks to the process pipeline, which then talks to the main
 application. This way neither IO nor processing blocks the main application and
 races are generally avoided.
 
-Tests are located in `tests/`.
-
-## Tools
-
-All tools are contained in `tools/`
-
-* `list_devices` lists all V4L2 devices and their hardware layout.
-* `camera_test` lists controls and video modes of a specific camera and tests capturing data from it.
-
-## Linux video subsystem 
-
-Most of the logic is contained inside `main.c`, but before we look at it, it is
-convenient to have some basic notions about the Linux video subsystem that
-Megapixels directly uses (instead of, for example, using a higher level
-framework such as `gstreamer`, as other camera apps do).
-
-Typically, for "simple" video capture devices (such as some old webcams on a
-PC), the Linux kernel creates an entry on `/dev/` called `/dev/videoX` (where X
-can be `0`, `1`, ...). The user can then `open()` that file descriptor, use
-standard `ioctl()`s on it to start/stop/configure the hardware and finally
-`read()` from it to obtain individual video frames.
-
-In the PinePhone we have two cameras ("front" and "rear") but, surprinsingly,
-the Linux kernel does not expose two video devices but just a single one named
-`/dev/video1`.
-
-This is because, on the PinePhone, there is one single "capture device" and two
-"image sensors" (one for each camera) attached to it:
-
-```
-    .-----------.         .--------------.
-    |           |---------| front sensor ))))))
-    |  Sensors  |         '--------------'
-    | interface |         .--------------.
-    |           |---------| rear sensor  ))))))
-    '-----------'         '--------------'
-```
-
-The only video device exposed (`/dev/video1`) represents the "sensors interface"
-block, which can be configured at runtime to capture data from one sensor or the
-other.
-
-But there is more: in order to configure the properties of each sensor (example:
-capture frame rate, auto exposure, ...), instead of issuing `ioctl()` calls on
-`/dev/video1`, the Linux kernel (for this particular case) exposes two extra
-devices (`/dev/v4l-subdev0` for one sensor and `/dev/v4l-subdev1` for the other
-one).
-
-How does the user know that `/dev/v4l-subdev0`, `/dev/v4l-subdev1` and
-`/dev/video1` are related? Thanks to the "media subsystem": for "complex" cases
-such as this one, the Linux kernel exposes an extra device (`/dev/mediaX`, where
-X can be `0`, `1`, ...) that can be used to...
-
-* Obtain the list of related devices to that "media interface". 
-* Link/unlink the different "blocks" at runtime.
-
-Pheeew.... let's recap what we have to far:
-
-* `/dev/mediaW` represents the "whole camera hardware".
-* `/dev/videoX` is the "sensors interface" from where we will `read()` frames.
-* `/dev/vl4-subdevY` and `/dev/vl4-subdevZ` can be used to configure the
-  sensors.
-
-Notice how I used `W`, `X`, `Y` and `Z` instead of numbers. In the current
-kernel `W==1`, `X==0`, `Y==0` and `Z==1`, but that might change in the future.
-That's why `main()` needs to figure them out by following this procedure:
-
-1. List all `/dev/mediaX` devices present (ex: `/dev/media0`, `/dev/media1`,
-   ...)
-2. Query each of them with `ioctl(MEDIA_IOC_DEVICE_INFO)` until we find the
-   entry managed by a driver named "sun6i-csi" (as that is the name of the
-   driver of the sensor interface for the [Allwinner SoC camera
-   sensor](https://linux-sunxi.org/CSI) that the PinePhone uses, which is
-   provided on the `*.ini` file).
-3. Obtain a list of elements associated to that "media device" by calling
-   `ioctl(MEDIA_IOC_ENUM_ENTITIES)`.
-4. The entry called "ov5640" is the rear camera (as that is the name of the
-   driver of the rear sensor, which is provided on the `*.ini` file). Save its
-   device name (ex: `/dev/v4l-subdev1`) for later.
-5. The entry called "gc2145" is the front camera (as that is the name of the
-   driver of the front sensor, which is provided on the `*.ini` file). Save its
-   device name (ex: `/dev/v4l-subdev0`) for later.
-6. The entry called "sun6i-csi" is the sensors interface (same name as the
-   driver in charge of the `/dev/mediaX` interface). Save its device name (ex:
-   `/dev/video1`) for later.
-
-By the way, regarding steps 1 and 2, you can manually inspect the list of
-"elements" that are related to a given `/dev/mediaX` entry from user space using
-the `media-ctl` tool. This is what the current kernel and hardware revision
-return:
-```shell-session
-$ media-ctl -d /dev/media1 -p
-
-Media controller API version 5.7.19
- 
-Media device information
-------------------------
-driver          sun6i-csi
-model           Allwinner Video Capture Device
-serial          
-bus info        
-hw revision     0x0
-driver version  5.7.19
- 
-Device topology
-- entity 1: sun6i-csi (1 pad, 2 links)
-            type Node subtype V4L flags 0
-            device node name /dev/video1
-        pad0: Sink
-                <- "gc2145 4-003c":0 []
-                <- "ov5640 4-004c":0 [ENABLED]
- 
-- entity 5: gc2145 4-003c (1 pad, 1 link)
-            type V4L2 subdev subtype Sensor flags 0
-            device node name /dev/v4l-subdev0
-        pad0: Source
-                [fmt:YUYV8_2X8/1280x720@1/10 field:none colorspace:srgb]
-                -> "sun6i-csi":0 []
- 
-- entity 7: ov5640 4-004c (1 pad, 1 link)
-            type V4L2 subdev subtype Sensor flags 0
-            device node name /dev/v4l-subdev1
-        pad0: Source
-                [fmt:YUYV8_2X8/1280x720@1/30 colorspace:srgb xfer:srgb ycbcr:601 quantization:full-range]
-                -> "sun6i-csi":0 [ENABLED]
-```
-...which means what we already know: `sun6i-csi` is the sensors interface sink
-(on `/dev/video1`) where the two sensors (`gc2145` on `/dev/v4l-subdev0` and
-`ov5640` on `/dev/v4l-subdev1` are connected). By default (or, at least, in the
-example above) the sensors interface is connected to the rear camera (`ov5640`)
-as its link is the only one "ENABLED".
-
-Anyway... once `main()` has figured out the values of `W`, `X`, `Y` and `Z`,
-this is how all these device entries are used to manage the camera hardware:
-
-* Use `ioctl(MEDIA_IOC_SETUP_LINK)` on the `/dev/mediaW` entry to "link" the
-  sensors interface with either the rear sensor or the front sensor (this is
-  how we choose from which camera we will be capturing frames)
-* Use `ioctl(VIDIOC_SUBDEV_...)` on `/dev/v4l-subdev{Y,Z}` to configure the
-  sensors.
-* Use `ioctl(VIDIOC_...)` on `/dev/videoX` to configure the sensors interface.
-* Use `read()` on `/dev/videoX` to capture frames.
-
-The mechanism described on the last point (ie. use `read()` to capture frames),
-while possible, is not actually what `main()` does. Instead, a more complex
-mechanism (described
-[here](https://www.kernel.org/doc/html/latest/userspace-api/media/v4l/io.html))
-is used, where a series of buffers are allocated, sent to `/dev/videoX` with
-`ioctl(VIDIOC_QBUF)` and then retrieved with `ioctl(VIDIOC_DQBUF)` once they
-have been filled with video frames (after having called
-`ioctl(VIDIOC_STREAMON)`)... but it is basically the same as performing a
-`read()` (except that it has more flexibility).
-
-## Source code walkthrough
-
-As we have just seen on the [previous section](#linux-video-subsystem), in the
-current kernel version, and for the latest PinePhone revision (1.2a), the Linux
-kernel exposes 4 device entries to manage the camera hardware:
-
-* `/dev/media1` to select the active camera ("front" or "rear")
-* `/dev/vl4-subdev0` and `/dev/vl4-subdev1` to configure the sensor of each
-  camera (aperture, auto exposure, etc...)
-* `/dev/video1` to capture frames (video stream and/or pictures)
-
-However these device entries might change with future versions of the kernel
-and/or the hardware (for example, `/dev/video3` instead of `/dev/video1`), and
-that's why function `main()` in `main.c` starts by trying to figure out the
-correct names.
-
-It does so by checking the hardware revision in `/proc/device-tree/compatible`
-and then opening the corresponding `.ini` file from the config folder (ex:
-`pine64,pinephone-1.2.ini` for the latest PinePhone revision as of today,
-`pine64,pinetab.ini` for the PineTab, etc...).
-
-The `.ini` file contains the name of the driver that manages the `/dev/mediaX`
-interface (`csi` entry on the `device` section) and, from there, `main()` can
-figure out the rest of the device names as already explained on the [previous
-section](#linux-video-subsystem).
-
-
-```
-    /proc/device-tree/compatible
-        |
-        |
-        V
-    config/*.ini ---------------.
-        |                       |
-        |                       V
-        |          .~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-        |          :                           :
-        |          :  .----> /dev/video1       :
-        V          :  |                        :
-    /dev/media1 ------+----> /dev/v4l-subdev0  :
-                   :  |                        :
-                   :  '----> /dev/v4l-subdev1  :
-                   :                           :
-                   '~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-```
-
-Anyway... in addition to figuring out these entry names, `main()` also prepares
-the GTK widgets layout and installs a series of callbacks. Among them we find
-these two:
-
-1. One on the "switch camera button" (`on_camera_switch_clicked()`) which uses
-   `/dev/media1` to switch between the front and rear cameras.
-   Every time this happens, the sensors and the sensors interface are
-   reconfigured according to the parameters provided on the `.ini` file using
-   `/dev/video1`, `/dev/v4l-subdev0` and `/v4l-subdev1`.
-   ```
-   on_camera_switch_clicked()
-   |
-   |--> stop_capturing()
-   |    `--> ioctl('/dev/video1', ...)           # Stop processing frames
-   |
-   |--> setup_front() or setup_rear()
-   |    |--> ioctl('/dev/media1', ...)
-   |    `--> init_sensor()
-   |         `--> ioctl('/dev/v4l-subdev{0,1}')  # Reconfigure sensor
-   |         
-   |--> init_device()
-   |    `--> ioctl('/dev/video1')                # Reconfigure sensors interface
-   |
-   `--> start_capturing()
-        `--> ioctl('/dev/video1')                # Resume capturing frames
-    
-   ```
-2. Another one on the "take a photo button" (`on_shutter_clicked()`) which
-   will use `/dev/v4l-subdev{0,1}` to disable hardware "auto gain" and "auto
-   exposure" and initiate the "single frame capture process" (described later).
-
-Finally, before calling GTK's main loop, `main()` installs another function
-(`get_frame()`) on the "nothing else todo" GTK slot. It will thus be called
-continuosly as long as there are no other GTK events queued (ie. almost always).
-
-This `get_frame()` function is where the magic happens: it will call
-`read_frame()` to `read()` from the `/dev/video1` device an image frame and
-then call `process_image()` to process it.
-
-> NOTE: As explained at the end of the [Linux video subsystem
-> section](#linux-video-subsystem), it is a bit more complex than that (that's
-> why you will find a `ioctl()` instead of a `read()` inside `read_frame()`),
-> but for all purposes, you can ignore this fact.
-
-So... let's recap: as long as the user does not click on any application button,
-the `process_image()` function is being called all the time with a pointer to
-the latest captured frame. What does it do with it?
-
-The captured frame buffer contains "RAW data", whose format depends on the value
-specified on the `.ini` file for each sensor. Right now we are using `BGGR8` for
-both of them, so the function that takes this buffer to process it is always the
-same (`quick_debayer_bggr8()`). The result is a buffer of "standard pixels" that
-can be drawn to screen using GTK/cairo functions.
-
-When the user clicks on the "take a photo button", however, a special global
-variable (`capture`) is set so that the next `N` times (currently `N==10`), the
-`process_image()` will do something different:
-1. It will first retrieve the latest "auto gain" and "auto exposure" values
-   (remember they were disabled when the user clicked on the "take a photo
-   button").
-2. It will save the latest captured buffer (in "RAW data" format, ie. `BGGR8`)
-   to a `.dng` file using the "TIFF" library, which makes it possible to attach
-   all the needed metadata (which Megapixels extracts from the hardware itself
-   and/or the values on the `.ini` file).
-3. In addition, **only** the very last time (from the `N` times):
-     - The captured buffer is run through `quick_debayer_bggr8()` and the result
-       printed to the UI.
-     - The `postprocess.sh` script (see the [Post processing
-       section](#post-processing)) is called with two arguments: the path to the
-       `/tmp` folder where the `N` `.dng` images have been saved and the path
-       and filename where the resulting post-processed (typically JPEG) image
-       should be saved to (as a result of running `postprocess.sh`)
-     - "Auto exposure" and "auto gain" are re-enabled.
-
-In other words: every time the user clicks on the "take a photo button", `N`
-RAW images are saved and `postprocess.sh` called, which is expected to take
-those `N` images and generate a final JPEG.
-
+Tests are located in `tests/`.