[{"id":39901,"web_url":"https://patchwork.libcamera.org/comment/39901/","msgid":"","date":"2026-07-29T09:21:30","subject":"Re: [PATCH v2 2/2] docs: Document SensorSequence request metadata","submitter":{"id":216,"url":"https://patchwork.libcamera.org/api/people/216/","name":"Barnabás Pőcze","email":"barnabas.pocze@ideasonboard.com"},"content":"Hi\n\n2026. 07. 04. 0:48 keltezéssel, Bruce Allen írta:\n> Describe how applications read SensorSequence from Request::metadata() and\n> how it differs from per-buffer FrameMetadata::sequence.\n> \n> Signed-off-by: Bruce Allen \n> ---\n> Documentation/guides/application-developer.rst | 26 ++++++++++++++++++++++\n> 1 file changed, 26 insertions(+)\n> \n> diff --git a/Documentation/guides/application-developer.rst b/Documentation/guides/application-developer.rst\n> index a9620ca..77b4135 100644\n> --- a/Documentation/guides/application-developer.rst\n> +++ b/Documentation/guides/application-developer.rst\n> @@ -469,6 +469,32 @@ and the bytes used by planes.\n> seq: 000040 bytesused: 1843200\n> seq: 000042 bytesused: 1843200\n> \n> +Request metadata\n> +~~~~~~~~~~~~~~~~\n\nI feel like this should be a subheading under \"Handle request completion events\",\nand at the very of it, just before the \"Request queueing\" header.\n\n\n> +\n> +Completed requests also expose metadata as a :doxy-pub:`ControlList` through\n> +:doxy-pub:`Request::metadata()`. Pipeline handlers populate this list with\n> +controls defined as ``direction: out`` in the control definition YAML files.\n\nI would write something like:\n\n \"Only controls where :doxy-pub:`ControlId::direction()` signals :doxy-pub:`ControlId::Direction::Out` are returned as metadata.\"\n\nbecause the yaml file is a completely internal implementation detail.\n\n> +\n> +Common entries include :doxy-pub:`controls::SensorTimestamp`,\n> +:doxy-pub:`controls::FrameWallClock`, and :doxy-pub:`controls::SensorSequence`.\n> +The latter reports the sequence number from the sensor-facing capture device\n> +(for example the CSI-2 receiver or V4L2 video node) for the frame associated\n> +with the request.\n> +\n> +While per-buffer :doxy-pub:`FrameMetadata::sequence` identifies frames in each\n> +completed stream, ``SensorSequence`` reflects the sensor-side capture path. If\n> +the value increases by more than one between consecutive completed requests,\n> +frames were not captured before the earlier request finished. This complements\n> +sequence numbers derived from request delivery and is intended for diagnosing\n> +frame continuity.\n> +\n> +.. code:: cpp\n> +\n> + const ControlList &metadata = request->metadata();\n> + if (auto seq = metadata.get(controls::SensorSequence))\n\nI would drop the `` part. And I also feel like most of this `SensorSequence`-specific\ninfo should be in the documentation of the `SensorSequence` control itself.\n\n\nRegards,\nBarnabás Pőcze\n\n\n> + std::cout << \" sensor sequence: \" << *seq << std::endl;\n> +\n> A completed buffer contains of course image data which can be accessed through\n> the per-plane dma-buf file descriptor transported by the ``FrameBuffer``\n> instance. An example of how to write image data to disk is available in the","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 E0B20C328C\n\tfor ;\n\tWed, 29 Jul 2026 09:21:40 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id D988867FA9;\n\tWed, 29 Jul 2026 11:21:39 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 7436E65F9F\n\tfor ;\n\tWed, 29 Jul 2026 11:21:38 +0200 (CEST)","from [192.168.33.16] (185.182.215.156.nat.pool.zt.hu\n\t[185.182.215.156])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 2059E63C;\n\tWed, 29 Jul 2026 11:20:33 +0200 (CEST)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"CT/QHJ5p\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1785316833;\n\tbh=FkxW35uhazeOsmaZ+2nEE0G3FZdr7r3Cz5mdvQbMmkA=;\n\th=Date:Subject:To:References:From:In-Reply-To:From;\n\tb=CT/QHJ5pEfuIJo8mpL7VvJk0R423CblBTKvPyNk2jIxGBwc3eizUviXvSkScPFTxy\n\trQ4zH68eqRxFJjLkOuIkGex26DcA4/0oLoBsanj0whbMmiD22xUaTHw2qcwh6tU1It\n\tOZaUvHaQyAwg/AWM/sL1mnRBkXbhFYYHT4TyXNgE=","Message-ID":"","Date":"Wed, 29 Jul 2026 11:21:30 +0200","MIME-Version":"1.0","User-Agent":"Mozilla Thunderbird","Subject":"Re: [PATCH v2 2/2] docs: Document SensorSequence request metadata","To":"Bruce Allen ,\n\tlibcamera-devel@lists.libcamera.org","References":"<20260626003712.26624-1-ballen4705@googlemail.com>\n\t<20260703224817.15650-1-ballen4705@googlemail.com>\n\t<20260703224817.15650-3-ballen4705@googlemail.com>","From":"=?utf-8?q?Barnab=C3=A1s_P=C5=91cze?= ","Content-Language":"en-US, hu-HU","In-Reply-To":"<20260703224817.15650-3-ballen4705@googlemail.com>","Content-Type":"text/plain; charset=UTF-8; format=flowed","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\" "}},{"id":39906,"web_url":"https://patchwork.libcamera.org/comment/39906/","msgid":"","date":"2026-07-30T10:22:58","subject":"Re: [PATCH v2 2/2] docs: Document SensorSequence request metadata","submitter":{"id":321,"url":"https://patchwork.libcamera.org/api/people/321/","name":"Bruce Allen","email":"ballen4705@googlemail.com"},"content":"Hi Barnabás,\n\nthanks very much for the helpful feedback. Your points (both here and \nin the second email) are all sensible. I'll upload a revised version of \nthe patch this weekend.\n\nCheers,\n\tBruce\n\nOn 29.07.26 11:21, Barnabás Pőcze wrote:\n> Hi\n> \n> 2026. 07. 04. 0:48 keltezéssel, Bruce Allen írta:\n>> Describe how applications read SensorSequence from Request::metadata() \n>> and\n>> how it differs from per-buffer FrameMetadata::sequence.\n>>\n>> Signed-off-by: Bruce Allen \n>> ---\n>>   Documentation/guides/application-developer.rst | 26 ++++++++++++++++ \n>> ++++++\n>>   1 file changed, 26 insertions(+)\n>>\n>> diff --git a/Documentation/guides/application-developer.rst b/ \n>> Documentation/guides/application-developer.rst\n>> index a9620ca..77b4135 100644\n>> --- a/Documentation/guides/application-developer.rst\n>> +++ b/Documentation/guides/application-developer.rst\n>> @@ -469,6 +469,32 @@ and the bytes used by planes.\n>>      seq: 000040 bytesused: 1843200\n>>      seq: 000042 bytesused: 1843200\n>> +Request metadata\n>> +~~~~~~~~~~~~~~~~\n> \n> I feel like this should be a subheading under \"Handle request completion \n> events\",\n> and at the very of it, just before the \"Request queueing\" header.\n> \n> \n>> +\n>> +Completed requests also expose metadata as a :doxy-pub:`ControlList` \n>> through\n>> +:doxy-pub:`Request::metadata()`. Pipeline handlers populate this list \n>> with\n>> +controls defined as ``direction: out`` in the control definition YAML \n>> files.\n> \n> I would write something like:\n> \n>   \"Only controls where :doxy-pub:`ControlId::direction()` \n> signals :doxy-pub:`ControlId::Direction::Out` are returned as metadata.\"\n> \n> because the yaml file is a completely internal implementation detail.\n> \n>> +\n>> +Common entries include :doxy-pub:`controls::SensorTimestamp`,\n>> +:doxy-pub:`controls::FrameWallClock`, and :doxy- \n>> pub:`controls::SensorSequence`.\n>> +The latter reports the sequence number from the sensor-facing capture \n>> device\n>> +(for example the CSI-2 receiver or V4L2 video node) for the frame \n>> associated\n>> +with the request.\n>> +\n>> +While per-buffer :doxy-pub:`FrameMetadata::sequence` identifies \n>> frames in each\n>> +completed stream, ``SensorSequence`` reflects the sensor-side capture \n>> path. If\n>> +the value increases by more than one between consecutive completed \n>> requests,\n>> +frames were not captured before the earlier request finished. This \n>> complements\n>> +sequence numbers derived from request delivery and is intended for \n>> diagnosing\n>> +frame continuity.\n>> +\n>> +.. code:: cpp\n>> +\n>> +   const ControlList &metadata = request->metadata();\n>> +   if (auto seq = metadata.get(controls::SensorSequence))\n> \n> I would drop the `` part. And I also feel like most of this \n> `SensorSequence`-specific\n> info should be in the documentation of the `SensorSequence` control itself.\n> \n> \n> Regards,\n> Barnabás Pőcze\n> \n> \n>> +      std::cout << \" sensor sequence: \" << *seq << std::endl;\n>> +\n>>   A completed buffer contains of course image data which can be \n>> accessed through\n>>   the per-plane dma-buf file descriptor transported by the \n>> ``FrameBuffer``\n>>   instance. An example of how to write image data to disk is available \n>> in the\n>","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 2E40CBDE4C\n\tfor ;\n\tThu, 30 Jul 2026 10:23:03 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id AB4EF67FBE;\n\tThu, 30 Jul 2026 12:23:01 +0200 (CEST)","from mail-wr1-x42f.google.com (mail-wr1-x42f.google.com\n\t[IPv6:2a00:1450:4864:20::42f])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 12BBD67F8D\n\tfor ;\n\tThu, 30 Jul 2026 12:23:00 +0200 (CEST)","by mail-wr1-x42f.google.com with SMTP id\n\tffacd0b85a97d-47ddf7b09aaso1804799f8f.3\n\tfor ;\n\tThu, 30 Jul 2026 03:23:00 -0700 (PDT)","from ?IPV6:2a01:599:c0a:eead:9d3:2e02:175c:d15a?\n\t([2a01:599:c0a:eead:9d3:2e02:175c:d15a])\n\tby smtp.gmail.com with ESMTPSA id\n\tffacd0b85a97d-47fc892cdeasm5098600f8f.22.2026.07.30.03.22.58\n\t(version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128);\n\tThu, 30 Jul 2026 03:22:58 -0700 (PDT)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (2048-bit key;\n\tunprotected) header.d=googlemail.com header.i=@googlemail.com\n\theader.b=\"pEOabZSs\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=googlemail.com; s=20251104; t=1785406979; x=1786011779;\n\tdarn=lists.libcamera.org; \n\th=content-transfer-encoding:content-type:in-reply-to:from:cc\n\t:content-language:references:to:subject:user-agent:mime-version:date\n\t:message-id:from:to:cc:subject:date:message-id:reply-to:content-type; \n\tbh=/T1AdHxTDvVeDmq063nZWITgcnhUWW7eIOb824wpvNc=;\n\tb=pEOabZSsG4eT+EfPp8qCTShUtKfRQfqOGuifG126M5ha2IGOUT2MxmNrh3CT/QpcvC\n\t5Ji/hXmpMOUtxnmmRq7ycUxWcP1lehH2RB7yjlEaXkmZLwqaWJYDf2KqyxrShX/mzBXr\n\tc2lhgUEKT+0vc0ddNr1AaCxeWeNtWv9+RGU1BUaFSPMtFzWUn72xPs8OPKYUpms0XKNQ\n\t6pCRjC/YWDQYBWF4i8eKbsmWAAgrCb9I8PwZPdNeDmtlfOLtu0AYnAOgNpMl1+lltcho\n\tAFuwBHV94A/AOBAxABqzX10mjmyEFA5B3zk/vUSmkEcp7z4ze44hOKWf5cdp3zYA4E+j\n\tsqbQ==","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20251104; t=1785406979; x=1786011779;\n\th=content-transfer-encoding:content-type:in-reply-to:from:cc\n\t:content-language:references:to:subject:user-agent:mime-version:date\n\t:message-id:x-gm-gg:x-gm-message-state:from:to:cc:subject:date\n\t:message-id:reply-to:content-type;\n\tbh=/T1AdHxTDvVeDmq063nZWITgcnhUWW7eIOb824wpvNc=;\n\tb=Mq79kw+Bd19GJGfVC6Raq/CJBOk2FWWNwU5mvs+mLykDytcSXLOGO3Oo9vgf0NCQZ6\n\t2KDxMFHJ0O2NrQzYnJKG9hmHGR3o2TM2n1lxiKwpaPMG4X2A/uw8fctyq0WzH5wiJ96m\n\tB+wI4nSEDxLwl/OHbk/5es4CS2hLghgQdOQI7vUCFVfb1rxKYAJWlEmNTEXxURff2xbf\n\tZMdrAuN72znlmbX4nczxR3uTOJy8V/A3XLpfCW6cEGXfBATV/1DOGTrkdofHZq0oSAfu\n\tB+ZoH0QwtUCg52GUJNjxlDZt/MoqC8hq7/pPL5nweXBK5ppZNnFT/pDQOe+NiNjm/rhu\n\t+ypQ==","X-Gm-Message-State":"AOJu0YxME2Q3qS4w/iuUZXT7yPNb3Z9uw25bPYulq7LkmW1CPn6LPyFX\n\taRe0EPCzrfVBOpV6rRNpVLl0bS3FdNifIGmsUfV+j9ktNQLeGFBV+G5h","X-Gm-Gg":"AR+sD13GpQknQ2CvX+Wx4RNWHstqy1aKgFDaQExntpcTwAaCA55xy1IBFxqShiQKNbG\n\tpx9r3C37Lm6FRcPW1UH5ut6PadC7KrQDt5FPoCq8GkugPrNj26Fi00j71J4T7tYEKCRPlolQxGE\n\tpcGpLz8IXGVwgKqAzvYbjIaw7Ss2G2p2LIaPDVd2s5NZDGUDHKBTkKCCIWCR3tNuxPu+Hj+Qcoy\n\tgSwiitFQmEAYSpLnGm5IdohdGuQC4pRSzg/aHB0/3kPi01e7BRm1AmZwDTcWd2VLl7Dc7IyG7U8\n\t4JrzZ3ViSXjVAZSXMVcEtVjwdyQaMv5OLZkf7m0/92VKCiT9RJpX8PxPnHSEU06TL2vzOUf7SoM\n\tHU4VcUuc9s2LXcUfzPuNYiKDc5WG5fqktlIGNiXNMP+Oa7GjE6xX3VpSBilh79hsYu7Czzr3+ha\n\tY3efUUlFe+Q12NKzr2EpzePuz/SiwgZvnLx0iwpXCDZdedNa0p9Qz/uCKxzMdsokAG97kbeWG1E\n\trVUGLN7AUUO96Pd+H9HnLw7nLio494lPOredE5t8H4xmDmdYHMS6jhb00blblq2cJKNYYc=","X-Received":"by 2002:a05:6000:38b:b0:47f:8488:50f0 with SMTP id\n\tffacd0b85a97d-47fc80c093emr2552618f8f.4.1785406979312; \n\tThu, 30 Jul 2026 03:22:59 -0700 (PDT)","Message-ID":"","Date":"Thu, 30 Jul 2026 12:22:58 +0200","MIME-Version":"1.0","User-Agent":"Mozilla Thunderbird","Subject":"Re: [PATCH v2 2/2] docs: Document SensorSequence request metadata","To":"=?utf-8?q?Barnab=C3=A1s_P=C5=91cze?= ","References":"<20260626003712.26624-1-ballen4705@googlemail.com>\n\t<20260703224817.15650-1-ballen4705@googlemail.com>\n\t<20260703224817.15650-3-ballen4705@googlemail.com>\n\t","Content-Language":"en-US","Cc":"libcamera-devel@lists.libcamera.org","From":"Bruce Allen ","In-Reply-To":"","Content-Type":"text/plain; charset=UTF-8; format=flowed","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\" "}}]