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

module libcamera;

/*
 * Things that can be defined here (and in other mojom files):
 * - consts
 * - enums
 * - structs
 *
 * Attributes:
 * - skipHeader - structs only, and only in core.mojom
 *   - designate that this struct shall not have a C++ header definition
 *     generated
 * - skipSerdes - structs only, and only in core.mojom
 *   - designate that this struct shall not have a (de)serializer generated
 *   - all fields need a (de)serializer to be defined, either hand-written
 *     in ipa_data_serializer.h
 * - hasFd - struct fields or empty structs only
 *   - designate that this field or empty struct contains a FileDescriptor
 *
 * Rules:
 * - Any struct that is used in a struct definition in mojom must also be
 *   defined in mojom
 *   - If the struct has both a definition in a C++ header and a (de)serializer
 *     in ipa_data_serializer.h, then the struct shall be declared as empty,
 *     with both the [skipHeader] and [skipSerdes] attributes
 *   - If the struct only has a definition in a C++ header, but no
 *     (de)serializer, then the struct definition should have the [skipHeader]
 *     attribute
 * - Nested structures (e.g. FrameBuffer::Plane) cannot be defined in mojom.
 *   - Avoid them, by defining them in a header in C++ and a (de)serializer in
 *     ipa_data_serializer.h
 * - If a struct is in an array/map inside a struct, then the struct that is
 *   the member of the array/map does not need a mojom definition if it is
 *   defined in a C++ header.
 *   - This can be used to embed nested structures. The C++ double colon is
 *     replaced with a dot (e.g. FrameBuffer::Plane -> FrameBuffer.Plane)
 *   - The struct must still be defined in a header in C++ and a (de)serializer
 *     implemented in ipa_data_serializer.h, as it cannot be defined in mojom
 * - [skipHeader] and [skipSerdes] only work here in core.mojom.
 * - If a struct definition has [skipHeader], then the header where the
 *   struct is defined must be #included in ipa_interface.h
 * - If a field in a struct has a FileDescriptor, 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 FileDescriptor {};

[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;
};

[skipHeader] struct CameraSensorInfo {
	string model;

	uint32 bitsPerPixel;

	Size activeAreaSize;
	Rectangle analogCrop;
	Size outputSize;

	uint64 pixelRate;
	uint32 lineLength;

	uint32 minFrameLength;
	uint32 maxFrameLength;
};

struct IPABuffer {
	uint32 id;
	[hasFd] array<FrameBuffer.Plane> planes;
};

struct IPASettings {
	string configurationFile;
	string sensorModel;
};

struct IPAStream {
	uint32 pixelFormat;
	Size size;
};

/**
 * \fn IPAInterface::init()
 * \brief Initialise the IPAInterface
 * \param[in] settings The IPA initialization settings
 *
 * This function initializes the IPA interface. It shall be called before any
 * other function of the IPAInterface. The \a settings carry initialization
 * parameters that are valid for the whole life time of the IPA interface.
 */

/**
 * \fn IPAInterface::stop()
 * \brief Stop the IPA
 *
 * This method informs the IPA module that the camera is stopped. The IPA module
 * shall release resources prepared in start().
 */