v4l2_ctrl_auto_cluster(9)

💅 v4l2_ctrl_auto_cluster(9) — Kernel API Manual, bestie edition

okay so you found the v4l2_ctrl_auto_cluster(9) page in the Kernel API Manual and you're like "what does this even do" — don't worry, I got you, sit down, hydrate, and let's go 🫶

---

✨ NAME ✨

v4l2_ctrl_auto_cluster — marks every control in the cluster as belonging to that cluster, and sets the whole thing up for autofoo/foo-type handling. that's it, that's the vibe 🎀

---

🌸 SYNOPSIS 🌸

void v4l2_ctrl_auto_cluster(unsigned int ncontrols, struct v4l2_ctrl **controls,
                            u8 manual_val, bool set_volatile);

---

🦋 ARGUMENTS 🦋

• ncontrols — how many controls are in this cluster. the headcount, basically ✨
• controls — the cluster control array, size ncontrols. and listen 👏 the first control has to be the 'auto' control (like autogain, autoexposure, etc.) — no exceptions, first slot is auto's moment 👑
• manual_val — the value you give the first control in the cluster that equals the manual setting. like "this number = manual mode" 💅
• set_volatile — if true, then every control except the first auto control will be volatile. if false... they won't. iconic behavior honestly 🙈

---

🌈 DESCRIPTION 🌈

Use this for control groups where one control selects some automatic feature, and the rest of the controls are only active whenever that automatic thing is turned off (a.k.a. manual mode). classic examples, no cap: autogain vs gain, auto-whitebalance vs red and blue balance, etc. ✨

The behavior of such controls is literally this:

• When the autofoo control is set to automatic, then any manual controls are set to inactive, and any reads will call g_volatile_ctrl (if the control was marked volatile).
• When the autofoo control is set to manual, then any manual controls get marked active, and any reads will just return the current value without going through g_volatile_ctrl. simple as that 🍓

In addition — and this is the part ppl forget — this function will set the V4L2_CTRL_FLAG_UPDATE flag on the autofoo control, and V4L2_CTRL_FLAG_INACTIVE on the foo control(s), if autofoo is in auto mode. yes, it's doing all that. main character energy fr fr 🔥

---

🔥 SEE ALSO 🔥

Kernel file ./include/media/v4l2-ctrls.h, union v4l2_ctrl_ptr(9), v4l2_ctrl_ptr_create(9), struct v4l2_ctrl_ops(9), struct v4l2_ctrl_type_ops(9), v4l2_ctrl_notify_fnc(9), struct v4l2_ctrl(9), struct v4l2_ctrl_ref(9), struct v4l2_ctrl_handler(9), struct v4l2_ctrl_config(9), v4l2_ctrl_fill(9), v4l2_ctrl_handler_init_class(9), v4l2_ctrl_handler_init(9), v4l2_ctrl_handler_free(9), v4l2_ctrl_lock(9), v4l2_ctrl_unlock(9), __v4l2_ctrl_handler_setup(9), v4l2_ctrl_handler_setup(9), v4l2_ctrl_handler_log_status(9), v4l2_ctrl_new_custom(9), v4l2_ctrl_new_std(9), v4l2_ctrl_new_std_menu(9), v4l2_ctrl_new_std_menu_items(9), v4l2_ctrl_new_std_compound(9), v4l2_ctrl_new_int_menu(9), v4l2_ctrl_filter(9), v4l2_ctrl_add_handler(9), v4l2_ctrl_radio_filter(9), v4l2_ctrl_cluster(9), v4l2_ctrl_find(9), v4l2_ctrl_activate(9), __v4l2_ctrl_grab(9), v4l2_ctrl_grab(9), __v4l2_ctrl_modify_range(9), v4l2_ctrl_modify_range(9), __v4l2_ctrl_modify_dimensions(9), v4l2_ctrl_modify_dimensions(9), v4l2_ctrl_notify(9), v4l2_ctrl_get_name(9), v4l2_ctrl_get_menu(9), v4l2_ctrl_get_int_menu(9), v4l2_ctrl_g_ctrl(9), __v4l2_ctrl_s_ctrl(9), v4l2_ctrl_s_ctrl(9), v4l2_ctrl_g_ctrl_int64(9), __v4l2_ctrl_s_ctrl_int64(9), v4l2_ctrl_s_ctrl_int64(9), __v4l2_ctrl_s_ctrl_string(9), v4l2_ctrl_s_ctrl_string(9), __v4l2_ctrl_s_ctrl_compound(9), v4l2_ctrl_s_ctrl_compound(9), v4l2_ctrl_replace(9), v4l2_ctrl_merge(9), v4l2_ctrl_log_status(9), v4l2_ctrl_subscribe_event(9), v4l2_ctrl_poll(9), v4l2_ctrl_request_setup(9), v4l2_ctrl_request_complete(9), v4l2_ctrl_request_hdl_find(9), v4l2_ctrl_request_hdl_put(9), v4l2_ctrl_request_hdl_ctrl_find(9), v4l2_queryctrl(9), v4l2_query_ext_ctrl_to_v4l2_queryctrl(9), v4l2_query_ext_ctrl(9), v4l2_querymenu(9), v4l2_g_ctrl(9), v4l2_s_ctrl(9), v4l2_g_ext_ctrls(9), v4l2_try_ext_ctrls(9), v4l2_s_ext_ctrls(9), v4l2_ctrl_subdev_subscribe_event(9), v4l2_ctrl_subdev_log_status(9), v4l2_ctrl_new_fwnode_properties(9), v4l2_ctrl_type_op_equal(9), v4l2_ctrl_type_op_init(9), v4l2_ctrl_type_op_log(9), v4l2_ctrl_type_op_validate(9)

like yes, that's a lot of links. read them. or don't. but they're there 💜

---

and that's the whole page bestie, you ate that 💅✨

cute lil sign-off: this came out of the ./include/media source, dated October 2026, for the Kernel API Manual entry v4l2_ctrl_auto_cluster(9) — go forth and cluster responsibly 🧚‍♀️💖