diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-dqevent.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/vidioc-dqevent.rst | 391 |
1 files changed, 0 insertions, 391 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-dqevent.rst b/Documentation/media/uapi/v4l/vidioc-dqevent.rst deleted file mode 100644 index 2f37d255352a..000000000000 --- a/Documentation/media/uapi/v4l/vidioc-dqevent.rst +++ /dev/null @@ -1,391 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDIOC_DQEVENT: - -******************** -ioctl VIDIOC_DQEVENT -******************** - -Name -==== - -VIDIOC_DQEVENT - Dequeue event - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, VIDIOC_DQEVENT, struct v4l2_event *argp ) - :name: VIDIOC_DQEVENT - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() <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. - - -.. tabularcolumns:: |p{3.0cm}|p{4.4cm}|p{2.4cm}|p{7.7cm}| - -.. c:type:: v4l2_event - -.. cssclass: longtable - -.. 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.6cm}|p{2.2cm}|p{8.7cm}| - -.. 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.7cm}| - -.. 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{1.8cm}|p{8.5cm}| - -.. 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 value of the control. See struct - :ref:`v4l2_queryctrl <v4l2-queryctrl>`. - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. 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.7cm}| - -.. 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.7cm}| - -.. 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.7cm}| - -.. _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. - - - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. _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. |