camera3_device_ops 结构体参考文档

configure_streams：

仅限 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 因新配置而需要更改现有数据流的流配置，则可能会在配置调用期间重写 usage 和/或 max_buffers 的值。

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

如果 stream_list 中未包含当前活跃的串流，HAL 可以安全地移除对该串流的所有引用。框架不会在后续的 configure() 调用中重复使用它，并且在 configure_streams() 调用返回后，系统会释放其所有 gralloc 缓冲区。

stream_list 结构归框架所有，此调用完成后可能无法访问。在第一个 configure_stream() 调用结束（stream_list 参数中不再包含该 camera3_stream_t）之前，单个 camera3_stream_t 结构的地址将保持有效，可供 HAL 访问。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 因新配置而需要更改现有数据流的流配置，则可能会在配置调用期间重写 usage 和/或 max_buffers 的值。

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

如果 stream_list 中未包含当前活跃的串流，HAL 可以安全地移除对该串流的所有引用。框架不会在后续的 configure() 调用中重复使用它，并且在 configure_streams() 调用返回后，系统会释放其所有 gralloc 缓冲区。

stream_list 结构归框架所有，此调用完成后可能无法访问。在第一个 configure_stream() 调用结束（stream_list 参数中不再包含该 camera3_stream_t）之前，单个 camera3_stream_t 结构的地址将保持有效，可供 HAL 访问。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 因新配置而需要更改现有数据流的流配置，则可能会在配置调用期间重写 usage 和/或 max_buffers 的值。

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

如果 stream_list 中未包含当前活跃的串流，HAL 可以安全地移除对该串流的所有引用。框架不会在后续的 configure() 调用中重复使用它，并且在 configure_streams() 调用返回后，系统会释放其所有 gralloc 缓冲区。

stream_list 结构归框架所有，此调用完成后可能无法访问。在第一个 configure_stream() 调用结束（stream_list 参数中不再包含该 camera3_stream_t）之前，单个 camera3_stream_t 结构的地址将保持有效，可供 HAL 访问。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：如果请求的信息流配置无效，则返回此值。无效数据流配置的一些示例包括：

• 包含多个可接收输入的串流（INPUT 或 BIDIRECTIONAL）
• 不包含任何可输出的串流（OUTPUT 或 BIDIRECTIONAL）
• 包含格式不受支持或格式大小不受支持的串流。
• 包含特定格式的输出流过多。
• 不受支持的旋转配置（仅适用于版本高于或等于 CAMERA_DEVICE_API_VERSION_3_3 的设备）
• 流大小/格式不满足非 NORMAL 模式的 camera3_stream_configuration_t->operation_mode 要求，或者 HAL 不支持请求的 operation_mode。（仅适用于版本高于 CAMERA_DEVICE_API_VERSION_3_3 的设备）

请注意，由于系统会在配置之前检查串流配置，因此框架提交无效的串流配置并非正常操作。配置无效表示框架代码中存在 bug，或者 HAL 的静态元数据与对数据流的要求不一致。

-ENODEV：如果发生了严重错误，并且设备无法再正常运行。返回此错误后，框架只能成功调用 close()。

定义位于文件 camera3.h 的 2769 行中。

construct_default_request_settings：

为标准相机用例创建拍摄设置。

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

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

性能要求：

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

返回值：

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

NULL：在发生致命错误时返回。返回此值后，框架只能成功调用 close() 方法。

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

dump：

打印出相机设备的调试状态。当相机服务被要求生成调试转储时，框架会调用此方法。这种情况会在使用 dumpsys 工具或捕获 bugreport 时发生。

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

性能要求：

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

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

flush：

在给定设备上刷新流水线中当前正在处理的所有截图和所有缓冲区。该框架将使用此方法尽快转储所有状态，以便为 configure_streams() 调用做好准备。

无需成功返回任何缓冲区，因此在 flush() 调用时持有的每个缓冲区（无论是否已成功填充）都可能会返回 CAMERA3_BUFFER_STATUS_ERROR。请注意，在此调用期间，HAL 仍可以返回有效的缓冲区（CAMERA3_BUFFER_STATUS_OK），前提是这些缓冲区已成功填充。

