Расширения поставщика CameraX

Производители устройств могут внедрить OEM-библиотеку OEM-производителей CameraX, чтобы предоставлять эффекты для конкретных устройств сторонним разработчикам через интерфейс расширений CameraX. CameraX определяет интерфейс расширений CameraX для реализованных поставщиком классов, загружаемых во время выполнения. На этой странице описывается, как внедрить библиотеку OEM-поставщика и включить ее на устройствах.

Прежде чем внедрять библиотеку поставщика, убедитесь, что вы понимаете, как работает библиотека поддержки CameraX Jetpack. Дополнительные сведения о CameraX см. в разделе Обзор CameraX . Дополнительные сведения о расширениях поставщиков см. в разделе Расширения поставщиков .

Архитектура

Архитектура

Рис. 1. Схема архитектуры расширений поставщика

Эта диаграмма описывает архитектуру расширений поставщика CameraX. Сторонние приложения могут быть созданы на основе библиотеки расширений CameraX ( camera-extensions ) и использовать общедоступный API -интерфейс расширений камеры ( API-интерфейс camera-extensions ). API расширений камеры определяется CameraX и обновляется при выпуске новой версии библиотеки расширений камеры. Версии общедоступного API-интерфейса camera-extensions и библиотеки camera-extensions одинаковы.

Начиная с Android 12, сторонние приложения можно создавать с помощью API расширений Camera2. Чтобы включить поддерживаемые режимы расширения, приложения могут создать сеанс захвата камеры ( CameraExtensionSession ) с помощью CameraDevice#createExtensionSession() .

Интерфейс расширений ( extensions-interface ), определенный CameraX, позволяет как библиотеке расширений камеры CameraX, так и API расширений Camera2 взаимодействовать с библиотекой OEM-поставщика ( camera-extensions-stub ). Это означает, что устройства, реализующие OEM-библиотеку OEM-производителя CameraX, также поддерживают API-интерфейс расширений Camera2.

Внедрение библиотеки поставщиков OEM

В этих инструкциях по реализации в качестве примера используется расширение поставщика боке (портрет), но вы можете применить их к другим расширениям, таким как HDR, ретушь лица и расширения ночного режима. Для этого скопируйте и вставьте код, используемый для расширения боке, и замените имя расширения на желаемое расширение (например, заменив BokehImageCaptureExtenderImpl на HdrImageCaptureExtenderImpl ).

Вы не обязаны предоставлять реализацию для каждого эффекта. Эффект без реализации поставщика по умолчанию использует реализацию CameraX. Если эффект недоступен, реализация по умолчанию не включает эффект и сообщает стороннему разработчику, что эффект недоступен.

Проверка версии

При загрузке OEM-библиотеки CameraX проверяет, содержит ли OEM-библиотека версию, совместимую с версией интерфейса расширений (называемой в этом документе версией-расширения ). Чтобы определить совместимость версий, CameraX проверяет только основную и дополнительную версии (например, 1.0), но не проверяет версию исправления, поскольку она используется только для исправления ошибок, а не для изменения интерфейса. Требуемая версия расширения для конкретных API указана в этом документе. API без указанной версии расширения совместимы с версией расширения 1.0.

Чтобы проверить версию, CameraX запрашивает интерфейс ExtensionVersionImpl . Затем CameraX использует версию, сообщаемую библиотекой OEM, для определения функциональных возможностей, которые можно вызывать.

Инициализация

CameraX запускает процесс инициализации, когда определяет версию интерфейса расширений, реализованную библиотекой OEM. Метод InitializerImpl.init сообщает библиотеке OEM, что приложение хочет использовать расширения. Никакие другие вызовы библиотеки OEM (кроме проверки версии) не выполняются до тех пор, пока не будет вызван OnExtensionsInitializedCallback с состоянием успеха.

Этот метод должен быть реализован начиная с версии расширения 1.1. Дополнительные сведения см. в исходном коде InitializerImpl .

Интерфейс ExtenderStateListener

CameraX предоставляет перехватчики в нескольких местах своего конвейера, чтобы позволить OEM-библиотеке устанавливать соответствующие SessionParameters и CaptureRequest . Чтобы позволить библиотеке OEM устанавливать эти значения в указанное время, реализуйте интерфейс ExtenderStateListener . Этот интерфейс должен быть реализован как часть любого расширителя, будь то предварительный просмотр, захват изображения, боке или расширитель HDR.

Захват изображения

Для поддержки расширения для захвата изображения реализуйте соответствующий интерфейс ImageCaptureExtender (например, BokehImageCaptureExtenderImpl или HdrImageCaptureExtenderImpl ).

ImageCaptureExtenderImpl включает интерфейсы, необходимые для расширений, связанных с захватом изображений.

Интерфейс CaptureProcessorImpl должен быть реализован, чтобы постобработка выполнялась на уровне приложения. Начиная с версии интерфейса расширений 1.1, должен поддерживаться только формат входного изображения YUV_420_888 . Интерфейс CaptureProcessor не требуется, если обработка выполняется в HAL камеры.

