1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
/* SPDX-License-Identifier: LGPL-2.1-or-later */
/*
* Copyright (C) 2019, Google Inc.
*
* ipa_interface.cpp - Image Processing Algorithm interface
*/
#include <libcamera/ipa/ipa_interface.h>
/**
* \file ipa_interface.h
* \brief Image Processing Algorithm interface
*
* Every pipeline handler in libcamera may attach some or all of its cameras to
* an Image Processing Algorithm (IPA) module. An IPA module is developed for a
* specific pipeline handler and each pipeline handler may be compatible with
* multiple IPA implementations, both open and closed source. To support this,
* libcamera communicates with IPA modules through a per-pipeline C++ interface.
*
* IPA modules shall provide an ipaCreate() function exported as a public C
* symbol with the following prototype:
*
* \code{.c}
* IPAInterface *ipaCreate();
* \endcode
*
* The ipaCreate() function creates an instance of an IPA interface, which models
* a context of execution for the IPA. IPA modules shall support creating one
* context per camera, as required by their associated pipeline handler.
*
* The IPA module interface operations are defined in the mojom file
* corresponding to the pipeline handler, in
* include/libcamera/ipa/{pipeline_name}.mojom.
*
* The IPA interface is specific to each pipeline handler. The pipeline handlers
* define a set of operations used to communicate with their IPA modules. The
* operations, along with the data structures they use, are collectively
* referred to as the IPA protocol.
*
* The IPA protocol is defined using the
* <a href="https://chromium.googlesource.com/chromium/src/+/master/mojo/public/tools/bindings/README.md">Mojo interface definition language</a>,
* in a Mojo module file stored in include/libcamera/ipa/{pipeline_name}.mojom.
* The Mojo module contains two Mojo interfaces: IPAInterface defines the
* operations exposed by the IPA and called by the pipeline handler, and
* IPAEventInterface defines the events generated by the IPA and received by the
* pipeline handler.
*
* \todo Add reference to how pipelines shall document their protocol.
*
* IPAs can be isolated in a separate process. This implies that arguments to
* the IPA interface functions may need to be transferred over IPC. An IPA
* proxy is auto-generated based on the mojom file, which abstracts away the
* (de)serialization from the pipeline handler and the IPA implementation. Thus
* any C++ structure that is defined in the mojom file, or the C++ libcamera
* objects that are listed in core.mojom, can be used directly.
*
* Due to IPC, synchronous communication between pipeline handlers and IPAs can
* be costly. For that reason, functions that cannot afford the high cost
* should be marked as [async] in the mojom file, and they will operate
* asynchronously. This implies that these methods don't return a status, and
* that all methods may copy their arguments. Synchronous functions are still
* allowed, but should be used with caution.
*/
/**
* \fn ipaCreate()
* \brief Entry point to the IPA modules
*
* This function is the entry point to the IPA modules. It is implemented by
* every IPA module, and called by libcamera to create a new IPA interface
* instance.
*
* \return A newly created IPA interface instance
*/
namespace libcamera {
/**
* \class IPAInterface
* \brief C++ Interface for IPA implementation
*
* This pure virtual class defines a skeletal C++ API for IPA modules.
* Specializations of this class must be defined in a mojom file in
* include/libcamera/ipa/ (see the IPA Writers Guide for details
* on how to do so).
*
* Due to process isolation all arguments to the IPAInterface methods and
* signals may need to be transferred over IPC. The class thus uses serializable
* data types only. The IPA C++ interface defines custom data structures that
* mirror core libcamera structures when the latter are not suitable, such as
* IPAStream to carry StreamConfiguration data.
*
* Custom data structures may also be defined in the mojom file, in which case
* the (de)serialization will automatically be generated. If any other libcamera
* structures are to be used as parameters, then a (de)serializer for them must
* be implemented in IPADataSerializer.
*
* The pipeline handlers shall use the IPAManager to locate a compatible
* IPAInterface. The interface may then be used to interact with the IPA module.
*
* \todo Figure out how to generate IPAInterface documentation.
*/
} /* namespace libcamera */
|
