From patchwork Fri Jan 5 16:41:00 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Scally X-Patchwork-Id: 19372 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id B083EC3240 for ; Fri, 5 Jan 2024 16:41:25 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 179D562B32; Fri, 5 Jan 2024 17:41:24 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1704472884; bh=AHU7PEquIJrGoeUzU1Luatu5O8VnvlbsJg5NrXatAKA=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=CX7QZB8EYzb7B7rOyn/sFSB9w2BsDBOZxA0na8yp+FKlNLTFxPQf4YCi3BN0XONTQ 2MnsrfcffRe7z8BNKAHjDG3N9Zj0dQY4CEcRpu58Kb2+Er/qyK+QTy7/sMPm/xP0wY 62owd0t2qeBlkS+B3ESocjr1jHLMpogOel+oqi6sDnKKrrLOPF+eKSIk5MeSHM7TO8 qHgwRaeUrWYd4UDr9MhOO634a3tNZfRscOpgyd/xBF2G6cCymbfPDeLnHUFIOp7WhP 94zBYgCDtNo2iFSiqGCJU1DyxWNueQUll8I9W/OxDK1KIGYgnSYkYeVe//LTzsrh8B OH2OKQ+XMPfWg== Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id EF96161D81 for ; Fri, 5 Jan 2024 17:41:21 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="Ehe07KGM"; dkim-atps=neutral Received: from mail.ideasonboard.com (cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 5CD54D49; Fri, 5 Jan 2024 17:40:20 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1704472820; bh=AHU7PEquIJrGoeUzU1Luatu5O8VnvlbsJg5NrXatAKA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Ehe07KGMZWSaz7FRTIdjqN1OI7DKm9XzpeR5WOiWofXw45Zgo89I6Y1ukg2LUYO8P ip92/iHWE97Lggw3WJ0s2r4772E7Lk1DwYtNaS3ZdSBmgcy9jk8V3C1tdUkauxluky VS3G6BRqpyJN3yenG8V3ihhNytpELF/FVjv/K1XE= To: libcamera-devel@lists.libcamera.org Date: Fri, 5 Jan 2024 16:41:00 +0000 Message-Id: <20240105164104.78398-2-dan.scally@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240105164104.78398-1-dan.scally@ideasonboard.com> References: <20240105164104.78398-1-dan.scally@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v2 1/5] libcamera: geometry: Correct doxygen reference to classes X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Daniel Scally via libcamera-devel From: Dan Scally Reply-To: Daniel Scally Cc: Jacopo Mondi Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The classes Rectangle, Size and SizeRange are referenced with \struct in the doxygen comments in geometry.cpp. Correct the reference to \class to better reflect their definition. Reviewed-by: Jacopo Mondi Reviewed-by: Laurent Pinchart Signed-off-by: Daniel Scally --- Changes in v2: - None src/libcamera/geometry.cpp | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libcamera/geometry.cpp b/src/libcamera/geometry.cpp index e50b46c5..8d85b758 100644 --- a/src/libcamera/geometry.cpp +++ b/src/libcamera/geometry.cpp @@ -95,10 +95,10 @@ std::ostream &operator<<(std::ostream &out, const Point &p) } /** - * \struct Size + * \class Size * \brief Describe a two-dimensional size * - * The Size structure defines a two-dimensional size with integer precision. + * The Size class defines a two-dimensional size with integer precision. */ /** @@ -455,7 +455,7 @@ std::ostream &operator<<(std::ostream &out, const Size &s) } /** - * \struct SizeRange + * \class SizeRange * \brief Describe a range of sizes * * A SizeRange describes a range of sizes included in the [min, max] interval @@ -589,7 +589,7 @@ std::ostream &operator<<(std::ostream &out, const SizeRange &sr) } /** - * \struct Rectangle + * \class Rectangle * \brief Describe a rectangle's position and dimensions * * Rectangles are used to identify an area of an image. They are specified by From patchwork Fri Jan 5 16:41:01 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Scally X-Patchwork-Id: 19373 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 4C06CC323E for ; Fri, 5 Jan 2024 16:41:28 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id EC8D862B40; Fri, 5 Jan 2024 17:41:27 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1704472888; bh=dwk3a9Y6xmTw3MwEuLMpOLZJyTebEKOIj/0Y3l2S380=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=brZWX7VET8xjhuBzoGfw9AFMsFSXwos/k08zDIeRSmvvUeSJ7qnYbvqARIsEhFWIY 92DFVPIeJQApeAX/m7HxnhwobVAHpDLgWcZsEFmDb0cQT6t8CLcgJR1EltvVrtr8S6 NMnWXRWlHYKMIOMBV6Fe8Abu91CzwpPfPvRdMq2o9L/rfjITrPSPQ4NOwjNmvMG/N8 uMz/8F33antot873F0UUwYUvxcgLXX5NGydue8Z2F/G/SzU/82C43BBV7EV5EZgdxb tELgxsGv7jNNnVP+n69m9BZXY4mYPRKtO+UINaxWjcbAKWEfGkYnb599LGGyjP2AlH CDFnIyu7siZnw== Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 5CD4E61D7F for ; Fri, 5 Jan 2024 17:41:22 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="Leo7BAL4"; dkim-atps=neutral Received: from mail.ideasonboard.com (cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id DE14F720; Fri, 5 Jan 2024 17:40:20 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1704472821; bh=dwk3a9Y6xmTw3MwEuLMpOLZJyTebEKOIj/0Y3l2S380=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Leo7BAL4E2ULe2UiD1Srh3VJQSSw85YjTwhkvLeMZxT2vDEy1GacROI64jmyBbkhn MVd1+fvqFMntN9+Xl3Sm36wMDjPtiFnIS5PuxVZS3AdV1Y1wqOWkMjJJDMqlrxdY1S z+0bnxmdzorc32fNkO7ET5P7Yta5ZEp2iAvThu0c= To: libcamera-devel@lists.libcamera.org Date: Fri, 5 Jan 2024 16:41:01 +0000 Message-Id: <20240105164104.78398-3-dan.scally@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240105164104.78398-1-dan.scally@ideasonboard.com> References: <20240105164104.78398-1-dan.scally@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v2 2/5] meson: libcamera: Split public and internal source arrays X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Daniel Scally via libcamera-devel From: Dan Scally Reply-To: Daniel Scally Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Meson array variables hold lists of libcamera's source files. To help facilitate the splitting of Doxygen generated documentation into distinct public and internal versions, split those arrays to separate public and internal variables. Signed-off-by: Daniel Scally Reviewed-by: Kieran Bingham --- Changes in v2: - New patch include/libcamera/base/meson.build | 2 +- include/libcamera/internal/meson.build | 21 +++++++++++---- src/libcamera/base/meson.build | 24 +++++++++++------ src/libcamera/meson.build | 36 ++++++++++++++++---------- 4 files changed, 55 insertions(+), 28 deletions(-) diff --git a/include/libcamera/base/meson.build b/include/libcamera/base/meson.build index bace25d5..f24f47de 100644 --- a/include/libcamera/base/meson.build +++ b/include/libcamera/base/meson.build @@ -10,7 +10,6 @@ libcamera_base_public_headers = files([ 'object.h', 'shared_fd.h', 'signal.h', - 'span.h', 'unique_fd.h', ]) @@ -25,6 +24,7 @@ libcamera_base_private_headers = files([ 'mutex.h', 'private.h', 'semaphore.h', + 'span.h', 'thread.h', 'thread_annotations.h', 'timer.h', diff --git a/include/libcamera/internal/meson.build b/include/libcamera/internal/meson.build index 7f1f3440..4d59cb2a 100644 --- a/include/libcamera/internal/meson.build +++ b/include/libcamera/internal/meson.build @@ -9,13 +9,21 @@ libcamera_tracepoint_header = custom_target( command : [gen_tracepoints_header, include_build_dir, '@OUTPUT@', '@INPUT@'], ) -libcamera_internal_headers = files([ +# Where libcamera's public API classes have Extensible::Private counterparts we +# need to include them in doxygen's public API run or it will complain that the +# functions defined in the "public" source are undeclared. +libcamera_internal_headers_publically_documented = files([ + 'camera.h', + 'camera_manager.h', + 'framebuffer.h', + 'request.h', +]) + +libcamera_internal_headers_publically_undocumented = files([ 'bayer_format.h', 'byte_stream_buffer.h', - 'camera.h', 'camera_controls.h', 'camera_lens.h', - 'camera_manager.h', 'camera_sensor.h', 'camera_sensor_properties.h', 'control_serializer.h', @@ -26,7 +34,6 @@ libcamera_internal_headers = files([ 'device_enumerator_sysfs.h', 'device_enumerator_udev.h', 'formats.h', - 'framebuffer.h', 'ipa_manager.h', 'ipa_module.h', 'ipa_proxy.h', @@ -37,7 +44,6 @@ libcamera_internal_headers = files([ 'pipeline_handler.h', 'process.h', 'pub_key.h', - 'request.h', 'source_paths.h', 'sysfs.h', 'v4l2_device.h', @@ -47,4 +53,9 @@ libcamera_internal_headers = files([ 'yaml_parser.h', ]) +libcamera_internal_headers = [ + libcamera_internal_headers_publically_documented, + libcamera_internal_headers_publically_undocumented +] + subdir('converter') diff --git a/src/libcamera/base/meson.build b/src/libcamera/base/meson.build index 7a7fd7e4..523c5885 100644 --- a/src/libcamera/base/meson.build +++ b/src/libcamera/base/meson.build @@ -1,27 +1,35 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_base_sources = files([ - 'backtrace.cpp', - 'class.cpp', +libcamera_base_public_sources = files([ 'bound_method.cpp', + 'class.cpp', + 'flags.cpp', + 'object.cpp', + 'shared_fd.cpp', + 'signal.cpp', + 'unique_fd.cpp', +]) + +libcamera_base_internal_sources = files([ + 'backtrace.cpp', 'event_dispatcher.cpp', 'event_dispatcher_poll.cpp', 'event_notifier.cpp', 'file.cpp', - 'flags.cpp', 'log.cpp', 'message.cpp', 'mutex.cpp', - 'object.cpp', 'semaphore.cpp', - 'shared_fd.cpp', - 'signal.cpp', 'thread.cpp', 'timer.cpp', - 'unique_fd.cpp', 'utils.cpp', ]) +libcamera_base_sources = [ + libcamera_base_public_sources, + libcamera_base_internal_sources +] + libdw = dependency('libdw', required : false) libunwind = dependency('libunwind', required : false) diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build index 45f63e93..676470c1 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -1,27 +1,35 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources = files([ +libcamera_public_sources = files([ + 'camera.cpp', + 'camera_manager.cpp', + 'color_space.cpp', + 'controls.cpp', + 'fence.cpp', + 'framebuffer.cpp', + 'framebuffer_allocator.cpp', + 'geometry.cpp', + 'orientation.cpp', + 'pixel_format.cpp', + 'request.cpp', + 'stream.cpp', + 'transform.cpp', +]) + +libcamera_internal_sources = files([ 'bayer_format.cpp', 'byte_stream_buffer.cpp', - 'camera.cpp', 'camera_controls.cpp', 'camera_lens.cpp', - 'camera_manager.cpp', 'camera_sensor.cpp', 'camera_sensor_properties.cpp', - 'color_space.cpp', - 'controls.cpp', 'control_serializer.cpp', 'control_validator.cpp', 'converter.cpp', 'delayed_controls.cpp', 'device_enumerator.cpp', 'device_enumerator_sysfs.cpp', - 'fence.cpp', 'formats.cpp', - 'framebuffer.cpp', - 'framebuffer_allocator.cpp', - 'geometry.cpp', 'ipa_controls.cpp', 'ipa_data_serializer.cpp', 'ipa_interface.cpp', @@ -34,16 +42,11 @@ libcamera_sources = files([ 'mapped_framebuffer.cpp', 'media_device.cpp', 'media_object.cpp', - 'orientation.cpp', 'pipeline_handler.cpp', - 'pixel_format.cpp', 'process.cpp', 'pub_key.cpp', - 'request.cpp', 'source_paths.cpp', - 'stream.cpp', 'sysfs.cpp', - 'transform.cpp', 'v4l2_device.cpp', 'v4l2_pixelformat.cpp', 'v4l2_subdevice.cpp', @@ -51,6 +54,11 @@ libcamera_sources = files([ 'yaml_parser.cpp', ]) +libcamera_sources = [ + libcamera_public_sources, + libcamera_internal_sources +] + libcamera_sources += libcamera_public_headers libcamera_sources += libcamera_generated_ipa_headers libcamera_sources += libcamera_tracepoint_header From patchwork Fri Jan 5 16:41:02 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Scally X-Patchwork-Id: 19374 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id EAC1AC32BC for ; Fri, 5 Jan 2024 16:41:28 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 7DA2E62B53; Fri, 5 Jan 2024 17:41:28 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1704472888; bh=oF2MZX1y0uQraRg0qMd6I/qnzRrOIfwYV/WDvHqU/aA=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=vevVRGA4ic+CjOCPcpoOwYm66/IEvFem6PhG5jeEK1XE4SAO6DqJec9Z/Oi3rT2Sm C48HInWZj0QgmcReMSSttLbC7t8PWVWOMiMGEI1fs8d18mmAEXh6qTkWP5pugL9yOg yVY+2Pd8krNDxJ2AEBcY+CIqwZpF4somCVvkI2uw+AGKLuU7HD+iQ5lmAWvB5aIU92 /VM/P7ItxdINahLlsggIHCMmfK8eJWYMzCZjX/kaRhTo2SstfuPyV7hxtDFjWqUOLl X+1OhaRsVWsb+sBkc7NPHCxeOHdtTJqHEUi15ijcx5x+XeFn7qfdPE/8kL8YUPzmvZ Kppx9k4zSoTpA== Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id B754662B49 for ; Fri, 5 Jan 2024 17:41:22 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="aJE7AVt2"; dkim-atps=neutral Received: from mail.ideasonboard.com (cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 50A8FD49; Fri, 5 Jan 2024 17:40:21 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1704472821; bh=oF2MZX1y0uQraRg0qMd6I/qnzRrOIfwYV/WDvHqU/aA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=aJE7AVt25UZcSv9oD3ahFUVZDP621em9Gg91ojpgSvulXU0dV/hr/6+eqLeaPOaCx mvXkEw0jh6xhkryggVFqx1syu9BVemlHJITRDzbLD6dtRQEJHUsLMN/Y0CMKT9L+sV U49agvfBdCHXlJRChF0RTkAn2ZbjADgiNBuhSVoI= To: libcamera-devel@lists.libcamera.org Date: Fri, 5 Jan 2024 16:41:02 +0000 Message-Id: <20240105164104.78398-4-dan.scally@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240105164104.78398-1-dan.scally@ideasonboard.com> References: <20240105164104.78398-1-dan.scally@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v2 3/5] Documentation: Add Thread support page X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Daniel Scally via libcamera-devel From: Dan Scally Reply-To: Daniel Scally Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Move the Thread Support page and the section of the Thread class' documentation dealing with stopping threads from src/libcamera/base/thread.cpp to a dedicated .dox file at Documentation/. This is done to support the splitting of the Documentation into a public and internal version. With a separate page, references can be made to thread safety without having to include the Thread class in the doxygen run. Signed-off-by: Daniel Scally Reviewed-by: Jacopo Mondi Reviewed-by: Kieran Bingham --- Changes in v2: - New patch Documentation/Doxyfile.in | 6 +- Documentation/thread.dox | 122 +++++++++++++++++++++++++++++++++ src/libcamera/base/thread.cpp | 123 ---------------------------------- 3 files changed, 126 insertions(+), 125 deletions(-) create mode 100644 Documentation/thread.dox diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in index a86ea6c1..48fea8bc 100644 --- a/Documentation/Doxyfile.in +++ b/Documentation/Doxyfile.in @@ -21,7 +21,8 @@ CASE_SENSE_NAMES = YES QUIET = YES -INPUT = "@TOP_SRCDIR@/include/libcamera" \ +INPUT = "@TOP_SRCDIR@/Documentation" \ + "@TOP_SRCDIR@/include/libcamera" \ "@TOP_SRCDIR@/src/ipa/ipu3" \ "@TOP_SRCDIR@/src/ipa/libipa" \ "@TOP_SRCDIR@/src/libcamera" \ @@ -30,7 +31,8 @@ INPUT = "@TOP_SRCDIR@/include/libcamera" \ FILE_PATTERNS = *.c \ *.cpp \ - *.h + *.h \ + *.dox RECURSIVE = YES diff --git a/Documentation/thread.dox b/Documentation/thread.dox new file mode 100644 index 00000000..805a864e --- /dev/null +++ b/Documentation/thread.dox @@ -0,0 +1,122 @@ +/** + * \page thread Thread Support + * + * libcamera supports multi-threaded applications through a threading model that + * sets precise rules to guarantee thread-safe usage of the API. Additionally, + * libcamera makes internal use of threads, and offers APIs that simplify + * interactions with application threads. Careful compliance with the threading + * model will ensure avoidance of race conditions. + * + * Every thread created by libcamera is associated with an instance of the + * Thread class. Those threads run an internal event loop by default to + * dispatch events to objects. Additionally, the main thread of the application + * (defined as the thread that calls CameraManager::start()) is also associated + * with a Thread instance, but has no event loop accessible to libcamera. Other + * application threads are not visible to libcamera. + * + * \section thread-objects Threads and Objects + * + * Instances of the Object class and all its derived classes are thread-aware + * and are bound to the thread they are created in. They are said to *live* in + * a thread, and they interact with the event loop of their thread for the + * purpose of message passing and signal delivery. Messages posted to the + * object with Object::postMessage() will be delivered from the event loop of + * the thread that the object lives in. Signals delivered to the object, unless + * explicitly connected with ConnectionTypeDirect, will also be delivered from + * the object thread's event loop. + * + * All Object instances created internally by libcamera are bound to internal + * threads. As objects interact with thread event loops for proper operation, + * creating an Object instance in a thread that has no internal event loop (such + * as the main application thread, or libcamera threads that have a custom main + * loop), prevents some features of the Object class from being used. See + * Thread::exec() for more details. + * + * \section thread-signals Threads and Signals + * + * When sent to a receiver that does not inherit from the Object class, signals + * are delivered synchronously in the thread of the sender. When the receiver + * inherits from the Object class, delivery is by default asynchronous if the + * sender and receiver live in different threads. In that case, the signal is + * posted to the receiver's message queue and will be delivered from the + * receiver's event loop, running in the receiver's thread. This mechanism can + * be overridden by selecting a different connection type when calling + * Signal::connect(). + * + * \section thread-reentrancy Reentrancy and Thread-Safety + * + * Through the documentation, several terms are used to define how classes and + * their member functions can be used from multiple threads. + * + * - A **reentrant** function may be called simultaneously from multiple + * threads if and only if each invocation uses a different instance of the + * class. This is the default for all member functions not explictly marked + * otherwise. + * + * - \anchor thread-safe A **thread-safe** function may be called + * simultaneously from multiple threads on the same instance of a class. A + * thread-safe function is thus reentrant. Thread-safe functions may also be + * called simultaneously with any other reentrant function of the same class + * on the same instance. + * + * - \anchor thread-bound A **thread-bound** function may be called only from + * the thread that the class instances lives in (see section \ref + * thread-objects). For instances of classes that do not derive from the + * Object class, this is the thread in which the instance was created. A + * thread-bound function is not thread-safe, and may or may not be reentrant. + * + * Neither reentrancy nor thread-safety, in this context, mean that a function + * may be called simultaneously from the same thread, for instance from a + * callback invoked by the function. This may deadlock and isn't allowed unless + * separately documented. + * + * A class is defined as reentrant, thread-safe or thread-bound if all its + * member functions are reentrant, thread-safe or thread-bound respectively. + * Some member functions may additionally be documented as having additional + * thread-related attributes. + * + * Most classes are reentrant but not thread-safe, as making them fully + * thread-safe would incur locking costs considered prohibitive for the + * expected use cases. + * + * \section thread-stop Stopping Threads + * + * Threads can't be forcibly stopped. Instead, a thread user first requests the + * thread to exit and then waits for the thread's main function to react to the + * request and return, at which points the thread will stop. + * + * For threads running exec(), the exit() function is used to request the thread + * to exit. For threads subclassing the Thread class and implementing a custom + * run() function, a subclass-specific mechanism shall be provided. In either + * case, the wait() function shall be called to wait for the thread to stop. + * + * Due to their asynchronous nature, threads are subject to race conditions when + * they stop. This is of particular importance for messages posted to the thread + * with postMessage() (and the other mechanisms that rely on it, such as + * Object::invokeMethod() or asynchronous signal delivery). To understand the + * issues, three contexts need to be considered: + * + * - The worker is the Thread performing work and being instructed to stop. + * - The controller is the context which instructs the worker thread to stop. + * - The other contexts are any threads other than the worker and controller + * that interact with the worker thread. + * + * Messages posted to the worker thread from the controller context before + * calling exit() are queued to the thread's message queue, and the Thread class + * offers no guarantee that those messages will be processed before the thread + * stops. This allows threads to stop fast. + * + * A thread that requires delivery of messages posted from the controller + * context before exit() should reimplement the run() function and call + * dispatchMessages() after exec(). + * + * Messages posted to the worker thread from the other contexts are asynchronous + * with respect to the exit() call from the controller context. There is no + * guarantee as to whether those messages will be processed or not before the + * thread stops. + * + * Messages that are not processed will stay in the queue, in the exact same way + * as messages posted after the thread has stopped. They will be processed when + * the thread is restarted. If the thread is never restarted, they will be + * deleted without being processed when the Thread instance is destroyed. + */ diff --git a/src/libcamera/base/thread.cpp b/src/libcamera/base/thread.cpp index b96951ac..6b034e06 100644 --- a/src/libcamera/base/thread.cpp +++ b/src/libcamera/base/thread.cpp @@ -19,88 +19,6 @@ #include #include -/** - * \page thread Thread Support - * - * libcamera supports multi-threaded applications through a threading model that - * sets precise rules to guarantee thread-safe usage of the API. Additionally, - * libcamera makes internal use of threads, and offers APIs that simplify - * interactions with application threads. Careful compliance with the threading - * model will ensure avoidance of race conditions. - * - * Every thread created by libcamera is associated with an instance of the - * Thread class. Those threads run an internal event loop by default to - * dispatch events to objects. Additionally, the main thread of the application - * (defined as the thread that calls CameraManager::start()) is also associated - * with a Thread instance, but has no event loop accessible to libcamera. Other - * application threads are not visible to libcamera. - * - * \section thread-objects Threads and Objects - * - * Instances of the Object class and all its derived classes are thread-aware - * and are bound to the thread they are created in. They are said to *live* in - * a thread, and they interact with the event loop of their thread for the - * purpose of message passing and signal delivery. Messages posted to the - * object with Object::postMessage() will be delivered from the event loop of - * the thread that the object lives in. Signals delivered to the object, unless - * explicitly connected with ConnectionTypeDirect, will also be delivered from - * the object thread's event loop. - * - * All Object instances created internally by libcamera are bound to internal - * threads. As objects interact with thread event loops for proper operation, - * creating an Object instance in a thread that has no internal event loop (such - * as the main application thread, or libcamera threads that have a custom main - * loop), prevents some features of the Object class from being used. See - * Thread::exec() for more details. - * - * \section thread-signals Threads and Signals - * - * When sent to a receiver that does not inherit from the Object class, signals - * are delivered synchronously in the thread of the sender. When the receiver - * inherits from the Object class, delivery is by default asynchronous if the - * sender and receiver live in different threads. In that case, the signal is - * posted to the receiver's message queue and will be delivered from the - * receiver's event loop, running in the receiver's thread. This mechanism can - * be overridden by selecting a different connection type when calling - * Signal::connect(). - * - * \section thread-reentrancy Reentrancy and Thread-Safety - * - * Through the documentation, several terms are used to define how classes and - * their member functions can be used from multiple threads. - * - * - A **reentrant** function may be called simultaneously from multiple - * threads if and only if each invocation uses a different instance of the - * class. This is the default for all member functions not explictly marked - * otherwise. - * - * - \anchor thread-safe A **thread-safe** function may be called - * simultaneously from multiple threads on the same instance of a class. A - * thread-safe function is thus reentrant. Thread-safe functions may also be - * called simultaneously with any other reentrant function of the same class - * on the same instance. - * - * - \anchor thread-bound A **thread-bound** function may be called only from - * the thread that the class instances lives in (see section \ref - * thread-objects). For instances of classes that do not derive from the - * Object class, this is the thread in which the instance was created. A - * thread-bound function is not thread-safe, and may or may not be reentrant. - * - * Neither reentrancy nor thread-safety, in this context, mean that a function - * may be called simultaneously from the same thread, for instance from a - * callback invoked by the function. This may deadlock and isn't allowed unless - * separately documented. - * - * A class is defined as reentrant, thread-safe or thread-bound if all its - * member functions are reentrant, thread-safe or thread-bound respectively. - * Some member functions may additionally be documented as having additional - * thread-related attributes. - * - * Most classes are reentrant but not thread-safe, as making them fully - * thread-safe would incur locking costs considered prohibitive for the - * expected use cases. - */ - /** * \file base/thread.h * \brief Thread support @@ -216,47 +134,6 @@ ThreadData *ThreadData::current() * called. The event loop dispatches events (messages, notifiers and timers) * sent to the objects living in the thread. This behaviour can be modified by * overriding the run() function. - * - * \section thread-stop Stopping Threads - * - * Threads can't be forcibly stopped. Instead, a thread user first requests the - * thread to exit and then waits for the thread's main function to react to the - * request and return, at which points the thread will stop. - * - * For threads running exec(), the exit() function is used to request the thread - * to exit. For threads subclassing the Thread class and implementing a custom - * run() function, a subclass-specific mechanism shall be provided. In either - * case, the wait() function shall be called to wait for the thread to stop. - * - * Due to their asynchronous nature, threads are subject to race conditions when - * they stop. This is of particular importance for messages posted to the thread - * with postMessage() (and the other mechanisms that rely on it, such as - * Object::invokeMethod() or asynchronous signal delivery). To understand the - * issues, three contexts need to be considered: - * - * - The worker is the Thread performing work and being instructed to stop. - * - The controller is the context which instructs the worker thread to stop. - * - The other contexts are any threads other than the worker and controller - * that interact with the worker thread. - * - * Messages posted to the worker thread from the controller context before - * calling exit() are queued to the thread's message queue, and the Thread class - * offers no guarantee that those messages will be processed before the thread - * stops. This allows threads to stop fast. - * - * A thread that requires delivery of messages posted from the controller - * context before exit() should reimplement the run() function and call - * dispatchMessages() after exec(). - * - * Messages posted to the worker thread from the other contexts are asynchronous - * with respect to the exit() call from the controller context. There is no - * guarantee as to whether those messages will be processed or not before the - * thread stops. - * - * Messages that are not processed will stay in the queue, in the exact same way - * as messages posted after the thread has stopped. They will be processed when - * the thread is restarted. If the thread is never restarted, they will be - * deleted without being processed when the Thread instance is destroyed. */ /** From patchwork Fri Jan 5 16:41:03 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Scally X-Patchwork-Id: 19375 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id B24B0C3240 for ; Fri, 5 Jan 2024 16:41:29 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 3A85362B5B; Fri, 5 Jan 2024 17:41:29 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1704472889; bh=NQpHMPwALrL+ZuhT+DAkDG8pXbOrNIfX059XoVyzUEo=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=LSbiJFcIVfKhdV7Heg34TFwzHSjMPayCsuTOAc1soDBeOC2LkjlgvRZFMtsZPJBCv lZ6qqFZMZsYNfPdtQEhhbpd3DWgLeLz9bo5xZ5UbdYsBRj+e3zlFej/pCRWwnFMRll FjV+OhrseBKnJxLvUuXxwsrOOiudIJNtK4PjU7Ai/UoxHDcsw3rfrXPq38NQJ08NDb ZkD3PQgrggeUAo4qKatJwTu3AkIXtSMUpjF8Gdb+QTGCToJL7TRD4pkvP00zT1Z6ni Bl+GAcSZWxgC+FYr+yk5kF9JvCqcE4JHwwslMTpeDTK3Ed7m8CtS23vqxClcudVHt6 /nkCpABpqpXbw== Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 1785B61D7F for ; Fri, 5 Jan 2024 17:41:23 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="KUmm9/b5"; dkim-atps=neutral Received: from mail.ideasonboard.com (cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id AB145720; Fri, 5 Jan 2024 17:40:21 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1704472821; bh=NQpHMPwALrL+ZuhT+DAkDG8pXbOrNIfX059XoVyzUEo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KUmm9/b5+ISDuBMJwlR4ej76KNpVQK1zHau2IDnSGQQqMoDYBLtot1oD6sgyIor9h 0My1NQb58+G2A99Ki55J2kfxwhrwu7RE1cofZAKq/NgepSqa6qbKeDlbJJlhkulLRT RBH149bfDK4eZx7laUXdUqmu6mKkK1whAXy69KlE= To: libcamera-devel@lists.libcamera.org Date: Fri, 5 Jan 2024 16:41:03 +0000 Message-Id: <20240105164104.78398-5-dan.scally@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240105164104.78398-1-dan.scally@ideasonboard.com> References: <20240105164104.78398-1-dan.scally@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v2 4/5] libcamera: Documentation: Split public/private documentation X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Daniel Scally via libcamera-devel From: Dan Scally Reply-To: Daniel Scally Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The API reference pages generated by Doxygen are comprehensive, but therefore quite overwhelming for application developers who will likely never need to use the majority of the library's objects. To reduce the complexity of the documentation, split it into two runs of doxygen. In the first run of doxygen we pass a specific list of source files to parse, which is built from the File arrays in Meson's build files. This ensures that we only generate the documentation for code from those files. In the second run allow doxygen to generate documentation for all of the library's objects as it currently does. This set will now be output into build/Documentation/internal-api-html. Signed-off-by: Daniel Scally Reviewed-by: Jacopo Mondi Reviewed-by: Kieran Bingham --- Changes in v2: - Formatting fixes (Jacopo) - Phraseology (Laurent) - Switched to passing specific files to parse to doxygen rather than relying on \internal to remove other docu-comments. Documentation/Doxyfile-internal.in | 21 +++++++ Documentation/Doxyfile-public.in | 5 ++ Documentation/Doxyfile.in | 26 ++------- Documentation/meson.build | 76 +++++++++++++++++++++++--- include/libcamera/base/meson.build | 7 +++ include/libcamera/internal/meson.build | 7 +++ include/libcamera/meson.build | 10 ++++ meson.build | 8 +++ src/libcamera/base/class.cpp | 1 + src/libcamera/base/meson.build | 7 +++ src/libcamera/camera.cpp | 7 +++ src/libcamera/camera_manager.cpp | 1 + src/libcamera/framebuffer.cpp | 6 +- src/libcamera/meson.build | 7 +++ src/libcamera/request.cpp | 1 + 15 files changed, 160 insertions(+), 30 deletions(-) create mode 100644 Documentation/Doxyfile-internal.in create mode 100644 Documentation/Doxyfile-public.in diff --git a/Documentation/Doxyfile-internal.in b/Documentation/Doxyfile-internal.in new file mode 100644 index 00000000..7b3cce49 --- /dev/null +++ b/Documentation/Doxyfile-internal.in @@ -0,0 +1,21 @@ +# SPDX-License-Identifier: CC-BY-SA-4.0 + +INPUT = "@TOP_SRCDIR@/Documentation" \ + "@TOP_SRCDIR@/include/libcamera" \ + "@TOP_SRCDIR@/src/ipa/ipu3" \ + "@TOP_SRCDIR@/src/ipa/libipa" \ + "@TOP_SRCDIR@/src/libcamera" \ + "@TOP_BUILDDIR@/include/libcamera" \ + "@TOP_BUILDDIR@/src/libcamera" + +EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/span.h \ + @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_sysfs.h \ + @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_udev.h \ + @TOP_SRCDIR@/include/libcamera/internal/ipc_pipe_unixsocket.h \ + @TOP_SRCDIR@/src/libcamera/device_enumerator_sysfs.cpp \ + @TOP_SRCDIR@/src/libcamera/device_enumerator_udev.cpp \ + @TOP_SRCDIR@/src/libcamera/ipc_pipe_unixsocket.cpp \ + @TOP_SRCDIR@/src/libcamera/pipeline/ \ + @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \ + @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \ + @TOP_BUILDDIR@/src/libcamera/proxy/ diff --git a/Documentation/Doxyfile-public.in b/Documentation/Doxyfile-public.in new file mode 100644 index 00000000..cdbc03a0 --- /dev/null +++ b/Documentation/Doxyfile-public.in @@ -0,0 +1,5 @@ +# SPDX-License-Identifier: CC-BY-SA-4.0 + +INPUT = "@TOP_SRCDIR@/Documentation" \ + "@INPUT@" \ + "@TOP_BUILDDIR@/src/libcamera/version.cpp" diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in index 48fea8bc..a271c7bc 100644 --- a/Documentation/Doxyfile.in +++ b/Documentation/Doxyfile.in @@ -21,14 +21,6 @@ CASE_SENSE_NAMES = YES QUIET = YES -INPUT = "@TOP_SRCDIR@/Documentation" \ - "@TOP_SRCDIR@/include/libcamera" \ - "@TOP_SRCDIR@/src/ipa/ipu3" \ - "@TOP_SRCDIR@/src/ipa/libipa" \ - "@TOP_SRCDIR@/src/libcamera" \ - "@TOP_BUILDDIR@/include/libcamera" \ - "@TOP_BUILDDIR@/src/libcamera" - FILE_PATTERNS = *.c \ *.cpp \ *.h \ @@ -36,17 +28,8 @@ FILE_PATTERNS = *.c \ RECURSIVE = YES -EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/span.h \ - @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_sysfs.h \ - @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_udev.h \ - @TOP_SRCDIR@/include/libcamera/internal/ipc_pipe_unixsocket.h \ - @TOP_SRCDIR@/src/libcamera/device_enumerator_sysfs.cpp \ - @TOP_SRCDIR@/src/libcamera/device_enumerator_udev.cpp \ - @TOP_SRCDIR@/src/libcamera/ipc_pipe_unixsocket.cpp \ - @TOP_SRCDIR@/src/libcamera/pipeline/ \ - @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \ - @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \ - @TOP_BUILDDIR@/src/libcamera/proxy/ +@INCLUDE_PATH = @TOP_BUILDDIR@/Documentation +@INCLUDE = @INCLUDE_FILE@ EXCLUDE_PATTERNS = @TOP_BUILDDIR@/include/libcamera/ipa/*_serializer.h \ @TOP_BUILDDIR@/include/libcamera/ipa/*_proxy.h \ @@ -70,7 +53,10 @@ EXCLUDE_SYMBOLS = libcamera::BoundMethodArgs \ EXCLUDE_SYMLINKS = YES -HTML_OUTPUT = api-html +HIDE_UNDOC_CLASSES = @HIDE_UNDOC_CLASSES@ +HIDE_UNDOC_MEMBERS = @HIDE_UNDOC_MEMBERS@ +HTML_OUTPUT = @HTML_OUTPUT@ +INTERNAL_DOCS = @INTERNAL_DOCS@ GENERATE_LATEX = NO diff --git a/Documentation/meson.build b/Documentation/meson.build index 7a58fec8..afaad751 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -23,12 +23,7 @@ if doxygen.found() and dot.found() cdata.set('PREDEFINED', ' \\\n\t\t\t '.join(doxygen_predefined)) - doxyfile = configure_file(input : 'Doxyfile.in', - output : 'Doxyfile', - configuration : cdata) - - doxygen_input = [ - doxyfile, + global_doxygen_input = [ libcamera_base_headers, libcamera_base_sources, libcamera_internal_headers, @@ -41,16 +36,79 @@ if doxygen.found() and dot.found() ] if is_variable('ipu3_ipa_sources') - doxygen_input += [ipu3_ipa_sources] + global_doxygen_input += [ipu3_ipa_sources] endif + # We need to generate two "include" files for the final Doxyfile which + # define a set of source files to use in the documentation parsing. We + # collected a list of the public sources in doxygen_public_sources, so we + # pass that to the doxyfiles so that Doxyfile-public refers only to those + # files. Although INPUT is sent to both, Doxyfile-internal.in doesn't refer + # to it and just hardcodes the directories to parse. + cdata.set('INPUT', '" \\\n\t\t\t "'.join(doxygen_public_sources)) + doxyfile_include_public = configure_file(input : 'Doxyfile-public.in', + output : 'Doxyfile-include-public', + configuration : cdata) + doxyfile_include_internal = configure_file(input : 'Doxyfile-internal.in', + output : 'Doxyfile-include-internal', + configuration : cdata) + + # We run doxygen twice - the first run excludes internal API objects as it + # is intended to document the public API only. A second run covers all of + # the library's objects for libcamera developers. To achieve this we need to + # flag as \internal some of the comments for objects which we wish to hide, + # and remove the auto generated documents via HIDE_UNDOC_CLASSES and + # HIDE_UNDOC_MEMBERS. + + cdata_public = configuration_data() + cdata_public.merge_from(cdata) + cdata_public.set('HIDE_UNDOC_CLASSES', 'YES') + cdata_public.set('HIDE_UNDOC_MEMBERS', 'YES') + cdata_public.set('HTML_OUTPUT', 'api-html') + cdata_public.set('INCLUDE_FILE', 'Doxyfile-include-public') + cdata_public.set('INTERNAL_DOCS', 'NO') + + doxyfile_public = configure_file(input : 'Doxyfile.in', + output : 'Doxyfile-public', + configuration : cdata_public) + + public_doxygen_input = global_doxygen_input + public_doxygen_input += doxyfile_public + custom_target('doxygen', - input : doxygen_input, + input : public_doxygen_input, output : 'api-html', - command : [doxygen, doxyfile], + command : [doxygen, doxyfile_public], install : true, install_dir : doc_install_dir, install_tag : 'doc') + + # This is the internal documentation, so _don't_ hide undocumented classes + # as we want everything to show up and warnings to be generated if any + # documentation is missing. + + cdata_internal = configuration_data() + cdata_internal.merge_from(cdata) + cdata_internal.set('HIDE_UNDOC_CLASSES', 'NO') + cdata_internal.set('HIDE_UNDOC_MEMBERS', 'NO') + cdata_internal.set('HTML_OUTPUT', 'internal-api-html') + cdata_internal.set('INCLUDE_FILE', 'Doxyfile-include-internal') + cdata_internal.set('INTERNAL_DOCS', 'YES') + + doxyfile_internal = configure_file(input : 'Doxyfile.in', + output : 'Doxyfile-internal', + configuration : cdata_internal) + + internal_doxygen_input = global_doxygen_input + internal_doxygen_input += doxyfile_internal + + custom_target('doxygen-internal', + input : internal_doxygen_input, + output : 'internal-api-html', + command : [doxygen, doxyfile_internal], + install : true, + install_dir : doc_install_dir, + install_tag : 'doc-internal') endif # diff --git a/include/libcamera/base/meson.build b/include/libcamera/base/meson.build index f24f47de..82277f46 100644 --- a/include/libcamera/base/meson.build +++ b/include/libcamera/base/meson.build @@ -38,3 +38,10 @@ libcamera_base_headers = [ install_headers(libcamera_base_public_headers, subdir : libcamera_base_include_dir) + +foreach lbph : libcamera_base_public_headers + doxygen_public_sources += '/'.join( + meson.project_source_root(), + '@0@'.format(lbph) + ) +endforeach diff --git a/include/libcamera/internal/meson.build b/include/libcamera/internal/meson.build index 4d59cb2a..4af36884 100644 --- a/include/libcamera/internal/meson.build +++ b/include/libcamera/internal/meson.build @@ -58,4 +58,11 @@ libcamera_internal_headers = [ libcamera_internal_headers_publically_undocumented ] +foreach lph : libcamera_internal_headers_publically_documented + doxygen_public_sources += '/'.join( + meson.project_source_root(), + '@0@'.format(lph) + ) +endforeach + subdir('converter') diff --git a/include/libcamera/meson.build b/include/libcamera/meson.build index bab858a3..25e2f8a4 100644 --- a/include/libcamera/meson.build +++ b/include/libcamera/meson.build @@ -26,6 +26,13 @@ subdir('ipa') install_headers(libcamera_public_headers, subdir : libcamera_include_dir) +foreach lph : libcamera_public_headers + doxygen_public_sources += '/'.join( + meson.project_source_root(), + '@0@'.format(lph) + ) +endforeach + # # Generate headers from templates. # @@ -85,6 +92,7 @@ foreach mode, entry : controls_map '-r', ranges_file, '@INPUT@'], install : true, install_dir : libcamera_headers_install_dir) + doxygen_public_sources += control_headers.get(-1).full_path() endforeach libcamera_public_headers += control_headers @@ -101,6 +109,7 @@ formats_h = custom_target('formats_h', install : true, install_dir : libcamera_headers_install_dir) libcamera_public_headers += formats_h +doxygen_public_sources += formats_h.full_path() # libcamera.h libcamera_h = custom_target('gen-header', @@ -111,6 +120,7 @@ libcamera_h = custom_target('gen-header', install_dir : libcamera_headers_install_dir) libcamera_public_headers += libcamera_h +doxygen_public_sources += libcamera_h.full_path() # version.h version = libcamera_version.split('.') diff --git a/meson.build b/meson.build index e49de4c2..cca1883e 100644 --- a/meson.build +++ b/meson.build @@ -231,6 +231,14 @@ endif # Utilities are parsed first to provide support for other components. subdir('utils') +# To support auto-generation of documentation We need an array of the paths to +# public headers and source files so that we can tell doxygen which files to +# look at later. Unfortunately the inclusion of custom targets in some of the +# existing arrays precludes using them directly and you cannot generate File +# objects from generated files, so we need to collect paths to relevant files +# within an array. +doxygen_public_sources = [] + subdir('include') subdir('src') diff --git a/src/libcamera/base/class.cpp b/src/libcamera/base/class.cpp index 9c2d9f21..70fd5cd5 100644 --- a/src/libcamera/base/class.cpp +++ b/src/libcamera/base/class.cpp @@ -184,6 +184,7 @@ Extensible::Extensible(std::unique_ptr d) */ /** + * \internal * \class Extensible::Private * \brief Base class for private data managed through a d-pointer */ diff --git a/src/libcamera/base/meson.build b/src/libcamera/base/meson.build index 523c5885..ae949a51 100644 --- a/src/libcamera/base/meson.build +++ b/src/libcamera/base/meson.build @@ -30,6 +30,13 @@ libcamera_base_sources = [ libcamera_base_internal_sources ] +foreach lbps : libcamera_base_public_sources + doxygen_public_sources += '/'.join( + meson.project_source_root(), + '@0@'.format(lbps) + ) +endforeach + libdw = dependency('libdw', required : false) libunwind = dependency('libunwind', required : false) diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp index 0ad1a4b5..ed46f853 100644 --- a/src/libcamera/camera.cpp +++ b/src/libcamera/camera.cpp @@ -560,6 +560,13 @@ CameraConfiguration::Status CameraConfiguration::validateColorSpaces(ColorSpaceF */ /** + * \internal + * \file libcamera\internal\camera.h + * \brief Internal Camera device handling + */ + +/** + * \internal * \class Camera::Private * \brief Base class for camera private data * diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp index 355f3ada..61d45256 100644 --- a/src/libcamera/camera_manager.cpp +++ b/src/libcamera/camera_manager.cpp @@ -23,6 +23,7 @@ */ /** + * \internal * \file libcamera/internal/camera_manager.h * \brief Internal camera manager support */ diff --git a/src/libcamera/framebuffer.cpp b/src/libcamera/framebuffer.cpp index 5a7f3c0b..db450e11 100644 --- a/src/libcamera/framebuffer.cpp +++ b/src/libcamera/framebuffer.cpp @@ -16,7 +16,10 @@ /** * \file libcamera/framebuffer.h * \brief Frame buffer handling - * + */ + +/** + * \internal * \file libcamera/internal/framebuffer.h * \brief Internal frame buffer handling support */ @@ -105,6 +108,7 @@ LOG_DEFINE_CATEGORY(Buffer) */ /** + * \internal * \class FrameBuffer::Private * \brief Base class for FrameBuffer private data * diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build index 676470c1..413e14db 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -59,6 +59,13 @@ libcamera_sources = [ libcamera_internal_sources ] +foreach lps : libcamera_public_sources + doxygen_public_sources += '/'.join( + meson.project_source_root(), + '@0@'.format(lps) + ) +endforeach + libcamera_sources += libcamera_public_headers libcamera_sources += libcamera_generated_ipa_headers libcamera_sources += libcamera_tracepoint_header diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp index 949c556f..930d8c92 100644 --- a/src/libcamera/request.cpp +++ b/src/libcamera/request.cpp @@ -33,6 +33,7 @@ namespace libcamera { LOG_DEFINE_CATEGORY(Request) /** + * \internal * \class Request::Private * \brief Request private data * From patchwork Fri Jan 5 16:41:04 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Scally X-Patchwork-Id: 19376 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 9F4F5C32BD for ; Fri, 5 Jan 2024 16:41:30 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 0FF3462B5C; Fri, 5 Jan 2024 17:41:30 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=libcamera.org; s=mail; t=1704472890; bh=vrwtTEGOTvWeWKk3iu+pHOPambWPQe0oO3irmpMVPSQ=; h=To:Date:In-Reply-To:References:Subject:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=RkgJXN6J2OUt1vVuorkO6F2Qnq9njYY+5hm66oeHei5vDGSkabKxfGsO7biLvQL83 YMmRoV/Uxm6ZX2i5yFfV/2apsiDgCszZtAxmryYTk2ZnHJoBWp+LcFzer1kYJB6Mcp B5krSkJwdtEujc7a+Bv+aU0Fs7zmnftQ8uGu04+4m8ukDymEPPXIxp9AD7kHCh6aD8 vWDXO1UNFpLkPb/WMLyQc+8tDr2PXGRIPJntEQotUUvYU+P+xCHasQ48oZWWxmYC79 6H0F7HTDgKWwZ4DmsNUrxxZoJSfYdp7oKA/zNANE7pOdrzS8zDNTcVVWOnM5Xv2FcS KbKNUmzVuBP2g== Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id B116F62B59 for ; Fri, 5 Jan 2024 17:41:23 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="hxAzKvus"; dkim-atps=neutral Received: from mail.ideasonboard.com (cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 0DEEAD49; Fri, 5 Jan 2024 17:40:22 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1704472822; bh=vrwtTEGOTvWeWKk3iu+pHOPambWPQe0oO3irmpMVPSQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hxAzKvusBttzmwFSyZKqOoqNg/dCf2vqBlVLGm9ivit4sc+GmGz4LxtiusfkusXvU AbwWyJ3ngNfhxvM6f+KIgUoeZgnrkHTAoAPeWEBWGij+hN0kp3YmpDCg47tn90rk33 Cwk3JiVQh5NxXjvDSL9aHHmrCMl5AZ6/dgUWAga8= To: libcamera-devel@lists.libcamera.org Date: Fri, 5 Jan 2024 16:41:04 +0000 Message-Id: <20240105164104.78398-6-dan.scally@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240105164104.78398-1-dan.scally@ideasonboard.com> References: <20240105164104.78398-1-dan.scally@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v2 5/5] libcamera: Documentation: Improve doxygen main page X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Daniel Scally via libcamera-devel From: Dan Scally Reply-To: Daniel Scally Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The "Main Page" of the doxygen generated API reference is currently totally empty. Expand it with some introductory text along with links to the developer's guide, application developer's guide and the pipeline and IPA module writer's guides. Provide an easy link to switch between the reduced public reference pages and the more complete internal ones. Signed-off-by: Daniel Scally Reviewed-by: Jacopo Mondi Reviewed-by: Kieran Bingham --- Changes in v2: - Changed the first paragraph to be more about what the documentation is than isn't (Jacopo) - Pushed the links to the guides into the \if internal block so that only the relevant one is presented. Documentation/Doxyfile.in | 1 + Documentation/libcamera.dox | 33 +++++++++++++++++++++++++++++++++ Documentation/meson.build | 2 ++ 3 files changed, 36 insertions(+) create mode 100644 Documentation/libcamera.dox diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in index a271c7bc..625d1e90 100644 --- a/Documentation/Doxyfile.in +++ b/Documentation/Doxyfile.in @@ -53,6 +53,7 @@ EXCLUDE_SYMBOLS = libcamera::BoundMethodArgs \ EXCLUDE_SYMLINKS = YES +ENABLED_SECTIONS = @ENABLED_SECTIONS@ HIDE_UNDOC_CLASSES = @HIDE_UNDOC_CLASSES@ HIDE_UNDOC_MEMBERS = @HIDE_UNDOC_MEMBERS@ HTML_OUTPUT = @HTML_OUTPUT@ diff --git a/Documentation/libcamera.dox b/Documentation/libcamera.dox new file mode 100644 index 00000000..d5a57653 --- /dev/null +++ b/Documentation/libcamera.dox @@ -0,0 +1,33 @@ +/** +\mainpage libcamera API reference + +Welcome to the API reference for libcamera, +a complex camera support library for Linux, Android and ChromeOS. These pages +are automatically generated from the libcamera source code and describe the API +in detail - if this is your first interaction with libcamera then you may find +it useful to visit the [developer's guide](../html/guides/introduction.html) in +the first instance, which can provide a more generic introduction to the +library's concepts. + +\if internal + +As a follow-on to the developer's guide, to assist you in adding support for +your platform the [pipeline handler writer's guide](../html/guides/pipeline-handler.html) +and the [ipa module writer's guide](../html/guides/ipa.html) should be helpful. + +The full libcamera API is documented here. If you wish to see only the public +part of the API you can use [these pages](../api-html/index.html) instead. + +\else + +As a follow-on to the developer's guide, to assist you in using libcamera within +your project the [application developer's guide](../html/guides/application-developer.html) +gives an overview on how to achieve that. + +Only the public part of the libcamera API is documented here; if you are a +developer seeking to add support for your hardware to the library or make other +improvements, you should switch to the internal API +[reference pages](../internal-api-html/index.html) instead. + +\endif +*/ diff --git a/Documentation/meson.build b/Documentation/meson.build index afaad751..ab8168bb 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -62,6 +62,7 @@ if doxygen.found() and dot.found() cdata_public = configuration_data() cdata_public.merge_from(cdata) + cdata_public.set('ENABLED_SECTIONS', '') cdata_public.set('HIDE_UNDOC_CLASSES', 'YES') cdata_public.set('HIDE_UNDOC_MEMBERS', 'YES') cdata_public.set('HTML_OUTPUT', 'api-html') @@ -89,6 +90,7 @@ if doxygen.found() and dot.found() cdata_internal = configuration_data() cdata_internal.merge_from(cdata) + cdata_internal.set('ENABLED_SECTIONS', 'internal') cdata_internal.set('HIDE_UNDOC_CLASSES', 'NO') cdata_internal.set('HIDE_UNDOC_MEMBERS', 'NO') cdata_internal.set('HTML_OUTPUT', 'internal-api-html')