Documentation/video4linux/v4l2-controls.txt

4 The V4L2 control API seems simple enough, but quickly becomes very hard to
10 1) How do I add a control?
11 2) How do I set the control's value? (i.e. s_ctrl)
15 3) How do I get the control's value? (i.e. g_volatile_ctrl)
16 4) How do I validate the user's proposed control value? (i.e. try_ctrl)
20 The control framework was created in order to implement all the rules of the
24 Note that the control framework relies on the presence of a struct v4l2_device
33 The v4l2_ctrl object describes the control properties and keeps track of the
34 control's value (both the current value and the proposed new value).
64 1.3) Hook the control handler into the driver:
80   Finally, remove all control functions from your v4l2_ioctl_ops:
99   And set all core control ops in your struct v4l2_subdev_core_ops to these
111   on subdev drivers are converted to the control framework these helpers will
153 control, but if you do not need to access the pointer outside the control ops,
156 The v4l2_ctrl_new_std function will fill in most fields based on the control
158 last four arguments. These values are driver specific while control attributes
159 like type, name, flags are all global. The control's current value will be set
175 It is recommended to add controls in ascending control ID order: it will be
178 3) Optionally force initial control setup:
183 initializes the hardware to the default control values. It is recommended
210 The control ops are called with the v4l2_ctrl pointer as argument.
211 The new control value has already been validated, so all you need to do is
215 to do any validation of control values, or implement QUERYCTRL/QUERYMENU. And
235 skipped (so a V4L2 driver can always override a subdev control).
242 Accessing Control Values
247 	/* The current control value. */
254 	/* The new control value. */
261 Within the control ops you can freely use these. The val and val64 speak for
265 In most cases 'cur' contains the current cached control value. When you create
266 a new control this value is made identical to the default value. After calling
288 To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:
298 If s_ctrl returns 0 (OK), then the control framework will copy the new final
306 Outside of the control ops you have to go through to helper functions to get
307 or set a single control value safely in your driver:
312 These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls
313 do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that
340 A good example is the MPEG Audio Layer II Bitrate menu control where the
347 control, or by calling v4l2_ctrl_new_std_menu().
373 control and will fill in the name, type and flags fields accordingly.
380 activate and deactivate controls. For example, if the Chroma AGC control is
381 on, then the Chroma Gain control is inactive. That is, you may set it, but
383 control is on. Typically user interfaces can disable such input fields.
390 The other flag is the 'grabbed' flag. A grabbed control means that you cannot
394 If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework
395 will return -EBUSY if an attempt is made to set this control. The
400 Control Clusters
404 complex scenarios you can get dependencies from one control to another.
422 cluster is set (or 'gotten', or 'tried'), only the control ops of the first
423 control ('volume' in this example) is called. You effectively create a new
424 composite control. Similar to how a 'struct' works in C.
461 The anonymous struct is used to clearly 'cluster' these two control pointers,
463 array with two control pointers. So you can just do:
475 only restriction is that the first control of the cluster must always be
476 present, since that is the 'master' control of the cluster. The master
477 control is the one that identifies the cluster and that provides the
481 a valid control or to NULL.
485 each control. For example, in the case of a volume/mute cluster the 'is_new'
486 flag of the mute control would be set if the user called VIDIOC_S_CTRL for
496 A common type of control cluster is one that handles 'auto-foo/foo'-type
498 autowhitebalance/red balance/blue balance. In all cases you have one control
499 that determines whether another control is handled automatically by the hardware,
500 or whether it is under manual control from the user.
513 Finally the V4L2_CTRL_FLAG_UPDATE should be set for the auto control since
514 changing that control affects the control flags of the manual controls.
530 The first control of the cluster is assumed to be the 'auto' control.
549 Usually the V4L2 driver has just one control handler that is global for
550 all video nodes. But you can also specify different control handlers for
556 control handler. You do that by simply setting the ctrl_handler field in
561 manually to add the subdev's control handler (sd->ctrl_handler) to the desired
562 control handler. This control handler may be specific to the video_device or
564 audio controls, while the video and vbi device nodes share the same control
592 control. The rule is to have one control for each hardware 'knob' that you
602 But sometimes you need to find a control from another handler that you do
603 not own. For example, if you have to find a volume control from a subdev.
626 attempting to find another control from the same handler will deadlock.
628 It is recommended not to use this function from inside the control ops.
634 When one control handler is added to another using v4l2_ctrl_add_handler, then
639 setting the 'is_private' flag of the control to 1:
644 		.name = "Some Private Control",
659 Controls of this type can be used by GUIs to get the name of the control class.
661 containing the controls belonging to a particular control class. The name of
662 each tab can be found by querying a special control with ID <control class | 1>.
665 a control of this type whenever the first control belonging to a new control
679 control ID. Not sure if it is worth the effort, though.