--- zzzz-none-000/linux-3.10.107/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml 2017-06-27 09:49:32.000000000 +0000 +++ scorpion-7490-727/linux-3.10.107/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml 2021-02-04 17:41:59.000000000 +0000 @@ -1,11 +1,12 @@ - ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU + ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU &manvol; VIDIOC_QUERYCTRL + VIDIOC_QUERY_EXT_CTRL VIDIOC_QUERYMENU Enumerate controls and menu control items @@ -24,6 +25,14 @@ int ioctl int fd int request + struct v4l2_query_ext_ctrl *argp + + + + + int ioctl + int fd + int request struct v4l2_querymenu *argp @@ -42,7 +51,7 @@ request - VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU + VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU @@ -67,7 +76,7 @@ VIDIOC_QUERYCTRL with successive id values starting from V4L2_CID_BASE up to and exclusive -V4L2_CID_BASE_LASTP1. Drivers may return +V4L2_CID_LASTP1. Drivers may return EINVAL if a control in this range is not supported. Further applications can enumerate private controls, which are not defined in this specification, by starting at @@ -89,9 +98,24 @@ When the application ORs id with V4L2_CTRL_FLAG_NEXT_CTRL the driver returns the -next supported control, or EINVAL if there is -none. Drivers which do not support this flag yet always return -EINVAL. +next supported non-compound control, or EINVAL +if there is none. In addition, the V4L2_CTRL_FLAG_NEXT_COMPOUND +flag can be specified to enumerate all compound controls (i.e. controls +with type ≥ V4L2_CTRL_COMPOUND_TYPES and/or array +control, in other words controls that contain more than one value). +Specify both V4L2_CTRL_FLAG_NEXT_CTRL and +V4L2_CTRL_FLAG_NEXT_COMPOUND in order to enumerate +all controls, compound or not. Drivers which do not support these flags yet +always return EINVAL. + + The VIDIOC_QUERY_EXT_CTRL ioctl was +introduced in order to better support controls that can use compound +types, and to expose additional control information that cannot be +returned in &v4l2-queryctrl; since that structure is full. + + VIDIOC_QUERY_EXT_CTRL is used in the +same way as VIDIOC_QUERYCTRL, except that the +reserved array must be zeroed as well. Additional information is required for menu controls: the names of the menu items. To query them applications set the @@ -142,38 +166,23 @@ __s32 minimum Minimum value, inclusive. This field gives a lower -bound for V4L2_CTRL_TYPE_INTEGER controls and the -lowest valid index for V4L2_CTRL_TYPE_MENU controls. -For V4L2_CTRL_TYPE_STRING controls the minimum value -gives the minimum length of the string. This length does not include the terminating -zero. It may not be valid for any other type of control, including -V4L2_CTRL_TYPE_INTEGER64 controls. Note that this is a -signed value. +bound for the control. See &v4l2-ctrl-type; how the minimum value is to +be used for each possible control type. Note that this a signed 32-bit value. __s32 maximum Maximum value, inclusive. This field gives an upper -bound for V4L2_CTRL_TYPE_INTEGER controls and the -highest valid index for V4L2_CTRL_TYPE_MENU -controls. For V4L2_CTRL_TYPE_BITMASK controls it is the -set of usable bits. -For V4L2_CTRL_TYPE_STRING controls the maximum value -gives the maximum length of the string. This length does not include the terminating -zero. It may not be valid for any other type of control, including -V4L2_CTRL_TYPE_INTEGER64 controls. Note that this is a -signed value. +bound for the control. See &v4l2-ctrl-type; how the maximum value is to +be used for each possible control type. Note that this a signed 32-bit value. __s32 step - This field gives a step size for -V4L2_CTRL_TYPE_INTEGER controls. For -V4L2_CTRL_TYPE_STRING controls this field refers to -the string length that has to be a multiple of this step size. -It may not be valid for any other type of control, including -V4L2_CTRL_TYPE_INTEGER64 -controls.Generally drivers should not scale hardware + This field gives a step size for the control. +See &v4l2-ctrl-type; how the step value is to be used for each possible +control type. Note that this an unsigned 32-bit value. +Generally drivers should not scale hardware control values. It may be necessary for example when the name or id imply a particular unit and the hardware actually accepts only multiples of @@ -192,10 +201,11 @@ default_value The default value of a V4L2_CTRL_TYPE_INTEGER, -_BOOLEAN or _MENU control. -Not valid for other types of controls. Drivers reset controls only -when the driver is loaded, not later, in particular not when the -func-open; is called. +_BOOLEAN, _BITMASK, +_MENU or _INTEGER_MENU control. +Not valid for other types of controls. +Note that drivers reset controls to their default value only when the +driver is first loaded, never afterwards. __u32 @@ -213,6 +223,126 @@ + + struct <structname>v4l2_query_ext_ctrl</structname> + + &cs-str; + + + __u32 + id + Identifies the control, set by the application. See + for predefined IDs. When the ID is ORed +with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the +flag and returns the first non-compound control with a higher ID. When the +ID is ORed with V4L2_CTRL_FLAG_NEXT_COMPOUND the driver +clears the flag and returns the first compound control with a higher ID. +Set both to get the first control (compound or not) with a higher ID. + + + __u32 + type + Type of control, see . + + + char + name[32] + Name of the control, a NUL-terminated ASCII +string. This information is intended for the user. + + + __s64 + minimum + Minimum value, inclusive. This field gives a lower +bound for the control. See &v4l2-ctrl-type; how the minimum value is to +be used for each possible control type. Note that this a signed 64-bit value. + + + __s64 + maximum + Maximum value, inclusive. This field gives an upper +bound for the control. See &v4l2-ctrl-type; how the maximum value is to +be used for each possible control type. Note that this a signed 64-bit value. + + + __u64 + step + This field gives a step size for the control. +See &v4l2-ctrl-type; how the step value is to be used for each possible +control type. Note that this an unsigned 64-bit value. +Generally drivers should not scale hardware +control values. It may be necessary for example when the +name or id imply +a particular unit and the hardware actually accepts only multiples of +said unit. If so, drivers must take care values are properly rounded +when scaling, such that errors will not accumulate on repeated +read-write cycles.This field gives the smallest change of +an integer control actually affecting hardware. Often the information +is needed when the user can change controls by keyboard or GUI +buttons, rather than a slider. When for example a hardware register +accepts values 0-511 and the driver reports 0-65535, step should be +128. + + + __s64 + default_value + The default value of a +V4L2_CTRL_TYPE_INTEGER, _INTEGER64, +_BOOLEAN, _BITMASK, +_MENU, _INTEGER_MENU, +_U8 or _U16 control. +Not valid for other types of controls. +Note that drivers reset controls to their default value only when the +driver is first loaded, never afterwards. + + + + __u32 + flags + Control flags, see . + + + __u32 + elem_size + The size in bytes of a single element of the array. +Given a char pointer p to a 3-dimensional array you can find the +position of cell (z, y, x) as follows: +p + ((z * dims[1] + y) * dims[0] + x) * elem_size. elem_size +is always valid, also when the control isn't an array. For string controls +elem_size is equal to maximum + 1. + + + + __u32 + elems + The number of elements in the N-dimensional array. If this control +is not an array, then elems is 1. The elems +field can never be 0. + + + __u32 + nr_of_dims + The number of dimension in the N-dimensional array. If this control +is not an array, then this field is 0. + + + __u32 + dims[V4L2_CTRL_MAX_DIMS] + The size of each dimension. The first nr_of_dims +elements of this array must be non-zero, all remaining elements must be zero. + + + __u32 + reserved[32] + Reserved for future extensions. Applications and drivers +must set the array to zero. + + + +
+ struct <structname>v4l2_querymenu</structname> @@ -293,7 +423,7 @@ any An integer-valued control ranging from minimum to maximum inclusive. The step value indicates the increment between -values which are actually different on the hardware. +values. V4L2_CTRL_TYPE_BOOLEAN @@ -347,11 +477,14 @@ V4L2_CTRL_TYPE_INTEGER64 - n/a - n/a - n/a + any + any + any A 64-bit integer valued control. Minimum, maximum -and step size cannot be queried. +and step size cannot be queried using VIDIOC_QUERYCTRL. +Only VIDIOC_QUERY_EXT_CTRL can retrieve the 64-bit +min/max/step values, they should be interpreted as n/a when using +VIDIOC_QUERYCTRL. V4L2_CTRL_TYPE_STRING @@ -379,6 +512,36 @@ Older drivers which do not support this feature return an &EINVAL;. + + V4L2_CTRL_TYPE_U8 + any + any + any + An unsigned 8-bit valued control ranging from minimum to +maximum inclusive. The step value indicates the increment between +values. + + + + V4L2_CTRL_TYPE_U16 + any + any + any + An unsigned 16-bit valued control ranging from minimum to +maximum inclusive. The step value indicates the increment between +values. + + + + V4L2_CTRL_TYPE_U32 + any + any + any + An unsigned 32-bit valued control ranging from minimum to +maximum inclusive. The step value indicates the increment between +values. + +
@@ -448,7 +611,25 @@ changes continuously. A typical example would be the current gain value if the device is in auto-gain mode. In such a case the hardware calculates the gain value based on the lighting conditions which can change over time. Note that setting a new value for -a volatile control will have no effect. The new value will just be ignored. +a volatile control will have no effect and no V4L2_EVENT_CTRL_CH_VALUE +will be sent, unless the V4L2_CTRL_FLAG_EXECUTE_ON_WRITE flag +(see below) is also set. Otherwise the new value will just be ignored. + + + V4L2_CTRL_FLAG_HAS_PAYLOAD + 0x0100 + This control has a pointer type, so its value has to be accessed +using one of the pointer fields of &v4l2-ext-control;. This flag is set for controls +that are an array, string, or have a compound type. In all cases you have to set a +pointer to memory containing the payload of the control. + + + V4L2_CTRL_FLAG_EXECUTE_ON_WRITE + 0x0200 + The value provided to the control will be propagated to the driver +even if it remains constant. This is required when the control represents an action +on the hardware. For example: clearing an error flag or triggering the flash. All the +controls of the type V4L2_CTRL_TYPE_BUTTON have this flag set.