{"id":25644,"url":"https://patchwork.libcamera.org/api/1.1/patches/25644/?format=json","web_url":"https://patchwork.libcamera.org/patch/25644/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/1.1/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20260106165754.1759831-15-barnabas.pocze@ideasonboard.com>","date":"2026-01-06T16:57:46","name":"[v4,14/22] libcamera: camera: Introduce metadataAvailable signal","commit_ref":null,"pull_url":null,"state":"new","archived":false,"hash":"8e4a5ec3de8d047c0c1bcd67618c09afbb4ae8ec","submitter":{"id":216,"url":"https://patchwork.libcamera.org/api/1.1/people/216/?format=json","name":"Barnabás Pőcze","email":"barnabas.pocze@ideasonboard.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/25644/mbox/","series":[{"id":5688,"url":"https://patchwork.libcamera.org/api/1.1/series/5688/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=5688","date":"2026-01-06T16:57:32","name":"libcamera: Add `MetadataList`","version":4,"mbox":"https://patchwork.libcamera.org/series/5688/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/25644/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/25644/checks/","tags":{},"headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id B30D1C3213\n\tfor ;\n\tTue, 6 Jan 2026 16:58:18 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 9464462001;\n\tTue, 6 Jan 2026 17:58:13 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 7D89161FC0\n\tfor ;\n\tTue, 6 Jan 2026 17:58:01 +0100 (CET)","from pb-laptop.local (185.221.143.114.nat.pool.zt.hu\n\t[185.221.143.114])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 69990581;\n\tTue, 6 Jan 2026 17:57:40 +0100 (CET)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"Yt0b3l+a\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1767718660;\n\tbh=MzC4wpVJD9DyEjqljKdnn3f8t8g71dRuRgLZqKSdLNI=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=Yt0b3l+a/z5qtSvBYjnvP+nMNaFp2+MQ11Cu6XEIzXCdKmHX+IbMNTL4A3+nHNB8e\n\ti7g4vXo27x5S8iWAt7SMbLr0RjPFMY0aSOSLc3cVChG4MtSwmZ2BFCL0PPBYAJ1Izu\n\tEduijfKg4bs3p8Za0Wvc/sdl/qp3ZqsIYCD9LBPs=","From":"=?utf-8?q?Barnab=C3=A1s_P=C5=91cze?= ","To":"libcamera-devel@lists.libcamera.org","Cc":"Jacopo Mondi ,\n\tPaul Elder ,\n\tKieran Bingham ","Subject":"[PATCH v4 14/22] libcamera: camera: Introduce metadataAvailable\n\tsignal","Date":"Tue, 6 Jan 2026 17:57:46 +0100","Message-ID":"<20260106165754.1759831-15-barnabas.pocze@ideasonboard.com>","X-Mailer":"git-send-email 2.52.0","In-Reply-To":"<20260106165754.1759831-1-barnabas.pocze@ideasonboard.com>","References":"<20260106165754.1759831-1-barnabas.pocze@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=UTF-8","Content-Transfer-Encoding":"8bit","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "},"content":"From: Jacopo Mondi \n\nAdd a new signal to the Camera class that allows applications to\nreceive notifications for early completion of metadata results.\n\nTo avoid expensive copies of the metadata results the signal\ntransports a view object of metadata items that are ready.\n\nThe signal is an opt-in feature for applications and the sum of\nall metadata results notified through this signal is available\nin Request::metadata() at request completion time.\n\nSigned-off-by: Jacopo Mondi \n[Use `MetadataList::Diff`, change documentation accordingly.]\nSigned-off-by: Barnabás Pőcze \nReviewed-by: Paul Elder \nReviewed-by: Kieran Bingham \n---\nOriginal: https://patchwork.libcamera.org/patch/22227/\n---\n Documentation/design/metadata-list.rst | 2 +-\n include/libcamera/camera.h | 2 +\n src/libcamera/camera.cpp | 54 ++++++++++++++++++++++++++\n src/libcamera/metadata_list.cpp | 1 +\n 4 files changed, 58 insertions(+), 1 deletion(-)","diff":"diff --git a/Documentation/design/metadata-list.rst b/Documentation/design/metadata-list.rst\nindex f535db008..299e30a4a 100644\n--- a/Documentation/design/metadata-list.rst\n+++ b/Documentation/design/metadata-list.rst\n@@ -20,7 +20,7 @@ extra processing on the image, etc. using certain metadata items. For such an\n application it is likely best if the value of each metadata item is reported as\n soon as possible, thus allowing it to start processing as soon as possible.\n \n-For this reason, libcamera provides the ``Camera::metadataAvailable`` signal.\n+For this reason, libcamera provides the :doxy-int:`Camera::metadataAvailable` signal.\n This signal is dispatched whenever new metadata items become available for a\n queued request. This mechanism is completely optional, only interested applications\n need to subscribe, others are free to ignore it completely. :doxy-int:`Request::metadata`\ndiff --git a/include/libcamera/camera.h b/include/libcamera/camera.h\nindex 53089282a..51aee7ee4 100644\n--- a/include/libcamera/camera.h\n+++ b/include/libcamera/camera.h\n@@ -21,6 +21,7 @@\n \n #include \n #include \n+#include \n #include \n #include \n #include \n@@ -123,6 +124,7 @@ public:\n \n \tconst std::string &id() const;\n \n+\tSignal metadataAvailable;\n \tSignal bufferCompleted;\n \tSignal requestCompleted;\n \tSignal<> disconnected;\ndiff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp\nindex 88990c3c0..6fb916400 100644\n--- a/src/libcamera/camera.cpp\n+++ b/src/libcamera/camera.cpp\n@@ -911,6 +911,60 @@ const std::string &Camera::id() const\n \treturn _d()->id_;\n }\n \n+/**\n+ * \\var Camera::metadataAvailable\n+ * \\brief Signal emitted when metadata for a request is available\n+ *\n+ * The metadataAvailable signal notifies applications about the availability\n+ * of metadata for a request before the request completes.\n+ *\n+ * As metadata results could be large in size, the signal transports only a view\n+ * object via which the newly completed metadata items can be accessed. Similarly\n+ * to the metadata list itself, this object is thread-safe, and can be sent to other\n+ * threads for deferred processing. The view object is valid until the request is\n+ * destroyed or reused, whichever happens first.\n+ *\n+ * Applications can access the value of the newly available metadata results as follows:\n+ *\n+ * \\code\n+\n+\tvoid metadataAvailableHandler(Request *request, MetadataList::Diff update)\n+\t{\n+\t\t// The object can be iterated...\n+\t\tfor (auto &&[id, data] : update) {\n+\t\t\t// `id` is the numeric identifier\n+\t\t\t// `data` is a `ControlValueView` object\n+\t\t}\n+\n+\t\t// ...or individual items can be looked up.\n+\t\tif (auto x = update.get(controls::SensorTimestamp)) {\n+\t\t\t// `SensorTimestamp` will only be found if it is part of this\n+\t\t\t// particular update; metadata items completed earlier will\n+\t\t\t// not be found.\n+\t\t}\n+\t}\n+ \\endcode\n+ *\n+ * This signal is emitted multiple times for the same request, it is in fact\n+ * emitted by libcamera every time a new set of metadata is made available\n+ * by the Camera to the application.\n+ *\n+ * The sum of all metadata reported through this signal is equal to\n+ * Request::metadata() list when the Request completes.\n+ *\n+ * Applications can opt-in to handle this signal to receive fast notifications\n+ * of metadata availability or can equally access the full metadata list\n+ * at Request completion time through Request::metadata() if they have no interest\n+ * in early metadata notification.\n+ *\n+ * \\note The received MetadataList::Diff object is merely a view, it is only valid until\n+ * the associated Request is destroyed or \\ref Request::reuse() \"reused\". However,\n+ * during its valid lifetime, an application is free to create copies and access the\n+ * completed metadata items from separate threads by iteration or MetadataList::Diff::get().\n+ *\n+ * \\sa ControlValueView\n+ */\n+\n /**\n * \\var Camera::bufferCompleted\n * \\brief Signal emitted when a buffer for a request queued to the camera has\ndiff --git a/src/libcamera/metadata_list.cpp b/src/libcamera/metadata_list.cpp\nindex 5b0a47cb4..5a5114fc7 100644\n--- a/src/libcamera/metadata_list.cpp\n+++ b/src/libcamera/metadata_list.cpp\n@@ -526,6 +526,7 @@ MetadataList::set(const Entry &e, ControlValueView v, State &s)\n * a series of consecutively added metadata items. Its main purposes is to\n * enable applications to receive a list of changes made to a MetadataList.\n *\n+ * \\sa Camera::metadataAvailable\n * \\internal\n * \\sa MetadataList::Checkpoint::diffSince()\n */\n","prefixes":["v4","14/22"]}