پیش‌نمایش دوربین

توجه: این صفحه به بسته Camera2 اشاره دارد. توصیه می‌کنیم از CameraX استفاده کنید، مگراینکه برنامه‌تان به ویژگی‌های خاص و سطح پایین Camera2 نیاز داشته باشد. ‫CameraX و Camera2 هر دو از Android 5.0 (سطح میانای برنامه‌سازی کاربردی ۲۱) و بالاتر پشتیبانی می‌کنند.

دوربین‌ها و پیش‌نمایش‌های دوربین همیشه در دستگاه‌های Android جهت یکسانی ندارند.

دوربین در موقعیت ثابتی روی دستگاه قرار دارد، صرف‌نظر از اینکه دستگاه تلفن، رایانه لوحی، یا رایانه باشد. وقتی جهت دستگاه تغییر می‌کند، جهت دوربین هم تغییر می‌کند.

درنتیجه، برنامه‌های دوربین معمولاً رابطه ثابتی بین جهت دستگاه و نسبت ابعادی پیش‌نمای دوربین فرض می‌کنند. وقتی تلفن در جهت عمودی باشد، پیش‌نمای دوربین بلندتر از عرض آن فرض می‌شود. وقتی تلفن (و دوربین) به حالت افقی چرخانده می‌شود، انتظار می‌رود پیش‌نمایش دوربین عریض‌تر از ارتفاع آن باشد.

اما این فرض‌ها با فاکتورهای شکل جدید، مانند دستگاه‌های تاشو، و حالت‌های نمایش مانند چندپنجره‌ای و چندنمایشگری به‌چالش کشیده می‌شوند. دستگاه‌های تاشو اندازه نمایشگر و نسبت ابعادی را بدون تغییر جهت تغییر می‌دهند. حالت چندپنجره‌ای برنامه‌های دوربین را به بخشی از صفحه‌نمایش محدود می‌کند و پیش‌نمایش دوربین را صرف‌نظر از جهت دستگاه مقیاس‌بندی می‌کند. حالت چندنمایشگری امکان استفاده از نمایشگرهای ثانویه را فراهم می‌کند که ممکن است جهتشان با نمایشگر اصلی یکسان نباشد.

جهت دوربین

تعریف سازگاری Android مشخص می‌کند که حسگر تصویر دوربین «باید به‌گونه‌ای جهت‌دهی شود که بُعد بلند دوربین با بُعد بلند صفحه‌نمایش هم‌راستا باشد. یعنی وقتی دستگاه در جهت افقی نگه داشته می‌شود، دوربین‌ها باید تصاویر را در جهت افقی ضبط کنند. این موضوع صرف‌نظر از جهت طبیعی دستگاه اعمال می‌شود؛ یعنی هم برای دستگاه‌های با جهت اصلی افقی و هم برای دستگاه‌های با جهت اصلی عمودی اعمال می‌شود.»

چیدمان دوربین به صفحه، ناحیه نمایش نمایاب دوربین را در برنامه دوربین به حداکثر می‌رساند. همچنین، حسگرهای تصویر معمولاً داده‌های خود را در نسبت‌های ابعادی افقی خروجی می‌دهند که ۴:۳ رایج‌ترین آن‌ها است.

تلفن و حسگر دوربین هر دو در جهت عمودی هستند.
شکل ۱. رابطه معمول جهت تلفن و حسگر دوربین.

جهت طبیعی حسگر دوربین افقی است. در شکل ۱، حسگر دوربین جلو (دوربینی که در همان جهت نمایشگر قرار دارد) ۲۷۰ درجه نسبت به تلفن چرخانده شده است تا با «تعریف سازگاری Android» مطابقت داشته باشد.

برای آشکار کردن چرخش حسگر برای برنامه‌ها، میانای برنامه‌سازی کاربردی camera2 شامل ثابت SENSOR_ORIENTATION است. در اکثر تلفن‌ها و رایانه‌های لوحی، دستگاه جهت حسگر را برای دوربین‌های جلو ۲۷۰ درجه و برای دوربین‌های پشت ۹۰ درجه (از دید پشت دستگاه) گزارش می‌کند که لبه بلند حسگر را با لبه بلند دستگاه تراز می‌کند. دوربین‌های رایانه کیفی معمولاً جهت حسگر را ۰ یا ۱۸۰ درجه گزارش می‌کنند.

