From patchwork Fri Feb 1 15:42:48 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 479 Return-Path: Received: from relay8-d.mail.gandi.net (relay8-d.mail.gandi.net [217.70.183.201]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 5BB3660DB5 for ; Fri, 1 Feb 2019 16:42:42 +0100 (CET) X-Originating-IP: 91.183.179.147 Received: from uno.localdomain (unknown [91.183.179.147]) (Authenticated sender: jacopo@jmondi.org) by relay8-d.mail.gandi.net (Postfix) with ESMTPSA id 107D71BF205; Fri, 1 Feb 2019 15:42:41 +0000 (UTC) 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 Subject: [libcamera-devel] [PATCH 7/7] libcamera: v4l2_device: Improve documentation X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 01 Feb 2019 15:42:42 -0000 Improve the V4L2DeviceFormat documentation as suggested during patches review. Signed-off-by: Jacopo Mondi --- src/libcamera/v4l2_device.cpp | 42 +++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/src/libcamera/v4l2_device.cpp b/src/libcamera/v4l2_device.cpp index 4d1f76b..5ae208f 100644 --- a/src/libcamera/v4l2_device.cpp +++ b/src/libcamera/v4l2_device.cpp @@ -84,48 +84,52 @@ LOG_DEFINE_CATEGORY(V4L2) * \class V4L2DeviceFormat * \brief The V4L2 device image format and sizes * - * Describes the image format and image sizes to be programmed on a V4L2 - * video device. The image format is defined by fourcc code as defined by - * the V4L2 APIs with the V4L2_PIX_FMT_ macros, a visible width and height - * and a variable number of planes (1 to 3) with variable sizes and line - * strides. + * This class describes the image format and image sizes to be programmed + * on a V4L2 video device. The image format is defined by a fourcc code + * as defined by the V4L2 API with the V4L2_PIX_FMT_* macros, a visible + * width and height and one to three planes with configurable line stride + * and a total per-plane size in bytes. * - * Formats defined as 'single planar' by the V4L2 APIs are represented with - * V4L2DeviceFormat instances with a single plane - * (V4L2DeviceFormat::planesCount = 1). Semi-planar and multiplanar formats use - * 2 and 3 planes respectively. + * The V4L2 APIs defines packed, semi-planar and planar image formats. + * Packed formats are stored as a single, contiguous memory area, while + * semi-planar and multi-planar ones use two or three (possibly not contiguous) + * memory regions to store the image components as separate planes. * - * V4L2DeviceFormat defines the exchange format between components that - * receive image configuration requests from applications and a V4L2Device. - * The V4L2Device validates and applies the requested size and format to - * the device driver. + * Packed formats are represented by V4L2DeviceFormat instances with a + * single valid \ref planes array entry (\ref planesCount = 1). + * Non-packed formats allows configuring per plane size and line stride length, + * but only when applied to devices that support the V4L2 multi-planar APIs. + * When a non-packed image format gets applied to a device that only supports + * the V4L2 single-planar APIs, it is not possible to configure per-plane sizes + * as the only valid informations are contained in the first entry of the \ref + * planes array, and apply to the image as a whole. */ /** * \var V4L2DeviceFormat::width - * \brief The image width + * \brief The image width in pixels */ /** * \var V4L2DeviceFormat::height - * \brief The image height + * \brief The image height in pixels */ /** * \var V4L2DeviceFormat::fourcc * \brief The pixel encoding scheme * - * The fourcc code, as defined by the V4L2 APIs with the V4L2_PIX_FMT_ macros, + * The fourcc code, as defined by the V4L2 API with the V4L2_PIX_FMT_* macros, * that identifies the image format pixel encoding scheme. */ /** * \var V4L2DeviceFormat::planes - * \brief The per-plane size information + * \brief The per-plane memory size information * * Images are stored in memory in one or more data planes. Each data plane - * has a specific size and line length, which could differ from the image - * visible sizes to accommodate line or plane padding data. + * has a specific memory size and line length, which could differ from the + * image visible sizes to accommodate line or plane padding data. * * Only the first \ref planesCount entries are considered valid. */