€•{Œ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 Khh×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 K hh×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”‰Œ c:parent_key”Œsphinx.domains.c”Œ LookupKey”“”)”}”Œdata”]”j,Œ ASTIdentifier”“”)”}”Œ identifier”ŒV4L”sbN†”asbjfŒv4l2_ext_controls”uh1hhŸh³h K4hjubhŒâ. 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”…””}”(hj?hž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)”}”(hjSh]”hŒ VIDIOC_S_CTRL”…””}”(hjUhžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjQubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”j_Œreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjfŒ vidioc_g_ctrl”uh1hhŸh³h K4hjubhŒ ioctl). Control class ”…””}”(hjhžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_CLASS_CODEC``”h]”hŒV4L2_CTRL_CLASS_CODEC”…””}”(hjuhž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 K4hj*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.”…””}”(hjhž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 KAhj*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”‰j+j/jfŒv4l2_ext_control”uh1hhŸh³h KDhj»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”‰j+j/jfŒv4l2_ext_control”uh1hhŸh³h KDhj»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”‰j+j/jfŒ v4l2_control”uh1hhŸh³h KDhj»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 KDhj*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 ”…””}”(hj2hž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”‰j+j/jfŒv4l2_ext_control”uh1hhŸh³h KJhj2ubhŒ˜ 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 ”…””}”(hj2hžhhŸNh Nubj)”}”(hŒ ``V4L2_CTRL_FLAG_NEXT_COMPOUND``”h]”hŒV4L2_CTRL_FLAG_NEXT_COMPOUND”…””}”(hj]hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj2ubhŒ¦ 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.”…””}”(hj2hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KJhj*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 ”…””}”(hjuhžhhŸNh Nubh)”}”(hŒ*:ref:`VIDIOC_QUERYCTRL `”h]”jH)”}”(hjh]”hŒVIDIOC_QUERYCTRL”…””}”(hjhž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 KQhjuubhŒ the ”…””}”(hjuhž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 KQhjuubhŒŽ ioctl was added. In particular, this ioctl gives the dimensions of the N-dimensional array if this control consists of more than one element.”…””}”(hjuhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KQhj*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 KYhjÜubhŒ to check this.”…””}”(hjÜhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KYhjØ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 ”…””}”(hjhžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_TYPE_MENU``”h]”hŒV4L2_CTRL_TYPE_MENU”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubhŒ may not be supported (”…””}”(hjhžhhŸNh Nubj)”}”(hŒ``VIDIOC_QUERYMENU``”h]”hŒVIDIOC_QUERYMENU”…””}”(hj2hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubhŒ¡ 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.”…””}”(hjhž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.”…””}”(hjahžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kdhj*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”…””}”(hjzhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhjwhžhhŸh³h Khubhé)”}”(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 ”…””}”(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&]”uh1jGhjubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”jžŒreftype”Œref”Œ refexplicit”‰Œrefwarn”ˆjfŒvidioc_queryctrl”uh1hhŸh³h KjhjˆubhŒ in combination 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:”…””}”(hjˆhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kjhjwhž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 Kohjwhž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 Kyhjwhž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”…””}”(hjhž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~hjwhž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; }”…””}”hj2sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j܉jÝjjÞ}”uh1jÌhŸh³h K„hjwhž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 ”…””}”(hjAhžhhŸNh Nubj)”}”(hŒ ``qctrl.id``”h]”hŒqctrl.id”…””}”(hjIhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjAubhŒY value is subdivided into three bit ranges: the top 4 bits are reserved for flags (e. g. ”…””}”(hjAhž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&]”uh1jhjAubhX}) 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 ”…””}”(hjAhžhhŸNh Nubj)”}”(hŒ``V4L2_CTRL_ID2CLASS(id)``”h]”hŒV4L2_CTRL_ID2CLASS(id)”…””}”(hjmhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjAubhŒ4 returns the control class ID based on a control ID.”…””}”(hjAhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KŽhjwhž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 ”…””}”(hj…hžhhŸNh Nubj)”}”(hŒ``VIDIOC_QUERYCTRL``”h]”hŒVIDIOC_QUERYCTRL”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj…ubhŒ) will fail when used in combination with ”…””}”(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ŒI. In that case the old method of enumerating control should be used (see ”…””}”(hj…hž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˜hj…ubhŒs). But if it is supported, then it is guaranteed to enumerate over all controls, including driver-private controls.”…””}”(hj…hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K˜hjwhžhubeh}”(h]”Œenumerating-extended-controls”ah ]”h"]”Œenumerating extended controls”ah$]”h&]”uh1hÂhhÄhžhhŸh³h KhubhÃ)”}”(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”…””}”(hjhž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 ”…””}”(hj&hžhhŸNh Nubh)”}”(hŒ&:ref:`v4l2_queryctrl `”h]”jH)”}”(hj0h]”hŒv4l2_queryctrl”…””}”(hj2hž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Œv4l2-queryctrl”uh1hhŸh³h K«hj&ubhŒ= also contains hints on the behavior of the control. See the ”…””}”(hj&hžhhŸNh Nubh)”}”(hŒ:ref:`VIDIOC_QUERYCTRL`”h]”jH)”}”(hjTh]”hŒVIDIOC_QUERYCTRL”…””}”(hjVhžhhŸNh Nubah}”(h]”h ]”(jSŒstd”Œstd-ref”eh"]”h$]”h&]”uh1jGhjRubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j`Œ refdomain”j`Œreftype”Œref”Œ refexplicit”‰Œrefwarn”ˆjfŒvidioc_queryctrl”uh1hhŸh³h K«hj&ubhŒ documentation for more details.”…””}”(hj&hž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Áj‰j†j'j$jtjqjàjÝjj~uŒ nametypes”}”(jŠˆj‰‰j'‰jt‰jà‰j‰uh}”(hÁhÄj†hÄj$h×jqj*jÝjwj~jã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èhjubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”h³Œline”Kuh1jubaŒ transformer”NŒ include_log”]”Œ decoration”Nhžhub.