{"id":479,"url":"https://patchwork.libcamera.org/api/1.1/patches/479/?format=json","web_url":"https://patchwork.libcamera.org/patch/479/","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":"<20190201154248.15006-8-jacopo@jmondi.org>","date":"2019-02-01T15:42:48","name":"[libcamera-devel,7/7] libcamera: v4l2_device: Improve documentation","commit_ref":null,"pull_url":null,"state":"accepted","archived":false,"hash":"084fe0e1f6a24dc68c15bcefbfb33b28b64186be","submitter":{"id":3,"url":"https://patchwork.libcamera.org/api/1.1/people/3/?format=json","name":"Jacopo Mondi","email":"jacopo@jmondi.org"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/479/mbox/","series":[{"id":162,"url":"https://patchwork.libcamera.org/api/1.1/series/162/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=162","date":"2019-02-01T15:42:41","name":"libcamera: v4l2_device: Address comments for s/g_fmt","version":1,"mbox":"https://patchwork.libcamera.org/series/162/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/479/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/479/checks/","tags":{},"headers":{"Return-Path":"","Received":["from relay8-d.mail.gandi.net (relay8-d.mail.gandi.net\n\t[217.70.183.201])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 5BB3660DB5\n\tfor ;\n\tFri, 1 Feb 2019 16:42:42 +0100 (CET)","from uno.localdomain (unknown [91.183.179.147])\n\t(Authenticated sender: jacopo@jmondi.org)\n\tby relay8-d.mail.gandi.net (Postfix) with ESMTPSA id 107D71BF205;\n\tFri, 1 Feb 2019 15:42:41 +0000 (UTC)"],"X-Originating-IP":"91.183.179.147","From":"Jacopo Mondi ","To":"libcamera-devel@lists.libcamera.org","Date":"Fri, 1 Feb 2019 16:42:48 +0100","Message-Id":"<20190201154248.15006-8-jacopo@jmondi.org>","X-Mailer":"git-send-email 2.20.1","In-Reply-To":"<20190201154248.15006-1-jacopo@jmondi.org>","References":"<20190201154248.15006-1-jacopo@jmondi.org>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [PATCH 7/7] libcamera: v4l2_device: Improve\n\tdocumentation","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.23","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","X-List-Received-Date":"Fri, 01 Feb 2019 15:42:42 -0000"},"content":"Improve the V4L2DeviceFormat documentation as suggested during patches\nreview.\n\nSigned-off-by: Jacopo Mondi \n---\n src/libcamera/v4l2_device.cpp | 42 +++++++++++++++++++----------------\n 1 file changed, 23 insertions(+), 19 deletions(-)","diff":"diff --git a/src/libcamera/v4l2_device.cpp b/src/libcamera/v4l2_device.cpp\nindex 4d1f76b..5ae208f 100644\n--- a/src/libcamera/v4l2_device.cpp\n+++ b/src/libcamera/v4l2_device.cpp\n@@ -84,48 +84,52 @@ LOG_DEFINE_CATEGORY(V4L2)\n * \\class V4L2DeviceFormat\n * \\brief The V4L2 device image format and sizes\n *\n- * Describes the image format and image sizes to be programmed on a V4L2\n- * video device. The image format is defined by fourcc code as defined by\n- * the V4L2 APIs with the V4L2_PIX_FMT_ macros, a visible width and height\n- * and a variable number of planes (1 to 3) with variable sizes and line\n- * strides.\n+ * This class describes the image format and image sizes to be programmed\n+ * on a V4L2 video device. The image format is defined by a fourcc code\n+ * as defined by the V4L2 API with the V4L2_PIX_FMT_* macros, a visible\n+ * width and height and one to three planes with configurable line stride\n+ * and a total per-plane size in bytes.\n *\n- * Formats defined as 'single planar' by the V4L2 APIs are represented with\n- * V4L2DeviceFormat instances with a single plane\n- * (V4L2DeviceFormat::planesCount = 1). Semi-planar and multiplanar formats use\n- * 2 and 3 planes respectively.\n+ * The V4L2 APIs defines packed, semi-planar and planar image formats.\n+ * Packed formats are stored as a single, contiguous memory area, while\n+ * semi-planar and multi-planar ones use two or three (possibly not contiguous)\n+ * memory regions to store the image components as separate planes.\n *\n- * V4L2DeviceFormat defines the exchange format between components that\n- * receive image configuration requests from applications and a V4L2Device.\n- * The V4L2Device validates and applies the requested size and format to\n- * the device driver.\n+ * Packed formats are represented by V4L2DeviceFormat instances with a\n+ * single valid \\ref planes array entry (\\ref planesCount = 1).\n+ * Non-packed formats allows configuring per plane size and line stride length,\n+ * but only when applied to devices that support the V4L2 multi-planar APIs.\n+ * When a non-packed image format gets applied to a device that only supports\n+ * the V4L2 single-planar APIs, it is not possible to configure per-plane sizes\n+ * as the only valid informations are contained in the first entry of the \\ref\n+ * planes array, and apply to the image as a whole.\n */\n \n /**\n * \\var V4L2DeviceFormat::width\n- * \\brief The image width\n+ * \\brief The image width in pixels\n */\n \n /**\n * \\var V4L2DeviceFormat::height\n- * \\brief The image height\n+ * \\brief The image height in pixels\n */\n \n /**\n * \\var V4L2DeviceFormat::fourcc\n * \\brief The pixel encoding scheme\n *\n- * The fourcc code, as defined by the V4L2 APIs with the V4L2_PIX_FMT_ macros,\n+ * The fourcc code, as defined by the V4L2 API with the V4L2_PIX_FMT_* macros,\n * that identifies the image format pixel encoding scheme.\n */\n \n /**\n * \\var V4L2DeviceFormat::planes\n- * \\brief The per-plane size information\n+ * \\brief The per-plane memory size information\n *\n * Images are stored in memory in one or more data planes. Each data plane\n- * has a specific size and line length, which could differ from the image\n- * visible sizes to accommodate line or plane padding data.\n+ * has a specific memory size and line length, which could differ from the\n+ * image visible sizes to accommodate line or plane padding data.\n *\n * Only the first \\ref planesCount entries are considered valid.\n */\n","prefixes":["libcamera-devel","7/7"]}