
<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<title></title>

</head>

<body>

<div name="messageBodySection">

<div dir="auto">Thanks Umang, some great small clarifications, just about to send a new patch</div>

</div>

<div name="messageSignatureSection"><br />

<div class="matchFont">Chris</div>

</div>

<div name="messageReplySection">On 6 Jul 2020, 19:55 +0200, Umang Jain <email@uajain.com>, wrote:<br />

<blockquote type="cite" style="border-left-color: grey; border-left-width: thin; border-left-style: solid; margin: 5px 5px;padding-left: 10px;">Hi Chris,<br />

<br />

On 7/2/20 4:15 PM, chris@gregariousmammal.com wrote:<br />

<blockquote type="cite">From: Chris Chinchilla <chris@gregariousmammal.com><br />

<br />

Creates a libcamera architecture overview guide and glossary.<br />

<br />

Signed-off-by: Chris Chinchilla <chris@gregariousmammal.com><br />

---<br />

Documentation/introduction.rst | 197 +++++++++++++++++++++++++++++++++<br />

1 file changed, 197 insertions(+)<br />

create mode 100644 Documentation/introduction.rst<br />

<br />

diff --git a/Documentation/introduction.rst b/Documentation/introduction.rst<br />

new file mode 100644<br />

index 0000000..cf914c7<br />

--- /dev/null<br />

+++ b/Documentation/introduction.rst<br />

@@ -0,0 +1,197 @@<br />

+An introduction to libcamera<br />

+============================<br />

+<br />

+The Video for Linux 2 (`V4L2 <https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html>`_) API provides kernel drivers for devices that provide and manipulate<br />

+images and video. However, Linux was missing a convenient way for application developers to take<br />

+advantage of these kernel drivers in userspace. Vendors of devices that provide image input sources<br />

+referred to as "image signal processors" (ISPs) sometimes contribute open-source V4L2 drivers.<br />

+However, ISPs vary so much, and it's a hard task for developers to write portable ISP-based<br />

+applications.<br />

+<br />

+The libcamera library aims to fill this gap by providing a complete userspace camera<br />

+stack for Linux-based systems that supports a wide variety of ISPs, including systems with multiple ISPs attached.<br />

+<br />

+The library currently supports:<br />

+<br />

+- Hardware<br />

+<br />

+ - Intel IPU3<br />

+ - Rockchip RK3399<br />

+ - RaspberryPi 3 and 4<br />

+ - USB video device class (UVC) cameras<br />

+ - Virtual media controller (vimc) driver<br />

+<br />

+- Software<br />

+<br />

+ - ChromeOS support through an Android HAL3 adaptation layer<br /></blockquote>

nit: `ChromeOS` alignment not in line with other points below.<br />

<blockquote type="cite">+ - Image processing algorithms<br />

+ - A V4L2 compatibility layer for existing V4L2 based applications<br />

+ - A gstreamer element for gstreamer pipeline based applications.<br />

+<br />

+The library provides a public API for managing ISPs, frame capture, video streams, frame and<br />

+request metadata, events and callbacks, image processing, and more.<br />

+<br />

+Where libcamera sits in the camera stack<br />

+----------------------------------------<br />

+<br />

+The libcamera library sits in userspace, just on top of the kernel drivers that directly interact<br />

+with hardware and the V4L2 family of APIs (Media Controller, V4L2 Video Device, and V4L2 sub-device APIs).<br />

+<br />

+When using libcamera in a camera stack, it is the core component, taking control of all camera<br />

+devices, and exposing a native C++ API to upper layers of the framework. Other language bindings are in development.<br />

+<br />

+Compatibility Layers<br />

+~~~~~~~~~~~~~~~~~~~~<br />

+<br />

+In a layer above the core framework are compatibility libraries to help existing applications and their developers.<br />

+<br />

+V4L2 Compatibility Layer<br />

+^^^^^^^^^^^^^^^^^^^^^^^^<br />

+<br />

+To emulate high-level V4L2 camera devices and capture all access to camera devices, libcamera uses<br />

+a shared library. The shared library is transparent to libcamera-based applications and injected<br />

+into a process address space using dynamic linking with "LD_PRELOAD ".<br />

+<br />

+The compatibility layer exposes camera device features on a best-effort basis and aims for the<br />

