Android源码第十五章:Camera2 与 CameraService——一帧图像怎样回到应用

按下"请求一帧",capture() 已经返回。你等到 onCaptureCompleted(),却还没有拿到 Image。这一帧究竟算不算到了?

可以把它想成照片和随片的报告:报告写着本帧的参数,照片才是像素。两者需要认出彼此,还要把借来的存储位置归还。这个比喻只帮助分清职责;真实系统靠 frame number、timestamp、buffer 与 fence 协作,并不会把一张照片塞进回调参数里。

这次我们只请求一帧 YUV:从 Camera2 打开设备,经过 CameraService 与 AIDL Camera Session,沿公开的外接 UVC 实现走到 Kernel,再回到应用的两个回调。读者需要认识 Binder、Surface 和基本 Android 开发;ISP 算法可以留到以后。

阅读边界:固定源码基线见下文。设备步骤是待执行教程;本轮完成源码与示例静态检查,没有连接设备、安装 APK、构建系统或测性能。文中的图是机制示意。

日期:2026-10-28,北京时间。本文是固定源码阅读与静态核对资料;实际实验仍为待执行,不把正文完成记成学习深度 L3。

先把对象与四条线分开

CameraManager 用于枚举相机、查询 CameraCharacteristics 并发起打开。CameraDevice 是已打开相机的客户端对象;CameraCaptureSession 描述本轮可使用的一组输出 Surface;CaptureRequest 从模板创建,携带本帧参数以及本帧要写入哪些输出。配置会话相当于先约定输出口的尺寸、格式和用途,请求再从这些口中选择目标。

ImageReader 是应用持有的图像消费者。它创建供生产者使用的 Surface,CameraService 通过这个生产者端取得、写入并排队图像缓冲区。Surface 是图像通路的端点,CaptureRequest 的 Java 对象里并不装整幅照片。

要追踪的东西 本章的具体对象 用途及常见误读
metadata CaptureRequest 参数、CaptureResult/TotalCaptureResult 例如控制模式、SENSOR_TIMESTAMP;不是像素
frame number Camera3Device 为每个采集请求分配的递增编号 关联 HAL request、SHUTTER、result;不是 API 返回的 sequence ID
buffer V4L2 MMAP 采集槽与应用 Surface 的 Gralloc 输出槽 本例是两组内存,中间有解码、裁剪、缩放和格式转换
fence acquireFence、releaseFence 中传递的同步 fd 表示何时可访问 buffer,不是像素地址、相机帧号或拍照回调

同一个 repeating request 会产生许多帧号;本章用一次 capture() 缩小关联范围。一个请求也能有多个输出 buffer、多个 partial metadata 回调,不能推广为"一个回调就装齐所有东西"。本例只有一个 YUV 输出;Image 自身没有 Camera2 frame number,应用用同一相机、同一会话、同一轮请求的 Image.timestamp 与 CaptureResult.SENSOR_TIMESTAMP 关联图像。SENSOR_INFO_TIMESTAMP_SOURCE 决定能否与其他时钟域比较;不要把所有时间戳都当墙钟或随意与 logcat 时间相减。

版本、后端与可证明范围

本地规划 manifest 使用 android17-release,但固定提交才是下面摘录的身份 。相关项目 HEAD 如下;本章相关文件内容已留存摘要,见 校验/源码身份.json。frameworks/av 下存在无关未跟踪 .gradle/;不把工作区整体称为干净,不修改它。

项目 固定提交
frameworks/base 94b4c163b7dfe5ce3607f7bb8456f9573f7de57d
frameworks/av 475269ec44acec82792be6b01fb8e16357d4d2c8
hardware/interfaces 0162af698935100a590b7359581ac8b1b80693e5
hardware/google/camera cd15337bd229dd521a860d88bca3e37c3ca845f7
kernel/common,独立下载的阅读材料 ccafb60de224d35a8bc14de33e1cd47caaaa786b

本章选择 AIDL ExternalCameraProvider + ExternalCameraDeviceSession,普通非共享 session,单路 YUV 输出,UVC/MJPEG 采集分支 。它的公开实现能继续追到 V4L2、videobuf2 与 UVC USB 收包。是否有具体设备支持这些配置,需要运行时能力和绑定信息证明。Kernel 提交取自工程第一章已有 Emulator Kernel 线索,本文已从官方仓库取得所需文件;它是可读 UVC 分支,没有证据证明某台当前相机正在运行这份 UVC 驱动。

工程既有主环境是 SDK Emulator emu64x。其 Camera 可能使用模拟图案、虚拟场景或 Host 摄像头路径。hardware/google/camera/devices/EmulatedCamera/hwl/ConfigUtils.cpp 的 GetCameraConfigurations 周边配置逻辑区分 ro.boot.qemu、ro.boot.qemu.legacy_fake_camera、vendor.qemu.sf.fake_camera;源码里存在 EmulatedSensor,不能证明当前进程加载了它,更不能证明经过物理 Sensor/CSI/ISP。本轮未采 Camera VINTF、进程、AVD 配置与节点,当前运行 Camera 后端保留"待辨认"。

物理手机通常另有 Sensor 的 I2C 控制、CSI 接收、ISP、平台 HAL/固件和厂商接口;UVC 摄像头内可能已完成传感与图像处理,Android 从 USB 收到压缩帧。二者是备选后端,不能把 Sensor→CSI→ISP→V4L2→UVC 全串成每次必经路线。DMA-BUF 是共享内存契约,fence 是同步契约;本例 V4L2 明确选 V4L2_MEMORY_MMAP,不能因为下游 Gralloc 可能使用 DMA-BUF 就宣称采集输入也用 DMA-BUF 导入或端到端零拷贝。

最小跟做:先定义什么才算收到一帧

下面是可自行跟做的设备步骤。本轮只核对文件、API 契约与源码,未执行这些设备操作。准备 Android Studio 的 Java Empty Views Activity 工程,namespace/applicationId 设为 org.example.cameraframe,minSdk 28,compileSdk 使用已安装的现代 SDK(至少 35)。删除模板 Activity 的重复声明,以文末完整 MainActivity 和 Manifest 替换对应文件;不依赖第三方库。MainActivity.java 的磁盘位置是 app/src/main/java/org/example/cameraframe/MainActivity.java,清单位置是 app/src/main/AndroidManifest.xml;直接替换模板中的同名文件。用 IDE 的现有工具链构建,成功产物通常位于 app/build/outputs/apk/debug/app-debug.apk。这里提供两个完整应用文件,接入你已有的 Android 工程工具链即可;文末附录保留全部实现。本章没有附 Gradle wrapper,也没有声称这是可独立命令构建的完整工程。

需要一台能枚举 Camera2 YUV 输出的 Android 设备或 Emulator。若想验证本章 UVC 分支,还需设备镜像确实部署 AIDL external provider、接入支持的 USB 摄像头并允许访问节点;有 USB webcam 并不自动满足 HAL、SELinux 和格式条件。

示例优先选择 LENS_FACING_EXTERNAL 且支持 YUV_420_888 的相机;没有则用第一个支持 YUV 的相机,并在 SELECT 日志中明确身份待核实。选择该相机公开的最小面积 YUV 尺寸,避免写死 640×480。枚举到尺寸不保证任意多流组合成立;本例只配一路。 TEMPLATE_PREVIEW 为本章读一帧 YUV 选择默认参数,不写 JPEG 文件、不保证 3A 收敛或照片观感。

主线程负责本例的打开、会话与采集回调;Image 回调只抽读一个 Y 样本并立即关闭 Image,避免在主线程做编码或大图处理。正式应用通常需独立执行器处理耗时工作,不能照搬本例线程选择作为性能建议。

先看会话配置的核心写法(教学示例,完整错误与收尾见附录):

