camera3_device_ops结构参考

camera3_device_ops结构参考

#include < camera3.h >

数据字段

整数(*初始化)(const structcamera3_device *, constcamera3_callback_ops_t *callback_ops)
整数(*配置_流)(常量结构camera3_device *, camera3_stream_configuration_t *stream_list)
整数(* register_stream_buffers )(const structcamera3_device *, constcamera3_stream_buffer_set_t *buffer_set)
常量camera_metadata_t *(* Construction_default_request_settings )(const structcamera3_device *,int类型)
整数(* process_capture_request )(常量结构camera3_device *, camera3_capture_request_t *请求)
空白(* get_metadata_vendor_tag_ops )(const structcamera3_device *,vendor_tag_query_ops_t *ops)
空白(*转储)(常量结构camera3_device *,int fd)
整数(*冲洗)(常量结构camera3_device *)
空白 *保留[8]

详细说明

文件camera3.h2509行的定义。

现场文档

int(*configure_streams)( conststructcamera3_device *, camera3_stream_configuration_t *stream_list)

配置流:

仅限 CAMERA_DEVICE_API_VERSION_3_0:

重置 HAL 相机设备处理管道并设置新的输入和输出流。此调用将任何现有的流配置替换为在stream_list 中定义的流。在使用process_capture_request()提交请求之前,在initialize()之后至少会调用此方法一次。

Stream_list 必须包含至少一个可输出的流,并且不能包含多于一个可输入的流。

Stream_list 可能包含当前活动的流集中的流(来自之前对configure_stream() 的调用)。这些流已经具有有效的使用值、max_buffers 和私有指针。

如果这样的流已经注册了其缓冲区,则不会再次为该流调用register_stream_buffers() ,并且流中的缓冲区可以立即包含在输入请求中。

如果 HAL 由于新配置而需要更改现有流的流配置,则它可能会在配置调用期间重写 use 和/或 max_buffers 的值。

框架将检测到此类更改,然后重新分配流缓冲区,并在请求中使用该流中的缓冲区之前再次调用register_stream_buffers()

如果当前活动的流未包含在stream_list中,则HAL可以安全地删除对该流的任何引用。框架不会在以后的 configure() 调用中重用它,并且在configure_streams()调用返回后,它的所有 gralloc 缓冲区都将被释放。

Stream_list 结构由框架拥有,一旦此调用完成,就可能无法访问。单个camera3_stream_t结构的地址将保持有效以供HAL访问,直到第一个configure_stream()调用结束,该调用不再在stream_list参数中包含该camera3_stream_t。 HAL 不能更改私有指针之外的流结构中的值,除了在configure_streams()调用本身期间的usage 和max_buffers 成员。

如果流是新的,则流结构的usage、max_buffer和私有指针字段将全部设置为0。HAL设备必须在configure_streams()调用返回之前设置这些字段。然后,框架和平台 gralloc 模块使用这些字段为每个流分配 gralloc 缓冲区。

在这样的新流可以将其缓冲区包含在捕获请求中之前,框架将对该流调用register_stream_buffers() 。但是,框架不需要在提交请求之前为所有流注册缓冲区。这允许快速启动(例如)预览流,并稍后或同时分配其他流。


仅限 CAMERA_DEVICE_API_VERSION_3_1:

重置 HAL 相机设备处理管道并设置新的输入和输出流。此调用将任何现有的流配置替换为在stream_list 中定义的流。在使用process_capture_request()提交请求之前,在initialize()之后至少会调用此方法一次。

Stream_list 必须包含至少一个可输出的流,并且不能包含多于一个可输入的流。

Stream_list 可能包含当前活动的流集中的流(来自之前对configure_stream() 的调用)。这些流已经具有有效的使用值、max_buffers 和私有指针。

如果这样的流已经注册了其缓冲区,则不会再次为该流调用register_stream_buffers() ,并且流中的缓冲区可以立即包含在输入请求中。

如果 HAL 由于新配置而需要更改现有流的流配置,则它可能会在配置调用期间重写 use 和/或 max_buffers 的值。

框架将检测到此类更改,然后重新分配流缓冲区,并在请求中使用该流中的缓冲区之前再次调用register_stream_buffers()