+level of features traditionally available from a UVC camera designed for video conferencing.<br />

+<br />

+Android Camera HAL<br />

+^^^^^^^^^^^^^^^^^^<br />

+<br />

+The libcamera library offers Android camera support through a generic `hardware abstraction layer (HAL) <https://source.android.com/devices/camera/camera3_requests_hal>`_ implementation.<br />

+The HAL focuses on supporting features required by Android that are missing from libcamera, such as JPEG encoding.<br />

+<br />

+The Android camera HAL implementation initially targets the "LIMITED "<br />

+`hardware level <https://source.android.com/devices/camera/versioning#camera_api2>`_,<br />

+with support for the "FULL "level then gradually implemented.<br /></blockquote>

<br />

Here I feel we should mention that ChromeOS actually uses Android HAL<br />

layer for it's camera<br />

to re-iterate the point above ("ChromeOS support through an Android HAL3<br />

adaptation layer").<br />

<br />

This is why libcamera ventures into Android's HAL layer (for now atleast).<br />

<blockquote type="cite">+<br />

+gstreamer element<br />

+^^^^^^^^^^^^^^^^^<br />

+<br />

+The library provides `a gstreamer element <https://gstreamer.freedesktop.org/documentation/application-development/basics/elements.html?gi-language=c>`_ that routes libcamera data for<br />

+further processing in a gstreamer pipeline.<br />

+<br />

+libcamera Architecture<br />

+----------------------<br />

+<br />

+The libcamera library exposes one unified API, but behind that is built from<br />

+re-usable components that provide hardware specific support and configuration<br />

+with a device agnostic API.<br />

+<br />

+Camera Manager<br />

+~~~~~~~~~~~~~~<br />

+<br />

+It enumerates cameras at runtime and instantiates a `Pipeline Handler`_ to manage each Camera<br />

+device that libcamera supports. The Camera Manager supports hotplug detection<br />

+and notification events when supported by the underlying kernel devices.<br />

+<br />

+There is only ever one instance of the Camera Manager running per application. Each application's<br />

+instance of the Camera Manager ensures that only a single application can take control of a camera<br />

+device at once.<br />

+<br />

+`Read the Camera Manager API documentation for more details <http://libcamera.org/api-html/classlibcamera_1_1CameraManager.html>`_<br />

+<br />

+Camera Device<br />

+~~~~~~~~~~~~~<br />

+<br />

+The camera class represents a single item of camera hardware that is capable of producing one or more image streams, and provides the API to interact with the underlying device.<br />

+<br />

+If a system has multiple instances of the same hardware attached, each has it's own instance of the camera class.<br />

+<br />

+The API exposes full control of the device to upper layers of libcamera through the public API,<br />

+making it the highest level object libcamera exposes, and the object that all other API operations<br />

+interact with from configuration to capture.<br />

+<br />

+`Read the Camera API documentation for more details <http://libcamera.org/api-html/classlibcamera_1_1Camera.html>`_<br />

+<br />

+Frame controls<br />

+^^^^^^^^^^^^^^<br />

+<br />

+Depending on the capabilities of a camera device and the hardware it is connected<br />

+to, libcamera supports controlling capture parameters for each stream on a per-frame basis.<br />

+<br />

+These controls include auto exposure, gain, brightness, contrast, lux, white balance, color<br />

+temperature, and saturation.<br />

+<br />

+`Read the Control API documentation for more details <http://libcamera.org/api-html/classlibcamera_1_1Control.html>`_<br />

+<br />

+Pipeline Handler<br />

+~~~~~~~~~~~~~~~~<br />

+<br />

+Pipeline handlers are the abstraction layer for platform-specific hardware configuration. They<br />

+access and control hardware through the V4L2 and Media Controller kernel interfaces, and implement<br />

+an internal API to control the ISP and Capture components of a pipeline directly.<br />

+<br />

+Pipeline handlers' create' Camera device instances based on the devices they detect and support on<br />

+the running system.<br />

+A pipeline handler manages most aspects of interacting with a camera device including:<br />

+<br />

+- frame controls<br />

+- pipelines and stream configuration<br />

+- the data the camera produces, and the buffers it needs to hold the data<br />

+- granting access to camera data<br />

+<br />

+Pipeline handlers form part of the libcamera codebase, and developers need to implement them for<br />

+complex hardware with an ISP that requires device-specific configurations.<br />

+<br />

+`Read the PipelineHandler API documentation for more details <http://libcamera.org/api-html/classlibcamera_1_1PipelineHandler.html>`_<br />

+<br />

+Image Processing Algorithms<br />

+~~~~~~~~~~~~~~~~~~~~~~~~~~~<br />

+<br />

+An image processing algorithm (IPA) component is a private API that implements<br />

+3A (Auto-Exposure, Auto-White Balance, and Auto-Focus) algorithms.<br />

+<br />

+Each supported camera device has its own IPA component that runs on the CPU and<br />

+interacts with the kernel camera devices to control hardware image processing<br />

+based on the parameters supplied by upper layers, and helps maintain state,<br />

+closing the control loop of the ISP.<br />

+<br />

+An IPA component can be part of the libcamera code base, in which case the same<br />

+license covers it, or provided externally as an open-source or closed-source component.<br />

+<br />

+The component is sandboxed and can only interact with libcamera through specifically<br />

+marked APIs. A component has no direct access to kernel camera devices, and dmabuf<br />

+instances explicitly passed to the component control its access to image data and<br />

+metadata. The component should run in a process separate from the main libcamera<br />

+process, and has a restricted view of the system, including no access to networking APIs<br />

+and limited access to file systems.<br />

+<br />

+While libcamera requires sandboxing, the implementation is platform-specific, and handled by<br />

+platform-specific plugins.<br />

+<br />

+To support this security and sandboxing model, libcamera provides an IPC mechanism<br />

+for an IPA and Pipeline Handler to communicate, but developers need to create the<br />

+API themselves. Platform vendors can also use any other IPC mechanism that supports<br />

+passing file descriptors.<br />

+<br />

+3A and Image Enhancement Algorithms<br />

+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^<br />

+<br />

+Camera devices should implement auto exposure, auto gain, and auto white balance,<br />

+and those that include a focus lens should also implement autofocus.<br />

+<br />

+Device vendors implement the control methods required to control these algorithms in hardware or<br />

+firmware outside of libcamera, or in an IPA component.<br />

+<br />

+.. TODO: Add link to guide when completed<br />

+<br />

+Helpers and Support Classes<br />

+~~~~~~~~~~~~~~~~~~~~~~~~~~~<br />

+<br />

+.. TODO: Feel like this is implied in other places of the doc<br />

+<br />

+To help developers create device-specific pipeline handlers and image processing<br />

+algorithms, libcamera provides helpers and support classes that sit on top of the<br />

+Media Controller and V4L2 APIs.<br />

+<br />

+Glossary<br />

+--------<br />

+<br />

+- **ISP**: Image Signal Processor.<br />

+- **Media controller API**: `The Linux Kernel API <https://www.kernel.org/doc/html/v4.10/media/uapi/mediactl/media-controller-intro.html>`_ that handles audio and video input and output.<br /></blockquote>

Small question: Anything specific to do with v4.10 version of the<br />

document here? Shouldn't we point to something newer / latest?<br />

A quick search gave me v5.6<br />

https://www.kernel.org/doc/html/v5.6/media/uapi/mediactl/media-controller-intro.html<br />

based on the release I guess?<br />

I don't know what to do here specifically? Maybe asking a bit around but<br />

generally something > v5.0 should be used I guess.<br />

<blockquote type="cite">+- **V4L2**: `Video for Linux API version 2 <https://www.linuxtv.org/downloads/v4l-dvb-apis-new/userspace-api/v4l/v4l2.html>`_. Device drivers and API for video capture on Linux.<br />

+- **UVC camera**: `USB Video Class <https://en.wikipedia.org/wiki/USB_video_device_class>`_ that describes devices capable of streaming video over the UVC protocol.<br />

+- **3A**: Common algorithms used by camera devices for auto-exposure, auto-white balance and auto-focus).<br />

+- **IPC**: `Inter-process communications based protocol <https://en.wikipedia.org/wiki/Inter-process_communication>`_.<br /></blockquote>

<br />

<br />

Thanks for the work.<br />

<br />

Reviewed-by: Umang Jain <email@uajain.com><br />

<br /></blockquote>

</div>

</body>

</html>