diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst new file mode 100644 index 000000000000..90e2a6635ebc --- /dev/null +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst @@ -0,0 +1,171 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDIOC_SUBDEV_G_FMT: + +********************************************** +ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT +********************************************** + +Name +==== + +VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_format *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``request`` + VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT + +``argp`` + + +Description +=========== + +These ioctls are used to negotiate the frame format at specific subdev +pads in the image pipeline. + +To retrieve the current format applications set the ``pad`` field of a +struct :ref:`v4l2_subdev_format <v4l2-subdev-format>` to the desired +pad number as reported by the media API and the ``which`` field to +``V4L2_SUBDEV_FORMAT_ACTIVE``. When they call the +``VIDIOC_SUBDEV_G_FMT`` ioctl with a pointer to this structure the +driver fills the members of the ``format`` field. + +To change the current format applications set both the ``pad`` and +``which`` fields and all members of the ``format`` field. When they call +the ``VIDIOC_SUBDEV_S_FMT`` ioctl with a pointer to this structure the +driver verifies the requested format, adjusts it based on the hardware +capabilities and configures the device. Upon return the struct +:ref:`v4l2_subdev_format <v4l2-subdev-format>` contains the current +format as would be returned by a ``VIDIOC_SUBDEV_G_FMT`` call. + +Applications can query the device capabilities by setting the ``which`` +to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' formats are not applied +to the device by the driver, but are changed exactly as active formats +and stored in the sub-device file handle. Two applications querying the +same sub-device would thus not interact with each other. + +For instance, to try a format at the output pad of a sub-device, +applications would first set the try format at the sub-device input with +the ``VIDIOC_SUBDEV_S_FMT`` ioctl. They would then either retrieve the +default format at the output pad with the ``VIDIOC_SUBDEV_G_FMT`` ioctl, +or set the desired output pad format with the ``VIDIOC_SUBDEV_S_FMT`` +ioctl and check the returned value. + +Try formats do not depend on active formats, but can depend on the +current links configuration or sub-device controls value. For instance, +a low-pass noise filter might crop pixels at the frame boundaries, +modifying its output frame size. + +Drivers must not return an error solely because the requested format +doesn't match the device capabilities. They must instead modify the +format to match what the hardware can provide. The modified format +should be as close as possible to the original request. + + +.. _v4l2-subdev-format: + +.. flat-table:: struct v4l2_subdev_format + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``pad`` + + - Pad number as reported by the media controller API. + + - .. row 2 + + - __u32 + + - ``which`` + + - Format to modified, from enum + :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. + + - .. row 3 + + - struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>` + + - ``format`` + + - Definition of an image format, see :ref:`v4l2-mbus-framefmt` for + details. + + - .. row 4 + + - __u32 + + - ``reserved``\ [8] + + - Reserved for future extensions. Applications and drivers must set + the array to zero. + + + +.. _v4l2-subdev-format-whence: + +.. flat-table:: enum v4l2_subdev_format_whence + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - V4L2_SUBDEV_FORMAT_TRY + + - 0 + + - Try formats, used for querying device capabilities. + + - .. row 2 + + - V4L2_SUBDEV_FORMAT_ACTIVE + + - 1 + + - Active formats, applied to the hardware. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EBUSY + The format can't be changed because the pad is currently busy. This + can be caused, for instance, by an active video stream on the pad. + The ioctl must not be retried without performing another action to + fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT`` + +EINVAL + The struct :ref:`v4l2_subdev_format <v4l2-subdev-format>` + ``pad`` references a non-existing pad, or the ``which`` field + references a non-existing format. + + +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. |