java 复制代码
reader = ImageReader.newInstance(width, height, ImageFormat.YUV_420_888, 2);
Surface target = reader.getSurface();
SessionConfiguration config = new SessionConfiguration(
        SessionConfiguration.SESSION_REGULAR,
        Collections.singletonList(new OutputConfiguration(target)),
        getMainExecutor(), sessionCallback);
camera.createCaptureSession(config);

reader 必须保持存活,target 必须是配置过的那个 Surface。 onConfigured 后才能创建本帧请求并提交:

java 复制代码
CaptureRequest.Builder b = camera.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW);
b.addTarget(target);
int sequence = session.capture(b.build(), captureCallback, handler);

sequence 是请求序列的标识,真正的 frame number 要从采集回调读取。 观察顺序上,OPENED、CONFIGURED 应在 SUBMITTED 前;RESULT 与 IMAGE 的应用回调不应被要求固定先后。

获授权后,在 Host 终端 A、工程根目录构建并安装后手动打开应用;本次没有执行这些命令:

bash 复制代码
adb devices
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n org.example.cameraframe/.MainActivity

终端 B 在点击按钮前启动观察,保留完整日志而非只抄"成功"一行:

bash 复制代码
adb logcat -v threadtime CameraFrame15:I '*:S'

第一次点"请求一帧"会请求 CAMERA 运行时权限,允许后再点一次。每轮日志带 UUID run 和线程名。下面只是格式示例,不是本轮运行记录:

text 复制代码
run=<同一轮> OPENED
run=<同一轮> CONFIGURED
run=<同一轮> SUBMITTED sequence=<序列号>
run=<同一轮> START frame=<帧号> ts=<纳秒>
run=<同一轮> RESULT frame=<帧号> ts=<纳秒>
run=<同一轮> IMAGE ts=<相同纳秒> planes=3 rowStride=<步长> pixelStride=<步长> y0=<样本>
run=<同一轮> IMAGE_CLOSED
run=<同一轮> PAIR_OK frame=<帧号> resultTs=<纳秒> imageTs=<相同纳秒>
run=<同一轮> DEVICE_CLOSED readerClosed=true

结果与图像以同一 run、相机、会话和时间戳匹配,且无 FAILED/BUFFER_LOST/DEVICE_ERROR,才认定本例收到配对的一帧。还要看到 IMAGE_CLOSED 和 DEVICE_CLOSED,分别确认应用归还图像与完成设备关闭回调。y0 只是可访问性抽样,不能证明画面内容正确。8 秒超时是主线程获得调度后执行的软观察截止,不是独立 watchdog;同步 open/configure 若阻塞主线程,timeout Runnable 也会延后,不能抢占 Binder 调用。它不是 HAL 性能指标;TIMEOUT、PAIR_MISMATCH 或离开前台导致取消都不记正常成功。即使 API 端通过,也未证明 UVC 后端,后端证据见 "成功、失败与关闭"一节。

总架构:请求往下走,结果分两路回来

先认清角色所在的进程。这里展示接口关系,同框内的对象仍可能由不同线程执行。下面是源码机制图,不是实测 Trace。实线标调用或数据交付,虚线标回调或事件通知;线型不表示是否同步返回,也不表示线程全局先后,同框内并不代表同线程。

打开由 CameraService 校验身份、权限和资源。HAL Provider 负责设备发现、状态及取得 ICameraDevice;打开后的 ICameraDeviceSession 才接受 configureStreams/processCaptureRequest。Provider 不是每一帧像素必须穿过的"中转站"。

Java Camera2 到 cameraserver 是 Java Binder 客户端对 Native 服务接口;这里不能机械补一层"CameraManager JNI 直接调用 CameraService"。JNI 的本章关键用途在 metadata Native 包装/FMQ 以及 ImageReader/Surface 图像消费;JNI 自身不意味着切线程。

先看这段概念动画:从客户端打开到 HAL 接受请求,每次交接的对象都不同。按阶段讲解,不代表跨线程的精确耗时或 Binder 返回的全局顺序。

打开:三个对象分别从哪里来

CameraDeviceImpl 先在应用创建,再取得远端设备

CameraManager.openCameraDeviceUserAsync 在当前调用线程查询特征,创建 CameraDeviceImpl,将它的 ICameraDeviceCallbacks Binder 传给 CameraService。下面是同一函数连续原文:

来源:frameworks/base/core/java/android/hardware/camera2/CameraManager.java,openCameraDeviceUserAsync,第 1085---1097 行,固定提交 94b4c163b7dfe5ce3607f7bb8456f9573f7de57d。固定原文。以下为连续原文片段,不是完整函数。