ازآنجایی‌که حسگرهای تصویر دوربین داده‌های خود (میان‌گیر تصویر) را در جهت طبیعی حسگر (افقی) خروجی می‌دهند، میان‌گیر تصویر باید به تعداد درجه‌های مشخص‌شده توسط SENSOR_ORIENTATION چرخانده شود تا پیش‌نمایش دوربین به‌صورت عمودی در جهت طبیعی دستگاه ظاهر شود. برای دوربین‌های جلو، چرخش پادساعت‌گرد است؛ برای دوربین‌های پشت، ساعت‌گرد.

برای مثال، برای دوربین جلو در شکل ۱، میان‌گیر تصویر تولیدشده توسط حسگر دوربین به‌این‌صورت است:

حسگر دوربین به جهت افقی با تصویر کج، بالا سمت چپ چرخید.
شکل ۲. بافر تصویر خام از حسگر دوربین جلو در جهت افقی طبیعی آن.

تصویر باید ۲۷۰ درجه پادساعت‌گرد چرخانده شود تا جهت پیش‌نمایش با جهت دستگاه مطابقت داشته باشد:

حسگر دوربین در جهت عمودی با تصویر ایستاده.
شکل ۳. بافر تصویر دوربین جلو ۲۷۰ درجه پادساعت‌گرد چرخانده شده است تا با جهت عمودی دستگاه مطابقت داشته باشد.

دوربین پشت میان‌گیر تصویری با همان جهت میان‌گیر قبلی تولید می‌کند، اما SENSOR_ORIENTATION ۹۰ درجه است. درنتیجه، میان‌گیر ۹۰ درجه در جهت عقربه‌های ساعت می‌چرخد.

چرخش دستگاه

چرخش دستگاه تعداد درجه‌ای است که دستگاه از جهت طبیعی خود می‌چرخد. برای مثال، تلفنی که در جهت افقی قرار دارد، بسته به جهت چرخش، چرخش دستگاه ۹۰ یا ۲۷۰ درجه دارد.

بافر تصویر حسگر دوربین باید به همان تعداد درجه‌ای که دستگاه می‌چرخد (علاوه‌بر درجه‌های جهت حسگر) بچرخد تا پیش‌نمای دوربین به‌صورت عمودی ظاهر شود.

محاسبه جهت‌یابی

جهت مناسب پیش‌نمایش دوربین، جهت حسگر و چرخش دستگاه را درنظر می‌گیرد.

چرخش کلی میان‌گیر تصویر حسگر را می‌توان بااستفاده از فرمول زیر محاسبه کرد:

rotation = (sensorOrientationDegrees - deviceOrientationDegrees * sign + 360) % 360

که sign برای دوربین‌های جلو 1 و برای دوربین‌های پشت -1 است.

برای دوربین‌های جلو، میان‌گیر تصویر پادساعت‌گرد (از جهت طبیعی حسگر) چرخانده می‌شود. برای دوربین‌های پشت، میان‌گیر تصویر حسگر در جهت ساعت‌گرد چرخانده می‌شود.

عبارت deviceOrientationDegrees * sign + 360 چرخش دستگاه را از پادساعت‌گرد به ساعت‌گرد برای دوربین‌های پشت تبدیل می‌کند (برای مثال، تبدیل ۲۷۰ درجه پادساعت‌گرد به ۹۰ درجه ساعت‌گرد). عملیات پیمانه نتیجه را به کمتر از ۳۶۰ درجه مقیاس‌بندی می‌کند (برای مثال، مقیاس‌بندی ۵۴۰ درجه چرخش به ۱۸۰ درجه).

میاناهای برنامه‌سازی کاربردی مختلف چرخش دستگاه را به‌طور متفاوتی گزارش می‌کنند:

  • Display#getRotation() چرخش پادساعت‌گرد دستگاه را (از دید کاربر) ارائه می‌دهد. این مقدار همان‌طور که هست به فرمول قبلی اضافه می‌شود.
  • OrientationEventListener#onOrientationChanged() چرخش ساعت‌گرد دستگاه را (از دیدگاه کاربر) برمی‌گرداند. مقدار را برای استفاده در فرمول قبلی منفی کنید.

دوربین‌های جلو

