camera3_device_ops结构参考

配置流：

仅限 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.h第2769行的定义。

构造默认请求设置：

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

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

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

性能要求：

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

返回值：

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

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

文件camera3.h第2859行的定义。

倾倒：

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

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

性能要求：

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

文件camera3.h第2971行的定义。

冲洗：

刷新给定设备上所有当前正在处理的捕获以及管道中的所有缓冲区。框架将使用它尽快转储所有状态，以便为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行。

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.h第2950行的定义。

初始化：

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

性能要求：

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

返回值：

0：初始化成功时

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

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

处理_捕获_请求：

向 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.h第2928行的定义。

注册流缓冲区：

>= 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.h第2823行的定义。

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