diff options
Diffstat (limited to 'Documentation/userspace-api/media/v4l/vidioc-dqevent.rst')
| -rw-r--r-- | Documentation/userspace-api/media/v4l/vidioc-dqevent.rst | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst new file mode 100644 index 0000000000..8db1037609 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/vidioc-dqevent.rst @@ -0,0 +1,377 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L + +.. _VIDIOC_DQEVENT: + +******************** +ioctl VIDIOC_DQEVENT +******************** + +Name +==== + +VIDIOC_DQEVENT - Dequeue event + +Synopsis +======== + +.. c:macro:: VIDIOC_DQEVENT + +``int ioctl(int fd, VIDIOC_DQEVENT, struct v4l2_event *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`v4l2_event`. + +Description +=========== + +Dequeue an event from a video device. No input is required for this +ioctl. All the fields of the struct :c:type:`v4l2_event` +structure are filled by the driver. The file handle will also receive +exceptions which the application may get by e.g. using the select system +call. + +.. c:type:: v4l2_event + +.. tabularcolumns:: |p{3.0cm}|p{3.4cm}|p{10.9cm}| + + +.. flat-table:: struct v4l2_event + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``type`` + - Type of the event, see :ref:`event-type`. + * - union { + - ``u`` + * - struct :c:type:`v4l2_event_vsync` + - ``vsync`` + - Event data for event ``V4L2_EVENT_VSYNC``. + * - struct :c:type:`v4l2_event_ctrl` + - ``ctrl`` + - Event data for event ``V4L2_EVENT_CTRL``. + * - struct :c:type:`v4l2_event_frame_sync` + - ``frame_sync`` + - Event data for event ``V4L2_EVENT_FRAME_SYNC``. + * - struct :c:type:`v4l2_event_motion_det` + - ``motion_det`` + - Event data for event V4L2_EVENT_MOTION_DET. + * - struct :c:type:`v4l2_event_src_change` + - ``src_change`` + - Event data for event V4L2_EVENT_SOURCE_CHANGE. + * - __u8 + - ``data``\ [64] + - Event data. Defined by the event type. The union should be used to + define easily accessible type for events. + * - } + - + * - __u32 + - ``pending`` + - Number of pending events excluding this one. + * - __u32 + - ``sequence`` + - Event sequence number. The sequence number is incremented for + every subscribed event that takes place. If sequence numbers are + not contiguous it means that events have been lost. + * - struct timespec + - ``timestamp`` + - Event timestamp. The timestamp has been taken from the + ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2, + use :c:func:`clock_gettime`. + * - u32 + - ``id`` + - The ID associated with the event source. If the event does not + have an associated ID (this depends on the event type), then this + is 0. + * - __u32 + - ``reserved``\ [8] + - Reserved for future extensions. Drivers must set the array to + zero. + + +.. tabularcolumns:: |p{6.2cm}|p{2.6cm}|p{8.5cm}| + +.. cssclass:: longtable + +.. _event-type: + +.. flat-table:: Event Types + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_EVENT_ALL`` + - 0 + - All events. V4L2_EVENT_ALL is valid only for + VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. + * - ``V4L2_EVENT_VSYNC`` + - 1 + - This event is triggered on the vertical sync. This event has a + struct :c:type:`v4l2_event_vsync` associated + with it. + * - ``V4L2_EVENT_EOS`` + - 2 + - This event is triggered when the end of a stream is reached. This + is typically used with MPEG decoders to report to the application + when the last of the MPEG stream has been decoded. + * - ``V4L2_EVENT_CTRL`` + - 3 + - This event requires that the ``id`` matches the control ID from + which you want to receive events. This event is triggered if the + control's value changes, if a button control is pressed or if the + control's flags change. This event has a struct + :c:type:`v4l2_event_ctrl` associated with it. + This struct contains much of the same information as struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct + :c:type:`v4l2_control`. + + If the event is generated due to a call to + :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or + :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the + event will *not* be sent to the file handle that called the ioctl + function. This prevents nasty feedback loops. If you *do* want to + get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK`` + flag. + + This event type will ensure that no information is lost when more + events are raised than there is room internally. In that case the + struct :c:type:`v4l2_event_ctrl` of the + second-oldest event is kept, but the ``changes`` field of the + second-oldest event is ORed with the ``changes`` field of the + oldest event. + * - ``V4L2_EVENT_FRAME_SYNC`` + - 4 + - Triggered immediately when the reception of a frame has begun. + This event has a struct + :c:type:`v4l2_event_frame_sync` + associated with it. + + If the hardware needs to be stopped in the case of a buffer + underrun it might not be able to generate this event. In such + cases the ``frame_sequence`` field in struct + :c:type:`v4l2_event_frame_sync` will not + be incremented. This causes two consecutive frame sequence numbers + to have n times frame interval in between them. + * - ``V4L2_EVENT_SOURCE_CHANGE`` + - 5 + - This event is triggered when a source parameter change is detected + during runtime by the video device. It can be a runtime resolution + change triggered by a video decoder or the format change happening + on an input connector. This event requires that the ``id`` matches + the input index (when used with a video device node) or the pad + index (when used with a subdevice node) from which you want to + receive events. + + This event has a struct + :c:type:`v4l2_event_src_change` + associated with it. The ``changes`` bitfield denotes what has + changed for the subscribed pad. If multiple events occurred before + application could dequeue them, then the changes will have the + ORed value of all the events generated. + * - ``V4L2_EVENT_MOTION_DET`` + - 6 + - Triggered whenever the motion detection state for one or more of + the regions changes. This event has a struct + :c:type:`v4l2_event_motion_det` + associated with it. + * - ``V4L2_EVENT_PRIVATE_START`` + - 0x08000000 + - Base event number for driver-private events. + + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. c:type:: v4l2_event_vsync + +.. flat-table:: struct v4l2_event_vsync + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``field`` + - The upcoming field. See enum :c:type:`v4l2_field`. + + +.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{10.8cm}| + +.. c:type:: v4l2_event_ctrl + +.. flat-table:: struct v4l2_event_ctrl + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``changes`` + - A bitmask that tells what has changed. See + :ref:`ctrl-changes-flags`. + * - __u32 + - ``type`` + - The type of the control. See enum + :c:type:`v4l2_ctrl_type`. + * - union { + - (anonymous) + * - __s32 + - ``value`` + - The 32-bit value of the control for 32-bit control types. This is + 0 for string controls since the value of a string cannot be passed + using :ref:`VIDIOC_DQEVENT`. + * - __s64 + - ``value64`` + - The 64-bit value of the control for 64-bit control types. + * - } + - + * - __u32 + - ``flags`` + - The control flags. See :ref:`control-flags`. + * - __s32 + - ``minimum`` + - The minimum value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + * - __s32 + - ``maximum`` + - The maximum value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + * - __s32 + - ``step`` + - The step value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + * - __s32 + - ``default_value`` + - The default value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. c:type:: v4l2_event_frame_sync + +.. flat-table:: struct v4l2_event_frame_sync + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``frame_sequence`` + - The sequence number of the frame being received. + + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. c:type:: v4l2_event_src_change + +.. flat-table:: struct v4l2_event_src_change + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``changes`` + - A bitmask that tells what has changed. See + :ref:`src-changes-flags`. + + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. c:type:: v4l2_event_motion_det + +.. flat-table:: struct v4l2_event_motion_det + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``flags`` + - Currently only one flag is available: if + ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the + ``frame_sequence`` field is valid, otherwise that field should be + ignored. + * - __u32 + - ``frame_sequence`` + - The sequence number of the frame being received. Only valid if the + ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set. + * - __u32 + - ``region_mask`` + - The bitmask of the regions that reported motion. There is at least + one region. If this field is 0, then no motion was detected at + all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control + (see :ref:`detect-controls`) to assign a different region to + each cell in the motion detection grid, then that all cells are + automatically assigned to the default region 0. + + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| + +.. _ctrl-changes-flags: + +.. flat-table:: Control Changes + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_EVENT_CTRL_CH_VALUE`` + - 0x0001 + - This control event was triggered because the value of the control + changed. Special cases: Volatile controls do no generate this + event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` + flag set, then this event is sent as well, regardless its value. + * - ``V4L2_EVENT_CTRL_CH_FLAGS`` + - 0x0002 + - This control event was triggered because the control flags + changed. + * - ``V4L2_EVENT_CTRL_CH_RANGE`` + - 0x0004 + - This control event was triggered because the minimum, maximum, + step or the default value of the control changed. + * - ``V4L2_EVENT_CTRL_CH_DIMENSIONS`` + - 0x0008 + - This control event was triggered because the dimensions of the + control changed. Note that the number of dimensions remains the + same. + + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| + +.. _src-changes-flags: + +.. flat-table:: Source Changes + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_EVENT_SRC_CH_RESOLUTION`` + - 0x0001 + - This event gets triggered when a resolution change is detected at + an input. This can come from an input connector or from a video + decoder. Applications will have to query the new resolution (if + any, the signal may also have been lost). + + For stateful decoders follow the guidelines in :ref:`decoder`. + Video Capture devices have to query the new timings using + :ref:`VIDIOC_QUERY_DV_TIMINGS` or + :ref:`VIDIOC_QUERYSTD <VIDIOC_QUERYSTD>`. + + *Important*: even if the new video timings appear identical to the old + ones, receiving this event indicates that there was an issue with the + video signal and you must stop and restart streaming + (:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` + followed by :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`). The reason is + that many Video Capture devices are not able to recover from a temporary + loss of signal and so restarting streaming I/O is required in order for + the hardware to synchronize to the video signal. + +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. |