java 复制代码
            android.hardware.camera2.impl.CameraDeviceImpl deviceImpl =
                    new CameraDeviceImpl(
                        cameraId,
                        callback,
                        executor,
                        characteristics,
                        this,
                        mContext.getApplicationInfo().targetSdkVersion,
                        mContext, cameraDeviceSetup, sharedMode);
            ICameraDeviceCallbacks callbacks = deviceImpl.getCallbacks();

            try {
                ICameraService cameraService = CameraManagerGlobal.get().getCameraService();

deviceImpl.getCallbacks() 是应用导出的回调实体,不是 CameraService 的设备代理。 随后的 cameraService.connectDevice(callbacks, cameraId, ...) 同步返回 ICameraDeviceUser cameraUser;函数后段调用 deviceImpl.setRemoteDevice(cameraUser)。CameraService 的全局代理来自 CameraManagerGlobal 的服务查询/缓存;cameraId 是枚举得到的字符串,不硬编码为 0。

CameraDeviceImpl.setRemoteDevice 用 ICameraDeviceUserWrapper 保存代理,创建结果 FMQ reader 并登记 Binder 死亡通知,然后通过设备 Executor 投递 mCallOnOpened。onOpened 是客户端完成连接后的异步通知;openCamera 的方法返回和它不是同一个事件。 初始错误进入 setRemoteFailure 或抛 CameraAccessException/SecurityException,不能据"创建了 deviceImpl"判断打开成功。

CameraService 创建每客户端的 CameraDeviceClient

CameraService 的 connectDevice 进入 connectDeviceImpl/connectHelper,先执行权限、用户/设备策略与资源仲裁,makeClient 为本 API2 请求创建 CameraDeviceClient。连接采用的 AttributionSource、调用 UID/PID 与 cameraId 参与校验,CAMERA 权限获批并不保证设备未被占用或策略允许。

来源:frameworks/av/services/camera/libcameraservice/CameraService.cpp,connectHelper,第 2673---2688 行,固定提交 475269ec44acec82792be6b01fb8e16357d4d2c8。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
        }
        client = static_cast<CLIENT*>(tmp.get());

        LOG_ALWAYS_FATAL_IF(client.get() == nullptr, "%s: CameraService in invalid state",
                __FUNCTION__);

        std::string monitorTags = isClientWatched(client.get()) ? mMonitorTags : std::string();
        err = client->initialize(mCameraProviderManager, monitorTags);
        if (err != OK) {
            ALOGE("%s: Could not initialize client from HAL.", __FUNCTION__);
            // Errors could be from the HAL module open call or from AppOpsManager
            mServiceLock.unlock();
            client->disconnect();
            mServiceLock.lock();
            switch(err) {
                case BAD_VALUE:

initialize 失败时会先 disconnect 已创建客户端,再转换错误返回调用者;例如忙、资源上限、拒绝访问、设备故障不是同一个错误。CameraDeviceClient.initializeImpl 委托 Camera2ClientBase.initialize,后者按 Provider transport 选择设备。本章 AIDL、非共享分支实际创建 AidlCamera3Device:

来源:frameworks/av/services/camera/libcameraservice/common/Camera2ClientBase.cpp,initializeImpl AIDL nonshared,第 132---137 行,固定提交 475269ec44acec82792be6b01fb8e16357d4d2c8。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
                mDevice =
                    new AidlCamera3Device(mCameraServiceProxyWrapper,
                            TClientBase::mAttributionAndPermissionUtils,
                            TClientBase::mCameraIdStr, mOverrideForPerfClass,
                            TClientBase::mCompatInfo, mIsVendorClient,
                            mLegacyClient);

这个 Native 对象属于 cameraserver。它不是应用 CameraDeviceImpl,也不是 HAL 的 Session。CameraDeviceClient 随后创建 FrameProcessorBase(mDevice),注册自己为结果 listener,形成 metadata 回来的接收端。

Provider 交出 ICameraDevice,open 再交出 ICameraDeviceSession

AidlCamera3Device 构造时创建 AidlCameraDeviceCallbacks。initialize 把这个回调传给 CameraProviderManager.openAidlSession;管理器找到设备信息、保持 Provider 引用,通过 AidlProviderInfo.startDeviceInterface 调用 Provider 的 getCameraDeviceInterface 取得接口,再调用 interface->open(callback, session)。

选定 external Provider 的 getCameraDeviceInterface 校验名称和 PRESENT 状态,由 cameraDevicePath 与 mCfg 创建 ExternalCameraDevice。这个映射来自 Provider 对 /dev/video* 的枚举/热插拔与能力检查,应用 cameraId 不必等于设备节点尾号。ExternalCameraDevice.open 打开 O_RDWR fd,调用 createSession:

来源:hardware/interfaces/camera/device/default/ExternalCameraDevice.cpp,createSession,第 184---191 行,固定提交 0162af698935100a590b7359581ac8b1b80693e5。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
std::shared_ptr<ExternalCameraDeviceSession> ExternalCameraDevice::createSession(
        const std::shared_ptr<ICameraDeviceCallback>& cb, const ExternalCameraConfig& cfg,
        const std::vector<SupportedV4L2Format>& sortedFormats, const CroppingType& croppingType,
        const common::V1_0::helper::CameraMetadata& chars, const std::string& cameraId,
        unique_fd v4l2Fd) {
    return ndk::SharedRefBase::make<ExternalCameraDeviceSession>(
            cb, cfg, sortedFormats, croppingType, chars, cameraId, std::move(v4l2Fd));
}

std::move(v4l2Fd) 把采集 fd 的所有权交给 Session 。open 将 mSession 弱引用及返回接口设为此 Session。初始化失败返回错误;已打开且未关闭的 Session 会报 CAMERA_IN_USE。AidlCamera3Device 接住返回接口并建立 AidlHalInterface,创建请求线程等公共状态。这样,应用远端代理、服务端设备对象、HAL Session 的来源才连起来。

配会话:Surface 怎样变成 HAL stream

ImageReader 构造调用 nativeInit,Native 的 ImageReader_init 创建消费者与 Surface 生产者,登记帧可用 listener,把 JNIImageReaderContext 放入 Java Native context;nativeGetSurface 再把生产者包装返回 Java mSurface。当前代码含 WB_MEDIA_MIGRATION 条件,消费者/生产者创建遵守所编译 libgui 分支,不把旧版手写 BufferQueue::createBufferQueue 当成本版原文:

来源:frameworks/base/core/jni/android_media_ImageReader.cpp,ImageReader_init,第 458---461 行,固定提交 94b4c163b7dfe5ce3607f7bb8456f9573f7de57d。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
    auto [bufferConsumer, surface] =
            BufferItemConsumer::create((uint64_t)consumerUsage, (int)maxImages,
                                       /*controlledByApp*/ true);
    sp<IGraphicBufferProducer> gbProducer = surface->getIGraphicBufferProducer();

传给 OutputConfiguration 的 Surface 能回到这个消费者关系。 后面 Native context 中持有消费者,应用持有 ImageReader,CameraService 持有从配置拿到的生产者端。

CameraDevice.createCaptureSession(SessionConfiguration) 进入 CameraDeviceImpl.createCaptureSessionInternal,调用 configureStreamsChecked;应用 callback 被 CameraCaptureSessionImpl 状态/采集包装接住,再由调用者传入的 Executor/Handler 执行。

本提交里有 Flags.configureStreamsBatch() 两条分支。关闭时依次 beginConfigure、删除旧 stream、createStream、endConfigure;开启时把输出差量装进 SessionConfigurationAndStreamIds,调用 mRemoteDevice.configureStreams,服务端批量入口仍按相应内部配置方法处理。不能把传统逐个调用写成所有本版构建唯一经过的路径。 两者都需将返回 stream ID 与应用 OutputConfiguration 对应保存,之后 Surface 才能转成请求里的目标 ID。

普通 CameraDeviceClient.createStreamLocked 校验尺寸、格式和 consumer usage,取得 Surface producer,调用 mDevice->createStream;Camera3Device 创建 Camera3OutputStream 并分配 stream ID。endConfigureLocked 调用 mDevice->configureStreams(sessionParams, operatingMode),Camera3Device.configureStreamsLocked 整理 stream 配置并通过 AidlHalInterface 传给 HAL。

该 AIDL 包装还检查 ICameraDeviceSession 的接口版本与 session buffer manager 支持,可能使用 configureStreamsV2;否则使用 configureStreams。本章 external 实现公开核心落在 configureStreams,并通过静态 metadata 声明 buffer management 版本,不能据接口名称猜走哪版。

external configureStreams 先检查组合、初始化状态和 in-flight 是否为空,选一个能供应全部输出的 V4L2 采集格式。然后配置 S_FMT/FPS、申请 MMAP 槽并送入驱动:

来源:hardware/interfaces/camera/device/default/ExternalCameraDeviceSession.cpp,configureV4l2StreamLocked,第 1147---1155 行,固定提交 0162af698935100a590b7359581ac8b1b80693e5。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
    // VIDIOC_REQBUFS: create buffers
    v4l2_requestbuffers req_buffers{};
    req_buffers.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
    req_buffers.memory = V4L2_MEMORY_MMAP;
    req_buffers.count = v4lBufferCount;
    if (TEMP_FAILURE_RETRY(ioctl(mV4l2Fd.get(), VIDIOC_REQBUFS, &req_buffers)) < 0) {
        ALOGE("%s: VIDIOC_REQBUFS failed: %s", __FUNCTION__, strerror(errno));
        return -errno;
    }

循环逐槽 QUERYBUF 取得偏移,QBUF 把采集槽交给驱动,再用 STREAMON 开流;稍后 DQBUF 才是 HAL 取回完成槽。此实现还丢弃初始化阶段的若干帧。Android stream 不等于一个专属硬件采集队列:这里可由同一 V4L2 帧供应多个 Android 输出。 HAL 返回 HalStream 的 overrideFormat、producerUsage、consumerUsage、maxBuffers;IMPLEMENTATION_DEFINED 在该实现可改为 YUV420。Camera3OutputStream 据协商结果连接/配置 consumer;onConfigured 成功仅证明会话可用,还没证明一帧完成。

提交:参数、帧号、输出 ID 到哪里汇合

请求模板先提供参数,Builder 再选本帧目标

TEMPLATE_PREVIEW 的默认参数从哪里来?普通 CameraDeviceImpl.createCaptureRequest(int) 同步调用远端 createDefaultRequest,接住 CameraMetadataNative 并交给 Builder:

来源:frameworks/base/core/java/android/hardware/camera2/impl/CameraDeviceImpl.java,createCaptureRequest(int),第 1187---1197 行,固定提交 94b4c163b7dfe5ce3607f7bb8456f9573f7de57d。固定原文。以下为连续原文片段,不是完整函数。

java 复制代码
            CameraMetadataNative templatedRequest = null;

            templatedRequest = mRemoteDevice.createDefaultRequest(templateType);

            disableZslIfNeeded(templatedRequest, mAppTargetSdkVersion, templateType);

            CaptureRequest.Builder builder = new CaptureRequest.Builder(
                    templatedRequest, /*reprocess*/false, CameraCaptureSession.SESSION_ID_NONE,
                    getId(), /*physicalCameraIdSet*/ null);

            return builder;

Builder 持有模板 metadata 后,addTarget 再加入本帧目标 Surface。服务端 CameraDeviceClient.createDefaultRequest 将模板 ID 映射给 Camera3Device.createDefaultRequest;先查缓存:

来源:frameworks/av/services/camera/libcameraservice/device3/Camera3Device.cpp,createDefaultRequest,第 1537---1546 行,固定提交 475269ec44acec82792be6b01fb8e16357d4d2c8。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
        if (!mRequestTemplateCache[templateId].isEmpty()) {
            *request = mRequestTemplateCache[templateId];
            mLastTemplateId = templateId;
            return OK;
        }
    }

    camera_metadata_t *rawRequest;
    status_t res = mInterface->constructDefaultRequestSettings(
            (camera_request_template_t) templateId, &rawRequest);

命中缓存直接返回;未命中才经 AidlHalInterface.constructDefaultRequestSettings 调用 Session。external 的 constructDefaultRequestSettings 以 PREVIEW 等模板类型从初始化建立的 mDefaultRequests 取 metadata,拒绝其不支持的 MANUAL/ZERO_SHUTTER_LAG。结果经缓存、CameraDeviceClient 的 CameraMetadataNative 返回 Java。不能把每次创建 Builder 都画成必然重新访问 HAL。返回模板也不意味着本帧已提交,capture 才提交。

CameraCaptureSessionImpl.capture 检查 session 状态,调用 CameraDeviceImpl.capture(非 repeating),再到 submitCaptureRequest。它检查每个 request 至少一个非空目标,按 mConfiguredOutputs 将 Surface 转为 stream/surface ID:

来源:frameworks/base/core/java/android/hardware/camera2/impl/CameraDeviceImpl.java,submitCaptureRequest,第 1723---1730 行,固定提交 94b4c163b7dfe5ce3607f7bb8456f9573f7de57d。固定原文。以下为连续原文片段,不是完整函数。

java 复制代码
            CaptureRequest[] requestArray = requestList.toArray(new CaptureRequest[requestList.size()]);
            // Convert Surface to streamIdx and surfaceIdx
            for (CaptureRequest request : requestArray) {
                request.convertSurfaceToStreamId(mConfiguredOutputs);
            }

            requestInfo = mRemoteDevice.submitRequestList(requestArray, repeating);

保存返回 requestId 与 CaptureCallbackHolder,才能在回调时找回原 request、session 与执行器。它同步返回的序列标识表示这批请求的登记,不是曝光、像素可读或 buffer 已归还。

CameraDeviceClient.submitRequestList 在 cameraserver Binder 线程解析 request 的 metadata、目标 Surface/stream,检查目标属于已配置输出,加入 ANDROID_REQUEST_ID 等内部字段。非共享非 repeating 分支调用 mDevice->captureList(metadataRequestList, surfaceMapList, &lastFrameNumber);Camera3Device.convertMetadataListToRequestListLocked 创建 Native CaptureRequest 并将 stream 对象与参数关联,submitRequestsHelper 交给 RequestThread.queueRequestList。queueRequestList 在服务端入队时即通过 unpauseForNewRequests 发信号;submitRequestsHelper 还等待进入 active 状态。请求线程可能在提交 Binder 调用返回之前推进,不能把"先返回序列号、后开始采集"画成必然顺序。应用收到回调仍需经过回调登记、锁与执行器调度。

RequestThread.waitForNextRequestLocked 取出请求、分配帧号:

来源:frameworks/av/services/camera/libcameraservice/device3/Camera3Device.cpp,waitForNextRequestLocked,第 5038---5042 行,固定提交 475269ec44acec82792be6b01fb8e16357d4d2c8。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
    if (nextRequest != NULL) {
        nextRequest->mResultExtras.frameNumber = mFrameNumber++;
        nextRequest->mResultExtras.afTriggerId = mCurrentAfTriggerId;
        nextRequest->mResultExtras.precaptureTriggerId = mCurrentPreCaptureTriggerId;

prepareHalRequests 将该值复制到 camera_capture_request_t.frame_number,绑定 settings 和输出 stream。HAL buffer management 开启的输出可先不附实体 buffer,由 HAL 后续按需取;普通分支则由请求线程先拿 buffer。frame number 不是 V4L2 buffer.index、V4L2 sequence、Gralloc bufferId 或请求序列号。

sendRequestsBatch 通过 AidlHalInterface.processBatchCaptureRequests 做 AIDL 包装,metadata 能写入 request FMQ 时只传 fmqSettingsSize,否则在 settings.metadata 携带字节。FMQ 是 fast message queue,共享队列在这里运送 metadata,像素仍走 buffer 通路。最终提交给 Session:

来源:frameworks/av/services/camera/libcameraservice/device3/aidl/AidlCamera3Device.cpp,AidlHalInterface::processBatchCaptureRequests,第 1363---1370 行,固定提交 475269ec44acec82792be6b01fb8e16357d4d2c8。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
    int32_t numRequests = 0;
    auto retS = mAidlSession->processCaptureRequest(captureRequests, cachesToRemove,
            &numRequests);
    if (!retS.isOk()) {
        res = AidlProviderInfo::mapToStatusT(retS);
    }
    if (res == OK) {
        if (numRequests < 0) {

返回 numRequests 表示 HAL 接受的请求数。这个实现的 processCaptureRequest 在接口锁下逐个 processOneCaptureRequest,只对成功接受的请求递增计数;遇错停止。Camera3Device 对未提交请求清理并报设备/request 错误路径,不能把"进了 HAL 函数"写成已成功。

external 的 processOneCaptureRequest 检查 inputBuffer(不支持 reprocess)、streaming 状态与有效输出流;从 FMQ 或 settings 解析参数,非空参数更新 mLatestReqSetting,空参数复用前次。configure 后第一份请求不能省掉参数;这也是应用要从 createCaptureRequest 模板建立完整初始 request 的理由。

它在当前 HAL Binder 调用线程执行 DQBUF,得到一份采集输入,再创建 HalRequest:

来源:hardware/interfaces/camera/device/default/ExternalCameraDeviceSession.cpp,processOneCaptureRequest,第 643---654 行,固定提交 0162af698935100a590b7359581ac8b1b80693e5。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
    nsecs_t shutterTs = 0;
    std::unique_ptr<V4L2Frame> frameIn = dequeueV4l2FrameLocked(&shutterTs);
    if (frameIn == nullptr) {
        ALOGE("%s: V4L2 deque frame failed!", __FUNCTION__);
        return Status::INTERNAL_ERROR;
    }

    std::shared_ptr<HalRequest> halReq = std::make_shared<HalRequest>();
    halReq->frameNumber = request.frameNumber;
    halReq->setting = mLatestReqSetting;
    halReq->frameIn = std::move(frameIn);
    halReq->shutterTs = shutterTs;

随后填每个目标输出的 streamId、bufferId、尺寸/格式/usage,bufPtr 先为空;登记 mInflightFrames,mOutputThread->submitRequest(halReq) 投递余下处理。本实现接受请求之前已经可能阻塞在 DQBUF;"HAL 接受后全部异步采集"不能概括这条分支。 OutputThread 接到的是含 frameIn 与参数副本的工作对象,不是 Binder 线程本身移动过去。

两组 buffer:从 UVC 到应用输出

先把上方采集槽 A 与下方输出槽 O 分开看:哪一次归还输入,哪一次才归还应用输出?

采集输入:QBUF/DQBUF 是队列所有权交换

ExternalCameraDeviceSession.dequeueV4l2FrameLocked 设定 V4L2_BUF_TYPE_VIDEO_CAPTURE 与 V4L2_MEMORY_MMAP,调用 DQBUF,检查 index、bytesused 等。V4L2Frame 保存 fd、长度/偏移和所选格式;OutputThread 访问 getData 时才按需映射并读取。MMAP 表示把驱动分配的采集存储映射到 HAL 地址空间,不等于把 Java byte\[\] 传进驱动。

Kernel 固定材料的实际 UVC ioctl 路径是 uvc_v4l2_fops.unlocked_ioctl=video_ioctl2,V4L2 ioctl 分派表把 VIDIOC_DQBUF 交给 uvc_ioctl_dqbuf,再委托 uvc_dequeue_buffer → vb2_dqbuf → vb2_core_dqbuf。file 的 O_NONBLOCK 决定无数据时返回 EAGAIN 还是等待,本例以 O_RDWR 打开,没设置非阻塞。

来源:drivers/media/usb/uvc/uvc_v4l2.c,uvc_ioctl_dqbuf,第 871---882 行,固定提交 ccafb60de224d35a8bc14de33e1cd47caaaa786b。固定原文。以下为连续原文片段,不是完整函数。

c 复制代码
static int uvc_ioctl_dqbuf(struct file *file, void *fh, struct v4l2_buffer *buf)
{
	struct uvc_fh *handle = fh;
	struct uvc_streaming *stream = handle->stream;

	if (!uvc_has_privileges(handle))
		return -EBUSY;

	return uvc_dequeue_buffer(&stream->queue, buf,
				  file->f_flags & O_NONBLOCK);
}

DQBUF 是等待完成槽再交给用户空间,不是在这次 ioctl 内从头触发一次物理曝光。 UVC 可以持续流送帧,HAL 还可能丢弃滞后输入。Camera2 请求帧号在 HAL 中与所取输入关联,驱动并没有收到同名 Camera2 frameNumber 字段。

USB 驱动的 uvc_video_complete 在 URB 完成回调里先同步收包存储,再由 stream->decode 解析 UVC payload;昂贵 memcpy 可投到 workqueue。EOF/FID 等条件形成帧边界;不是每个 USB 包都等于一帧。uvc_queue_next_buffer 移除本帧队列节点并释放引用,异步拷贝持有的引用归零后进入 uvc_queue_buffer_complete。先检查坏帧丢弃策略:启用 UVC_QUEUE_DROP_CORRUPTED 且 buf->error 时重新排队并直接 return,不进入本次完成通知。未走该分支时才交给 videobuf2:

来源:drivers/media/usb/uvc/uvc_queue.c,uvc_queue_buffer_complete,第 479---488 行,固定提交 ccafb60de224d35a8bc14de33e1cd47caaaa786b。固定原文。以下为连续原文片段,不是完整函数。

c 复制代码
	if ((queue->flags & UVC_QUEUE_DROP_CORRUPTED) && buf->error) {
		uvc_queue_buffer_requeue(queue, buf);
		return;
	}

	buf->state = buf->error ? UVC_BUF_STATE_ERROR : UVC_BUF_STATE_DONE;
	vb2_set_plane_payload(&buf->buf.vb2_buf, 0, buf->bytesused);
	vb2_buffer_done(&buf->buf.vb2_buf, buf->error ? VB2_BUF_STATE_ERROR :
							VB2_BUF_STATE_DONE);
}

本版 uvc_driver.c 的 uvc_no_drop_param 默认值为0,队列初始化传 !uvc_no_drop_param,因此默认可重排坏帧;实际参数仍须运行时确认。对于进入完成通知的帧,videobuf2 的 vb2_buffer_done 把 DONE/ERROR 槽放入 done_list,在 done_wq 唤醒等待者;阻塞 DQBUF 的 __vb2_wait_for_done_vb 重查队列、开流和错误状态后返回。wake_up 表示可被调度,不能写成 HAL 此时已运行或 Java 回调立即执行。 中断、streamoff、队列错误会有独立返回。

输出:HAL 反向向 CameraService 取 Gralloc buffer

本例 ExternalCameraDeviceSession.initOutputThread 创建 BufferRequestThread 和 OutputThread。OutputThread 从队列取 HalRequest,调用 requestBufferStart,BufferRequestThread 构造每个目标 stream 的 BufferRequest,反向调用:

来源:hardware/interfaces/camera/device/default/ExternalCameraDeviceSession.cpp,BufferRequestThread::threadLoop,第 2054---2060 行,固定提交 0162af698935100a590b7359581ac8b1b80693e5。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
    ATRACE_BEGIN("AIDL requestStreamBuffers");
    BufferRequestStatus status;
    std::vector<StreamBufferRet> bufRets;
    ScopedAStatus ret = mCallbacks->requestStreamBuffers(mHalBufferReqs, &bufRets, &status);
    if (!ret.isOk()) {
        ALOGE("%s: Transaction error: %d:%d", __FUNCTION__, ret.getExceptionCode(),
              ret.getServiceSpecificError());

cameraserver 的 AidlCamera3Device.requestStreamBuffers 委托 camera3::requestStreamBuffers,定位 Camera3OutputStream,getBuffer 从 Surface consumer 的生产者侧 dequeue 空闲输出,返回 bufferId、NativeHandle 与 acquireFence。HAL importer 导入/缓存该 handle,BufferRequestThread 把 bufPtr 与 fence 填入 HalStreamBuffer 并通知 OutputThread。bufferId 用于缓存标识,不是 fd,更不能跨会话当全局地址。

OutputThread 已可并行处理输入转换,在需要写输出前等待 BufferRequest 完成。它对 MJPEG 解码到中间 YU12,对 YUV 输出执行 lockYCbCr、裁剪缩放、formatConvert;YUV_420_888 的 plane rowStride/pixelStride 要按实际布局读取,不假设宽×高紧密连续。

写入前等待 acquireFence:

来源:hardware/interfaces/camera/device/default/ExternalCameraDeviceSession.cpp,OutputThread::threadLoop,第 2895---2904 行,固定提交 0162af698935100a590b7359581ac8b1b80693e5。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
        } else if (halBuf.acquireFence >= 0) {
            int ret = sync_wait(halBuf.acquireFence, kSyncWaitTimeoutMs);
            if (ret) {
                halBuf.fenceTimeout = true;
            } else {
                ::close(halBuf.acquireFence);
                halBuf.acquireFence = -1;
            }
        }

成功等待后关闭本进程所拥有的 fence fd,再写 buffer;失败时标记 fenceTimeout,不继续写。Gralloc unlock 可能产生新的 release fence,该实现临时存入名为 acquireFence 的内部字段,processCaptureResult 再把它放到返回 StreamBuffer.releaseFence;不要只凭字段名把新 fence 误讲成旧的等待条件。

若从未等待/消费输入 acquireFence 就失败,HAL 契约要求把相应同步责任随 releaseFence 归还;fenceTimeout 分支返回 ERROR buffer 并 notify ERROR_BUFFER。把所有错误都画成"立刻可复用"会破坏同步约束。

回来时,metadata 与图像各走一条路

处理完输出后,external processCaptureResult 先将 V4L2Frame QBUF 回采集队列,再 notifyShutter;构造返回对象:

来源:hardware/interfaces/camera/device/default/ExternalCameraDeviceSession.cpp,processCaptureResult,第 1797---1806 行,固定提交 0162af698935100a590b7359581ac8b1b80693e5。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
    notifyShutter(req->frameNumber, req->shutterTs);

    // Fill output buffers;
    std::vector<CaptureResult> results(1);
    CaptureResult& result = results[0];
    result.frameNumber = req->frameNumber;
    result.partialResult = 1;
    result.inputBuffer.streamId = -1;
    result.outputBuffers.resize(req->buffers.size());
    for (size_t i = 0; i < req->buffers.size(); i++) {

之后填 outputBuffers 的 streamId/bufferId/status/releaseFence,fillCaptureResult 填 metadata(包含输入时间戳),从 mInflightFrames 删除该编号,invokeProcessCaptureResultCallback 可先写结果 FMQ,最后调用 cameraserver 的 ICameraDeviceCallback.processCaptureResult。QBUF 归还采集输入,不表示应用输出 buffer 已被消费。

本实现的 shutterTs 优先用带 MONOTONIC 标记的 V4L2 buffer timestamp,否则取当前 monotonic 时间;源码也说明可能拿到 EOF 时间。它不能被包装成已测量的传感器曝光起点。这是通用 Camera2 语义与具体外接实现近似之间的边界。

metadata 回到 CaptureCallback

AidlCameraDeviceCallbacks 晋升设备弱引用,转给 AidlCamera3Device.processCaptureResult;它通过 AidlCamera3OutputUtils 的 processOneCaptureResultLocked 读 FMQ/metadata、还原 buffer 记录,调用公共 Camera3OutputUtils.processCaptureResult。公共逻辑按 frame number 查询 in-flight,合并 partial、处理错误、核对 shutter 与 pending buffers;未满足交付条件的数据会暂存,不能把 HAL 单次回调等同于应用立即可见。

完整 metadata 被整理入结果队列并 signal;CameraDeviceClient.initializeImpl 创建的 FrameProcessorBase 线程 waitForNextFrame/getNextResult 取出结果,按 requestId 找已登记 listener,调用 CameraDeviceClient.onResultAvailable。它写应用侧结果 FMQ或使用 metadata parcel,再发送 remoteCb->onResultReceived。

应用的 CameraDeviceImpl.CameraDeviceCallbacks.onResultReceived 读出 requestId、frameNumber,必要时通过 nativeReadResultMetadata 读应用侧 FMQ,用 mCaptureCallbackMap 找回 CaptureCallbackHolder。partial 调 onCaptureProgressed,最终结果构造 TotalCaptureResult;holder.getExecutor().execute(resultDispatch) 把通知投给指定执行器,经 session callback 包装最后进入本例 onCaptureCompleted。HAL→cameraserver FMQ 与 cameraserver→应用 FMQ 是两段队列,不能当作同一地址直接贯通。

像素到 ImageReader

公共输出处理将 buffer 与 release fence 交回 Camera3OutputStream,必要时先等 SHUTTER、暂存 pending buffer;正常输出路径设置 buffer timestamp,再排入 Surface:

来源:frameworks/av/services/camera/libcameraservice/device3/Camera3OutputStream.cpp,returnBufferCheckedLocked,第 569---575 行,固定提交 475269ec44acec82792be6b01fb8e16357d4d2c8。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
            res = queueBufferToConsumer(currentConsumer, anwBuffer, anwReleaseFence, surface_ids);
            if (shouldLogError(res, state)) {
                ALOGE("%s: Stream %d: Error queueing buffer to native window:"
                      " %s (%d)", __FUNCTION__, mId, strerror(-res), res);
            }
        }

应用 ImageReader 的 Native BufferItemConsumer 收到 onFrameAvailable,JNIImageReaderContext 回调 Java 静态 postEventFromNative;Java 检查 reader 仍有效,再通过 listener Executor 调用 onImageAvailable。这个通知是"可能有可取图像",实际仍需 acquireNextImage,返回 null 也要处理。

acquireNextImage 创建 SurfaceImage,nativeImageSetup 通过消费者 acquireBuffer 取得 BufferItem;访问 planes 时按 buffer fence/Gralloc 约束映射像素。Image.getPlanes().getBuffer 对应图像存储视图;onCaptureCompleted 的 metadata 不会自动变成这些像素。 Image.close() 经 releaseImage/nativeReleaseImage 归还已 acquire 的 buffer。ImageReader.close 是消费者整体关闭,不能代替每帧及时关闭 Image。

把返回拆成 metadata 和图像两路来看:应用回调的先后可交换,最后要核对同一轮请求,并完成资源归还。

成功、失败与关闭分别观察

应用侧建议先验证一帧配对,再辨认它走的是哪个后端。后续获授权时,在 Host 保存设备身份与 CameraService dump:

bash 复制代码
adb shell getprop ro.build.fingerprint
adb shell getprop ro.boot.qemu
adb shell getprop vendor.qemu.sf.fake_camera
adb shell dumpsys media.camera
adb shell ps -A
adb shell ls -l /dev/video0

最后一行只查候选节点;没有 /dev/video0 不证明没有相机,有节点也不证明它由 UVC 驱动。需根据 dump 中选定 cameraId、Provider 服务实例/VINTF、HAL 进程、打开 fd 对应节点、sysfs driver 绑定与 Kernel/module 版本共同确认。本例配对后会立即开始关闭。若要核对这一轮 HAL 持有的采集 fd,应提前准备观察,在 OPENED 到 DEVICE_CLOSED 的窗口取得证据;错过窗口就记录该项尚缺,关闭后的 dump 仍可辅助辨认静态 Provider/设备信息,不能据"没看到 fd"反推本轮没走该节点。普通 user 镜像可能限制进程 fd/driver 读取;受限时记录缺失证据,不改权限或假造结论。Emulator 还需保存 AVD 的 camera 配置与 Host 输入源;API 配对成功不证明物理驱动通过。

想再向下关联时,先确认目标实际提供哪些 tracepoints/标签,再针对 RequestThread、CameraHal::processBatchCaptureRequests、VIDIOC_DQBUF、AIDL requestStreamBuffers 与 UVC/vb2 完成事件采集。用户空间 frame number 与驱动 index/sequence 不是同一键,需在 HAL DQBUF 返回处同时记录 frame number、index、V4L2 timestamp、输出 streamId/bufferId 才能建立映射。仅按时间附近拼接两段日志不算证明。此项为待实施的插桩/Trace 方案,本轮没有改框架或驱动。

观察到的现象 意味着什么,下一步看哪里
SecurityException/CameraAccessException 检查运行时权限、前台状态、相机占用、策略、cameraId;未必进入 HAL
onConfigureFailed / 参数异常 核对所选格式、尺寸、Surface 有效性与流组合;枚举成功不等于组合可配
SUBMITTED 后 TIMEOUT 尚未取得完整配对;区分 DQBUF 等输入、buffer request、fence、metadata/image 分支
onCaptureFailed / ERROR_RESULT metadata/request 错误不是"收到照片";按 frame 查结果与错误状态
onCaptureBufferLost / ERROR_BUFFER 某输出丢失;metadata 仍可能到达,不能单看 RESULT 判成功
acquire 超 maxImages / 持续卡住 检查 Image 是否逐帧 close;不要简单增大队列掩盖占用
断开或 ERROR_DEVICE 停止提交,关闭 session/device,等 onClosed 后收 reader;要重新 open,不能沿用旧对象

本例超时或离开前台立即停止发起新请求,close session 后 close device;若 open 尚未回调,保持 opening 标记,等 onOpened/onError 接住真实设备再 close,防止无人接收的打开结果。open 的某些错误既排异步错误回调又抛异常,完整示例用递增 generation/token 废止失败尝试;迟到旧回调只 close 自己的设备,不得覆盖新一轮 run/device/active。session 与 capture 回调同样按设备/会话身份过滤;ImageReader通知按token和reader实例过滤,因为close不会取消已经排出的listener Runnable。示例在 device.onClosed 后才 close reader,避免生产者仍用目标 Surface。

框架 CameraDeviceImpl.close 断开远端、解除死亡通知并清 callback/Native FMQ 状态;CameraDeviceClient/Camera2ClientBase.disconnect 停止结果线程并断开设备,Camera3Device 停止请求线程、清理 in-flight,与 HAL close 配对。external closeImpl 先 flush/退出 OutputThread,再退出 BufferRequestThread、清缓存,streamoff,REQBUFS(count=0),最后 reset V4L2 fd:

来源:hardware/interfaces/camera/device/default/ExternalCameraDeviceSession.cpp,closeImpl,第 1429---1433 行,固定提交 0162af698935100a590b7359581ac8b1b80693e5。固定原文。以下为连续原文片段,不是完整函数。

cpp 复制代码
        v4l2StreamOffLocked();
        ALOGV("%s: closing V4L2 camera FD %d", __FUNCTION__, mV4l2Fd.get());
        mV4l2Fd.reset();
        mClosed = true;
    }

这描述正常关闭与实现尝试,不承诺所有异常 ioctl 都能成功。 streamoff 会检查未归还输入数,错误仍需看实际返回与日志。应用宿主死亡由 Binder death/服务端 disconnect 清理,不把"系统会兜底"当作允许示例长期持有 Image 的理由。abortCaptures、flush、close 也不是同一个动作:flush 使待处理请求完成或失败,close 才终止会话设备资源。

回到按下按钮的那一刻

现在可以把这一帧重新串起来:应用创建 ImageReader/Surface,CameraManager 创建客户端并连 CameraDeviceClient;服务按 AIDL transport 创建 AidlCamera3Device,从 Provider 取得 Device.open 返回的 Session。配置把 Surface 变成 stream,Session 开启 V4L2 采集队列。capture 先登记请求,RequestThread 分配 frame number;external DQBUF 取输入,工作线程反向取输出 buffer,等 fence 后转换。HAL 归还输入并报告结果;服务将 metadata 投给应用 CaptureCallback,将像素 buffer 排给 ImageReader,应用 acquire 后必须 close。

查什么 固定源码符号
应用设备与远端代理如何关联 CameraManager.openCameraDeviceUserAsync / CameraDeviceImpl.setRemoteDevice
版本差异为何改变配置调用 CameraDeviceImpl.configureStreamsChecked / Flags.configureStreamsBatch
帧号分配与 AIDL 封装 RequestThread.waitForNextRequestLocked / AidlHalInterface.processBatchCaptureRequests
输入与输出为何不是同一组 ExternalCameraDeviceSession.processOneCaptureRequest / BufferRequestThread.threadLoop
返回如何分流 AidlCamera3OutputUtils / Camera3OutputUtils / FrameProcessorBase / Camera3OutputStream
Kernel 等待与完成 uvc_ioctl_dqbuf / uvc_queue_buffer_complete / vb2_buffer_done

回想第一个问题:capture 返回 7,Image 的 timestamp 是一串纳秒值,谁是 frame number?答:都不能据此断定;在 onCaptureStarted/onCaptureCompleted 读帧号,7 是 sequence ID。

再问一步:onCaptureCompleted 到了,Image 没有来,可以称拍照成功吗?答:只能证明最终 metadata 回调,按本例还缺图像与匹配,需查 buffer 状态、队列和消费者。

检验两组 buffer:HAL 执行 QBUF 后,应用是否可以立即复用自己的输出?答:不可以;这是采集输入队列,输出还有独立 buffer/fence/消费者生命周期。

检验线程边界:UVC 的唤醒证明 HAL 线程在同一时刻运行吗?答:不证明;done_wq 唤醒允许调度,DQBUF 还要重获锁并检查状态。

检验后端边界:EmulatedSensor 的源码能证明手机 CSI/ISP 正常吗?答:不能;源码分支与运行身份、虚拟与物理后端必须分开。

回到开头,图像要与随片的报告相认,借来的存储位置也要归还。这一帧的去路与归途,才算在应用里接上。

资料入口

以下是进一步核对的入口,本文摘录索引包含逐文件固定链接、函数归属、行号、文件摘要,见 校验/摘录索引.json。Kernel 文件本轮通过官方 Gitiles 原始接口取得,详细成功/缺失清单见 校验/Kernel来源.json;未取得的一份 sensor 文档不作为技术依据。

附录:可复制的单帧示例

这一段对应 "最小跟做"一节 的打开、配置、请求与结果配对,"成功、失败与关闭"一节 的超时/关闭处理。采用主线程统一状态,便于逐事件学习;只有一个请求,不做图像保存。工程接入、SDK 与安装步骤已在 "最小跟做"一节 给出;以下两份完整文件可直接复制到上面约定的示例工程,也分别保存在 示例/MainActivity.java、示例/AndroidManifest.xml。更改示例时必须同步本附录,本轮只做 Java 静态编译和契约核对,没有 APK 构建或设备运行记录。

MainActivity.java

java 复制代码
package org.example.cameraframe;

import android.Manifest;
import android.app.Activity;
import android.content.pm.PackageManager;
import android.graphics.ImageFormat;
import android.hardware.camera2.*;
import android.hardware.camera2.params.*;
import android.media.Image;
import android.media.ImageReader;
import android.os.Bundle;
import android.os.Handler;
import android.os.Looper;
import android.util.Log;
import android.util.Size;
import android.view.Surface;
import android.widget.*;
import java.util.*;

/** 单帧教学示例:API 28+,所有回调在主线程,不保存用户图像。 */
public final class MainActivity extends Activity {
    private static final String TAG = "CameraFrame15";
    private final Handler handler = new Handler(Looper.getMainLooper());
    private CameraDevice device;
    private CameraCaptureSession session;
    private ImageReader reader;
    private boolean foreground, opening, active;
    private String run;
    private int generation;
    private Long resultTs, imageTs;
    private long resultFrame = -1;
    private final Runnable timeout = () -> { log("TIMEOUT incomplete"); stop(); };

    @Override public void onCreate(Bundle state) {
        super.onCreate(state);
        LinearLayout box = new LinearLayout(this);
        box.setOrientation(LinearLayout.VERTICAL);
        TextView text = new TextView(this);
        text.setText("单帧 Camera2:开始后查看 CameraFrame15 日志;不保存图片。权限允许后再点开始。");
        box.addView(text);
        Button start = new Button(this); start.setText("请求一帧");
        start.setOnClickListener(v -> start()); box.addView(start);
        Button end = new Button(this); end.setText("结束并归还资源");
        end.setOnClickListener(v -> stop()); box.addView(end);
        setContentView(box);
    }
    @Override public void onResume() { super.onResume(); foreground = true; }
    @Override public void onPause() { foreground = false; stop(); super.onPause(); }
    private void log(String event) {
        Log.i(TAG, "run=" + run + " thread=" + Thread.currentThread().getName() + " " + event);
    }
    private void start() {
        if (!foreground || opening || device != null) return;
        if (checkSelfPermission(Manifest.permission.CAMERA) != PackageManager.PERMISSION_GRANTED) {
            requestPermissions(new String[]{Manifest.permission.CAMERA}, 15); return;
        }
        final int token = ++generation;
        run = UUID.randomUUID().toString(); resultTs = null; imageTs = null; resultFrame = -1;
        try {
            CameraManager manager = getSystemService(CameraManager.class);
            String selected = null;
            for (String id : manager.getCameraIdList()) {
                CameraCharacteristics c = manager.getCameraCharacteristics(id);
                StreamConfigurationMap map = c.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP);
                Size[] sizes = map == null ? null : map.getOutputSizes(ImageFormat.YUV_420_888);
                if (sizes == null || sizes.length == 0) continue;
                if (selected == null) selected = id;
                Integer facing = c.get(CameraCharacteristics.LENS_FACING);
                if (facing != null && facing == CameraCharacteristics.LENS_FACING_EXTERNAL) {
                    selected = id; break;
                }
            }
            if (selected == null) { log("NO_YUV_CAMERA"); return; }
            CameraCharacteristics c = manager.getCameraCharacteristics(selected);
            Size[] sizes = c.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)
                    .getOutputSizes(ImageFormat.YUV_420_888);
            Size size = Collections.min(Arrays.asList(sizes),
                    Comparator.comparingLong(s -> (long)s.getWidth() * s.getHeight()));
            log("SELECT id=" + selected + " facing=" + c.get(CameraCharacteristics.LENS_FACING)
                    + " size=" + size + " timestampSource="
                    + c.get(CameraCharacteristics.SENSOR_INFO_TIMESTAMP_SOURCE)
                    + " backend=requires_service_identity");
            active = true; opening = true;
            final Size outputSize = size;
            handler.postDelayed(timeout, 8000);
            manager.openCamera(selected, getMainExecutor(), new CameraDevice.StateCallback() {
                @Override public void onOpened(CameraDevice camera) {
                    if (token != generation) { camera.close(); return; }
                    opening = false; device = camera; log("OPENED");
                    if (!foreground || !active) { stop(); return; }
                    try {
                        reader = ImageReader.newInstance(outputSize.getWidth(), outputSize.getHeight(),
                                ImageFormat.YUV_420_888, 2);
                        reader.setOnImageAvailableListener(r -> {
                            if (token != generation || r != reader || !active) return;
                            try (Image image = r.acquireNextImage()) {
                                if (image == null) { log("IMAGE_NULL"); return; }
                                imageTs = image.getTimestamp();
                                Image.Plane y = image.getPlanes()[0];
                                // 仅抽读一个 Y 样本,不将 YUV 当紧密排列的 JPEG/RGB。
                                int sample = y.getBuffer().remaining() == 0 ? -1
                                        : (y.getBuffer().get(y.getBuffer().position()) & 255);
                                log("IMAGE ts=" + imageTs + " planes=" + image.getPlanes().length
                                        + " rowStride=" + y.getRowStride() + " pixelStride="
                                        + y.getPixelStride() + " y0=" + sample);
                            } catch (RuntimeException e) { log("IMAGE_ERROR " + e); stop(); return; }
                            log("IMAGE_CLOSED"); checkPair();
                        }, handler);
                        Surface target = reader.getSurface();
                        SessionConfiguration config = new SessionConfiguration(
                                SessionConfiguration.SESSION_REGULAR,
                                Collections.singletonList(new OutputConfiguration(target)),
                                getMainExecutor(), new CameraCaptureSession.StateCallback() {
                            @Override public void onConfigured(CameraCaptureSession s) {
                                if (token != generation || device != camera) { s.close(); return; }
                                session = s;
                                if (!active || !foreground) { stop(); return; }
                                log("CONFIGURED");
                                try {
                                    CaptureRequest.Builder b = camera.createCaptureRequest(
                                            CameraDevice.TEMPLATE_PREVIEW);
                                    b.addTarget(target);
                                    int sequence = s.capture(b.build(), captureCallback, handler);
                                    log("SUBMITTED sequence=" + sequence);
                                } catch (CameraAccessException | RuntimeException e) {
                                    log("SUBMIT_ERROR " + e); stop();
                                }
                            }
                            @Override public void onConfigureFailed(CameraCaptureSession s) {
                                s.close();
                                if (token != generation || device != camera) return;
                                log("CONFIGURE_FAILED"); stop();
                            }
                        });
                        camera.createCaptureSession(config);
                    } catch (CameraAccessException | RuntimeException e) { log("CONFIG_ERROR " + e); stop(); }
                }
                @Override public void onDisconnected(CameraDevice c) {
                    if (token != generation) { c.close(); return; }
                    opening = false; device = c; log("DISCONNECTED"); stop();
                }
                @Override public void onError(CameraDevice c, int error) {
                    if (token != generation) { c.close(); return; }
                    opening = false; device = c; log("DEVICE_ERROR code=" + error); stop();
                }
                @Override public void onClosed(CameraDevice c) {
                    if (token != generation || device != c) return;
                    device = null;
                    if (reader != null) { reader.close(); reader = null; }
                    log("DEVICE_CLOSED readerClosed=true");
                }
            });
        } catch (CameraAccessException | RuntimeException e) {
            // open可能先排异步错误回调再抛异常:废止本轮token,旧回调只关闭自身对象。
            generation++; opening = false; log("OPEN_ERROR " + e); stop();
        }
    }
    private final CameraCaptureSession.CaptureCallback captureCallback =
            new CameraCaptureSession.CaptureCallback() {
        @Override public void onCaptureStarted(CameraCaptureSession s, CaptureRequest r,
                long timestamp, long frameNumber) {
            if (s != session) return;
            log("START frame=" + frameNumber + " ts=" + timestamp);
        }
        @Override public void onCaptureCompleted(CameraCaptureSession s, CaptureRequest r,
                TotalCaptureResult result) {
            if (!active || s != session) return;
            resultFrame = result.getFrameNumber();
            resultTs = result.get(CaptureResult.SENSOR_TIMESTAMP);
            log("RESULT frame=" + resultFrame + " ts=" + resultTs); checkPair();
        }
        @Override public void onCaptureFailed(CameraCaptureSession s, CaptureRequest r,
                CaptureFailure failure) {
            if (s != session) return;
            log("FAILED frame=" + failure.getFrameNumber() + " reason=" + failure.getReason()); stop();
        }
        @Override public void onCaptureBufferLost(CameraCaptureSession s, CaptureRequest r,
                Surface target, long frameNumber) {
            if (s != session) return;
            log("BUFFER_LOST frame=" + frameNumber); stop();
        }
        @Override public void onCaptureSequenceAborted(CameraCaptureSession s, int sequenceId) {
            if (s != session) return;
            log("SEQUENCE_ABORTED sequence=" + sequenceId); stop();
        }
    };
    private void checkPair() {
        if (resultTs != null && imageTs != null) {
            log((resultTs.equals(imageTs) ? "PAIR_OK" : "PAIR_MISMATCH")
                    + " frame=" + resultFrame + " resultTs=" + resultTs + " imageTs=" + imageTs);
            stop();
        }
    }
    private void stop() {
        active = false; handler.removeCallbacks(timeout);
        if (session != null) { session.close(); session = null; }
        if (device != null) device.close();
        // open 正在进行时等 onOpened/onError 接住对象并关闭;禁止新一轮抢占。
        // reader 等 device.onClosed 后再关闭,避免生产者仍使用其 Surface。
        if (!opening && device == null && reader != null) { reader.close(); reader = null; }
    }
}

