/* SPDX-License-Identifier: LGPL-2.1-or-later */

module libcamera;

/**
 * \file core_ipa_interface.h
 * \brief libcamera structs for IPAs
 */

/*
 * Things that can be defined here (and in other mojom files):
 * - consts
 * - enums
 * - structs
 *
 * Attributes:
 * - skipHeader - structs only, and only in core.mojom
 *   - Do not generate a C++ definition for the structure
 *   - Any type used in a mojom interface definition must have a corresponding
 *     definition in a mojom file for the code generator to accept it, except
 *     for types solely used as map/array members for which a definition is not
 *     required
 *   - This attribute allows defining a symbol for the code generator that
 *     corresponds to a libcamera type without duplicating its definition in the
 *     generated C++ headers
 * - skipSerdes - structs only, and only in core.mojom
 *   - All types need a (de)serializer to be defined in order to be transported
 *     over IPC. The (de)serializer can be:
 *     - Manually implemented as a template specialization in
 *       ipa_data_serializer.cpp in the libcamera sources
 *     - Generated at build time for types defined in a mojom file
 *   - This attribute instructs the build system that a (de)serializer is
 *     available for the type and there's no need to generate one
 * - hasFd - struct fields or empty structs only
 *   - Designate that this field or empty struct contains a SharedFD
 *
 * Rules:
 * - If the type is defined in a libcamera C++ header *and* a (de)serializer is
 *   available then the type shall be declared as empty with both attributes
 *   associated and specified as: [skipHeader, skipSerdes]
 *   - Example: [skipHeader, skipSerdes] ControlList {};
 * - If the type is defined in libcamera but no (de)serializer is available
 *   then the type definition in the core.mojom file should have the
 *   [skipHeader] attribute only
 *   - A (de)serializer will be generated for the type
 * - If a type definition has [skipHeader], then the header where the type is
 *   defined must be included in ipa_interface.h
 * - Types that are solely used as array/map members do not require a mojom
 *   definition if one exists in libcamera
 * - Nested types (e.g. FrameBuffer::Plane) cannot be defined in mojom
 *   - If used in mojom, the nested type shall be defined in a C++ header
 *     and a (de)serializer shall be provided
 *   - Nested types can only be used as array/map members
 *   - When using the type, the C++ namespace separator :: is replaced with a
 *     dot
 *   - In example, to use the FrameBuffer::Plane type in mojom:
 *     - Provide a definition of the FrameBuffer::Plane type in a C++ header
 *     - Include the header in ipa_interface.h
 *     - Provide a (de)serializer implementation ipa_data_serializer.cpp
 *     - In mojom, reference the type as FrameBuffer.Plane and only as map/array
 *       member
 * - [skipHeader] and [skipSerdes] only work here in core.mojom
 * - If a field in a struct has a SharedFD, but is not explicitly
 *   defined so in mojom, then the field must be marked with the [hasFd]
 *   attribute
 *
 * \todo Generate documentation from Doxygen comments in .mojom files
 * \todo Figure out how to keep the skipHeader structs in sync with their
 * C++ definitions, and the skipSerdes structs in sync with their
 * (de)serializers
 */
[skipSerdes, skipHeader] struct ControlInfoMap {};
[skipSerdes, skipHeader] struct ControlList {};
[skipSerdes, skipHeader] struct SharedFD {};

[skipHeader] struct Point {
	int32 x;
	int32 y;
};

[skipHeader] struct Size {
	uint32 width;
	uint32 height;
};

[skipHeader] struct SizeRange {
	Size min;
	Size max;
	uint32 hStep;
	uint32 vStep;
};

[skipHeader] struct Rectangle {
	int32 x;
	int32 y;
	uint32 width;
	uint32 height;
};

/**
 * \struct IPACameraSensorInfo
 * \brief Report the image sensor characteristics
 *
 * The structure reports image sensor characteristics used by IPA modules to
 * tune their algorithms based on the image sensor model currently in use and
 * its configuration.
 *
 * The reported information describes the sensor's intrinsics characteristics,
 * such as its pixel array size and the sensor model name, as well as
 * information relative to the currently configured mode, such as the produced
 * image size and the bit depth of the requested image format.
 *
 * Instances of this structure are meant to be assembled by the CameraSensor
 * class by inspecting the sensor static properties as well as information
 * relative to the current configuration.
 */

/**
 * \var IPACameraSensorInfo::model
 * \brief The image sensor model name
 *
 * The sensor model name is a free-formed string that uniquely identifies the
 * sensor model.
 */

/**
 * \var IPACameraSensorInfo::bitsPerPixel
 * \brief The number of bits per pixel of the image format produced by the
 * image sensor
 */

/**
 * \var IPACameraSensorInfo::activeAreaSize
 * \brief The size of the pixel array active area of the sensor
 */

