include/media/v4l2-ctrls.h

1 /* SPDX-License-Identifier: GPL-2.0-or-later */
14 #include <media/media-request.h>
29  * union v4l2_ctrl_ptr - A pointer to a control value.
30  * @p_s32:			Pointer to a 32-bit signed value.
31  * @p_s64:			Pointer to a 64-bit signed value.
32  * @p_u8:			Pointer to a 8-bit unsigned value.
33  * @p_u16:			Pointer to a 16-bit unsigned value.
34  * @p_u32:			Pointer to a 32-bit unsigned value.
60  * @p:				Pointer to a compound value.
61  * @p_const:			Pointer to a constant compound value.
99  * v4l2_ctrl_ptr_create() - Helper function to return a v4l2_ctrl_ptr from a
111  * struct v4l2_ctrl_ops - The control operations that the driver has to provide.
114  *		for volatile (and usually read-only) controls such as a control
121  *		ctrl->handler->lock is held when these ops are called, so no
131  * struct v4l2_ctrl_type_ops - The control type operations that the driver
134  * @equal: return true if all ctrl->elems array elements are equal.
135  * @init: initialize the value for array elements from from_idx to ctrl->elems.
139  * @validate: validate the value for ctrl->new_elems array elements.
156  * typedef v4l2_ctrl_notify_fnc - typedef for a notify argument with a function
168  * struct v4l2_ctrl - The control structure.
189  *		uses ctrl->val).
195  * @is_array: If set, then this control contains an N-dimensional array.
196  * @is_dyn_array: If set, then this control contains a dynamically sized 1-dimensional array.
215  * @step:	The control's step value for non-menu controls.
216  * @elems:	The number of elements in the N-dimensional array.
230  *		empty strings ("") correspond to non-existing menu items (this
234  * @qmenu_int:	A 64-bit integer array for with integer menu items.
236  *		:math:`ceil(\frac{maximum - minimum}{step}) + 1`.
255  *		through a pointer (for compound controls only).
258  *		through a pointer (for compound controls only).
261  *		through a pointer (for compound controls only).
328  * struct v4l2_ctrl_ref - The control reference.
331  * @next:	Single-link list node for the hash.
334  *		``prepare_ext_ctrls`` function at ``v4l2-ctrl.c``.
336  *		device than the &struct v4l2_ctrl_handler.
345  *		result in ENOMEM. Only valid if ctrl->is_array is true.
347  *		array. Only valid if @p_req_valid and ctrl->is_array are
350  *		ctrl->elems, except for dynamic arrays. In that case it is in
362  * keep a sorted-by-control-ID list of all controls, while the next pointer
380  * struct v4l2_ctrl_handler - The control handler keeps track of all the
430  * struct v4l2_ctrl_config - Control configuration structure.
433  * @type_ops:	The control type ops. Only needed for compound controls.
439  * @step:	The control's step value for non-menu controls.
441  * @p_def:	The control's default value for compound controls.
442  * @p_min:	The control's minimum value for compound controls.
443  * @p_max:	The control's maximum value for compound controls.
454  *		empty strings ("") correspond to non-existing menu items (this
485  * v4l2_ctrl_fill - Fill in the control fields based on the control ID.
497  * For non-standard controls it will only fill in the given arguments
515  * v4l2_ctrl_handler_init_class() - Initialize the control handler.
533  * error will also be stored in @hdl->error.
542  * v4l2_ctrl_handler_init - helper function to create a static struct
568 					"(" #hdl ")->_lock");		\
577  * v4l2_ctrl_handler_free() - Free all controls owned by the handler and free
586  * v4l2_ctrl_lock() - Helper function to lock the handler
592 	mutex_lock(ctrl->handler->lock);  in v4l2_ctrl_lock()
596  * v4l2_ctrl_unlock() - Helper function to unlock the handler
602 	mutex_unlock(ctrl->handler->lock);  in v4l2_ctrl_unlock()
606  * __v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
612  * Button controls will be skipped, as are read-only controls.
619  * v4l2_ctrl_handler_setup() - Call the s_ctrl op for all controls belonging
623  * Button controls will be skipped, as are read-only controls.
630  * v4l2_ctrl_handler_log_status() - Log all controls owned by the handler.
645  * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
650  * @priv:	The control's driver-specific private data.
653  * and @hdl->error is set to the error code (if it wasn't set already).
660  * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu
672  * ID is not known, then NULL is returned and @hdl->error is set to the
685  * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2
703  * If @id refers to a non-menu control, then this function will return NULL.
710  * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
737  * v4l2_ctrl_new_std_compound() - Allocate and initialize a new standard V4L2
738  *      compound control.
747  * Same as v4l2_ctrl_new_std(), but with support for compound controls.
751  * value of the compound control to be all zeroes.
752  * If the compound control does not set the ``V4L2_CTRL_FLAG_HAS_WHICH_MIN_MAX``
765  * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
777  * If @id refers to a non-integer-menu control, then this function will
786  * typedef v4l2_ctrl_filter - Typedef to define the filter function to be
795  * v4l2_ctrl_add_handler() - Add all controls from handler @add to
803  *		device than @hdl.
808  * In case of an error @hdl->error will be set to the error code (if it
817  * v4l2_ctrl_radio_filter() - Standard filter for radio controls.
821  * This will return true for any controls that are valid for radio device
830  * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging
840  * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging
841  *	to that cluster and set it up for autofoo/foo-type handling.
853  * off (manual mode). Typical examples: autogain vs gain, auto-whitebalance vs
876  * v4l2_ctrl_find() - Find a control with the given ID.
887  * v4l2_ctrl_activate() - Make the control active or inactive.
901  * __v4l2_ctrl_grab() - Unlocked variant of v4l2_ctrl_grab.
917  * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
942  *__v4l2_ctrl_modify_range() - Unlocked variant of v4l2_ctrl_modify_range()
964  * v4l2_ctrl_modify_range() - Update the range of a control.
995  *__v4l2_ctrl_modify_dimensions() - Unlocked variant of v4l2_ctrl_modify_dimensions()
1017  * v4l2_ctrl_modify_dimensions() - Update the dimensions of an array control.
1048  * v4l2_ctrl_notify() - Function to set a notify callback for a control.
1065  * v4l2_ctrl_get_name() - Get the name of the control
1075  * v4l2_ctrl_get_menu() - Get the menu string array of the control
1079  * This function returns the NULL-terminated menu string array name of the
1085  * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
1096  * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from
1110  * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
1124  * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from
1147  * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
1156  * This function is for 64-bit integer type controls only.
1161  * __v4l2_ctrl_s_ctrl_int64() - Unlocked variant of v4l2_ctrl_s_ctrl_int64().
1170  * This function is for 64-bit integer type controls only.
1175  * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
1185  * This function is for 64-bit integer type controls only.
1199  * __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
1213  * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
1237  * __v4l2_ctrl_s_ctrl_compound() - Unlocked variant to set a compound control
1241  * @p:    The new compound payload.
1243  * This sets the control's new compound payload safely by going through the
1247  * This function is for compound type controls only.
1253  * v4l2_ctrl_s_ctrl_compound() - Helper function to set a compound control
1258  * @p:    The new compound payload.
1260  * This sets the control's new compound payload safely by going through the
1264  * This function is for compound type controls only.
1289  * v4l2_ctrl_replace - Function to be used as a callback to
1300  * v4l2_ctrl_merge - Function to be used as a callback to
1311  * v4l2_ctrl_log_status - helper function to implement %VIDIOC_LOG_STATUS ioctl
1323  * v4l2_ctrl_subscribe_event - Subscribes to an event
1336  * v4l2_ctrl_poll - function to be used as a callback to the poll()
1345  * v4l2_ctrl_request_setup - helper function to apply control values in a request
1352  * applying control values in a request is only applicable to memory-to-memory
1359  * v4l2_ctrl_request_complete - Complete a control handler request object
1376  * v4l2_ctrl_request_hdl_find - Find the control handler in the request
1397  * v4l2_ctrl_request_hdl_put - Put the control handler
1407 		media_request_object_put(&hdl->req_obj);  in v4l2_ctrl_request_hdl_put()
1411  * v4l2_ctrl_request_hdl_ctrl_find() - Find a control with the given ID.
1425  * v4l2_queryctrl - Helper function to implement
1431  * If hdl == NULL then they will all return -EINVAL.
1436  * v4l2_query_ext_ctrl_to_v4l2_queryctrl - Convert a qec to qe.
1448  * v4l2_query_ext_ctrl - Helper function to implement
1454  * If hdl == NULL then they will all return -EINVAL.
1460  * v4l2_querymenu - Helper function to implement
1466  * If hdl == NULL then they will all return -EINVAL.
1471  * v4l2_g_ctrl - Helper function to implement
1477  * If hdl == NULL then they will all return -EINVAL.
1482  * v4l2_s_ctrl - Helper function to implement
1490  * If hdl == NULL then they will all return -EINVAL.
1496  * v4l2_g_ext_ctrls - Helper function to implement
1504  * If hdl == NULL then they will all return -EINVAL.
1510  * v4l2_try_ext_ctrls - Helper function to implement
1518  * If hdl == NULL then they will all return -EINVAL.
1526  * v4l2_s_ext_ctrls - Helper function to implement
1535  * If hdl == NULL then they will all return -EINVAL.
1543  * v4l2_ctrl_subdev_subscribe_event - Helper function to implement
1555  * v4l2_ctrl_subdev_log_status - Log all controls owned by subdev's control
1563  * v4l2_ctrl_new_fwnode_properties() - Register controls for the device
1570  * This function registers controls associated to device properties, using the
1575  * - V4L2_CID_CAMERA_ORIENTATION
1576  * - V4L2_CID_CAMERA_SENSOR_ROTATION;
1589  * v4l2_ctrl_type_op_equal - Default v4l2_ctrl_type_ops equal callback.
1601  * v4l2_ctrl_type_op_init - Default v4l2_ctrl_type_ops init callback.
1613  * v4l2_ctrl_type_op_log - Default v4l2_ctrl_type_ops log callback.
1622  * v4l2_ctrl_type_op_validate - Default v4l2_ctrl_type_ops validate callback.