AndroidManifest.xml

xml 复制代码
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-feature android:name="android.hardware.camera.any" android:required="false" />
    <application android:label="CameraFrame15" android:theme="@android:style/Theme.Material.Light">
        <activity android:name="org.example.cameraframe.MainActivity" android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>
相关推荐
恋猫de小郭6 小时前
Flutter Analyzer 系列坑推进,必看,AI 时代这玩意最吃你内存
android·前端·flutter
LinXunFeng17 小时前
拿竞品 App 一扫,技术栈全暴露了
android·flutter·开源
Gracker20 小时前
AIW:从系统机制到性能排查,一本可以对照源码的 Android 电子书
android
三少爷的鞋20 小时前
代码越来越便宜,判断力越来越贵:AI 时代的 Android 架构与协程避坑指南
android
Gracker1 天前
SmartPerfetto 1.19.0:换过分析引擎之后,这次更新了什么
android
HQL_seven1 天前
【Android】BroadcastReceiver 详解
android
_祝你今天愉快1 天前
Paint Cavans高级绘制:[二] Paint-滤镜,XFERMODE
android
小乖写代码1 天前
字段获取代码(Android) · Android Input Examples
android·whatsapp·账号注册
booboosui1 天前
停一个活只有杀进程:界面上少了「说点要求」
android