پیش‌نمای دوربین و حسگر هر دو در جهت افقی، حسگر در جهت درست است.
شکل ۴. پیش‌نمایش دوربین و حسگر با تلفنی که ۹۰ درجه به جهت افقی چرخیده است.

در اینجا میان‌گیر تصویر تولیدشده توسط حسگر دوربین در شکل ۴ آمده است:

حسگر دوربین در جهت افقی با تصویر عمودی.
شکل ۵. بافر تصویر تولیدشده توسط حسگر دوربین جلو وقتی تلفن ۹۰ درجه پادساعت‌گرد چرخانده می‌شود.

بافر باید ۲۷۰ درجه پادساعت‌گرد چرخانده شود تا با جهت حسگر مطابقت داشته باشد (به جهت دوربین در بالا مراجعه کنید):

حسگر دوربین به جهت عمودی با تصویر جانبی، بالا سمت راست، چرخید.
شکل ۶. بافر تصویر ۲۷۰ درجه پادساعت‌گرد چرخانده شد تا با جهت حسگر تنظیم شود.

سپس میان‌گیر ۹۰ درجه دیگر در جهت پادساعت‌گرد چرخانده می‌شود تا چرخش دستگاه را درنظر بگیرد، که منجر به جهت صحیح پیش‌نمای دوربین در شکل ۴ می‌شود:

حسگر دوربین به جهت افقی با تصویر عمودی چرخانده شد.
شکل ۷. بافر تصویر پس‌از چرخش ۹۰ درجه‌ای پادساعت‌گرد اضافی برای جهت دستگاه.

در اینجا دوربین به سمت راست در جهت افقی چرخانده شده است:

پیش‌نمایش دوربین و حسگر هر دو در جهت افقی هستند، اما حسگر وارونه است.
شکل ۸. پیش‌نمایش دوربین و حسگر با تلفن ۲۷۰ درجه چرخیده (یا ۹۰- درجه) به جهت افقی.

این هم میان‌گیر تصویر:

حسگر دوربین به جهت افقی چرخید و تصویر وارونه شد.
شکل ۹. بافر تصویر تولیدشده توسط حسگر دوربین جلو وقتی تلفن ۲۷۰ درجه پادساعت‌گرد چرخانده می‌شود.

بافر باید ۲۷۰ درجه پادساعت‌گرد چرخانده شود تا با جهت حسگر مطابقت داشته باشد:

حسگر دوربین به جهت عمودی با تصویر جانبی، بالا سمت چپ چرخید.
شکل ۱۰. بافر تصویر ۲۷۰ درجه پادساعت‌گرد چرخانده شد تا با جهت حسگر تنظیم شود.

سپس میان‌گیر ۲۷۰ درجه دیگر در جهت پادساعت‌گرد چرخانده می‌شود تا چرخش دستگاه را درنظر بگیرد:

حسگر دوربین به جهت افقی با تصویر عمودی چرخانده شد.
شکل ۱۱. بافر تصویر پس‌از چرخش پادساعت‌گرد ۲۷۰ درجه‌ای اضافی برای جهت دستگاه.

دوربین‌های پشت

دوربین‌های پشت معمولاً جهت حسگر ۹۰ درجه دارند (همان‌طور که از پشت دستگاه دیده می‌شود). هنگام جهت‌دهی پیش‌نمایش دوربین، میان‌گیر تصویر حسگر به‌اندازه چرخش حسگر در جهت ساعت‌گرد چرخانده می‌شود (نه در جهت پادساعت‌گرد مانند دوربین‌های جلو)، و سپس میان‌گیر تصویر به‌اندازه چرخش دستگاه در جهت پادساعت‌گرد چرخانده می‌شود.

پیش‌نمایش دوربین و حسگر هر دو در جهت افقی هستند، اما حسگر وارونه است.
شکل ۱۲. تلفن با دوربین پشت در جهت افقی (۲۷۰ یا ۹۰- درجه چرخانده شده).

در اینجا میان‌گیر تصویر از حسگر دوربین در شکل ۱۲ آمده است:

حسگر دوربین به جهت افقی چرخید و تصویر وارونه شد.
شکل ۱۳. میان‌گیر تصویر تولیدشده توسط حسگر دوربین پشت وقتی تلفن در جهت افقی است.

بافر باید ۹۰ درجه ساعت‌گرد چرخانده شود تا با جهت حسگر مطابقت داشته باشد:

حسگر دوربین به جهت عمودی با تصویر جانبی، بالا سمت چپ چرخید.
شکل ۱۴. بافر تصویر ۹۰ درجه در جهت عقربه‌های ساعت چرخانده شد تا با جهت حسگر پشت تنظیم شود.

سپس میان‌گیر ۲۷۰ درجه پادساعت‌گرد چرخانده می‌شود تا چرخش دستگاه را درنظر بگیرد:

حسگر دوربین به جهت افقی با تصویر عمودی چرخانده شد.
شکل ۱۵. بافر تصویر پس‌از چرخش ۲۷۰ درجه‌ای پادساعت‌گرد برای جهت دستگاه.

نسبت ابعادی

نسبت ابعادی نمایشگر زمانی تغییر می‌کند که جهت دستگاه تغییر کند، اما همچنین زمانی که دستگاه‌های تاشو تا و باز می‌شوند، زمانی که اندازه پنجره‌ها در محیط‌های چندپنجره‌ای تغییر می‌کند، و زمانی که برنامه‌ها در نمایشگرهای ثانویه باز می‌شوند.

بافر تصویر حسگر دوربین باید جهت‌دهی و مقیاس‌بندی شود تا با جهت و نسبت ابعادی عنصر میانای کاربر نمایاب مطابقت داشته باشد، زیرا میانای کاربر به‌طور پویا جهت را تغییر می‌دهد—با یا بدون تغییر جهت دستگاه.

در فاکتورهای شکل جدید یا در محیط‌های چندپنجره‌ای یا چندنمایشی، اگر برنامه شما فرض کند که پیش‌نمایش دوربین همان جهت دستگاه (عمودی یا افقی) را دارد، ممکن است پیش‌نمایش شما جهت نادرستی داشته باشد، مقیاس نادرستی داشته باشد، یا هر دو.

دستگاه تاشو بازشده با پیش‌نمایش دوربین عمودی که به پهلو چرخیده است.
شکل ۱۶. دستگاه تاشو از نسبت ابعادی عمودی به افقی تغییر می‌کند اما حسگر دوربین در جهت عمودی باقی می‌ماند.

در شکل ۱۶، برنامه به‌اشتباه فرض کرده است که دستگاه ۹۰ درجه پادساعت‌گرد چرخیده است؛ بنابراین، برنامه پیش‌نمایش را به همان اندازه چرخانده است.

دستگاه تاشو بازشده با پیش‌نمایش دوربین به‌صورت عمودی اما فشرده‌شده به‌دلیل مقیاس‌بندی نادرست.
شکل ۱۷. دستگاه تاشو از نسبت ابعادی عمودی به افقی تغییر می‌کند و پیش‌نمایش دوربین به‌درستی مقیاس‌بندی نشده است.

در شکل ۱۷، برنامه نسبت ابعادی میان‌گیر تصویر را تنظیم نکرده است تا بتواند به‌درستی مقیاس‌بندی شود و در ابعاد جدید عنصر میانای کاربر پیش‌نمایش دوربین جا شود.

برنامه‌های دوربین با جهت ثابت معمولاً در دستگاه‌های تاشو و دیگر دستگاه‌های دارای صفحه‌نمایش بزرگ مانند رایانه‌های کیفی با مشکل مواجه می‌شوند:

پیش‌نمای دوربین در رایانه کیفی عمودی است اما میانای کاربر برنامه افقی است.
شکل ۱۸. برنامه عمودی با جهت ثابت در رایانه کیفی.

در شکل ۱۸، میانای کاربر برنامه دوربین به‌صورت افقی است زیرا جهت برنامه فقط به حالت عمودی محدود شده است. تصویر نمایاب نسبت به حسگر دوربین جهت‌گیری درستی دارد.

حالت چهره درج‌شده

برنامه‌های دوربین که از حالت چندپنجره‌ای پشتیبانی نمی‌کنند (resizeableActivity="false") و جهت خود را محدود می‌کنند (screenOrientation="portrait" یا screenOrientation="landscape") می‌توانند در حالت عمودی درج‌شده در دستگاه‌های با صفحه‌نمایش بزرگ قرار گیرند تا پیش‌نمایش دوربین به‌درستی جهت‌دهی شود.

