external_libcamera/src/libcamera/ipa_interface.cpp

/* 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 */