Справочник по структуре camera3_device_ops
#include < camera3.h >
Поля данных | |
| интервал(* | инициализировать )(const struct camera3_device *, const camera3_callback_ops_t *callback_ops) |
| интервал(* | configure_streams )(const struct camera3_device *, camera3_stream_configuration_t *stream_list) |
| интервал(* | Register_stream_buffers )(const struct camera3_device *, const camera3_stream_buffer_set_t *buffer_set) |
| const camera_metadata_t *(* | struct_default_request_settings )(const struct camera3_device *, тип int) |
| интервал(* | process_capture_request )(const struct camera3_device *, camera3_capture_request_t *request) |
| пустота(* | get_metadata_vendor_tag_ops )(const struct camera3_device *,vendor_tag_query_ops_t *ops) |
| пустота(* | дамп )(const struct camera3_device *, int fd) |
| интервал(* | флеш )(const struct camera3_device *) |
| пустота * | зарезервировано [8] |
Подробное описание
Полевая документация
| int(* configure_streams)(const struct camera3_device *, camera3_stream_configuration_t *stream_list) |
конфигурационные_стримы:
Только CAMERA_DEVICE_API_VERSION_3_0:
Сбросьте конвейер обработки устройства камеры HAL и настройте новые входные и выходные потоки. Этот вызов заменяет любую существующую конфигурацию потока потоками, определенными в потоке_списка. Этот метод будет вызван как минимум один раз после инициализации() перед отправкой запроса с помощью процесса_capture_request() .
Список потоков_список должен содержать по крайней мере один поток с возможностью вывода и не может содержать более одного потока с возможностью ввода.
Список потоков_список может содержать потоки, которые также входят в активный в данный момент набор потоков (из предыдущего вызова метода configure_stream()). Эти потоки уже будут иметь допустимые значения для использования, max_buffers и частного указателя.
Если в таком потоке уже зарегистрированы буферы, метод Register_stream_buffers() не будет повторно вызываться для потока, и буферы из потока могут быть немедленно включены во входные запросы.
Если HAL необходимо изменить конфигурацию существующего потока из-за новой конфигурации, он может перезаписать значения использования и/или max_buffers во время вызова настройки.
Платформа обнаружит такое изменение, а затем перераспределит буферы потока и снова вызовет Register_stream_buffers() перед использованием буферов из этого потока в запросе.
Если активный в данный момент поток не включен в поток_список, HAL может безопасно удалить любые ссылки на этот поток. Он не будет повторно использоваться платформой при последующем вызове configure(), и все буферы gralloc для него будут освобождены после возврата из вызова configure_streams() .
Структураstream_list принадлежит платформе и не может быть доступна после завершения этого вызова. Адрес отдельной структуры camera3_stream_t будет оставаться действительным для доступа со стороны HAL до конца первого вызова configure_stream(), который больше не включает эту камеру camera3_stream_t в аргументstream_list. HAL не может изменять значения в структуре потока за пределами частного указателя, за исключением членов использования и max_buffers во время самого вызова configure_streams() .
Если поток новый, поля использования, max_buffer и частного указателя структуры потока будут установлены в 0. Устройство HAL должно установить эти поля до возврата вызова configure_streams() . Эти поля затем используются платформой и модулем gralloc платформы для выделения буферов gralloc для каждого потока.
Прежде чем буферы такого нового потока смогут быть включены в запрос захвата, платформа вызовет метод Register_stream_buffers() с этим потоком. Однако инфраструктуре не требуется регистрировать буферы для всех потоков перед отправкой запроса. Это позволяет быстро запустить (например) поток предварительного просмотра, а выделение для других потоков произойдет позже или одновременно.
Только CAMERA_DEVICE_API_VERSION_3_1:
Сбросьте конвейер обработки устройства камеры HAL и настройте новые входные и выходные потоки. Этот вызов заменяет любую существующую конфигурацию потока потоками, определенными в потоке_списка. Этот метод будет вызван как минимум один раз после инициализации() перед отправкой запроса с помощью процесса_capture_request() .
Список потоков_список должен содержать по крайней мере один поток с возможностью вывода и не может содержать более одного потока с возможностью ввода.
Список потоков_список может содержать потоки, которые также входят в активный в данный момент набор потоков (из предыдущего вызова метода configure_stream()). Эти потоки уже будут иметь допустимые значения для использования, max_buffers и частного указателя.
Если в таком потоке уже зарегистрированы буферы, метод Register_stream_buffers() не будет повторно вызываться для потока, и буферы из потока могут быть немедленно включены во входные запросы.
Если HAL необходимо изменить конфигурацию существующего потока из-за новой конфигурации, он может перезаписать значения использования и/или max_buffers во время вызова настройки.
Платформа обнаружит такое изменение, а затем перераспределит буферы потока и снова вызовет Register_stream_buffers() перед использованием буферов из этого потока в запросе.
Если активный в данный момент поток не включен в поток_список, HAL может безопасно удалить любые ссылки на этот поток. Он не будет повторно использоваться платформой при последующем вызове configure(), и все буферы gralloc для него будут освобождены после возврата из вызова configure_streams() .
Структураstream_list принадлежит платформе и не может быть доступна после завершения этого вызова. Адрес отдельной структуры camera3_stream_t будет оставаться действительным для доступа со стороны HAL до конца первого вызова configure_stream(), который больше не включает эту камеру camera3_stream_t в аргументstream_list. HAL не может изменять значения в структуре потока за пределами частного указателя, за исключением членов использования и max_buffers во время самого вызова configure_streams() .
Если поток новый, поля max_buffer и частные указатели структуры потока будут установлены в 0. Использование будет установлено на флаги использования потребителя. Устройство HAL должно установить эти поля до возврата вызова configure_streams() . Эти поля затем используются платформой и модулем gralloc платформы для выделения буферов gralloc для каждого потока.
Прежде чем буферы такого нового потока смогут быть включены в запрос захвата, платформа вызовет метод Register_stream_buffers() с этим потоком. Однако инфраструктуре не требуется регистрировать буферы для всех потоков перед отправкой запроса. Это позволяет быстро запустить (например) поток предварительного просмотра, а выделение для других потоков произойдет позже или одновременно.
>= CAMERA_DEVICE_API_VERSION_3_2:
Сбросьте конвейер обработки устройства камеры HAL и настройте новые входные и выходные потоки. Этот вызов заменяет любую существующую конфигурацию потока потоками, определенными в потоке_списка. Этот метод будет вызван как минимум один раз после инициализации() перед отправкой запроса с помощью процесса_capture_request() .
Список потоков_список должен содержать по крайней мере один поток с возможностью вывода и не может содержать более одного потока с возможностью ввода.
Список потоков_список может содержать потоки, которые также входят в активный в данный момент набор потоков (из предыдущего вызова метода configure_stream()). Эти потоки уже будут иметь допустимые значения для использования, max_buffers и частного указателя.
Если HAL необходимо изменить конфигурацию существующего потока из-за новой конфигурации, он может перезаписать значения использования и/или max_buffers во время вызова настройки.
Платформа обнаружит такое изменение и затем может перераспределить буферы потока перед использованием буферов из этого потока в запросе.
Если активный в данный момент поток не включен в поток_список, HAL может безопасно удалить любые ссылки на этот поток. Он не будет повторно использоваться платформой при последующем вызове configure(), и все буферы gralloc для него будут освобождены после возврата из вызова configure_streams() .
Структураstream_list принадлежит платформе и не может быть доступна после завершения этого вызова. Адрес отдельной структуры camera3_stream_t будет оставаться действительным для доступа со стороны HAL до конца первого вызова configure_stream(), который больше не включает эту камеру camera3_stream_t в аргументstream_list. HAL не может изменять значения в структуре потока за пределами частного указателя, за исключением членов использования и max_buffers во время самого вызова configure_streams() .
Если поток новый, поля max_buffer и частные указатели структуры потока будут установлены в 0. Использование будет установлено на флаги использования потребителя. Устройство HAL должно установить эти поля до возврата вызова configure_streams() . Эти поля затем используются платформой и модулем gralloc платформы для выделения буферов gralloc для каждого потока.
Вновь выделенные буферы могут быть включены в запрос захвата платформой в любое время. Как только буфер gralloc возвращается в платформу с помощью функцииprocess_capture_result (и соответствующий сигнал Release_fence был получен), платформа может освободить или повторно использовать его в любое время.
Предварительные условия:
Платформа будет вызывать этот метод только в том случае, если никакие захваты не обрабатываются. То есть все результаты были возвращены в платформу, и все текущие входные и выходные буферы были возвращены, а их ограничения синхронизации выпуска были проинформированы HAL. Платформа не будет отправлять новые запросы на захват, пока выполняется вызов configure_streams() .
Постусловия:
Устройство HAL должно настроить себя для обеспечения максимально возможной частоты кадров вывода с учетом размеров и форматов выходных потоков, как описано в статических метаданных устройства камеры.
Требования к производительности:
Ожидается, что этот вызов будет тяжелым и, возможно, займет несколько сотен миллисекунд, поскольку для него может потребоваться сброс и перенастройка датчика изображения и конвейера обработки камеры. Тем не менее, устройству HAL следует попытаться свести к минимуму задержку реконфигурации, чтобы свести к минимуму видимые пользователю паузы во время изменений режима работы приложения (например, переключения с режима захвата неподвижных изображений на запись видео).
HAL должен вернуться из этого вызова через 500 мс и должен вернуться из этого вызова через 1000 мс.
Возвращаемые значения:
0: при успешной настройке потока.
-EINVAL: Если запрошенная конфигурация потока недействительна. Некоторые примеры недопустимых конфигураций потока включают в себя:
- Включая более 1 потока с возможностью ввода (INPUT или BIDIRECTIONAL)
- Не включая потоки с возможностью вывода (OUTPUT или BIDIRECTIONAL).
- Включая потоки неподдерживаемых форматов или неподдерживаемого размера для этого формата.
- Включая слишком много выходных потоков определенного формата.
- Неподдерживаемая конфигурация ротации (применяется только к устройствам с версией >= CAMERA_DEVICE_API_VERSION_3_3)
- Размеры/форматы потока не удовлетворяют требованиям camera3_stream_configuration_t->operation_mode для режима, отличного от NORMAL, или запрошенный Operation_mode не поддерживается HAL. (применяется только к устройствам с версией >= CAMERA_DEVICE_API_VERSION_3_3)
Обратите внимание, что платформа, отправляющая недопустимую конфигурацию потока, не является нормальной работой, поскольку конфигурации потока проверяются перед настройкой. Недопустимая конфигурация означает, что в коде платформы существует ошибка или существует несоответствие статических метаданных HAL требованиям к потокам.
-ENODEV: Если произошла фатальная ошибка и устройство больше не работает. После возврата этой ошибки платформа может успешно вызвать только функцию close().
| const camera_metadata_t *(*struct_default_request_settings)(const struct camera3_device *, тип int) |
build_default_request_settings:
Создайте настройки захвата для стандартных случаев использования камеры.
Устройство должно вернуть буфер настроек, настроенный в соответствии с запрошенным вариантом использования, который должен быть одним из перечислений CAMERA3_TEMPLATE_*. Все поля управления запросами должны быть включены.
HAL сохраняет право собственности на эту структуру, но указатель на структуру должен быть действительным до тех пор, пока устройство не будет закрыто. Платформа и HAL не могут изменять буфер, как только он будет возвращен этим вызовом. Тот же буфер может быть возвращен для последующих вызовов того же шаблона или других шаблонов.
Требования к производительности:
Это должен быть неблокирующий вызов. HAL должен вернуться из этого вызова через 1 мс и должен вернуться из этого вызова через 5 мс.
Возвращаемые значения:
Действительные метаданные: при успешном создании буфера настроек по умолчанию.
NULL: В случае фатальной ошибки. После этого фреймворк может успешно вызвать только метод close().
| void(* dump)(const struct camera3_device *, int fd) |
свалка:
Распечатайте состояние отладки устройства камеры. Это будет вызвано платформой, когда служба камеры запрашивает дамп отладки, что происходит при использовании инструмента dumpsys или при записи отчета об ошибке.
Переданный файловый дескриптор можно использовать для записи отладочного текста с помощью dprintf() или write(). Текст должен быть только в кодировке ASCII.
Требования к производительности:
Это должен быть неблокирующий вызов. HAL должен вернуться из этого вызова через 1 мс, должен вернуться из этого вызова через 10 мс. Этот вызов должен избегать взаимоблокировок, поскольку его можно вызвать в любой момент во время работы камеры. Любые используемые примитивы синхронизации (например, блокировки мьютексов или семафоры) должны быть получены с таймаутом.
| int(* флеш)(const struct camera3_device *) |
румянец:
Очистить все текущие захваты и все буферы в конвейере на данном устройстве. Платформа будет использовать это для максимально быстрого сброса всего состояния, чтобы подготовиться к вызову configure_streams() .
Для успешного возврата не требуется никаких буферов, поэтому каждый буфер, удерживаемый во время сброса() (независимо от того, успешно он заполнен или нет), может быть возвращен с CAMERA3_BUFFER_STATUS_ERROR. Обратите внимание, что HAL по-прежнему может возвращать допустимые буферы (CAMERA3_BUFFER_STATUS_OK) во время этого вызова, при условии, что они успешно заполнены.
Ожидается, что все запросы, находящиеся в настоящее время в HAL, будут возвращены как можно скорее. Запросы, не находящиеся в процессе, должны немедленно возвращать ошибки. Любые прерываемые аппаратные блоки должны быть остановлены, а выполнение любых непрерываемых блоков должно быть приостановлено.
lush() может быть вызван одновременно с Process_capture_request() с ожиданием, что процесс_capture_request быстро вернется, и запрос, отправленный в этом вызове Process_capture_request, будет обрабатываться как все другие текущие запросы. Из-за проблем с параллелизмом возможно, что с точки зрения HAL вызовprocess_capture_request() может быть запущен после того, как метод Flush был вызван, но еще не вернулся. Если такой вызов происходит до возврата функцииlush() , HAL должен обрабатывать новый запрос захвата так же, как и другие ожидающие запросы (см. № 4 ниже).
Более конкретно, HAL должен следовать приведенным ниже требованиям для различных случаев:
- Для захватов, которые слишком поздно отменить/остановить HAL и которые будут завершены HAL в обычном режиме; т.е. HAL может отправлять Shutter/notify, Process_capture_result и буферы как обычно.
- Для ожидающих запросов, которые не выполнили никакой обработки, HAL должен вызвать notify CAMERA3_MSG_ERROR_REQUEST и вернуть все выходные буферы с Process_capture_result в состоянии ошибки (CAMERA3_BUFFER_STATUS_ERROR). HAL не должен переводить ограждение выпуска в состояние ошибки, вместо этого ограждения выпуска должны быть установлены на ограждения получения, переданные платформой, или -1, если они уже ожидаются HAL. Это также путь, по которому следует следовать для любых захватов, для которых HAL уже вызвал notify() с CAMERA3_MSG_SHUTTER, но не будет создавать никаких метаданных/действительных буферов. После CAMERA3_MSG_ERROR_REQUEST для данного кадра разрешены только Process_capture_results с буферами в CAMERA3_BUFFER_STATUS_ERROR. Никакие дальнейшие уведомления илиprocess_capture_result с ненулевыми метаданными не допускаются.
Для частично завершенных ожидающих запросов, которые не будут иметь все выходные буферы или, возможно, отсутствующие метаданные, HAL должен следовать ниже:
3.1. Вызовите уведомление с помощью CAMERA3_MSG_ERROR_RESULT, если некоторые из метаданных ожидаемого результата (т. е. одни или несколько частичных метаданных) не будут доступны для захвата.
3.2. Вызовите уведомление с помощью CAMERA3_MSG_ERROR_BUFFER для каждого буфера, который не будет создан для захвата.
3.3 Вызовите уведомление с помощью CAMERA3_MSG_SHUTTER с отметкой времени захвата, прежде чем какие-либо буферы/метаданные будут возвращены с помощьюprocess_capture_result.
3.4 Для захватов, которые дадут какие-то результаты, HAL не должен вызывать CAMERA3_MSG_ERROR_REQUEST, поскольку это указывает на полный сбой.
3.5. Действительные буферы/метаданные должны передаваться в платформу как обычно.
3.6. Неисправные буферы должны быть возвращены в структуру, как описано для случая 2. Но неисправные буферы не обязательно должны следовать строгому порядку, как допустимые буферы, и могут быть не в порядке по отношению к действительным буферам. Например, если буферы A, B, C, D, E отправлены, а D и E завершились сбоем, то A, E, B, D, C является приемлемым порядком возврата.
3.7. Для полностью отсутствующих метаданных достаточно вызова CAMERA3_MSG_ERROR_RESULT, нет необходимости вызыватьprocess_capture_result с метаданными NULL или эквивалентом.
- Если методlush() вызывается, когда активен вызовprocess_capture_request() , этот вызов процесса должен вернуться как можно скорее. Кроме того, если вызов Process_capture_request() выполняется после того, как была вызвана функцияlush() , но до того, как методфлеш() возвратился, запрос на захват, предоставленный поздним вызовом процесса_capture_request, должен рассматриваться как ожидающий запрос в случае №2 выше.
flash() должен возвращаться только тогда, когда в HAL больше не осталось невыполненных буферов или запросов. Платформа может вызывать configure_streams (поскольку состояние HAL теперь приостановлено) или может выдавать новые запросы.
Обратите внимание, что достаточно поддерживать только полностью успешные и полностью неудачные результаты. Однако крайне желательно поддерживать также случаи частичного сбоя, так как это может помочь улучшить общую производительность вызова сброса.
Требования к производительности:
HAL должен вернуться из этого вызова через 100 мс и должен вернуться из этого вызова через 1000 мс. И этот вызов не должен блокироваться дольше, чем задержка конвейера (определение см. в S7).
Информация о версии:
доступно только в том случае, если версия устройства >= CAMERA_DEVICE_API_VERSION_3_1.
Возвращаемые значения:
0: При успешной очистке HAL камеры.
-EINVAL: Если ввод неверен (устройство недействительно).
-ENODEV: Если в устройстве камеры возникла серьезная ошибка. После возврата этой ошибки платформа может успешно вызвать только метод close().
| void(* get_metadata_vendor_tag_ops)(const struct camera3_device *,vendor_tag_query_ops_t *ops) |
get_metadata_vendor_tag_ops:
Получите методы для запроса информации тега метаданных расширения поставщика. HAL должен заполнить все методы работы с тегами поставщиков или оставить операции без изменений, если теги поставщиков не определены.
Определениеvendor_tag_query_ops_t можно найти в system/media/camera/include/system/camera_metadata.h.
>= CAMERA_DEVICE_API_VERSION_3_2: УСТАРЕЛО. Эта функция устарела и HAL должен установить значение NULL. Вместо этого реализуйте get_vendor_tag_ops в camera_common.h .
| int(* инициализировать)(const struct camera3_device *, const camera3_callback_ops_t *callback_ops) |
инициализировать:
Одноразовая инициализация для передачи указателей функций обратного вызова платформы в HAL. Будет вызываться один раз после успешного вызова open(), до вызова любых других функций в структуре camera3_device_ops .
Требования к производительности:
Это должен быть неблокирующий вызов. HAL должен вернуться из этого вызова через 5 мс и должен вернуться из этого вызова через 10 мс.
Возвращаемые значения:
0: При успешной инициализации
-ENODEV: Если инициализация не удалась. После этого фреймворк может успешно вызвать только close().
| int(*process_capture_request)(const struct camera3_device *, camera3_capture_request_t *request) |
процесс_capture_request:
Отправьте новый запрос на захват в HAL. HAL не должен возвращаться из этого вызова до тех пор, пока он не будет готов принять следующий запрос для обработки. Платформа будет одновременно выполнять только один вызов Process_capture_request() , и все вызовы будут из одного потока. Следующий вызов Process_capture_request() будет выполнен, как только станет доступен новый запрос и связанные с ним буферы. В обычном сценарии предварительного просмотра это означает, что функция будет снова вызвана платформой почти мгновенно.
Фактическая обработка запроса является асинхронной, при этом результаты захвата возвращаются HAL через вызовprocess_capture_result(). Для этого вызова требуется, чтобы метаданные результата были доступны, но выходные буферы могут просто обеспечивать ограничения синхронизации для ожидания. Ожидается, что несколько запросов будут выполняться одновременно, чтобы поддерживать полную частоту кадров на выходе.
Платформа сохраняет право собственности на структуру запроса. Гарантируется, что он будет действителен только во время этого вызова. Устройство HAL должно делать копии информации, которую ему необходимо сохранить для обработки захвата. HAL отвечает за ожидание и закрытие границ буферов, а также за возврат дескрипторов буферов в платформу.
HAL должен записать дескриптор файла для ограничения синхронизации освобождения входного буфера в input_buffer->release_fence, если input_buffer не равен NULL. Если HAL возвращает -1 для ограничения синхронизации освобождения входного буфера, платформа может немедленно повторно использовать входной буфер. В противном случае платформа будет ожидать синхронизации перед повторным заполнением и повторным использованием входного буфера.
>= CAMERA_DEVICE_API_VERSION_3_2:
Буферы ввода/вывода, предоставляемые платформой в каждом запросе, могут быть совершенно новыми (никогда ранее не встречавшимися в HAL).
Соображения производительности:
Обработка нового буфера должна быть чрезвычайно легкой, и не должно быть никакого снижения частоты кадров или дрожания кадров.
Этот вызов должен возвращаться достаточно быстро, чтобы обеспечить поддержание запрошенной частоты кадров, особенно для случаев потоковой передачи (настройки качества постобработки установлены на FAST). HAL должен вернуть этот вызов через интервал 1 кадра и должен вернуться из этого вызова через интервал 4 кадра.
Возвращаемые значения:
0: При успешном начале обработки запроса на захват.
-EINVAL: если входные данные имеют неправильный формат (настройки равны NULL, если они не разрешены, имеется 0 выходных буферов и т. д.), и обработка захвата не может начаться. Сбои во время обработки запроса следует обрабатывать путем вызова camera3_callback_ops_t.notify() . В случае этой ошибки платформа сохранит ответственность за ограждения буферов потока и дескрипторы буферов; HAL не должен закрывать ограничения или возвращать эти буферы с помощьюprocess_capture_result.
-ENODEV: Если в устройстве камеры возникла серьезная ошибка. После возврата этой ошибки платформа может успешно вызвать только метод close().
| int(* Register_stream_buffers)(const struct camera3_device *, const camera3_stream_buffer_set_t *buffer_set) |
Register_stream_buffers:
>= CAMERA_DEVICE_API_VERSION_3_2:
УСТАРЕЛО. Это не будет вызываться и должно быть установлено в NULL.
<= CAMERA_DEVICE_API_VERSION_3_1:
Зарегистрируйте буферы для данного потока с помощью устройства HAL. Этот метод вызывается платформой после того, как новый поток определен с помощью configure_streams и до того, как буферы из этого потока будут включены в запрос захвата. Если тот же поток указан в последующем вызове configure_streams() , Register_stream_buffers не будет вызываться снова для этого потока.
Платформе не требуется регистрировать буферы для всех настроенных потоков перед отправкой первого запроса на захват. Это позволяет быстро запустить предварительный просмотр (или аналогичные варианты использования), пока другие потоки еще распределяются.
Этот метод предназначен для того, чтобы позволить устройству HAL отображать или иным образом готовить буферы для последующего использования. Переданные буферы уже будут заблокированы для использования. В конце вызова все буферы должны быть готовы к возврату в поток. Аргумент buffer_set действителен только на время этого вызова.
Если формат потока был установлен на HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, HAL камеры должен проверить переданные здесь буферы, чтобы определить любую информацию о формате пикселей, частную для платформы.
Требования к производительности:
Это должен быть неблокирующий вызов. HAL должен вернуться из этого вызова через 1 мс и должен вернуться из этого вызова через 5 мс.
Возвращаемые значения:
0: при успешной регистрации новых буферов потока.
-EINVAL: Если поток_буфер_сет не ссылается на действительный активный поток или если массив буферов недействителен.
-ENOMEM: Если произошла ошибка при регистрации буферов. Платформа должна считать все буферы потоков незарегистрированными и может попытаться зарегистрировать их снова позже.
-ENODEV: Если произошла фатальная ошибка и устройство больше не работает. После возврата этой ошибки платформа может успешно вызвать только функцию close().
Документация для этой структуры была создана из следующего файла:
- Аппаратное обеспечение/libhardware/include/hardware/ camera3.h