From ff9276cc626dce468d0f2aa63a908a836a7a33d5 Mon Sep 17 00:00:00 2001 From: Umang Jain Date: Mon, 24 May 2021 14:50:18 +0530 Subject: ipa: Move core IPA interface documentation to a .cpp file Moving the core.mojom documentation to its corresponding .cpp file (core_ipa_interface.cpp). This will allow Doxygen to generate the documentation for IPABuffer, IPASettings and IPAStream structures. Since the .mojom files are placed in include/ directory, the .cpp file will live in $sourcedir/src/libcamera/ipa/ - which can also contain documentation for other mojom generated IPA interfaces in subsequent commit. Also hide the constructors in generated IPA interface from doxygen, via #ifndef __DOXYGEN__. These constructors provide no major value in documenting them, instead will spew out doxygen warnings during the build. Signed-off-by: Umang Jain Acked-by: Kieran Bingham Reviewed-by: Laurent Pinchart Reviewed-by: Paul Elder Signed-off-by: Laurent Pinchart --- Documentation/Doxyfile.in | 8 +- Documentation/meson.build | 1 + include/libcamera/ipa/core.mojom | 72 ----------------- include/libcamera/ipa/ipu3.mojom | 5 ++ include/libcamera/ipa/raspberrypi.mojom | 5 ++ include/libcamera/ipa/rkisp1.mojom | 5 ++ include/libcamera/ipa/vimc.mojom | 5 ++ src/libcamera/ipa/core_ipa_interface.cpp | 89 ++++++++++++++++++++++ src/libcamera/ipa/meson.build | 5 ++ src/libcamera/meson.build | 1 + .../libcamera_templates/definition_functions.tmpl | 3 + 11 files changed, 125 insertions(+), 74 deletions(-) create mode 100644 src/libcamera/ipa/core_ipa_interface.cpp create mode 100644 src/libcamera/ipa/meson.build diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in index af006724..8305f56a 100644 --- a/Documentation/Doxyfile.in +++ b/Documentation/Doxyfile.in @@ -844,7 +844,6 @@ EXCLUDE = @TOP_SRCDIR@/include/libcamera/span.h \ @TOP_SRCDIR@/src/libcamera/pipeline/ \ @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \ @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \ - @TOP_BUILDDIR@/include/libcamera/ipa/ \ @TOP_BUILDDIR@/src/libcamera/proxy/ # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or @@ -861,7 +860,12 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = @TOP_BUILDDIR@/include/libcamera/ipa/*_serializer.h \ + @TOP_BUILDDIR@/include/libcamera/ipa/*_proxy.h \ + @TOP_BUILDDIR@/include/libcamera/ipa/ipu3_*.h \ + @TOP_BUILDDIR@/include/libcamera/ipa/raspberrypi_*.h \ + @TOP_BUILDDIR@/include/libcamera/ipa/rkisp1_*.h \ + @TOP_BUILDDIR@/include/libcamera/ipa/vimc_*.h \ # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the diff --git a/Documentation/meson.build b/Documentation/meson.build index c8521574..9ecf4dfc 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -24,6 +24,7 @@ if doxygen.found() and dot.found() doxyfile, libcamera_internal_headers, libcamera_ipa_headers, + libcamera_ipa_interfaces, libcamera_public_headers, libcamera_sources, libipa_headers, diff --git a/include/libcamera/ipa/core.mojom b/include/libcamera/ipa/core.mojom index 6caaa63e..e49815d8 100644 --- a/include/libcamera/ipa/core.mojom +++ b/include/libcamera/ipa/core.mojom @@ -94,88 +94,16 @@ module libcamera; 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 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() method. 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; diff --git a/include/libcamera/ipa/ipu3.mojom b/include/libcamera/ipa/ipu3.mojom index a717b1e6..9e3cd885 100644 --- a/include/libcamera/ipa/ipu3.mojom +++ b/include/libcamera/ipa/ipu3.mojom @@ -1,5 +1,10 @@ /* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * \todo Document the interface as src/libcamera/ipa/ipu3_ipa_interface.cpp + * and remove the EXCLUDE_PATTERNS entry in Doxygen.in for its generation. + */ + module ipa.ipu3; import "include/libcamera/ipa/core.mojom"; diff --git a/include/libcamera/ipa/raspberrypi.mojom b/include/libcamera/ipa/raspberrypi.mojom index 42321bee..770e3049 100644 --- a/include/libcamera/ipa/raspberrypi.mojom +++ b/include/libcamera/ipa/raspberrypi.mojom @@ -1,5 +1,10 @@ /* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * \todo Document the interface as src/libcamera/ipa/raspberrypi_ipa_interface.cpp + * and remove the EXCLUDE_PATTERNS entry in Doxygen.in for its generation. + */ + module ipa.RPi; import "include/libcamera/ipa/core.mojom"; diff --git a/include/libcamera/ipa/rkisp1.mojom b/include/libcamera/ipa/rkisp1.mojom index cca871a0..da6646df 100644 --- a/include/libcamera/ipa/rkisp1.mojom +++ b/include/libcamera/ipa/rkisp1.mojom @@ -1,5 +1,10 @@ /* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * \todo Document the interface as src/libcamera/ipa/rkisp1_ipa_interface.cpp + * and remove the EXCLUDE_PATTERNS entry in Doxygen.in for its generation. + */ + module ipa.rkisp1; import "include/libcamera/ipa/core.mojom"; diff --git a/include/libcamera/ipa/vimc.mojom b/include/libcamera/ipa/vimc.mojom index be4b85b8..9ffd93bb 100644 --- a/include/libcamera/ipa/vimc.mojom +++ b/include/libcamera/ipa/vimc.mojom @@ -1,5 +1,10 @@ /* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * \todo Document the interface as src/libcamera/ipa/vimc_ipa_interface.cpp + * and remove the EXCLUDE_PATTERNS entry in Doxygen.in for its generation. + */ + module ipa.vimc; import "include/libcamera/ipa/core.mojom"; diff --git a/src/libcamera/ipa/core_ipa_interface.cpp b/src/libcamera/ipa/core_ipa_interface.cpp new file mode 100644 index 00000000..a6711e0e --- /dev/null +++ b/src/libcamera/ipa/core_ipa_interface.cpp @@ -0,0 +1,89 @@ +/* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * Copyright (C) 2021, Google Inc. + * + * core_ipa_interface.cpp - Docs file for core.mojom generated header + */ + +namespace libcamera { + +/** + * \file core_ipa_interface.h + * \brief Core IPA inteface + */ + +/** + * \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 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 IPAStream + * \brief Stream configuration for the IPA interface + * + * The IPAStream structure stores stream configuration parameters needed by the + * IPAInterface::configure() method. 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 + */ + +} /* namespace libcamera */ diff --git a/src/libcamera/ipa/meson.build b/src/libcamera/ipa/meson.build new file mode 100644 index 00000000..560b2fdd --- /dev/null +++ b/src/libcamera/ipa/meson.build @@ -0,0 +1,5 @@ +# SPDX-License-Identifier: CC0-1.0 + +libcamera_ipa_interfaces = files([ + 'core_ipa_interface.cpp', +]) diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build index 5a41816e..cc2b8669 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -66,6 +66,7 @@ includes = [ libcamera_includes, ] +subdir('ipa') subdir('pipeline') subdir('proxy') diff --git a/utils/ipc/generators/libcamera_templates/definition_functions.tmpl b/utils/ipc/generators/libcamera_templates/definition_functions.tmpl index cdd75f89..94bb4918 100644 --- a/utils/ipc/generators/libcamera_templates/definition_functions.tmpl +++ b/utils/ipc/generators/libcamera_templates/definition_functions.tmpl @@ -25,6 +25,7 @@ enum {{enum.mojom_name}} { struct {{struct.mojom_name}} { public: +#ifndef __DOXYGEN__ {{struct.mojom_name}}() {%- if struct|has_default_fields %} :{% endif %} {%- for field in struct.fields|with_default_values -%} @@ -44,6 +45,8 @@ public: {%- endfor %} { } +#endif + {% for field in struct.fields %} {{field|name}} {{field.mojom_name}}; {%- endfor %} -- cgit v1.2.1