[{"id":1935,"web_url":"https://patchwork.libcamera.org/comment/1935/","msgid":"<20190619122545.GF5045@pendragon.ideasonboard.com>","date":"2019-06-19T12:25:45","subject":"Re: [libcamera-devel] [PATCH v5 3/4] libcamera: v4l2_videodevice:\n\tUpdate documentation","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Jacopo,\n\nThank you for the patch.\n\nOn Wed, Jun 19, 2019 at 01:05:47PM +0200, Jacopo Mondi wrote:\n> Now that we have V4L2Device and V4L2VideoDevice update the documentation\n> of the latter to use \"video device\" every time the term \"device\" was\n> used in the V4L2 context.\n> \n> While at it clean up by removing a stale todo entry.\n> \n> Documentation only change, no functional changes intended.\n> \n> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>\n> ---\n>  src/libcamera/v4l2_videodevice.cpp | 156 ++++++++++++++---------------\n>  1 file changed, 78 insertions(+), 78 deletions(-)\n> \n> diff --git a/src/libcamera/v4l2_videodevice.cpp b/src/libcamera/v4l2_videodevice.cpp\n> index 403e0b2e0653..bcbac79e82e9 100644\n> --- a/src/libcamera/v4l2_videodevice.cpp\n> +++ b/src/libcamera/v4l2_videodevice.cpp\n> @@ -26,7 +26,7 @@\n>  \n>  /**\n>   * \\file v4l2_videodevice.h\n> - * \\brief V4L2 Video Device API\n> + * \\brief V4L2 Video Device\n>   */\n>  namespace libcamera {\n>  \n> @@ -48,89 +48,86 @@ LOG_DECLARE_CATEGORY(V4L2)\n>  \n>  /**\n>   * \\fn V4L2Capability::card()\n> - * \\brief Retrieve the device card name\n> - * \\return The string containing the device name\n> + * \\brief Retrieve the video device card name\n> + * \\return The string containing the video device name\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::bus_info()\n> - * \\brief Retrieve the location of the device in the system\n> - * \\return The string containing the device location\n> + * \\brief Retrieve the location of the video device in the system\n> + * \\return The string containing the video device location\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::device_caps()\n> - * \\brief Retrieve the capabilities of the device\n> - * \\return The device specific capabilities if V4L2_CAP_DEVICE_CAPS is set or\n> - * \t   driver capabilities otherwise\n> + * \\brief Retrieve the capabilities of the video device\n> + * \\return The video device specific capabilities if V4L2_CAP_DEVICE_CAPS is\n> + * set or driver capabilities otherwise\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::isMultiplanar()\n> - * \\brief Identify if the device implements the V4L2 multiplanar APIs\n> - * \\return True if the device supports multiplanar APIs\n> + * \\brief Identify if the video device implements the V4L2 multiplanar APIs\n> + * \\return True if the video device supports multiplanar APIs\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::isCapture()\n> - * \\brief Identify if the device captures data\n> - * \\return True if the device can capture data\n> + * \\brief Identify if the video device captures data\n> + * \\return True if the video device can capture data\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::isOutput()\n> - * \\brief Identify if the device outputs data\n> - * \\return True if the device can output data\n> + * \\brief Identify if the video device outputs data\n> + * \\return True if the video device can output data\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::isVideo()\n> - * \\brief Identify if the device captures or outputs images\n> - * \\return True if the device can capture or output images\n> + * \\brief Identify if the video device captures or outputs images\n> + * \\return True if the video device can capture or output images\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::isMeta()\n> - * \\brief Identify if the device captures or outputs image meta-data\n> - *\n> - * \\todo Add support for META_CAPTURE introduced in Linux v5.0\n> - *\n> - * \\return True if the device can capture or output image meta-data\n> + * \\brief Identify if the video device captures or outputs image meta-data\n> + * \\return True if the video device can capture or output image meta-data\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::isVideoCapture()\n> - * \\brief Identify if the device captures images\n> - * \\return True if the device can capture images\n> + * \\brief Identify if the video device captures images\n> + * \\return True if the video device can capture images\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::isVideoOutput()\n> - * \\brief Identify if the device outputs images\n> - * \\return True if the device can output images\n> + * \\brief Identify if the video device outputs images\n> + * \\return True if the video device can output images\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::isMetaCapture()\n> - * \\brief Identify if the device captures image meta-data\n> - * \\return True if the device can capture image meta-data\n> + * \\brief Identify if the video device captures image meta-data\n> + * \\return True if the video device can capture image meta-data\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::isMetaOutput()\n> - * \\brief Identify if the device outputs image meta-data\n> - * \\return True if the device can output image meta-data\n> + * \\brief Identify if the video device outputs image meta-data\n> + * \\return True if the video device can output image meta-data\n>   */\n>  \n>  /**\n>   * \\fn V4L2Capability::hasStreaming()\n> - * \\brief Determine if the device can perform Streaming I/O\n> - * \\return True if the device provides Streaming I/O IOCTLs\n> + * \\brief Determine if the video device can perform Streaming I/O\n> + * \\return True if the video device provides Streaming I/O IOCTLs\n>   */\n>  \n>  /**\n>   * \\class V4L2DeviceFormat\n> - * \\brief The V4L2 device image format and sizes\n> + * \\brief The V4L2 video device image format and sizes\n>   *\n>   * This class describes the image format and resolution to be programmed on a\n>   * V4L2 video device. The image format is defined by a fourcc code (as specified\n> @@ -176,27 +173,29 @@ LOG_DECLARE_CATEGORY(V4L2)\n>   * length and total size.\n>   *\n>   * Packed image formats, which occupy a single memory area, are easily described\n> - * through the single-plane API. When used on a device that implements the\n> + * through the single-plane API. When used on a video device that implements the\n>   * multi-plane API, only the size and stride information contained in the first\n>   * plane are taken into account.\n>   *\n>   * Planar image formats, which occupy distinct memory areas, are easily\n> - * described through the multi-plane APIs. When used on a device that implements\n> - * the single-plane API, all planes are stored one after the other in a\n> - * contiguous memory area, and it is not possible to configure per-plane stride\n> - * length and size, but only a global stride length which is applied to all\n> + * described through the multi-plane APIs. When used on a video device that\n> + * implements the single-plane API, all planes are stored one after the other\n> + * in a contiguous memory area, and it is not possible to configure per-plane\n> + * stride length and size, but only a global stride length which is applied to\n> + * all\n>   * planes.\n\nThe last two lines should be squashed together.\n\n>   *\n>   * The V4L2DeviceFormat class describes both packed and planar image formats,\n> - * regardless of the API type (single or multi plane) implemented by the device\n> - * the format has to be applied to. The total size and bytes per line of images\n> - * represented with packed formats are configured using the first entry of the\n> - * V4L2DeviceFormat::planes array, while the per-plane size and per-plane stride\n> - * length of images represented with planar image formats are configured using\n> - * the opportune number of entries of the V4L2DeviceFormat::planes array, as\n> - * prescribed by the image format definition (semi-planar formats use 2 entries,\n> - * while planar formats use the whole 3 entries). The number of valid entries of\n> - * the V4L2DeviceFormat::planes array is defined by the\n> + * regardless of the API type (single or multi plane) implemented by the video\n> + * device the format has to be applied to. The total size and bytes per line\n> + * of images represented with packed formats are configured using the first\n> + * entry of the V4L2DeviceFormat::planes array, while the per-plane size and\n> + * per-plane stride length of images represented with planar image formats are\n> + * configured using the opportune number of entries of the\n> + * V4L2DeviceFormat::planes array, as prescribed by the image format\n> + * definition (semi-planar formats use 2 entries, while planar formats use the\n> + * whole 3 entries). The number of valid entries of the\n> + * V4L2DeviceFormat::planes array is defined by the\n>   * V4L2DeviceFormat::planesCount value.\n>   */\n>  \n> @@ -246,13 +245,13 @@ const std::string V4L2DeviceFormat::toString() const\n>   * \\class V4L2VideoDevice\n>   * \\brief V4L2VideoDevice object and API\n>   *\n> - * The V4L2 Device API class models an instance of a V4L2 device node.\n> + * The V4L2VideoDevice class models an instance of a V4L2 video device.\n>   * It is constructed with the path to a V4L2 video device node. The device node\n>   * is only opened upon a call to open() which must be checked for success.\n>   *\n> - * The device capabilities are validated when the device is opened and the\n> - * device is rejected if it is not a suitable V4L2 capture or output device, or\n> - * if the device does not support streaming I/O.\n> + * The video device capabilities are validated when the device is opened and the\n> + * device is rejected if it is not a suitable V4L2 capture or output vide\n\ns/vide/video/\n\n> + * device, or if the video device does not support streaming I/O.\n>   *\n>   * No API call other than open(), isOpen() and close() shall be called on an\n>   * unopened device instance.\n> @@ -274,8 +273,8 @@ V4L2VideoDevice::V4L2VideoDevice(const std::string &deviceNode)\n>  \t  queuedBuffersCount_(0), fdEvent_(nullptr)\n>  {\n>  \t/*\n> -\t * We default to an MMAP based CAPTURE device, however this will be\n> -\t * updated based upon the device capabilities.\n> +\t * We default to an MMAP based CAPTURE video device, however this will\n> +\t * be updated based upon the device capabilities.\n>  \t */\n>  \tbufferType_ = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;\n>  \tmemoryType_ = V4L2_MEMORY_MMAP;\n> @@ -283,7 +282,7 @@ V4L2VideoDevice::V4L2VideoDevice(const std::string &deviceNode)\n>  \n>  /**\n>   * \\brief Construct a V4L2VideoDevice from a MediaEntity\n> - * \\param[in] entity The MediaEntity to build the device from\n> + * \\param[in] entity The MediaEntity to build the video device from\n>   *\n>   * Construct a V4L2VideoDevice from a MediaEntity's device node path.\n>   */\n> @@ -298,7 +297,7 @@ V4L2VideoDevice::~V4L2VideoDevice()\n>  }\n>  \n>  /**\n> - * \\brief Open a V4L2 device and query its capabilities\n> + * \\brief Open a V4L2 video device and query its capabilities\n>   * \\return 0 on success or a negative error code otherwise\n>   */\n>  int V4L2VideoDevice::open()\n> @@ -327,8 +326,9 @@ int V4L2VideoDevice::open()\n>  \t}\n>  \n>  \t/*\n> -\t * Set buffer type and wait for read notifications on CAPTURE devices\n> -\t * (POLLIN), and write notifications for OUTPUT devices (POLLOUT).\n> +\t * Set buffer type and wait for read notifications on CAPTURE video\n> +\t * devices (POLLIN), and write notifications for OUTPUT video devices\n> +\t * (POLLOUT).\n>  \t */\n>  \tif (caps_.isVideoCapture()) {\n>  \t\tfdEvent_ = new EventNotifier(fd(), EventNotifier::Read);\n> @@ -358,7 +358,7 @@ int V4L2VideoDevice::open()\n>  }\n>  \n>  /**\n> - * \\brief Close the device, releasing any resources acquired by open()\n> + * \\brief Close the video device, releasing any resources acquired by open()\n>   */\n>  void V4L2VideoDevice::close()\n>  {\n> @@ -373,13 +373,13 @@ void V4L2VideoDevice::close()\n>  \n>  /**\n>   * \\fn V4L2VideoDevice::driverName()\n> - * \\brief Retrieve the name of the V4L2 device driver\n> + * \\brief Retrieve the name of the V4L2 video device driver\n\nHere I would keep \"V4L2 device driver\", as the driver refers to a\nv4l2_device structure inside the kernel, not just a video device (it can\nalso have subdevs).\n\nReviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\n\n>   * \\return The string containing the driver name\n>   */\n>  \n>  /**\n>   * \\fn V4L2VideoDevice::deviceName()\n> - * \\brief Retrieve the name of the V4L2 device\n> + * \\brief Retrieve the name of the V4L2 video device\n>   * \\return The string containing the device name\n>   */\n>  \n> @@ -390,8 +390,8 @@ void V4L2VideoDevice::close()\n>   */\n>  \n>  /**\n> - * \\brief Retrieve the image format set on the V4L2 device\n> - * \\param[out] format The image format applied on the device\n> + * \\brief Retrieve the image format set on the V4L2 video device\n> + * \\param[out] format The image format applied on the video device\n>   * \\return 0 on success or a negative error code otherwise\n>   */\n>  int V4L2VideoDevice::getFormat(V4L2DeviceFormat *format)\n> @@ -405,10 +405,10 @@ int V4L2VideoDevice::getFormat(V4L2DeviceFormat *format)\n>  }\n>  \n>  /**\n> - * \\brief Configure an image format on the V4L2 device\n> - * \\param[inout] format The image format to apply to the device\n> + * \\brief Configure an image format on the V4L2 video device\n> + * \\param[inout] format The image format to apply to the video device\n>   *\n> - * Apply the supplied \\a format to the device, and return the actually\n> + * Apply the supplied \\a format to the video device, and return the actually\n>   * applied format parameters, as \\ref V4L2VideoDevice::getFormat would do.\n>   *\n>   * \\return 0 on success or a negative error code otherwise\n> @@ -462,7 +462,7 @@ int V4L2VideoDevice::setFormatMeta(V4L2DeviceFormat *format)\n>  \t}\n>  \n>  \t/*\n> -\t * Return to caller the format actually applied on the device,\n> +\t * Return to caller the format actually applied on the video device,\n>  \t * which might differ from the requested one.\n>  \t */\n>  \tformat->size.width = 0;\n> @@ -526,7 +526,7 @@ int V4L2VideoDevice::setFormatMultiplane(V4L2DeviceFormat *format)\n>  \t}\n>  \n>  \t/*\n> -\t * Return to caller the format actually applied on the device,\n> +\t * Return to caller the format actually applied on the video device,\n>  \t * which might differ from the requested one.\n>  \t */\n>  \tformat->size.width = pix->width;\n> @@ -601,7 +601,7 @@ int V4L2VideoDevice::setFormatSingleplane(V4L2DeviceFormat *format)\n>   *\n>   * Enumerate all pixel formats and frame sizes supported by the video device.\n>   *\n> - * \\return A list of the supported device formats\n> + * \\return A list of the supported video device formats\n>   */\n>  ImageFormats V4L2VideoDevice::formats()\n>  {\n> @@ -646,8 +646,8 @@ int V4L2VideoDevice::requestBuffers(unsigned int count)\n>  }\n>  \n>  /**\n> - * \\brief Request buffers to be allocated from the device and stored in the\n> - *  buffer pool provided.\n> + * \\brief Request buffers to be allocated from the video device and stored in\n> + * the buffer pool provided.\n>   * \\param[out] pool BufferPool to populate with buffers\n>   * \\return 0 on success or a negative error code otherwise\n>   */\n> @@ -878,13 +878,13 @@ int V4L2VideoDevice::releaseBuffers()\n>  }\n>  \n>  /**\n> - * \\brief Queue a buffer into the device\n> + * \\brief Queue a buffer into the video device\n>   * \\param[in] buffer The buffer to be queued\n>   *\n> - * For capture devices the \\a buffer will be filled with data by the device.\n> - * For output devices the \\a buffer shall contain valid data and will be\n> - * processed by the device. Once the device has finished processing the buffer,\n> - * it will be available for dequeue.\n> + * For capture video devices the \\a buffer will be filled with data by the\n> + * device. For output video devices the \\a buffer shall contain valid data and\n> + * will be processed by the device. Once the device has finished processing the\n> + * buffer, it will be available for dequeue.\n>   *\n>   * \\return 0 on success or a negative error code otherwise\n>   */\n> @@ -941,7 +941,7 @@ int V4L2VideoDevice::queueBuffer(Buffer *buffer)\n>  }\n>  \n>  /**\n> - * \\brief Dequeue the next available buffer from the device\n> + * \\brief Dequeue the next available buffer from the video device\n>   *\n>   * This method dequeues the next available buffer from the device. If no buffer\n>   * is available to be dequeued it will return nullptr immediately.\n> @@ -987,14 +987,14 @@ Buffer *V4L2VideoDevice::dequeueBuffer()\n>  }\n>  \n>  /**\n> - * \\brief Slot to handle completed buffer events from the V4L2 device\n> + * \\brief Slot to handle completed buffer events from the V4L2 video device\n>   * \\param[in] notifier The event notifier\n>   *\n>   * When this slot is called, a Buffer has become available from the device, and\n>   * will be emitted through the bufferReady Signal.\n>   *\n> - * For Capture devices the Buffer will contain valid data.\n> - * For Output devices the Buffer can be considered empty.\n> + * For Capture video devices the Buffer will contain valid data.\n> + * For Output video devices the Buffer can be considered empty.\n>   */\n>  void V4L2VideoDevice::bufferAvailable(EventNotifier *notifier)\n>  {","headers":{"Return-Path":"<laurent.pinchart@ideasonboard.com>","Received":["from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 3013C61A15\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tWed, 19 Jun 2019 14:26:03 +0200 (CEST)","from pendragon.ideasonboard.com\n\t(dfj612yhrgyx302h3jwwy-3.rev.dnainternet.fi\n\t[IPv6:2001:14ba:21f5:5b00:ce28:277f:58d7:3ca4])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id B584B333;\n\tWed, 19 Jun 2019 14:26:02 +0200 (CEST)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1560947162;\n\tbh=ep7+Mh3ytlSNPyAg1xjXeMWYfl1cUX92EbYoEz2ty+Y=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=n3XKsd/8seUvsS0TuLuW5n5M0dJFMWGrCINAQ8JKHs6lcsLDZO/9rJbe1DvqVz9Q9\n\tmM9+hNKjyzcpuCdmJZ9Pf35xqpZp8v3dAYupV+DhFUVWT/CtfBpJddyCdZziFiDdBM\n\tZCJjeaEwvcXzGl2CxdJVKM5p3Ry2nIJYyiVDqfwM=","Date":"Wed, 19 Jun 2019 15:25:45 +0300","From":"Laurent Pinchart <laurent.pinchart@ideasonboard.com>","To":"Jacopo Mondi <jacopo@jmondi.org>","Cc":"libcamera-devel@lists.libcamera.org","Message-ID":"<20190619122545.GF5045@pendragon.ideasonboard.com>","References":"<20190619110548.20742-1-jacopo@jmondi.org>\n\t<20190619110548.20742-4-jacopo@jmondi.org>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20190619110548.20742-4-jacopo@jmondi.org>","User-Agent":"Mutt/1.10.1 (2018-07-13)","Subject":"Re: [libcamera-devel] [PATCH v5 3/4] libcamera: v4l2_videodevice:\n\tUpdate documentation","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.23","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":"Wed, 19 Jun 2019 12:26:03 -0000"}}]