HAL 中目前的所有请求都有望尽快返回。未在处理的请求应立即返回错误。应停止所有可中断的硬件块，并等待所有不可中断的块。

flush() 可以与 process_capture_request() 并发调用，预计 process_capture_request 会快速返回，并且在该 process_capture_request 调用中提交的请求会像所有其他正在处理的请求一样处理。由于并发问题，从 HAL 的角度来看，在调用刷新但尚未返回后，系统可能会启动 process_capture_request() 调用。如果此类调用发生在 flush() 返回之前，HAL 应将新拍摄请求视为其他正在处理的待处理请求（请参阅下文中的 4）。

具体而言，对于各种情况，HAL 必须遵循以下要求：

1. 对于 HAL 无法取消/停止且将由 HAL 正常完成的拍摄；即 HAL 可以照常发送快门/通知以及 process_capture_result 和缓冲区。
2. 对于尚未执行任何处理的待处理请求，HAL 必须调用 notify CAMERA3_MSG_ERROR_REQUEST，并返回所有输出缓冲区，其中 process_capture_result 处于错误状态 (CAMERA3_BUFFER_STATUS_ERROR)。HAL 不得将释放栅栏置于错误状态，而必须将释放栅栏设置为框架传递的获取栅栏，如果 HAL 已等待这些栅栏，则设置为 -1。对于 HAL 已使用 CAMERA3_MSG_SHUTTER 调用 notify() 但不会生成任何元数据/有效缓冲区的任何拍摄，也应采用此路径。在 CAMERA3_MSG_ERROR_REQUEST 之后，对于给定帧，仅允许使用 CAMERA3_BUFFER_STATUS_ERROR 中的缓冲区进行 process_capture_results。不允许再发送任何 notify 或包含非 null 元数据的 process_capture_result。

3. 对于部分完成的待处理请求（不包含所有输出缓冲区或可能缺少元数据），HAL 应遵循以下说明：

   3.1. 如果某些预期结果元数据（即一个或多个部分元数据）无法用于拍摄，请使用 CAMERA3_MSG_ERROR_RESULT 调用 notify。

   3.2. 对于不会为拍摄生成的每个缓冲区，请调用 CAMERA3_MSG_ERROR_BUFFER 通知。

   3.3 在通过 process_capture_result 返回任何缓冲区/元数据之前，使用 CAMERA3_MSG_SHUTTER 调用 notify，并附带捕获时间戳。

   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() 调用处于活动状态时调用了 flush() ，则该进程调用应尽快返回。此外，如果在调用 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 行。

initialize：

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

性能要求：

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

返回值：

0：在成功初始化后

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

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

process_capture_request：

向 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 从未见过）。

---

性能注意事项：

处理新缓冲区应该非常轻量，并且不应引入帧速率下降或帧抖动。

此调用必须足够快地返回，以确保能够持续请求的帧速率，尤其是在流式传输情形（后处理质量设置设为“快”）下。HAL 应在 1 帧间隔内返回此调用，并且必须在 4 帧间隔内从此调用返回。

返回值：

0：成功开始处理捕获请求

-EINVAL：如果输入格式有误（设置为 NULL 时不允许，输出缓冲区为 0 等），并且无法启动捕获处理。应通过调用 camera3_callback_ops_t.notify() 来处理请求处理期间的失败。如果发生此错误，框架将保留对数据流缓冲区栅栏和缓冲区句柄的责任；HAL 不应关闭栅栏或使用 process_capture_result 返回这些缓冲区。

-ENODEV：在相机设备遇到严重错误时返回。返回此错误后，框架只能成功调用 close() 方法。

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

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：如果 stream_buffer_set 未引用有效的有效串流，或者缓冲区数组无效。

-ENOMEM：如果注册缓冲区时出错，则返回此值。框架必须将所有流缓冲区视为未注册，并稍后尝试重新注册。

-ENODEV：如果出现致命错误且设备不再运行，则返回此值。返回此错误后，框架只能成功调用 close()。

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

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