/**
 * \var IPACameraSensorInfo::analogCrop
 * \brief The portion of the pixel array active area which is read-out and
 * processed
 *
 * The analog crop rectangle top-left corner is defined as the displacement
 * from the top-left corner of the pixel array active area. The rectangle
 * horizontal and vertical sizes define the portion of the pixel array which
 * is read-out and provided to the sensor's internal processing pipeline, before
 * any pixel sub-sampling method, such as pixel binning, skipping and averaging
 * take place.
 */

/**
 * \var IPACameraSensorInfo::outputSize
 * \brief The size of the images produced by the camera sensor
 *
 * The output image size defines the horizontal and vertical sizes of the images
 * produced by the image sensor. The output image size is defined as the end
 * result of the sensor's internal image processing pipeline stages, applied on
 * the pixel array portion defined by the analog crop rectangle. Each image
 * processing stage that performs pixel sub-sampling techniques, such as pixel
 * binning or skipping, or perform any additional digital scaling concur in the
 * definition of the output image size.
 */

/**
 * \var IPACameraSensorInfo::pixelRate
 * \brief The number of pixels produced in a second
 *
 * To obtain the read-out time in seconds of a full line:
 *
 * \verbatim
       lineDuration(s) = lineLength(pixels) / pixelRate(pixels per second)
   \endverbatim
 */

/**
 * \var IPACameraSensorInfo::lineLength
 * \brief Total line length in pixels
 *
 * The total line length in pixel clock periods, including blanking.
 */

/**
 * \var IPACameraSensorInfo::minFrameLength
 * \brief The minimum allowable frame length in units of lines
 *
 * The sensor frame length comprises of active output lines and blanking lines
 * in a frame. The minimum frame length value dictates the minimum allowable
 * frame duration of the sensor mode.
 *
 * To obtain the minimum frame duration:
 *
 * \verbatim
       frameDuration(s) = minFrameLength(lines) * lineLength(pixels) / pixelRate(pixels per second)
   \endverbatim
 */

/**
 * \var IPACameraSensorInfo::maxFrameLength
 * \brief The maximum allowable frame length in units of lines
 *
 * The sensor frame length comprises of active output lines and blanking lines
 * in a frame. The maximum frame length value dictates the maximum allowable
 * frame duration of the sensor mode.
 *
 * To obtain the maximum frame duration:
 *
 * \verbatim
       frameDuration(s) = maxFrameLength(lines) * lineLength(pixels) / pixelRate(pixels per second)
   \endverbatim
 */
struct IPACameraSensorInfo {
	string model;

	uint32 bitsPerPixel;

	Size activeAreaSize;
	Rectangle analogCrop;
	Size outputSize;

	uint64 pixelRate;
	uint32 lineLength;

	uint32 minFrameLength;
	uint32 maxFrameLength;
};

/**
 * \struct IPABuffer
 * \brief Buffer information for the IPA interface
 *
 * The IPABuffer structure associates buffer memory with a unique ID. It is
 * used to map buffers to the IPA with IPAInterface::mapBuffers(), after which
 * buffers will be identified by their ID in the IPA interface.
 */

/**
 * \var IPABuffer::id
 * \brief The buffer unique ID
 *
 * Buffers mapped to the IPA are identified by numerical unique IDs. The IDs
 * are chosen by the pipeline handler to fulfil the following constraints:
 *
 * - IDs shall be positive integers different than zero
 * - IDs shall be unique among all mapped buffers
 *
 * When buffers are unmapped with IPAInterface::unmapBuffers() their IDs are
 * freed and may be reused for new buffer mappings.
 */

/**
 * \var IPABuffer::planes
 * \brief The buffer planes description
 *
 * Stores the dmabuf handle and length for each plane of the buffer.
 */
struct IPABuffer {
	uint32 id;
	[hasFd] array<FrameBuffer.Plane> planes;
};

/**
 * \struct IPASettings
 * \brief IPA interface initialization settings
 *
 * The IPASettings structure stores data passed to the IPAInterface::init()
 * function. The data contains settings that don't depend on a particular camera
 * or pipeline configuration and are valid for the whole life time of the IPA
 * interface.
 */

/**
 * \var IPASettings::configurationFile
 * \brief The name of the IPA configuration file
 *
 * This field may be an empty string if the IPA doesn't require a configuration
 * file.
 */

/**
 * \var IPASettings::sensorModel
 * \brief The sensor model name
 *
 * Provides the sensor model name to the IPA.
 */
struct IPASettings {
	string configurationFile;
	string sensorModel;
};

/**
 * \struct IPAStream
 * \brief Stream configuration for the IPA interface
 *
 * The IPAStream structure stores stream configuration parameters needed by the
 * IPAInterface::configure() function. It mirrors the StreamConfiguration class
 * that is not suitable for this purpose due to not being serializable.
 */

/**
 * \var IPAStream::pixelFormat
 * \brief The stream pixel format
 */

/**
 * \var IPAStream::size
 * \brief The stream size in pixels
 */
struct IPAStream {
	uint32 pixelFormat;
	Size size;
};