€•¬+Œ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”ŒE/translations/zh_CN/userspace-api/media/v4l/selection-api-vs-crop-api”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”ŒE/translations/zh_TW/userspace-api/media/v4l/selection-api-vs-crop-api”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”ŒE/translations/it_IT/userspace-api/media/v4l/selection-api-vs-crop-api”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”ŒE/translations/ja_JP/userspace-api/media/v4l/selection-api-vs-crop-api”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”ŒE/translations/ko_KR/userspace-api/media/v4l/selection-api-vs-crop-api”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”ŒE/translations/sp_SP/userspace-api/media/v4l/selection-api-vs-crop-api”Œ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ŸŒ_/var/lib/git/docbuild/linux/Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst”h KubhŒtarget”“”)”}”(hŒ.. _selection-vs-crop:”h]”h}”(h]”h ]”h"]”h$]”h&]”Œrefid”Œselection-vs-crop”uh1h´h KhhhžhhŸh³ubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ Comparison with old cropping API”h]”hŒ Comparison with old cropping API”…””}”(hhÉhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÇhhÄhžhhŸh³h KubhŒ paragraph”“”)”}”(hXThe selection API was introduced to cope with deficiencies of the older :ref:`CROP API `, that was designed to control simple capture devices. Later the cropping API was adopted by video output drivers. The ioctls are used to select a part of the display were the video signal is inserted. It should be considered as an API abuse because the described operation is actually the composing. The selection API makes a clear distinction between composing and cropping operations by setting the appropriate targets.”h]”(hŒHThe selection API was introduced to cope with deficiencies of the older ”…””}”(hhÙhžhhŸNh Nubh)”}”(hŒ:ref:`CROP API `”h]”hŒinline”“”)”}”(hhãh]”hŒCROP API”…””}”(hhçhžhhŸNh Nubah}”(h]”h ]”(Œxref”Œstd”Œstd-ref”eh"]”h$]”h&]”uh1håhháubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”Œ1userspace-api/media/v4l/selection-api-vs-crop-api”Œ refdomain”hòŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆŒ reftarget”Œcrop”uh1hhŸh³h K hhÙubhX¦, that was designed to control simple capture devices. Later the cropping API was adopted by video output drivers. The ioctls are used to select a part of the display were the video signal is inserted. It should be considered as an API abuse because the described operation is actually the composing. The selection API makes a clear distinction between composing and cropping operations by setting the appropriate targets.”…””}”(hhÙhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K hhÄhžhubhØ)”}”(hXyThe CROP API lacks any support for composing to and cropping from an image inside a memory buffer. The application could configure a capture device to fill only a part of an image by abusing V4L2 API. Cropping a smaller image from a larger one is achieved by setting the field ``bytesperline`` at struct :c:type:`v4l2_pix_format`. Introducing an image offsets could be done by modifying field ``m_userptr`` at struct :c:type:`v4l2_buffer` before calling :ref:`VIDIOC_QBUF `. Those operations should be avoided because they are not portable (endianness), and do not work for macroblock and Bayer formats and mmap buffers.”h]”(hXThe CROP API lacks any support for composing to and cropping from an image inside a memory buffer. The application could configure a capture device to fill only a part of an image by abusing V4L2 API. Cropping a smaller image from a larger one is achieved by setting the field ”…””}”(hjhžhhŸNh NubhŒliteral”“”)”}”(hŒ``bytesperline``”h]”hŒ bytesperline”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubhŒ at struct ”…””}”(hjhžhhŸNh Nubh)”}”(hŒ:c:type:`v4l2_pix_format`”h]”j)”}”(hj.h]”hŒv4l2_pix_format”…””}”(hj0hžhhŸNh Nubah}”(h]”h ]”(hñŒc”Œc-type”eh"]”h$]”h&]”uh1jhj,ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hþŒ refdomain”j:Œreftype”Œtype”Œ refexplicit”‰Œrefwarn”‰jŒv4l2_pix_format”uh1hhŸh³h KhjubhŒ@. Introducing an image offsets could be done by modifying field ”…””}”(hjhžhhŸNh Nubj)”}”(hŒ ``m_userptr``”h]”hŒ m_userptr”…””}”(hjPhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubhŒ at struct ”…””}”hjsbh)”}”(hŒ:c:type:`v4l2_buffer`”h]”j)”}”(hjdh]”hŒ v4l2_buffer”…””}”(hjfhžhhŸNh Nubah}”(h]”h ]”(hñj:Œc-type”eh"]”h$]”h&]”uh1jhjbubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hþŒ refdomain”j:Œreftype”Œtype”Œ refexplicit”‰Œrefwarn”‰jŒ v4l2_buffer”uh1hhŸh³h KhjubhŒ before calling ”…””}”(hjhžhhŸNh Nubh)”}”(hŒ :ref:`VIDIOC_QBUF `”h]”hæ)”}”(hj‡h]”hŒ VIDIOC_QBUF”…””}”(hj‰hžhhŸNh Nubah}”(h]”h ]”(hñŒstd”Œstd-ref”eh"]”h$]”h&]”uh1håhj…ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hþŒ refdomain”j“Œreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjŒ vidioc_qbuf”uh1hhŸh³h KhjubhŒ“. Those operations should be avoided because they are not portable (endianness), and do not work for macroblock and Bayer formats and mmap buffers.”…””}”(hjhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KhhÄhžhubhØ)”}”(hXÃThe selection API deals with configuration of buffer cropping/composing in a clear, intuitive and portable way. Next, with the selection API the concepts of the padded target and constraints flags are introduced. Finally, struct :c:type:`v4l2_crop` and struct :c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no way to extend their functionality. The new struct :c:type:`v4l2_selection` provides a lot of place for future extensions.”h]”(hŒåThe selection API deals with configuration of buffer cropping/composing in a clear, intuitive and portable way. Next, with the selection API the concepts of the padded target and constraints flags are introduced. Finally, struct ”…””}”(hj¯hžhhŸNh Nubh)”}”(hŒ:c:type:`v4l2_crop`”h]”j)”}”(hj¹h]”hŒ v4l2_crop”…””}”(hj»hžhhŸNh Nubah}”(h]”h ]”(hñj:Œc-type”eh"]”h$]”h&]”uh1jhj·ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hþŒ refdomain”j:Œreftype”Œtype”Œ refexplicit”‰Œrefwarn”‰jŒ v4l2_crop”uh1hhŸh³h Khj¯ubhŒ and struct ”…””}”(hj¯hžhhŸNh Nubh)”}”(hŒ:c:type:`v4l2_cropcap`”h]”j)”}”(hjÜh]”hŒ v4l2_cropcap”…””}”(hjÞhžhhŸNh Nubah}”(h]”h ]”(hñj:Œc-type”eh"]”h$]”h&]”uh1jhjÚubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hþŒ refdomain”j:Œreftype”Œtype”Œ refexplicit”‰Œrefwarn”‰jŒ v4l2_cropcap”uh1hhŸh³h Khj¯ubhŒb have no reserved fields. Therefore there is no way to extend their functionality. The new struct ”…””}”(hj¯hžhhŸNh Nubh)”}”(hŒ:c:type:`v4l2_selection`”h]”j)”}”(hjÿh]”hŒv4l2_selection”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”(hñj:Œc-type”eh"]”h$]”h&]”uh1jhjýubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”hþŒ refdomain”j:Œreftype”Œtype”Œ refexplicit”‰Œrefwarn”‰jŒv4l2_selection”uh1hhŸh³h Khj¯ubhŒ/ provides a lot of place for future extensions.”…””}”(hj¯hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h KhhÄhžhubhØ)”}”(hŒDriver developers are encouraged to implement only selection API. The former cropping API would be simulated using the new one.”h]”hŒDriver developers are encouraged to implement only selection API. The former cropping API would be simulated using the new one.”…””}”(hj&hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh³h K&hhÄhžhubeh}”(h]”(Œ comparison-with-old-cropping-api”hÁeh ]”h"]”(Œ comparison with old cropping api”Œselection-vs-crop”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”jdŒ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Áj9j6uŒ nametypes”}”(j:ˆj9‰uh}”(hÁhÄj6hÄ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 "selection-vs-crop" is not referenced.”…””}”hjÎsbah}”(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.