如果当前活动的流未包含在stream_list中,则HAL可以安全地删除对该流的任何引用。框架不会在以后的 configure() 调用中重用它,并且在configure_streams()调用返回后,它的所有 gralloc 缓冲区都将被释放。

Stream_list 结构由框架拥有,一旦此调用完成,就可能无法访问。单个camera3_stream_t结构的地址将保持有效以供HAL访问,直到第一个configure_stream()调用结束,该调用不再在stream_list参数中包含该camera3_stream_t。 HAL 不能更改私有指针之外的流结构中的值,除了在configure_streams()调用本身期间的usage 和max_buffers 成员。

如果流是新的,则流结构的 max_buffer 和私有指针字段将全部设置为 0。使用情况将设置为消费者使用标志。 HAL 设备必须在configure_streams()调用返回之前设置这些字段。然后,框架和平台 gralloc 模块使用这些字段为每个流分配 gralloc 缓冲区。

在这样的新流可以将其缓冲区包含在捕获请求中之前,框架将对该流调用register_stream_buffers() 。但是,框架不需要在提交请求之前为所有流注册缓冲区。这允许快速启动(例如)预览流,并稍后或同时分配其他流。


>= CAMERA_DEVICE_API_VERSION_3_2:

重置 HAL 相机设备处理管道并设置新的输入和输出流。此调用将任何现有的流配置替换为在stream_list 中定义的流。在使用process_capture_request()提交请求之前,在initialize()之后至少会调用此方法一次。

Stream_list 必须包含至少一个可输出的流,并且不能包含多于一个可输入的流。

Stream_list 可能包含当前活动的流集中的流(来自之前对configure_stream() 的调用)。这些流已经具有有效的使用值、max_buffers 和私有指针。

如果 HAL 由于新配置而需要更改现有流的流配置,则它可能会在配置调用期间重写 use 和/或 max_buffers 的值。

框架将检测此类更改,然后可能会在请求中使用该流中的缓冲区之前重新分配流缓冲区。

如果当前活动的流未包含在stream_list中,则HAL可以安全地删除对该流的任何引用。框架不会在以后的 configure() 调用中重用它,并且在configure_streams()调用返回后,它的所有 gralloc 缓冲区都将被释放。

Stream_list 结构由框架拥有,一旦此调用完成,就可能无法访问。单个camera3_stream_t结构的地址将保持有效以供HAL访问,直到第一个configure_stream()调用结束,该调用不再在stream_list参数中包含该camera3_stream_t。 HAL 不能更改私有指针之外的流结构中的值,除了在configure_streams()调用本身期间的usage 和max_buffers 成员。

如果流是新的,则流结构的 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)
  • 不包括任何可输出的流(输出或双向)
  • 包括格式不受支持的流,或者该格式的大小不受支持。
  • 包括太多某种格式的输出流。
  • 不支持的旋转配置(仅适用于版本 >= CAMERA_DEVICE_API_VERSION_3_3 的设备)
  • 流大小/格式不满足非正常模式的camera3_stream_configuration_t->操作模式要求,或者HAL不支持请求的操作模式。 (仅适用于版本 >= CAMERA_DEVICE_API_VERSION_3_3 的设备)

请注意,提交无效流配置的框架不是正常操作,因为在配置之前会检查流配置。无效的配置意味着框架代码中存在错误,或者HAL的静态元数据与流的要求不匹配。

-ENODEV:如果出现致命错误并且设备无法再运行。返回此错误后,框架只能成功调用 close()。

文件camera3.h2769行的定义。

constcamera_metadata_t *(*construct_default_request_settings)(const structcamera3_device *, int 类型)

构造默认请求设置:

为标准相机用例创建捕捉设置。

设备必须返回一个配置为满足所请求用例的设置缓冲区,该缓冲区必须是 CAMERA3_TEMPLATE_* 枚举之一。必须包含所有请求控制字段。

HAL 保留该结构的所有权,但指向该结构的指针必须在设备关闭之前有效。一旦此调用返回缓冲区,框架和 HAL 就不能修改缓冲区。可以为同一模板或其他模板的后续调用返回相同的缓冲区。

性能要求:

