€•€zŒsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œ translations”Œ LanguagesNode”“”)”}”(hhh]”(hŒ pending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ=/translations/zh_CN/userspace-api/media/v4l/extended-controls”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ=/translations/zh_TW/userspace-api/media/v4l/extended-controls”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ=/translations/it_IT/userspace-api/media/v4l/extended-controls”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ=/translations/ja_JP/userspace-api/media/v4l/extended-controls”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ=/translations/ko_KR/userspace-api/media/v4l/extended-controls”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ=/translations/sp_SP/userspace-api/media/v4l/extended-controls”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ8SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later”h]”hŒ8SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1h¡hhhžhhŸŒW/var/lib/git/docbuild/linux/Documentation/userspace-api/media/v4l/extended-controls.rst”h KubhŒtarget”“”)”}”(hŒ.. _extended-controls:”h]”h}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œextended-controls”uh1h´h KhhhžhhŸh³ubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒExtended Controls API”h]”hŒExtended Controls API”…””}”(hhÉhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhhÄhžhhŸh³h KubhÃ)”}”(hhh]”(hÈ)”}”(hŒ Introduction”h]”hŒ Introduction”…””}”(hhÚhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhh×hžhhŸh³h K ubhŒ paragraph”“”)”}”(hX The control mechanism as originally designed was meant to be used for user settings (brightness, saturation, etc). However, it turned out to be a very useful model for implementing more complicated driver APIs where each driver implements only a subset of a larger API.”h]”hX The control mechanism as originally designed was meant to be used for user settings (brightness, saturation, etc). However, it turned out to be a very useful model for implementing more complicated driver APIs where each driver implements only a subset of a larger API.”…””}”(hhêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K hh×hžhubhé)”}”(hXõThe MPEG encoding API was the driving force behind designing and implementing this extended control mechanism: the MPEG standard is quite large and the currently supported hardware MPEG encoders each only implement a subset of this standard. Further more, many parameters relating to how the video is encoded into an MPEG stream are specific to the MPEG encoding chip since the MPEG standard only defines the format of the resulting MPEG stream, not how the video is actually encoded into that format.”h]”hXõThe MPEG encoding API was the driving force behind designing and implementing this extended control mechanism: the MPEG standard is quite large and the currently supported hardware MPEG encoders each only implement a subset of this standard. Further more, many parameters relating to how the video is encoded into an MPEG stream are specific to the MPEG encoding chip since the MPEG standard only defines the format of the resulting MPEG stream, not how the video is actually encoded into that format.”…””}”(hhøhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubhé)”}”(hŒ¬Unfortunately, the original control API lacked some features needed for these new uses and so it was extended into the (not terribly originally named) extended control API.”h]”hŒ¬Unfortunately, the original control API lacked some features needed for these new uses and so it was extended into the (not terribly originally named) extended control API.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubhé)”}”(hX0Even though the MPEG encoding API was the first effort to use the Extended Control API, nowadays there are also other classes of Extended Controls, such as Camera Controls and FM Transmitter Controls. The Extended Controls API as well as all Extended Controls classes are described in the following text.”h]”hX0Even though the MPEG encoding API was the first effort to use the Extended Control API, nowadays there are also other classes of Extended Controls, such as Camera Controls and FM Transmitter Controls. The Extended Controls API as well as all Extended Controls classes are described in the following text.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubeh}”(h]”Œ introduction”ah ]”h"]”Œ introduction”ah$]”h&]”uh1hÂhhÄhžhhŸh³h K ubhÃ)”}”(hhh]”(hÈ)”}”(hŒThe Extended Control API”h]”hŒThe Extended Control API”…””}”(hj-hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhj*hžhhŸh³h K'ubhé)”}”(hX»Three new ioctls are available: :ref:`VIDIOC_G_EXT_CTRLS `, :ref:`VIDIOC_S_EXT_CTRLS ` and :ref:`VIDIOC_TRY_EXT_CTRLS `. These ioctls act on arrays of controls (as opposed to the :ref:`VIDIOC_G_CTRL ` and :ref:`VIDIOC_S_CTRL ` ioctls that act on a single control). This is needed since it is often required to atomically change several controls at once.”h]”(hŒ Three new ioctls are available: ”…””}”(hj;hžhhŸNh Nubh)”}”(hŒ.:ref:`VIDIOC_G_EXT_CTRLS `”h]”hŒinline”“”)”}”(hjEh]”hŒVIDIOC_G_EXT_CTRLS”…””}”(hjIhžhhŸNh Nubah}”(h]”h ]”(Œxref”Œstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjCubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”Œ)userspace-api/media/v4l/extended-controls”Œ refdomain”jTŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆŒ reftarget”Œvidioc_g_ext_ctrls”uh1hhŸh³h K)hj;ubhŒ, ”…””}”(hj;hžhhŸNh Nubh)”}”(hŒ.:ref:`VIDIOC_S_EXT_CTRLS `”h]”jH)”}”(hjnh]”hŒVIDIOC_S_EXT_CTRLS”…””}”(hjphžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjlubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jzŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjfŒvidioc_g_ext_ctrls”uh1hhŸh³h K)hj;ubhŒ and ”…””}”(hj;hžhhŸNh Nubh)”}”(hŒ0:ref:`VIDIOC_TRY_EXT_CTRLS `”h]”jH)”}”(hj’h]”hŒVIDIOC_TRY_EXT_CTRLS”…””}”(hj”hžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jžŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjfŒvidioc_g_ext_ctrls”uh1hhŸh³h K)hj;ubhŒ<. These ioctls act on arrays of controls (as opposed to the ”…””}”(hj;hžhhŸNh Nubh)”}”(hŒ$:ref:`VIDIOC_G_CTRL `”h]”jH)”}”(hj¶h]”hŒ VIDIOC_G_CTRL”…””}”(hj¸hžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhj´ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jÂŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjfŒ vidioc_g_ctrl”uh1hhŸh³h K)hj;ubhŒ and ”…””}”hj;sbh)”}”(hŒ$:ref:`VIDIOC_S_CTRL `”h]”jH)”}”(hjÚh]”hŒ VIDIOC_S_CTRL”…””}”(hjÜhžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjØubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jæŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjfŒ vidioc_g_ctrl”uh1hhŸh³h K)hj;ubhŒ ioctls that act on a single control). This is needed since it is often required to atomically change several controls at once.”…””}”(hj;hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K)hj*hžhubhé)”}”(hXEach of the new ioctls expects a pointer to a struct :c:type:`v4l2_ext_controls`. This structure contains a pointer to the control array, a count of the number of controls in that array and a control class. Control classes are used to group similar controls into a single class. For example, control class ``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls that can also be set using the old :ref:`VIDIOC_S_CTRL ` ioctl). Control class ``V4L2_CTRL_CLASS_CODEC`` contains controls relating to codecs.”h]”(hŒ5Each of the new ioctls expects a pointer to a struct ”…””}”(hjhžhhŸNh Nubh)”}”(hŒ:c:type:`v4l2_ext_controls`”h]”hŒliteral”“”)”}”(hj h]”hŒv4l2_ext_controls”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”(jSŒc”Œc-type”eh"]”h$]”h&]”uh1jhj ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jŒreftype”Œtype”Œ refexplicit”‰Œrefwarn”‰jfŒv4l2_ext_controls”uh1hhŸh³h K3hjubhŒâ. This structure contains a pointer to the control array, a count of the number of controls in that array and a control class. Control classes are used to group similar controls into a single class. For example, control class ”…””}”(hjhžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_CLASS_USER``”h]”hŒV4L2_CTRL_CLASS_USER”…””}”(hj0hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubhŒS contains all user controls (i. e. all controls that can also be set using the old ”…””}”(hjhžhhŸNh Nubh)”}”(hŒ$:ref:`VIDIOC_S_CTRL `”h]”jH)”}”(hjDh]”hŒ VIDIOC_S_CTRL”…””}”(hjFhžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjBubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jPŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjfŒ vidioc_g_ctrl”uh1hhŸh³h K3hjubhŒ ioctl). Control class ”…””}”(hjhžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_CLASS_CODEC``”h]”hŒV4L2_CTRL_CLASS_CODEC”…””}”(hjfhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubhŒ& contains controls relating to codecs.”…””}”(hjhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K3hj*hžhubhé)”}”(hŒ{All controls in the control array must belong to the specified control class. An error is returned if this is not the case.”h]”hŒ{All controls in the control array must belong to the specified control class. An error is returned if this is not the case.”…””}”(hj~hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K=hj*hžhubhé)”}”(hŒ}It is also possible to use an empty control array (``count`` == 0) to check whether the specified control class is supported.”h]”(hŒ3It is also possible to use an empty control array (”…””}”(hjŒhžhhŸNh Nubj)”}”(hŒ ``count``”h]”hŒcount”…””}”(hj”hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjŒubhŒA == 0) to check whether the specified control class is supported.”…””}”(hjŒhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K@hj*hžhubhé)”}”(hŒìThe control array is a struct :c:type:`v4l2_ext_control` array. The struct :c:type:`v4l2_ext_control` is very similar to struct :c:type:`v4l2_control`, except for the fact that it also allows for 64-bit values and pointers to be passed.”h]”(hŒThe control array is a struct ”…””}”(hj¬hžhhŸNh Nubh)”}”(hŒ:c:type:`v4l2_ext_control`”h]”j)”}”(hj¶h]”hŒv4l2_ext_control”…””}”(hj¸hžhhŸNh Nubah}”(h]”h ]”(jSjŒc-type”eh"]”h$]”h&]”uh1jhj´ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jŒreftype”Œtype”Œ refexplicit”‰Œrefwarn”‰jfŒv4l2_ext_control”uh1hhŸh³h KChj¬ubhŒ array. The struct ”…””}”(hj¬hžhhŸNh Nubh)”}”(hŒ:c:type:`v4l2_ext_control`”h]”j)”}”(hjÙh]”hŒv4l2_ext_control”…””}”(hjÛhžhhŸNh Nubah}”(h]”h ]”(jSjŒc-type”eh"]”h$]”h&]”uh1jhj×ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jŒreftype”Œtype”Œ refexplicit”‰Œrefwarn”‰jfŒv4l2_ext_control”uh1hhŸh³h KChj¬ubhŒ is very similar to struct ”…””}”(hj¬hžhhŸNh Nubh)”}”(hŒ:c:type:`v4l2_control`”h]”j)”}”(hjüh]”hŒ v4l2_control”…””}”(hjþhžhhŸNh Nubah}”(h]”h ]”(jSjŒc-type”eh"]”h$]”h&]”uh1jhjúubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jŒreftype”Œtype”Œ refexplicit”‰Œrefwarn”‰jfŒ v4l2_control”uh1hhŸh³h KChj¬ubhŒV, except for the fact that it also allows for 64-bit values and pointers to be passed.”…””}”(hj¬hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KChj*hžhubhé)”}”(hX‰Since the struct :c:type:`v4l2_ext_control` supports pointers it is now also possible to have controls with compound types such as N-dimensional arrays and/or structures. You need to specify the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually be able to see such compound controls. In other words, these controls with compound types should only be used programmatically.”h]”(hŒSince the struct ”…””}”(hj#hžhhŸNh Nubh)”}”(hŒ:c:type:`v4l2_ext_control`”h]”j)”}”(hj-h]”hŒv4l2_ext_control”…””}”(hj/hžhhŸNh Nubah}”(h]”h ]”(jSjŒc-type”eh"]”h$]”h&]”uh1jhj+ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jŒreftype”Œtype”Œ refexplicit”‰Œrefwarn”‰jfŒv4l2_ext_control”uh1hhŸh³h KIhj#ubhŒ˜ supports pointers it is now also possible to have controls with compound types such as N-dimensional arrays and/or structures. You need to specify the ”…””}”(hj#hžhhŸNh Nubj)”}”(hŒ ``V4L2_CTRL_FLAG_NEXT_COMPOUND``”h]”hŒV4L2_CTRL_FLAG_NEXT_COMPOUND”…””}”(hjNhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj#ubhŒ¦ when enumerating controls to actually be able to see such compound controls. In other words, these controls with compound types should only be used programmatically.”…””}”(hj#hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KIhj*hžhubhé)”}”(hXPSince such compound controls need to expose more information about themselves than is possible with :ref:`VIDIOC_QUERYCTRL ` the :ref:`VIDIOC_QUERY_EXT_CTRL ` ioctl was added. In particular, this ioctl gives the dimensions of the N-dimensional array if this control consists of more than one element.”h]”(hŒdSince such compound controls need to expose more information about themselves than is possible with ”…””}”(hjfhžhhŸNh Nubh)”}”(hŒ*:ref:`VIDIOC_QUERYCTRL `”h]”jH)”}”(hjph]”hŒVIDIOC_QUERYCTRL”…””}”(hjrhžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjnubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”j|Œreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjfŒvidioc_queryctrl”uh1hhŸh³h KPhjfubhŒ the ”…””}”(hjfhžhhŸNh Nubh)”}”(hŒ/:ref:`VIDIOC_QUERY_EXT_CTRL `”h]”jH)”}”(hj”h]”hŒVIDIOC_QUERY_EXT_CTRL”…””}”(hj–hžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhj’ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”j Œreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjfŒvidioc_queryctrl”uh1hhŸh³h KPhjfubhŒŽ ioctl was added. In particular, this ioctl gives the dimensions of the N-dimensional array if this control consists of more than one element.”…””}”(hjfhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KPhj*hžhubhŒnote”“”)”}”(hX:#. It is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set actually is supported in the driver and what the valid range of values is. So use :ref:`VIDIOC_QUERYCTRL` to check this. #. It is possible that some of the menu indices in a control of type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU`` will return an error). A good example is the list of supported MPEG audio bitrates. Some drivers only support one or two bitrates, others support a wider range.”h]”hŒenumerated_list”“”)”}”(hhh]”(hŒ list_item”“”)”}”(hŒùIt is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set actually is supported in the driver and what the valid range of values is. So use :ref:`VIDIOC_QUERYCTRL` to check this. ”h]”hé)”}”(hŒøIt is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set actually is supported in the driver and what the valid range of values is. So use :ref:`VIDIOC_QUERYCTRL` to check this.”h]”(hŒÒIt is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set actually is supported in the driver and what the valid range of values is. So use ”…””}”(hjÍhžhhŸNh Nubh)”}”(hŒ:ref:`VIDIOC_QUERYCTRL`”h]”jH)”}”(hj×h]”hŒVIDIOC_QUERYCTRL”…””}”(hjÙhžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjÕubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jãŒreftype”Œref”Œ refexplicit”‰Œrefwarn”ˆjfŒvidioc_queryctrl”uh1hhŸh³h KXhjÍubhŒ to check this.”…””}”(hjÍhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KXhjÉubah}”(h]”h ]”h"]”h$]”h&]”uh1jÇhjÄubjÈ)”}”(hX%It is possible that some of the menu indices in a control of type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU`` will return an error). A good example is the list of supported MPEG audio bitrates. Some drivers only support one or two bitrates, others support a wider range.”h]”hé)”}”(hX%It is possible that some of the menu indices in a control of type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU`` will return an error). A good example is the list of supported MPEG audio bitrates. Some drivers only support one or two bitrates, others support a wider range.”h]”(hŒBIt is possible that some of the menu indices in a control of type ”…””}”(hj hžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_TYPE_MENU``”h]”hŒV4L2_CTRL_TYPE_MENU”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj ubhŒ may not be supported (”…””}”(hj hžhhŸNh Nubj)”}”(hŒ``VIDIOC_QUERYMENU``”h]”hŒVIDIOC_QUERYMENU”…””}”(hj#hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj ubhŒ¡ will return an error). A good example is the list of supported MPEG audio bitrates. Some drivers only support one or two bitrates, others support a wider range.”…””}”(hj hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K]hjubah}”(h]”h ]”h"]”h$]”h&]”uh1jÇhjÄubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ.”uh1jÂhj¾ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¼hj*hžhhŸNh Nubhé)”}”(hŒ$All controls use machine endianness.”h]”hŒ$All controls use machine endianness.”…””}”(hjRhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kchj*hžhubeh}”(h]”Œthe-extended-control-api”ah ]”h"]”Œthe extended control api”ah$]”h&]”uh1hÂhhÄhžhhŸh³h K'ubhÃ)”}”(hhh]”(hÈ)”}”(hŒEnumerating Extended Controls”h]”hŒEnumerating Extended Controls”…””}”(hjkhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjhhžhhŸh³h Kgubhé)”}”(hŒšThe recommended way to enumerate over the extended controls is by using :ref:`VIDIOC_QUERYCTRL` in combination with the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag:”h]”(hŒHThe recommended way to enumerate over the extended controls is by using ”…””}”(hjyhžhhŸNh Nubh)”}”(hŒ:ref:`VIDIOC_QUERYCTRL`”h]”jH)”}”(hjƒh]”hŒVIDIOC_QUERYCTRL”…””}”(hj…hžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jŒreftype”Œref”Œ refexplicit”‰Œrefwarn”ˆjfŒvidioc_queryctrl”uh1hhŸh³h KihjyubhŒ in combination with the ”…””}”(hjyhžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_FLAG_NEXT_CTRL``”h]”hŒV4L2_CTRL_FLAG_NEXT_CTRL”…””}”(hj¥hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjyubhŒ flag:”…””}”(hjyhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KihjhhžhubhŒ literal_block”“”)”}”(hŒ°struct v4l2_queryctrl qctrl; qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) { /* ... */ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; }”h]”hŒ°struct v4l2_queryctrl qctrl; qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) { /* ... */ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; }”…””}”hj¿sbah}”(h]”h ]”h"]”h$]”h&]”h±h²Œforce”‰Œlanguage”jŒhighlight_args”}”uh1j½hŸh³h Knhjhhžhubhé)”}”(hŒïThe initial control ID is set to 0 ORed with the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will return the first control with a higher ID than the specified one. When no such controls are found an error is returned.”h]”(hŒ1The initial control ID is set to 0 ORed with the ”…””}”(hjÑhžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_FLAG_NEXT_CTRL``”h]”hŒV4L2_CTRL_FLAG_NEXT_CTRL”…””}”(hjÙhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjÑubhŒ flag. The ”…””}”(hjÑhžhhŸNh Nubj)”}”(hŒ``VIDIOC_QUERYCTRL``”h]”hŒVIDIOC_QUERYCTRL”…””}”(hjëhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjÑubhŒƒ ioctl will return the first control with a higher ID than the specified one. When no such controls are found an error is returned.”…””}”(hjÑhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kxhjhhžhubhé)”}”(hŒçIf you want to get all controls within a specific control class, then you can set the initial ``qctrl.id`` value to the control class and add an extra check to break out of the loop when a control of another control class is found:”h]”(hŒ^If you want to get all controls within a specific control class, then you can set the initial ”…””}”(hjhžhhŸNh Nubj)”}”(hŒ ``qctrl.id``”h]”hŒqctrl.id”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubhŒ} value to the control class and add an extra check to break out of the loop when a control of another control class is found:”…””}”(hjhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K}hjhhžhubj¾)”}”(hŒ÷qctrl.id = V4L2_CTRL_CLASS_CODEC | V4L2_CTRL_FLAG_NEXT_CTRL; while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) { if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_CODEC) break; /* ... */ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; }”h]”hŒ÷qctrl.id = V4L2_CTRL_CLASS_CODEC | V4L2_CTRL_FLAG_NEXT_CTRL; while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) { if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_CODEC) break; /* ... */ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; }”…””}”hj#sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j͉jÎjjÏ}”uh1j½hŸh³h Kƒhjhhžhubhé)”}”(hXWThe 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the top 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``) and are not actually part of the ID. The remaining 28 bits form the control ID, of which the most significant 12 bits define the control class and the least significant 16 bits identify the control within the control class. It is guaranteed that these last 16 bits are always non-zero for controls. The range of 0x1000 and up are reserved for driver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns the control class ID based on a control ID.”h]”(hŒ The 32-bit ”…””}”(hj2hžhhŸNh Nubj)”}”(hŒ ``qctrl.id``”h]”hŒqctrl.id”…””}”(hj:hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj2ubhŒY value is subdivided into three bit ranges: the top 4 bits are reserved for flags (e. g. ”…””}”(hj2hžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_FLAG_NEXT_CTRL``”h]”hŒV4L2_CTRL_FLAG_NEXT_CTRL”…””}”(hjLhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj2ubhX}) and are not actually part of the ID. The remaining 28 bits form the control ID, of which the most significant 12 bits define the control class and the least significant 16 bits identify the control within the control class. It is guaranteed that these last 16 bits are always non-zero for controls. The range of 0x1000 and up are reserved for driver-specific controls. The macro ”…””}”(hj2hžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_ID2CLASS(id)``”h]”hŒV4L2_CTRL_ID2CLASS(id)”…””}”(hj^hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj2ubhŒ4 returns the control class ID based on a control ID.”…””}”(hj2hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khjhhžhubhé)”}”(hXdIf the driver does not support extended controls, then ``VIDIOC_QUERYCTRL`` will fail when used in combination with ``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating control should be used (see :ref:`enum_all_controls`). But if it is supported, then it is guaranteed to enumerate over all controls, including driver-private controls.”h]”(hŒ7If the driver does not support extended controls, then ”…””}”(hjvhžhhŸNh Nubj)”}”(hŒ``VIDIOC_QUERYCTRL``”h]”hŒVIDIOC_QUERYCTRL”…””}”(hj~hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjvubhŒ) will fail when used in combination with ”…””}”(hjvhžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_FLAG_NEXT_CTRL``”h]”hŒV4L2_CTRL_FLAG_NEXT_CTRL”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjvubhŒI. In that case the old method of enumerating control should be used (see ”…””}”(hjvhžhhŸNh Nubh)”}”(hŒ:ref:`enum_all_controls`”h]”jH)”}”(hj¤h]”hŒenum_all_controls”…””}”(hj¦hžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhj¢ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”j°Œreftype”Œref”Œ refexplicit”‰Œrefwarn”ˆjfŒenum_all_controls”uh1hhŸh³h K—hjvubhŒs). But if it is supported, then it is guaranteed to enumerate over all controls, including driver-private controls.”…””}”(hjvhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K—hjhhžhubeh}”(h]”Œenumerating-extended-controls”ah ]”h"]”Œenumerating extended controls”ah$]”h&]”uh1hÂhhÄhžhhŸh³h KgubhÃ)”}”(hhh]”(hÈ)”}”(hŒCreating Control Panels”h]”hŒCreating Control Panels”…””}”(hj×hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjÔhžhhŸh³h K ubhé)”}”(hX¢It is possible to create control panels for a graphical user interface where the user can select the various controls. Basically you will have to iterate over all controls using the method described above. Each control class starts with a control of type ``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name of this control class which can be used as the title of a tab page within a control panel.”h]”(hŒÿIt is possible to create control panels for a graphical user interface where the user can select the various controls. Basically you will have to iterate over all controls using the method described above. Each control class starts with a control of type ”…””}”(hjåhžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_TYPE_CTRL_CLASS``”h]”hŒV4L2_CTRL_TYPE_CTRL_CLASS”…””}”(hjíhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjåubhŒ. ”…””}”(hjåhžhhŸNh Nubj)”}”(hŒ``VIDIOC_QUERYCTRL``”h]”hŒVIDIOC_QUERYCTRL”…””}”(hjÿhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjåubhŒp will return the name of this control class which can be used as the title of a tab page within a control panel.”…””}”(hjåhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K¢hjÔhžhubhé)”}”(hŒ´The flags field of struct :ref:`v4l2_queryctrl ` also contains hints on the behavior of the control. See the :ref:`VIDIOC_QUERYCTRL` documentation for more details.”h]”(hŒThe flags field of struct ”…””}”(hjhžhhŸNh Nubh)”}”(hŒ&:ref:`v4l2_queryctrl `”h]”jH)”}”(hj!h]”hŒv4l2_queryctrl”…””}”(hj#hžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”j-Œreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjfŒv4l2-queryctrl”uh1hhŸh³h KªhjubhŒ= also contains hints on the behavior of the control. See the ”…””}”(hjhžhhŸNh Nubh)”}”(hŒ:ref:`VIDIOC_QUERYCTRL`”h]”jH)”}”(hjEh]”hŒVIDIOC_QUERYCTRL”…””}”(hjGhžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjCubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jQŒreftype”Œref”Œ refexplicit”‰Œrefwarn”ˆjfŒvidioc_queryctrl”uh1hhŸh³h KªhjubhŒ documentation for more details.”…””}”(hjhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KªhjÔhžhubeh}”(h]”Œcreating-control-panels”ah ]”h"]”Œcreating control panels”ah$]”h&]”uh1hÂhhÄhžhhŸh³h K ubeh}”(h]”(Œextended-controls-api”hÁeh ]”h"]”(Œextended controls api”Œextended-controls”eh$]”h&]”uh1hÂhhhžhhŸh³h KŒexpect_referenced_by_name”}”j{h¶sŒexpect_referenced_by_id”}”hÁh¶subeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒ current_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hÇNŒ generator”NŒ datestamp”NŒ source_link”NŒ source_url”NŒ toc_backlinks”Œentry”Œfootnote_backlinks”KŒ sectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒ strip_classes”NŒ report_level”KŒ halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ traceback”ˆŒinput_encoding”Œ utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j¥Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œ language_code”Œen”Œrecord_dependencies”NŒconfig”NŒ id_prefix”hŒauto_id_prefix”Œid”Œ dump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ _destination”NŒ _config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒ raw_enabled”KŒline_length_limit”M'Œpep_references”NŒ pep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒ rfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œ smart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œ docinfo_xform”KŒsectsubtitle_xform”‰Œ image_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”hÁ]”h¶asŒnameids”}”(j{hÁjzjwj'j$jejbjÑjÎjrjouŒ nametypes”}”(j{ˆjz‰j'‰je‰jщjr‰uh}”(hÁhÄjwhÄj$h×jbj*jÎjhjojÔuŒ footnote_refs”}”Œ citation_refs”}”Œ autofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ footnotes”]”Œ citations”]”Œautofootnote_start”KŒsymbol_footnote_start”KŒ id_counter”Œ collections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”hŒsystem_message”“”)”}”(hhh]”hé)”}”(hhh]”hŒ7Hyperlink target "extended-controls" is not referenced.”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”uh1hèhj ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h³Œline”Kuh1j ubaŒ transformer”NŒ include_log”]”Œ decoration”Nhžhub.