[libcamera-devel] [PATCH v5 3/4] libcamera: v4l2_videodevice: Update documentation
Laurent Pinchart
laurent.pinchart at ideasonboard.com
Wed Jun 19 14:25:45 CEST 2019
Hi Jacopo,
Thank you for the patch.
On Wed, Jun 19, 2019 at 01:05:47PM +0200, Jacopo Mondi wrote:
> Now that we have V4L2Device and V4L2VideoDevice update the documentation
> of the latter to use "video device" every time the term "device" was
> used in the V4L2 context.
>
> While at it clean up by removing a stale todo entry.
>
> Documentation only change, no functional changes intended.
>
> Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>
> ---
> src/libcamera/v4l2_videodevice.cpp | 156 ++++++++++++++---------------
> 1 file changed, 78 insertions(+), 78 deletions(-)
>
> diff --git a/src/libcamera/v4l2_videodevice.cpp b/src/libcamera/v4l2_videodevice.cpp
> index 403e0b2e0653..bcbac79e82e9 100644
> --- a/src/libcamera/v4l2_videodevice.cpp
> +++ b/src/libcamera/v4l2_videodevice.cpp
> @@ -26,7 +26,7 @@
>
> /**
> * \file v4l2_videodevice.h
> - * \brief V4L2 Video Device API
> + * \brief V4L2 Video Device
> */
> namespace libcamera {
>
> @@ -48,89 +48,86 @@ LOG_DECLARE_CATEGORY(V4L2)
>
> /**
> * \fn V4L2Capability::card()
> - * \brief Retrieve the device card name
> - * \return The string containing the device name
> + * \brief Retrieve the video device card name
> + * \return The string containing the video device name
> */
>
> /**
> * \fn V4L2Capability::bus_info()
> - * \brief Retrieve the location of the device in the system
> - * \return The string containing the device location
> + * \brief Retrieve the location of the video device in the system
> + * \return The string containing the video device location
> */
>
> /**
> * \fn V4L2Capability::device_caps()
> - * \brief Retrieve the capabilities of the device
> - * \return The device specific capabilities if V4L2_CAP_DEVICE_CAPS is set or
> - * driver capabilities otherwise
> + * \brief Retrieve the capabilities of the video device
> + * \return The video device specific capabilities if V4L2_CAP_DEVICE_CAPS is
> + * set or driver capabilities otherwise
> */
>
> /**
> * \fn V4L2Capability::isMultiplanar()
> - * \brief Identify if the device implements the V4L2 multiplanar APIs
> - * \return True if the device supports multiplanar APIs
> + * \brief Identify if the video device implements the V4L2 multiplanar APIs
> + * \return True if the video device supports multiplanar APIs
> */
>
> /**
> * \fn V4L2Capability::isCapture()
> - * \brief Identify if the device captures data
> - * \return True if the device can capture data
> + * \brief Identify if the video device captures data
> + * \return True if the video device can capture data
> */
>
> /**
> * \fn V4L2Capability::isOutput()
> - * \brief Identify if the device outputs data
> - * \return True if the device can output data
> + * \brief Identify if the video device outputs data
> + * \return True if the video device can output data
> */
>
> /**
> * \fn V4L2Capability::isVideo()
> - * \brief Identify if the device captures or outputs images
> - * \return True if the device can capture or output images
> + * \brief Identify if the video device captures or outputs images
> + * \return True if the video device can capture or output images
> */
>
> /**
> * \fn V4L2Capability::isMeta()
> - * \brief Identify if the device captures or outputs image meta-data
> - *
> - * \todo Add support for META_CAPTURE introduced in Linux v5.0
> - *
> - * \return True if the device can capture or output image meta-data
> + * \brief Identify if the video device captures or outputs image meta-data
> + * \return True if the video device can capture or output image meta-data
> */
>
> /**
> * \fn V4L2Capability::isVideoCapture()
> - * \brief Identify if the device captures images
> - * \return True if the device can capture images
> + * \brief Identify if the video device captures images
> + * \return True if the video device can capture images
> */
>
> /**
> * \fn V4L2Capability::isVideoOutput()
> - * \brief Identify if the device outputs images
> - * \return True if the device can output images
> + * \brief Identify if the video device outputs images
> + * \return True if the video device can output images
> */
>
> /**
> * \fn V4L2Capability::isMetaCapture()
> - * \brief Identify if the device captures image meta-data
> - * \return True if the device can capture image meta-data
> + * \brief Identify if the video device captures image meta-data
> + * \return True if the video device can capture image meta-data
> */
>
> /**
> * \fn V4L2Capability::isMetaOutput()
> - * \brief Identify if the device outputs image meta-data
> - * \return True if the device can output image meta-data
> + * \brief Identify if the video device outputs image meta-data
> + * \return True if the video device can output image meta-data
> */
>
> /**
> * \fn V4L2Capability::hasStreaming()
> - * \brief Determine if the device can perform Streaming I/O
> - * \return True if the device provides Streaming I/O IOCTLs
> + * \brief Determine if the video device can perform Streaming I/O
> + * \return True if the video device provides Streaming I/O IOCTLs
> */
>
> /**
> * \class V4L2DeviceFormat
> - * \brief The V4L2 device image format and sizes
> + * \brief The V4L2 video device image format and sizes
> *
> * This class describes the image format and resolution to be programmed on a
> * V4L2 video device. The image format is defined by a fourcc code (as specified
> @@ -176,27 +173,29 @@ LOG_DECLARE_CATEGORY(V4L2)
> * length and total size.
> *
> * Packed image formats, which occupy a single memory area, are easily described
> - * through the single-plane API. When used on a device that implements the
> + * through the single-plane API. When used on a video device that implements the
> * multi-plane API, only the size and stride information contained in the first
> * plane are taken into account.
> *
> * Planar image formats, which occupy distinct memory areas, are easily
> - * described through the multi-plane APIs. When used on a device that implements
> - * the single-plane API, all planes are stored one after the other in a
> - * contiguous memory area, and it is not possible to configure per-plane stride
> - * length and size, but only a global stride length which is applied to all
> + * described through the multi-plane APIs. When used on a video device that
> + * implements the single-plane API, all planes are stored one after the other
> + * in a contiguous memory area, and it is not possible to configure per-plane
> + * stride length and size, but only a global stride length which is applied to
> + * all
> * planes.
The last two lines should be squashed together.
> *
> * The V4L2DeviceFormat class describes both packed and planar image formats,
> - * regardless of the API type (single or multi plane) implemented by the device
> - * the format has to be applied to. The total size and bytes per line of images
> - * represented with packed formats are configured using the first entry of the
> - * V4L2DeviceFormat::planes array, while the per-plane size and per-plane stride
> - * length of images represented with planar image formats are configured using
> - * the opportune number of entries of the V4L2DeviceFormat::planes array, as
> - * prescribed by the image format definition (semi-planar formats use 2 entries,
> - * while planar formats use the whole 3 entries). The number of valid entries of
> - * the V4L2DeviceFormat::planes array is defined by the
> + * regardless of the API type (single or multi plane) implemented by the video
> + * device the format has to be applied to. The total size and bytes per line
> + * of images represented with packed formats are configured using the first
> + * entry of the V4L2DeviceFormat::planes array, while the per-plane size and
> + * per-plane stride length of images represented with planar image formats are
> + * configured using the opportune number of entries of the
> + * V4L2DeviceFormat::planes array, as prescribed by the image format
> + * definition (semi-planar formats use 2 entries, while planar formats use the
> + * whole 3 entries). The number of valid entries of the
> + * V4L2DeviceFormat::planes array is defined by the
> * V4L2DeviceFormat::planesCount value.
> */
>
> @@ -246,13 +245,13 @@ const std::string V4L2DeviceFormat::toString() const
> * \class V4L2VideoDevice
> * \brief V4L2VideoDevice object and API
> *
> - * The V4L2 Device API class models an instance of a V4L2 device node.
> + * The V4L2VideoDevice class models an instance of a V4L2 video device.
> * It is constructed with the path to a V4L2 video device node. The device node
> * is only opened upon a call to open() which must be checked for success.
> *
> - * The device capabilities are validated when the device is opened and the
> - * device is rejected if it is not a suitable V4L2 capture or output device, or
> - * if the device does not support streaming I/O.
> + * The video device capabilities are validated when the device is opened and the
> + * device is rejected if it is not a suitable V4L2 capture or output vide
s/vide/video/
> + * device, or if the video device does not support streaming I/O.
> *
> * No API call other than open(), isOpen() and close() shall be called on an
> * unopened device instance.
> @@ -274,8 +273,8 @@ V4L2VideoDevice::V4L2VideoDevice(const std::string &deviceNode)
> queuedBuffersCount_(0), fdEvent_(nullptr)
> {
> /*
> - * We default to an MMAP based CAPTURE device, however this will be
> - * updated based upon the device capabilities.
> + * We default to an MMAP based CAPTURE video device, however this will
> + * be updated based upon the device capabilities.
> */
> bufferType_ = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
> memoryType_ = V4L2_MEMORY_MMAP;
> @@ -283,7 +282,7 @@ V4L2VideoDevice::V4L2VideoDevice(const std::string &deviceNode)
>
> /**
> * \brief Construct a V4L2VideoDevice from a MediaEntity
> - * \param[in] entity The MediaEntity to build the device from
> + * \param[in] entity The MediaEntity to build the video device from
> *
> * Construct a V4L2VideoDevice from a MediaEntity's device node path.
> */
> @@ -298,7 +297,7 @@ V4L2VideoDevice::~V4L2VideoDevice()
> }
>
> /**
> - * \brief Open a V4L2 device and query its capabilities
> + * \brief Open a V4L2 video device and query its capabilities
> * \return 0 on success or a negative error code otherwise
> */
> int V4L2VideoDevice::open()
> @@ -327,8 +326,9 @@ int V4L2VideoDevice::open()
> }
>
> /*
> - * Set buffer type and wait for read notifications on CAPTURE devices
> - * (POLLIN), and write notifications for OUTPUT devices (POLLOUT).
> + * Set buffer type and wait for read notifications on CAPTURE video
> + * devices (POLLIN), and write notifications for OUTPUT video devices
> + * (POLLOUT).
> */
> if (caps_.isVideoCapture()) {
> fdEvent_ = new EventNotifier(fd(), EventNotifier::Read);
> @@ -358,7 +358,7 @@ int V4L2VideoDevice::open()
> }
>
> /**
> - * \brief Close the device, releasing any resources acquired by open()
> + * \brief Close the video device, releasing any resources acquired by open()
> */
> void V4L2VideoDevice::close()
> {
> @@ -373,13 +373,13 @@ void V4L2VideoDevice::close()
>
> /**
> * \fn V4L2VideoDevice::driverName()
> - * \brief Retrieve the name of the V4L2 device driver
> + * \brief Retrieve the name of the V4L2 video device driver
Here I would keep "V4L2 device driver", as the driver refers to a
v4l2_device structure inside the kernel, not just a video device (it can
also have subdevs).
Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> * \return The string containing the driver name
> */
>
> /**
> * \fn V4L2VideoDevice::deviceName()
> - * \brief Retrieve the name of the V4L2 device
> + * \brief Retrieve the name of the V4L2 video device
> * \return The string containing the device name
> */
>
> @@ -390,8 +390,8 @@ void V4L2VideoDevice::close()
> */
>
> /**
> - * \brief Retrieve the image format set on the V4L2 device
> - * \param[out] format The image format applied on the device
> + * \brief Retrieve the image format set on the V4L2 video device
> + * \param[out] format The image format applied on the video device
> * \return 0 on success or a negative error code otherwise
> */
> int V4L2VideoDevice::getFormat(V4L2DeviceFormat *format)
> @@ -405,10 +405,10 @@ int V4L2VideoDevice::getFormat(V4L2DeviceFormat *format)
> }
>
> /**
> - * \brief Configure an image format on the V4L2 device
> - * \param[inout] format The image format to apply to the device
> + * \brief Configure an image format on the V4L2 video device
> + * \param[inout] format The image format to apply to the video device
> *
> - * Apply the supplied \a format to the device, and return the actually
> + * Apply the supplied \a format to the video device, and return the actually
> * applied format parameters, as \ref V4L2VideoDevice::getFormat would do.
> *
> * \return 0 on success or a negative error code otherwise
> @@ -462,7 +462,7 @@ int V4L2VideoDevice::setFormatMeta(V4L2DeviceFormat *format)
> }
>
> /*
> - * Return to caller the format actually applied on the device,
> + * Return to caller the format actually applied on the video device,
> * which might differ from the requested one.
> */
> format->size.width = 0;
> @@ -526,7 +526,7 @@ int V4L2VideoDevice::setFormatMultiplane(V4L2DeviceFormat *format)
> }
>
> /*
> - * Return to caller the format actually applied on the device,
> + * Return to caller the format actually applied on the video device,
> * which might differ from the requested one.
> */
> format->size.width = pix->width;
> @@ -601,7 +601,7 @@ int V4L2VideoDevice::setFormatSingleplane(V4L2DeviceFormat *format)
> *
> * Enumerate all pixel formats and frame sizes supported by the video device.
> *
> - * \return A list of the supported device formats
> + * \return A list of the supported video device formats
> */
> ImageFormats V4L2VideoDevice::formats()
> {
> @@ -646,8 +646,8 @@ int V4L2VideoDevice::requestBuffers(unsigned int count)
> }
>
> /**
> - * \brief Request buffers to be allocated from the device and stored in the
> - * buffer pool provided.
> + * \brief Request buffers to be allocated from the video device and stored in
> + * the buffer pool provided.
> * \param[out] pool BufferPool to populate with buffers
> * \return 0 on success or a negative error code otherwise
> */
> @@ -878,13 +878,13 @@ int V4L2VideoDevice::releaseBuffers()
> }
>
> /**
> - * \brief Queue a buffer into the device
> + * \brief Queue a buffer into the video device
> * \param[in] buffer The buffer to be queued
> *
> - * For capture devices the \a buffer will be filled with data by the device.
> - * For output devices the \a buffer shall contain valid data and will be
> - * processed by the device. Once the device has finished processing the buffer,
> - * it will be available for dequeue.
> + * For capture video devices the \a buffer will be filled with data by the
> + * device. For output video devices the \a buffer shall contain valid data and
> + * will be processed by the device. Once the device has finished processing the
> + * buffer, it will be available for dequeue.
> *
> * \return 0 on success or a negative error code otherwise
> */
> @@ -941,7 +941,7 @@ int V4L2VideoDevice::queueBuffer(Buffer *buffer)
> }
>
> /**
> - * \brief Dequeue the next available buffer from the device
> + * \brief Dequeue the next available buffer from the video device
> *
> * This method dequeues the next available buffer from the device. If no buffer
> * is available to be dequeued it will return nullptr immediately.
> @@ -987,14 +987,14 @@ Buffer *V4L2VideoDevice::dequeueBuffer()
> }
>
> /**
> - * \brief Slot to handle completed buffer events from the V4L2 device
> + * \brief Slot to handle completed buffer events from the V4L2 video device
> * \param[in] notifier The event notifier
> *
> * When this slot is called, a Buffer has become available from the device, and
> * will be emitted through the bufferReady Signal.
> *
> - * For Capture devices the Buffer will contain valid data.
> - * For Output devices the Buffer can be considered empty.
> + * For Capture video devices the Buffer will contain valid data.
> + * For Output video devices the Buffer can be considered empty.
> */
> void V4L2VideoDevice::bufferAvailable(EventNotifier *notifier)
> {
--
Regards,
Laurent Pinchart
More information about the libcamera-devel
mailing list