这应该是一个非阻塞调用。 HAL 应在 1 毫秒内从此调用返回,并且必须在 5 毫秒内从此调用返回。

返回值:

有效元数据:成功创建默认设置缓冲区时。

NULL:如果发生致命错误。返回后,框架才能成功调用close()方法。

文件camera3.h2859行的定义。

void(* dump)(const structcamera3_device *, int fd)

倾倒:

打印相机设备的调试状态。当相机服务被要求进行调试转储时(使用 dumpsys 工具或捕获错误报告时会发生这种情况),框架将调用此函数。

传入的文件描述符可用于使用 dprintf() 或 write() 写入调试文本。文本应仅采用 ASCII 编码。

性能要求:

这必须是非阻塞调用。 HAL 应在 1 毫秒内从此调用返回,必须在 10 毫秒内从此调用返回。此调用必须避免死锁,因为它可能在相机操作期间的任何时刻被调用。使用的任何同步原语(例如互斥锁或信号量)都应该在超时时获取。

文件camera3.h2971行的定义。

int(* 刷新)(const structcamera3_device *)

冲洗:

刷新给定设备上所有当前正在处理的捕获以及管道中的所有缓冲区。框架将使用它尽快转储所有状态,以便为configure_streams()调用做好准备。

不需要成功返回缓冲区,因此在flush()时保存的每个缓冲区(无论是否成功填充)都可能会返回CAMERA3_BUFFER_STATUS_ERROR。请注意,在此调用期间,HAL 仍然允许返回有效的 (CAMERA3_BUFFER_STATUS_OK) 缓冲区,前提是它们已成功填充。

当前 HAL 中的所有请求预计都会尽快返回。未处理的请求应立即返回错误。应停止任何可中断的硬件块,并应等待任何不可中断的块。