حالت چهره درج‌شده برنامه‌های فقط عمودی را در جهت عمودی درج می‌کند، حتی اگر نسبت ابعادی نمایشگر افقی باشد. برنامه‌هایی که فقط در حالت افقی هستند، در جهت افقی به‌صورت جعبه‌ای نمایش داده می‌شوند، حتی اگر نسبت ابعادی نمایشگر عمودی باشد. تصویر دوربین چرخانده می‌شود تا با میانای کاربر برنامه تراز شود، برش داده می‌شود تا با نسبت ابعادی پیش‌نمایش دوربین مطابقت داشته باشد، و سپس مقیاس‌بندی می‌شود تا پیش‌نمایش را پر کند.

وقتی نسبت ابعادی حسگر تصویر دوربین و نسبت ابعادی فعالیت اصلی برنامه با هم مطابقت نداشته باشند، حالت چهره توکار راه‌اندازی می‌شود.

پیش‌نمای دوربین و میانای کاربر برنامه در جهت عمودی مناسب در رایانه کیفی. تصویر پیش‌نمای عریض برای قرار گرفتن در جهت عمودی مقیاس‌بندی و برش داده شده است.
شکل ۱۹. برنامه عمودی با جهت ثابت در حالت عمودی درج‌شده در رایانه کیفی.

در شکل ۱۹، برنامه دوربین فقط عمودی چرخانده شده است تا میانای کاربر را به‌صورت عمودی در نمایشگر رایانه کیفی نشان دهد. برنامه به‌دلیل تفاوت در نسبت ابعادی بین برنامه عمودی و نمایشگر افقی، در حالت جعبه‌ای قرار گرفته است. تصویر پیش‌نمایش دوربین برای جبران چرخش میانای کاربر برنامه (به‌دلیل حالت چهره درج‌شده) چرخانده شده است و تصویر برای مطابقت با جهت عمودی برش داده شده و مقیاس‌بندی شده است که این امر میدان دید را کاهش می‌دهد.

چرخاندن، برش دادن، مقیاس‌بندی

حالت چهره توکار برای برنامه دوربین فقط چهره در نمایشگری که نسبت ابعادی افقی دارد فراخوانده می‌شود:

پیش‌نمای دوربین در رایانه کیفی عمودی است اما میانای کاربر برنامه افقی است.
شکل ۲۰. برنامه عمودی با جهت ثابت در رایانه کیفی.

برنامه در جهت عمودی به‌صورت جعبه‌ای نمایش داده می‌شود:

برنامه به جهت عمودی چرخید و در حالت جعبه‌ای قرار گرفت. تصویر کج است، بالا در سمت راست است.
شکل ۲۱. برنامه فقط عمودی که در نمایشگر افقی چرخانده شده و حاشیه‌دار شده است، قبل‌از چرخش تصویر حسگر.

تصویر دوربین ۹۰ درجه می‌چرخد تا با جهت جدید برنامه مطابقت پیدا کند:

تصویر حسگر ۹۰ درجه چرخانده شد تا عمودی شود.
شکل ۲۲. تصویر دوربین ۹۰ درجه چرخانده شد تا با میانای کاربر برنامه که جهت آن تغییر کرده است تراز شود.

تصویر به نسبت ابعادی پیش‌نمای دوربین برش داده می‌شود، سپس مقیاس‌بندی می‌شود تا پیش‌نما را پر کند (میدان دید کاهش می‌یابد):

تصویر برش‌خورده دوربین برای پر کردن پیش‌نمایش دوربین مقیاس‌بندی شده است.
شکل ۲۳. تصویر دوربین برش داده شده و مقیاس‌بندی شده است تا پیش‌نمایش دوربین عمودی را پر کند.

در دستگاه‌های تاشو، جهت حسگر دوربین می‌تواند عمودی باشد درحالی‌که نسبت ابعادی نمایشگر افقی است:

پیش‌نمایش دوربین و میانای کاربر برنامه در نمایشگر عریض و بازشده به‌صورت افقی نشان داده می‌شود.
شکل ۲۴. دستگاه بازشده با برنامه دوربین فقط عمودی و نسبت‌های ابعادی متفاوت حسگر دوربین و نمایشگر.

چون پیش‌نمایش دوربین برای تنظیم جهت حسگر چرخانده می‌شود، تصویر در نمایاب به‌درستی جهت‌دهی می‌شود، اما برنامه فقط عمودی به‌صورت افقی است.

