Patch Detail
Show a patch.
GET /api/patches/2555/?format=api
{ "id": 2555, "url": "https://patchwork.libcamera.org/api/patches/2555/?format=api", "web_url": "https://patchwork.libcamera.org/patch/2555/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/projects/1/?format=api", "name": "libcamera", "link_name": "libcamera", "list_id": "libcamera_core", "list_email": "libcamera-devel@lists.libcamera.org", "web_url": "", "scm_url": "", "webscm_url": "" }, "msgid": "<20200110193808.2266294-9-niklas.soderlund@ragnatech.se>", "date": "2020-01-10T19:37:43", "name": "[libcamera-devel,v3,08/33] libcamera: buffer: Add FrameBuffer interface", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": false, "hash": "1792d2529ef400ceb964f690b0266ded2c79ffb6", "submitter": { "id": 5, "url": "https://patchwork.libcamera.org/api/people/5/?format=api", "name": "Niklas Söderlund", "email": "niklas.soderlund@ragnatech.se" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/2555/mbox/", "series": [ { "id": 615, "url": "https://patchwork.libcamera.org/api/series/615/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=615", "date": "2020-01-10T19:37:35", "name": "libcamera: Rework buffer API", "version": 3, "mbox": "https://patchwork.libcamera.org/series/615/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/2555/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/2555/checks/", "tags": {}, "headers": { "Return-Path": "<niklas.soderlund@ragnatech.se>", "Received": [ "from bin-mail-out-06.binero.net (bin-mail-out-06.binero.net\n\t[195.74.38.229])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id A315F60684\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tFri, 10 Jan 2020 20:38:41 +0100 (CET)", "from bismarck.berto.se (p54ac5d7b.dip0.t-ipconnect.de\n\t[84.172.93.123]) by bin-vsp-out-02.atm.binero.net (Halon) with ESMTPA\n\tid cc0de2a4-33e0-11ea-b6d8-005056917f90;\n\tFri, 10 Jan 2020 20:38:37 +0100 (CET)" ], "X-Halon-ID": "cc0de2a4-33e0-11ea-b6d8-005056917f90", "Authorized-sender": "niklas@soderlund.pp.se", "From": "=?utf-8?q?Niklas_S=C3=B6derlund?= <niklas.soderlund@ragnatech.se>", "To": "libcamera-devel@lists.libcamera.org", "Date": "Fri, 10 Jan 2020 20:37:43 +0100", "Message-Id": "<20200110193808.2266294-9-niklas.soderlund@ragnatech.se>", "X-Mailer": "git-send-email 2.24.1", "In-Reply-To": "<20200110193808.2266294-1-niklas.soderlund@ragnatech.se>", "References": "<20200110193808.2266294-1-niklas.soderlund@ragnatech.se>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=UTF-8", "Content-Transfer-Encoding": "8bit", "Subject": "[libcamera-devel] [PATCH v3 08/33] libcamera: buffer: Add\n\tFrameBuffer interface", "X-BeenThere": "libcamera-devel@lists.libcamera.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "<libcamera-devel.lists.libcamera.org>", "List-Unsubscribe": "<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>", "List-Archive": "<https://lists.libcamera.org/pipermail/libcamera-devel/>", "List-Post": "<mailto:libcamera-devel@lists.libcamera.org>", "List-Help": "<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>", "List-Subscribe": "<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>", "X-List-Received-Date": "Fri, 10 Jan 2020 19:38:41 -0000" }, "content": "Add a new FrameBuffer class to describe memory used to store frames.\nThis change just adds the new interface, future patches will migrate all\nparts of libcamera to use this and replace the old Buffer interface.\n\nThis change needs to specify the const keyword for Plane::length() as to\nnot get Doxygen confused with FrameBuffer::Plane::length added in this\nchange.\n\nSigned-off-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>\n---\n* Changes since v2\n- Drop default value for planes argument for FrameBuffer::FrameBuffer(planes, cookie).\n- Deleted FrameBuffer copy constructor and assignment operator.\n- Add a Move constructor for FrameBuffer.\n- Update documentation.\n\nChanges since v1:\n- Rename FrameBuffer::info() to FrameBuffer::metadata()\n- Fixup commit message\n- Reorder method order\n- Rewrite documentation\n- Add operator==() and operator=!() for FrameBuffer::Plane\n---\n include/libcamera/buffer.h | 36 ++++++++++\n src/libcamera/buffer.cpp | 130 ++++++++++++++++++++++++++++++++++++-\n 2 files changed, 165 insertions(+), 1 deletion(-)", "diff": "diff --git a/include/libcamera/buffer.h b/include/libcamera/buffer.h\nindex 0b95e41a2dd205b2..f5522edaf68bbf61 100644\n--- a/include/libcamera/buffer.h\n+++ b/include/libcamera/buffer.h\n@@ -11,6 +11,8 @@\n #include <stdint.h>\n #include <vector>\n \n+#include <libcamera/file_descriptor.h>\n+\n namespace libcamera {\n \n class Request;\n@@ -33,6 +35,40 @@ struct FrameMetadata {\n \tstd::vector<Plane> planes;\n };\n \n+class FrameBuffer final\n+{\n+public:\n+\tstruct Plane {\n+\t\tFileDescriptor fd;\n+\t\tunsigned int length;\n+\t};\n+\n+\tFrameBuffer(const std::vector<Plane> &planes, unsigned int cookie = 0);\n+\tFrameBuffer(FrameBuffer &&other);\n+\n+\tFrameBuffer(const FrameBuffer &other) = delete;\n+\tFrameBuffer &operator=(const FrameBuffer &) = delete;\n+\n+\tconst std::vector<Plane> &planes() const { return planes_; }\n+\n+\tRequest *request() const { return request_; }\n+\tconst FrameMetadata &metadata() const { return metadata_; };\n+\n+\tunsigned int cookie() const { return cookie_; }\n+\tvoid setCookie(unsigned int cookie) { cookie_ = cookie; }\n+\n+private:\n+\tfriend class Request; /* Needed to update request_. */\n+\tfriend class V4L2VideoDevice; /* Needed to update metadata_. */\n+\n+\tstd::vector<Plane> planes_;\n+\n+\tRequest *request_;\n+\tFrameMetadata metadata_;\n+\n+\tunsigned int cookie_;\n+};\n+\n class Plane final\n {\n public:\ndiff --git a/src/libcamera/buffer.cpp b/src/libcamera/buffer.cpp\nindex b7bc948c80748b18..3e2cc9b94595795e 100644\n--- a/src/libcamera/buffer.cpp\n+++ b/src/libcamera/buffer.cpp\n@@ -240,7 +240,7 @@ void *Plane::mem()\n }\n \n /**\n- * \\fn Plane::length()\n+ * \\fn Plane::length() const\n * \\brief Retrieve the length of the memory region\n * \\return The length of the memory region\n */\n@@ -473,4 +473,132 @@ void Buffer::cancel()\n * The intended callers are Request::prepare() and Request::completeBuffer().\n */\n \n+/**\n+ * \\class FrameBuffer\n+ * \\brief Frame buffer data and its associated dynamic metadata\n+ *\n+ * The FrameBuffer class is the primary interface for applications, IPAs and\n+ * pipelines to interact with frame memory. It contains all the static and\n+ * dynamic information to manage the whole life cycle of a frame capture, from\n+ * buffer creation to consumption.\n+ *\n+ * The static information describes the memory planes that make a frame. The\n+ * planes are specified when creating the FrameBuffer and are expressed as a set\n+ * of dmabuf file descriptors and length.\n+ *\n+ * The dynamic information is grouped in a FrameMetadata instance. It is updated\n+ * during the processing of a queued capture request, and is valid from the\n+ * completion of the buffer as signaled by Camera::bufferComplete() until the\n+ * FrameBuffer is either reused in a new request or deleted.\n+ *\n+ * The creator of a FrameBuffer (application, IPA or pipeline) may associate\n+ * to it an integer cookie for any private purpose. The cookie may be set when\n+ * creating the FrameBuffer, and updated at any time with setCookie(). The\n+ * cookie is transparent to the libcamera core and shall only be set by the\n+ * creator of the FrameBuffer. This mechanism supplements the Request cookie.\n+ */\n+\n+/**\n+ * \\struct FrameBuffer::Plane\n+ * \\brief A memory region to store a single plane of a frame\n+ *\n+ * Planar pixel formats use multiple memory regions to store the different\n+ * colour components of a frame. The Plane structure describes such a memory\n+ * region by a dmabuf file descriptor and a length. A FrameBuffer then\n+ * contains one or multiple planes, depending on the pixel format of the\n+ * frames it is meant to store.\n+ *\n+ * To support DMA access, planes are associated with dmabuf objects represented\n+ * by FileDescriptor handles. The Plane class doesn't handle mapping of the\n+ * memory to the CPU, but applications and IPAs may use the dmabuf file\n+ * descriptors to map the plane memory with mmap() and access its contents.\n+ *\n+ * \\todo Once we have a Kernel API which can express offsets within a plane\n+ * this structure shall be extended to contain this information. See commit\n+ * 83148ce8be55e for initial documentation of this feature.\n+ */\n+\n+/**\n+ * \\var FrameBuffer::Plane::fd\n+ * \\brief The dmabuf file descriptor\n+ */\n+\n+/**\n+ * \\var FrameBuffer::Plane::length\n+ * \\brief The plane length in bytes\n+ */\n+\n+/**\n+ * \\brief Construct a FrameBuffer with an array of planes\n+ * \\param[in] planes The frame memory planes\n+ * \\param[in] cookie Cookie\n+ *\n+ * The file descriptors associated with each plane are duplicated and can be\n+ * closed by the caller after the FrameBuffer has been constructed.\n+ */\n+FrameBuffer::FrameBuffer(const std::vector<Plane> &planes, unsigned int cookie)\n+\t: planes_(planes), request_(nullptr), cookie_(cookie)\n+{\n+}\n+\n+/**\n+ * \\brief Move constructor, create a FrameBuffer by taking over \\a other\n+ * \\param[in] other The other FrameBuffer\n+ *\n+ * The \\a other FrameBuffer will be invalidated.\n+ */\n+FrameBuffer::FrameBuffer(FrameBuffer &&other)\n+\t: planes_(std::move(other.planes_)),\n+\t request_(utils::exchange(other.request_, nullptr)),\n+\t metadata_(std::move(other.metadata_)),\n+\t cookie_(utils::exchange(other.cookie_, 0))\n+{\n+}\n+\n+/**\n+ * \\fn FrameBuffer::planes()\n+ * \\brief Retrieve the static plane descriptors\n+ * \\return Array of plane descriptors\n+ */\n+\n+/**\n+ * \\fn FrameBuffer::request()\n+ * \\brief Retrieve the request this buffer belongs to\n+ *\n+ * The intended callers of this method are buffer completion handlers that\n+ * need to associate a buffer to the request it belongs to.\n+ *\n+ * \\return The Request the Buffer belongs to, or nullptr if the buffer is\n+ * not associated with a request\n+ */\n+\n+/**\n+ * \\fn FrameBuffer::metadata()\n+ * \\brief Retrieve the dynamic metadata\n+ * \\return Dynamic metadata for the frame contained in the buffer\n+ */\n+\n+/**\n+ * \\fn FrameBuffer::cookie()\n+ * \\brief Retrieve the cookie\n+ *\n+ * The cookie belongs to the creator of the FrameBuffer, which controls its\n+ * lifetime and value.\n+ *\n+ * \\sa setCookie()\n+ *\n+ * \\return The cookie\n+ */\n+\n+/**\n+ * \\fn FrameBuffer::setCookie()\n+ * \\brief Set the cookie\n+ * \\param[in] cookie Cookie to set\n+ *\n+ * The cookie belongs to the creator of the FrameBuffer. Its value may be\n+ * modified at any time with this method. Applications and IPAs shall not modify\n+ * the cookie value of buffers they haven't created themselves. The libcamera\n+ * core never modifies the buffer cookie.\n+ */\n+\n } /* namespace libcamera */\n", "prefixes": [ "libcamera-devel", "v3", "08/33" ] }