lush()可以与process_capture_request()同时调用,期望 process_capture_request 将快速返回,并且在 process_capture_request 调用中提交的请求将像所有其他正在进行的请求一样对待。由于并发问题,从 HAL 的角度来看, process_capture_request()调用可能会在调用 flash 后启动但尚未返回。如果这样的调用发生在flush()返回之前,HAL应该像其他正在进行的待处理请求一样对待新的捕获请求(参见下面的#4)。

更具体地说,HAL 必须针对各种情况遵循以下要求:

  1. 对于 HAL 来不及取消/停止的捕获,将由 HAL 正常完成;即 HAL 可以正常发送快门/通知和 process_capture_result 和缓冲区。
  2. 对于尚未完成任何处理的待处理请求,HAL 必须调用通知 CAMERA3_MSG_ERROR_REQUEST,并返回所有 process_capture_result 处于错误状态 (CAMERA3_BUFFER_STATUS_ERROR) 的输出缓冲区。 HAL 不得将释放栅栏置于错误状态,相反,释放栅栏必须设置为框架传递的获取栅栏,如果 HAL 已等待它们,则设置为 -1。对于 HAL 已使用 CAMERA3_MSG_SHUTTER 调用 notification() 但不会生成任何元数据/有效缓冲区的任何捕获,这也是要遵循的路径。在 CAMERA3_MSG_ERROR_REQUEST 之后,对于给定帧,仅允许使用 CAMERA3_BUFFER_STATUS_ERROR 中的缓冲区的 process_capture_results。不允许进一步使用非空元数据进行通知或 process_capture_result。
  3. 对于部分完成的待处理请求,这些请求不会具有所有输出缓冲区或可能缺少元数据,HAL 应遵循以下步骤:

    3.1.如果某些预期结果元数据(即一个或多个部分元数据)不可用于捕获,请使用 CAMERA3_MSG_ERROR_RESULT 调用通知。

    3.2.对于不会为捕获生成的每个缓冲区,使用 CAMERA3_MSG_ERROR_BUFFER 调用通知。

    3.3 在使用 process_capture_result 返回任何缓冲区/元数据之前,使用 CAMERA3_MSG_SHUTTER 调用带有捕获时间戳的通知。

    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 就足够了,无需使用 NULL 元数据或等效函数调用 process_capture_result。

  4. 如果在process_capture_request( ) 调用处于活动状态时调用了 flash() ,则该进程调用应尽快返回。此外,如果在调用flush()之后但在flush()返回之前进行process_capture_request ()调用,那么后期process_capture_request调用提供的捕获请求应被视为上述情况#2中的待处理请求。

仅当 HAL 中不再有未完成的缓冲区或请求时, flush()才应返回。框架可能会调用configure_streams(因为HAL状态现在已停止)或者可能会发出新的请求。

请注意,仅支持完全成功和完全失败的结果情况就足够了。然而,非常希望也支持部分失败情况,因为它可以帮助提高刷新调用的整体性能。

性能要求:

HAL 应在 100 毫秒内从此调用返回,并且必须在 1000 毫秒内从此调用返回。并且此调用的阻塞时间不得超过管道延迟(请参阅 S7 的定义)。

版本信息:

仅当设备版本 >= CAMERA_DEVICE_API_VERSION_3_1 时可用。

返回值:

0:成功刷新相机 HAL。

-EINVAL:如果输入格式错误(设备无效)。

-ENODEV:如果相机设备遇到严重错误。返回此错误后,框架只能成功调用close()方法。

定义在文件camera3.h的第3077行。

void(* get_metadata_vendor_tag_ops)(const structcamera3_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。请改为在camera_common.h中实现get_vendor_tag_ops。

文件camera3.h2950行的定义。

int(* 初始化)(const structcamera3_device *, constcamera3_callback_ops_t *callback_ops)

初始化:

一次性初始化,将框架回调函数指针传递给 HAL。将在成功调用 open() 后、在camera3_device_ops结构上调用任何其他函数之前调用一次。

性能要求:

这应该是一个非阻塞调用。 HAL 应在 5 毫秒内从此调用返回,并且必须在 10 毫秒内从此调用返回。

返回值:

0:初始化成功时

-ENODEV:如果初始化失败。此后框架只能成功调用 close()。

定义位于文件camera3.h的第2530行。

int(* process_capture_request)(const structcamera3_device *, camera3_capture_request_t *请求)

处理_捕获_请求:

向 HAL 发送新的捕获请求。在准备好接受下一个要处理的请求之前,HAL 不应从此调用返回。框架一次只会调用一次process_capture_request() ,并且所有调用都来自同一线程。一旦新请求及其关联的缓冲区可用,就会立即调用process_capture_request() 。在正常的预览场景中,这意味着框架几乎会立即再次调用该函数。

实际的请求处理是异步的,捕获结果由 HAL 通过 process_capture_result() 调用返回。此调用要求结果元数据可用,但输出缓冲区可能只是提供同步栅栏来等待。多个请求预计会同时进行,以保持完整的输出帧速率。

框架保留请求结构的所有权。仅保证在本次调用期间有效。 HAL 设备必须复制捕获处理所需保留的信息。 HAL 负责等待和关闭缓冲区的栅栏,并将缓冲区句柄返回给框架。

如果 input_buffer 不为 NULL,HAL 必须将输入缓冲区的释放同步栅栏的文件描述符写入 input_buffer->release_fence。如果 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()方法。

文件camera3.h2928行的定义。

int(* register_stream_buffers)(const structcamera3_device *, constcamera3_stream_buffer_set_t *buffer_set)

注册流缓冲区:

>= 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_IMPLMENTATION_DEFINED,则相机 HAL 应检查此处传入的缓冲区以确定任何平台私有的像素格式信息。

性能要求:

这应该是一个非阻塞调用。 HAL 应在 1 毫秒内从此调用返回,并且必须在 5 毫秒内从此调用返回。

返回值:

0:成功注册新流缓冲区

-EINVAL:如果stream_buffer_set未引用有效的活动流,或者缓冲区数组无效。

-ENOMEM:如果注册缓冲区失败。框架必须考虑所有流缓冲区都已取消注册,并且可以稍后尝试再次注册。

-ENODEV:如果出现致命错误,并且设备无法再运行。返回此错误后,框架只能成功调用 close()。

文件camera3.h2823行的定义。

无效* 保留[8]

定义在文件camera3.h的第3080行。


该结构的文档是从以下文件生成的:
  • 硬件/libhardware/include/hardware/camera3.h