حالت چهره درج‌شده فقط باید برنامه را در جهت عمودی حاشیه‌بندی کند تا برنامه و پیش‌نمایش دوربین را به‌درستی جهت‌دهی کند:

برنامه با حاشیه سیاه در جهت عمودی با پیش‌نمایش دوربین به‌صورت عمودی در دستگاه تاشو.
شکل ۲۵. برنامه فقط عمودی در حالت عمودی درج‌شده در دستگاه تاشو بازشده به‌صورت جعبه‌ای نمایش داده شده است.

API

از Android 12 (سطح میانای برنامه‌سازی کاربردی ۳۱) به بعد، برنامه‌ها می‌توانند به‌طور صریح حالت عمودی درج‌شده را بااستفاده از ویژگی SCALER_ROTATE_AND_CROP کلاس CaptureRequest کنترل کنند.

مقدار پیش‌فرض SCALER_ROTATE_AND_CROP_AUTO است که به سیستم امکان می‌دهد حالت چهره درج‌شده را فراخوانی کند. SCALER_ROTATE_AND_CROP_90 رفتار حالت چهره درج‌شده است که قبلاً شرح داده شد.

همه دستگاه‌ها از همه مقادیر SCALER_ROTATE_AND_CROP پشتیبانی نمی‌کنند. برای دریافت فهرست مقادیر پشتیبانی‌شده، به CameraCharacteristics#SCALER_AVAILABLE_ROTATE_AND_CROP_MODES مراجعه کنید.

CameraX

کتابخانه Jetpack CameraX ایجاد نمایاب دوربین را که با جهت حسگر و چرخش دستگاه سازگار باشد به کاری ساده تبدیل می‌کند.

عنصر چیدمان PreviewView پیش‌نمایش دوربین ایجاد می‌کند، و به‌طور خودکار برای جهت‌گیری حسگر، چرخش دستگاه، و مقیاس‌بندی تنظیم می‌شود. PreviewView با اعمال نوع مقیاس FILL_CENTER، نسبت ابعادی تصویر دوربین را حفظ می‌کند. این نوع مقیاس تصویر را در مرکز قرار می‌دهد اما ممکن است آن را برای مطابقت با ابعاد PreviewView برش دهد. برای جعبه‌نامه‌ای کردن تصویر دوربین، نوع مقیاس را روی FIT_CENTER تنظیم کنید.

برای آشنایی با اصول ایجاد پیش‌نمایش دوربین با PreviewView، پیاده‌سازی پیش‌نمایش را ببینید.

برای مشاهده نمونه کامل پیاده‌سازی، به مخزن CameraXBasic در GitHub مراجعه کنید.

CameraViewfinder

مشابه مورد استفاده پیش‌نمایش، کتابخانه CameraViewfinder مجموعه‌ای از ابزارها را برای ساده‌سازی ایجاد پیش‌نمایش دوربین ارائه می‌دهد. این کتابخانه به CameraX Core وابسته نیست، بنابراین می‌توانید آن را به‌طور یکپارچه در پایگاه کد Camera2 موجود خود ادغام کنید.

به‌جای استفاده مستقیم از Surface، می‌توانید از ابزاره CameraViewfinder برای نمایش فید دوربین برای Camera2 استفاده کنید.

CameraViewfinder به‌طور داخلی از TextureView یا SurfaceView برای نمایش فید دوربین استفاده می‌کند و تبدیل‌های لازم را روی آن‌ها اعمال می‌کند تا نمایاب را به‌درستی نمایش دهد. این شامل اصلاح نسبت ابعادی، مقیاس، و چرخش آن‌ها می‌شود.

برای درخواست سطح از شیء CameraViewfinder، باید ViewfinderSurfaceRequest ایجاد کنید.

این درخواست حاوی الزامات مربوط به وضوح سطح و اطلاعات دستگاه دوربین از CameraCharacteristics است.

فراخوانی requestSurfaceAsync() درخواست را به ارائه‌دهنده سطح ارسال می‌کند که یا TextureView است یا SurfaceView و ListenableFuture از Surface را دریافت می‌کند.

فراخوانی markSurfaceSafeToRelease() به ارائه‌دهنده سطح اطلاع می‌دهد که به سطح نیازی نیست و منابع مرتبط می‌توانند آزاد شوند.