Следующая диаграмма иллюстрирует поток процесса захвата изображения.

Поток процесса захвата изображения

Рисунок 2. Блок-схема захвата изображения

Пример: BokehImageCaptureExtenderImpl

Чтобы поддерживать расширение bokeh для захвата изображения, реализуйте класс BokehImageCaptureExtenderImpl в пакете androidx.camera.extensions.impl .

Предварительный просмотр

Для поддержки расширения для предварительного просмотра реализуйте соответствующий интерфейс PreviewExtender (например, BokehPreviewExtenderImpl или HdrPreviewExtenderImpl ). Интерфейс PreviewExtender включает в себя интерфейсы, необходимые для расширений, связанных с предварительным просмотром.

Подробности смотрите в источнике на PreviewExtenderImpl .

Обработка изображений для расширения предварительного просмотра может выполняться в HAL камеры или на уровне приложения. Это определяется значением ProcessorType , возвращаемым PreviewExtenderImpl .

Если возвращается тип PROCESSOR_TYPE_REQUEST_UPDATE_ONLY , обработка выполняется в HAL через ключи CaptureRequest . Если возвращается тип PROCESSOR_TYPE_IMAGE_PROCESSOR , обработка выполняется на уровне приложения интерфейсом PreviewImageProcessorImpl . Этот интерфейс работает с парой Image и TotalCaptureResult . Начиная с версии интерфейса расширений 1.1, должен поддерживаться только формат входного изображения YUV_420_888 .

На следующей диаграмме показан процесс для расширения поставщика предварительной версии.

Блок-схема предварительного просмотра

Рисунок 3. Блок-схема предварительного просмотра

Пример: BokehPreviewExtenderImpl

Чтобы поддерживать боке для предварительного просмотра, реализуйте класс BokehPreviewExtenderImpl в пакете androidx.camera.extensions.impl .

Эталонная реализация

Реализацию эталонной библиотеки поставщиков OEM см. в разделе camera-testlib-extensions . Обратите внимание, что эта реализация выполняет сквозные переходы без фактической реализации эффектов.

Настройка библиотеки поставщиков на устройстве

Библиотека OEM-поставщика не встроена в приложение, а загружается с устройства во время выполнения с помощью CameraX. Тег <uses-library> объявляет, что библиотека androidx.camera.extensions.impl , определенная в файле AndroidManifest.xml , является зависимостью от CameraX и должна загружаться во время выполнения. Это позволяет сторонним приложениям, использующим расширения поставщиков, автоматически пытаться загрузить библиотеку OEM-поставщиков. Библиотека OEM помечена как необязательная, поэтому приложения могут работать на устройствах, на которых нет этой библиотеки.

CameraX автоматически обрабатывает это поведение, когда приложение пытается использовать расширение поставщика, если производитель устройства размещает OEM-библиотеку на устройстве, чтобы приложение могло ее обнаружить.

Чтобы настроить OEM-библиотеку на устройстве, выполните следующие действия.

  1. Добавьте файл разрешений, требуемый <uses-library> , в следующем формате: /etc/permissions/ ANY_FILENAME .xml . Например, /etc/permissions/camera_extensions.xml . Файлы в этом каталоге обеспечивают сопоставление библиотеки, названной в <uses-library> , с фактическим путем к файлу на устройстве.
  2. Используйте приведенный ниже пример, чтобы добавить необходимую информацию в файл.

    • name должно быть androidx.camera.extensions.impl , так как это библиотека, которую ищет CameraX.
    • file — абсолютный путь к файлу, содержащему реализацию расширений (например, /system/framework/androidx.camera.extensions.impl.jar ).
    <?xml version="1.0" encoding="utf-8"?>
    <permissions>
        <library name="androidx.camera.extensions.impl"
                 file="OEM_IMPLEMENTED_JAR" />
    </permissions>
    

В Android 12 или выше устройства, поддерживающие расширения CameraX, должны иметь для свойства ro.camerax.extensions.enabled значение true , что позволяет запрашивать, поддерживает ли устройство расширения. Для этого добавьте следующую строку в make-файл устройства:

PRODUCT_VENDOR_PROPERTIES += \
    ro.camerax.extensions.enabled=true \

Проверка

Чтобы протестировать реализацию библиотеки поставщика OEM на этапе разработки, используйте пример приложения по адресу androidx-main/camera/integration-tests/extensionstestapp/ , который запускается через различные расширения поставщиков.

После завершения внедрения используйте средство проверки расширений поставщика CameraX , чтобы запустить автоматические и ручные тесты, чтобы убедиться, что библиотека поставщика реализована правильно.

Часто задаваемые вопросы (FAQ)

Есть ли ограничения по уровням API?

Да. Это зависит от набора функций Android API, который требуется для реализации библиотеки OEM-поставщика. Например, ExtenderStateListener.onPresetSession() использует SessionConfiguration.setSessionParameters() для установки базового набора тегов. Этот вызов доступен только на уровне API 28 и выше. Подробнее о конкретных методах интерфейса см. в справочной документации по API .