fun startCamera() {
    val previewResolution = Size(width, height)
    val viewfinderSurfaceRequest =
        ViewfinderSurfaceRequest(previewResolution, characteristics)
    val surfaceListenableFuture =
        cameraViewfinder.requestSurfaceAsync(viewfinderSurfaceRequest)

    Futures.addCallback(surfaceListenableFuture, object : FutureCallback<Surface> {
        override fun onSuccess(surface: Surface) {
            /* create a CaptureSession using this surface as usual */
        }
        override fun onFailure(t: Throwable) { /* something went wrong */ }
    }, ContextCompat.getMainExecutor(context))
}

SurfaceView

SurfaceView رویکردی ساده برای ایجاد پیش‌نمایش دوربین است، اگر پیش‌نمایش نیازی به پردازش نداشته باشد و پویانمایی نشده باشد.

SurfaceView میان‌گیر تصویر حسگر دوربین را به‌طور خودکار می‌چرخاند تا با جهت نمایشگر مطابقت داشته باشد، و هم جهت حسگر و هم چرخش دستگاه را درنظر می‌گیرد. بااین‌حال، میان‌گیر تصویر برای مطابقت با ابعاد SurfaceView بدون درنظر گرفتن نسبت ابعادی مقیاس‌بندی می‌شود.

باید مطمئن شوید که نسبت ابعادی میان‌گیر تصویر با نسبت ابعادی SurfaceView مطابقت داشته باشد. این کار را می‌توانید با مقیاس‌بندی محتوای SurfaceView در روش onMeasure() مؤلفه انجام دهید:

(کد منبع computeRelativeRotation() در چرخش نسبی در زیر قرار دارد.)

override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
    val width = MeasureSpec.getSize(widthMeasureSpec)
    val height = MeasureSpec.getSize(heightMeasureSpec)

    val relativeRotation = computeRelativeRotation(characteristics, surfaceRotationDegrees)

    if (previewWidth > 0f && previewHeight > 0f) {
        /* Scale factor required to scale the preview to its original size on the x-axis. */
        val scaleX =
            if (relativeRotation % 180 == 0) {
                width.toFloat() / previewWidth
            } else {
                width.toFloat() / previewHeight
            }
        /* Scale factor required to scale the preview to its original size on the y-axis. */
        val scaleY =
            if (relativeRotation % 180 == 0) {
                height.toFloat() / previewHeight
            } else {
                height.toFloat() / previewWidth
            }

        /* Scale factor required to fit the preview to the SurfaceView size. */
        val finalScale = min(scaleX, scaleY)

        setScaleX(1 / scaleX * finalScale)
        setScaleY(1 / scaleY * finalScale)
    }
    setMeasuredDimension(width, height)
}

برای جزئیات بیشتر درباره پیاده‌سازی SurfaceView به‌عنوان پیش‌نمای دوربین، به جهت‌های دوربین مراجعه کنید.

TextureView

TextureView عملکرد ضعیف‌تری نسبت‌به SurfaceView دارد—و کار بیشتری می‌برد—اما TextureView حداکثر کنترل را بر پیش‌نمایش دوربین به شما می‌دهد.

TextureView میان‌گیر تصویر حسگر را براساس جهت حسگر می‌چرخاند اما چرخش دستگاه یا مقیاس‌بندی پیش‌نمایش را مدیریت نمی‌کند.

مقیاس‌بندی و چرخش را می‌توان در تبدیل ماتریس کدگذاری کرد. برای آشنایی با نحوه مقیاس‌بندی و چرخاندن صحیح TextureView، به پشتیبانی از سطوح با قابلیت تغییر اندازه در برنامه دوربین مراجعه کنید.

چرخش نسبی

چرخش نسبی حسگر دوربین مقدار چرخش لازم برای تراز کردن خروجی حسگر دوربین با جهت دستگاه است.

چرخش نسبی توسط مؤلفه‌هایی مانند SurfaceView و TextureView استفاده می‌شود تا ضریب‌های مقیاس x و y را برای تصویر پیش‌نمایش تعیین کند. همچنین برای مشخص کردن چرخش میان‌گیر تصویر حسگر استفاده می‌شود.

کلاس‌های CameraCharacteristics و Surface امکان محاسبه چرخش نسبی حسگر دوربین را فراهم می‌کنند:

/**
 * Computes rotation required to transform the camera sensor output orientation to the
 * device's current orientation in degrees.
 *
 * @param characteristics The CameraCharacteristics to query for the sensor orientation.
 * @param surfaceRotationDegrees The current device orientation as a Surface constant.
 * @return Relative rotation of the camera sensor output.
 */
public fun computeRelativeRotation(
    characteristics: CameraCharacteristics,
    surfaceRotationDegrees: Int
): Int {
    val sensorOrientationDegrees =
        characteristics.get(CameraCharacteristics.SENSOR_ORIENTATION) ?: 0

    // Reverse device orientation for back-facing cameras.
    val sign = if (characteristics.get(CameraCharacteristics.LENS_FACING) ==
        CameraCharacteristics.LENS_FACING_FRONT
    ) 1 else -1

    // Calculate desired orientation relative to camera orientation to make
    // the image upright relative to the device orientation.
    return (sensorOrientationDegrees - surfaceRotationDegrees * sign + 360) % 360
}

سنجه‌های پنجره

از اندازه صفحه‌نمایش نباید برای تعیین ابعاد نمایاب دوربین استفاده شود؛ برنامه دوربین ممکن است در بخشی از صفحه‌نمایش، در حالت چندپنجره‌ای در دستگاه‌های همراه، یا در حالت آزاد در ChromeOS اجرا شود.

WindowManager#getCurrentWindowMetrics() (اضافه‌شده در سطح میانای برنامه‌سازی کاربردی ۳۰) اندازه پنجره برنامه را به‌جای اندازه صفحه‌نمایش برمی‌گرداند. روش‌های کتابخانه Jetpack WindowManager WindowMetricsCalculator#computeCurrentWindowMetrics() و WindowInfoTracker#currentWindowMetrics() پشتیبانی مشابهی را با سازگاری با نسخه قدیمی برای سطح میانای برنامه‌سازی کاربردی ۱۴ ارائه می‌دهند.

چرخش ۱۸۰ درجه

چرخش ۱۸۰ درجه‌ای دستگاه (برای مثال، از جهت طبیعی به جهت طبیعی وارونه) باعث راه‌اندازی فراخوانی onConfigurationChanged() نمی‌شود. درنتیجه، ممکن است پیش‌نمایش دوربین وارونه باشد.

برای تشخیص چرخش ۱۸۰ درجه، DisplayListener را پیاده‌سازی کنید و چرخش دستگاه را با تماس با Display#getRotation() در فراخوانی برگشتی onDisplayChanged() بررسی کنید.

منابع انحصاری

پیش‌از Android 10، فقط بالاترین فعالیت قابل‌مشاهده در محیط چندپنجره‌ای در وضعیت RESUMED بود. این موضوع برای کاربران گیج‌کننده بود زیرا سیستم هیچ نشانه‌ای از اینکه کدام فعالیت ازسر گرفته شده است ارائه نمی‌داد.

Android 10 (سطح میانای برنامه‌سازی کاربردی ۲۹) ازسرگیری چندگانه را معرفی کرد که در آن همه فعالیت‌های نمایان در وضعیت RESUMED هستند. فعالیت‌های قابل‌مشاهده همچنان می‌توانند وارد وضعیت PAUSED شوند، مثلاً اگر فعالیت شفافی روی فعالیت قرار داشته باشد یا فعالیت قابل‌تمرکز نباشد، مانند حالت تصویردرتصویر (به پشتیبانی تصویردرتصویر مراجعه کنید).

برنامه‌ای که از دوربین، میکروفون، یا هر منبع انحصاری یا تک‌نمونه‌ای در سطح میانای برنامه‌سازی کاربردی ۲۹ یا بالاتر استفاده می‌کند باید از ازسرگیری چندگانه پشتیبانی کند. برای مثال، اگر سه فعالیت ازسرگرفته‌شده بخواهند از دوربین استفاده کنند، فقط یکی از آن‌ها می‌تواند به این منبع انحصاری دسترسی داشته باشد. هر فعالیت باید یک onDisconnected() callback را پیاده‌سازی کند تا از دسترسی پیش‌گیرانه به دوربین توسط یک فعالیت با اولویت بالاتر مطلع بماند.

برای اطلاعات بیشتر، به ازسرگیری چندگانه مراجعه کنید.

منابع بیشتر