README_zh.md
1# Camera<a name="ZH-CN_TOPIC_0000001078436908"></a>
2
3- [简介](#section11660541593)
4- [目录](#section161941989596)
5- [接口说明](#section1564411661810)
6- [使用说明](#section19806524151819)
7- [相关仓](#section1371113476307)
8
9## 简介<a name="section11660541593"></a>
10
11OHOS相机驱动框架模型对上实现相机HDI接口，对下实现相机Pipeline模型，管理相机各个硬件设备。
12各层的基本概念如下：
13
141. HDI实现层，对上实现OHOS相机标准南向接口。
15
162. 框架层，对接HDI实现层的控制、流的转发，实现数据通路的搭建、管理相机各个硬件设备等功能。
17
183. 适配层，屏蔽底层芯片和OS差异，支持多平台适配。
19
20**图 1** Camera驱动模块架构图<a name="fig14142101381112"></a>
21
22
23
24
25
26## 目录<a name="section161941989596"></a>
27
28
29```
30/drivers/peripheral/input
31 ├── hal # camera模块的hal层代码
32 │ ├── adapter # camera hal平台适配层的实现
33 │ ├── buffer_manager # camera hal统一的Buffer管理
34 │ ├── device_manager # 提供camera hal层设备管理能力，包括设备枚举、设备能力查询等
35 │ ├── hdi_impl # camera hal HDI的具体实现
36 │ ├── include # camera hal层内部的头文件
37 │ ├── init # camera hal层HDI接口使用样例实现
38 │ ├── pipeline_core # camera hal层pipeline核心代码
39 │ ├── test # camera hal层测试代码实现
40 │ └── utils # camera hal层工具类代码，目前提供的是watchdog
41 ├── hal_c # 提供C实现的HAL接口
42 │ ├── hdi_cif # C实现的HDI接口适配代码
43 │ └── include # C形式的HDI接口
44 └── interfaces # camera hal对上层服务提供的驱动能力接口
45 ├── hdi_ipc # IPC模式的HDI实现
46 ├── hdi_passthrough # 直通模式的HDI实现
47 └── include # camera hal对外提供的HDI定义
48
49
50```
51
52## 接口说明<a name="section1564411661810"></a>
53
54<table border=0 cellpadding=0 cellspacing=0 width=1119 style='border-collapse:
55 collapse;table-layout:fixed;width:839pt'>
56 <col width=119 style='mso-width-source:userset;mso-width-alt:3797;width:89pt'>
57 <col width=568 style='mso-width-source:userset;mso-width-alt:18176;width:426pt'>
58 <col width=363 style='mso-width-source:userset;mso-width-alt:11605;width:272pt'>
59 <col width=69 style='width:52pt'>
60 <tr height=19 style='height:14.0pt'>
61 <td height=19 width=119 style='height:14.0pt;width:89pt'>头文件</td>
62 <td width=568 style='width:426pt'><a name=p14132125715552>接口名称</a></td>
63 <td width=363 style='width:272pt'><a name=p18132205755516>功能描述</a>
64</td>
65 </tr>
66 <tr height=93 style='height:70.0pt'>
67 <td rowspan=10 height=728 class=xl66 style='height:546.0pt'>icamera_device.h</td>
68 <td class=xl65 width=568 style='width:426pt'>CamRetCode
69 IsStreamsSupported(<br>
70 <span style='mso-spacerun:yes'>
71 </span>OperationMode mode,<br>
72 <span style='mso-spacerun:yes'>
73 </span>const std::shared_ptr<CameraMetadata>& modeSetting,<br>
74 <span style='mso-spacerun:yes'>
75 </span>const std::vector<std::shared_ptr<StreamInfo>> &info,<br>
76 <span style='mso-spacerun:yes'>
77 </span>StreamSupportType &type)</td>
78 <td>查询是否支持添加参数对应的流</td>
79 </tr>
80 <tr height=75 style='height:56.0pt'>
81 <td height=75 style='height:56.0pt'>CamRetCode CreateStreams(const
82 std::vector<std::shared_ptr<StreamInfo>> &streamInfo<span
83 style='display:none'>s)</span></td>
84 <td class=xl65 width=363 style='width:272pt'>创建流<br>
85 <span style='mso-spacerun:yes'> </span>此函数接口依据输入的流信息创建流，调用该接口之前需先通过
86 {@link IsStreamsSupported} 查询HAL是否支持要创建的流</td>
87 </tr>
88 <tr height=19 style='height:14.0pt'>
89 <td height=19 style='height:14.0pt'>CamRetCode ReleaseStreams(const
90 std::vector<int> &streamIds)</td>
91 <td>释放流</td>
92 </tr>
93 <tr height=37 style='height:28.0pt'>
94 <td height=37 class=xl65 width=568 style='height:28.0pt;width:426pt'>CamRetCode
95 CommitStreams(OperationMode mode,<br>
96 <span style='mso-spacerun:yes'>
97 </span>const std::shared_ptr<CameraMetadata> &modeSetting)</td>
98 <td class=xl65 width=363 style='width:272pt'>配置流<br>
99 本接口需在调用{@link CreateStreams}创建流之后调用</td>
100 </tr>
101 <tr height=37 style='height:28.0pt'>
102 <td height=37 class=xl65 width=568 style='height:28.0pt;width:426pt'>CamRetCode
103 GetStreamAttributes(<br>
104 <span style='mso-spacerun:yes'>
105 </span>std::vector<std::shared_ptr<StreamAttribute>>
106 &attributes)</td>
107 <td>获取流的属性</td>
108 </tr>
109 <tr height=168 style='height:126.0pt'>
110 <td height=168 class=xl65 width=568 style='height:126.0pt;width:426pt'>CamRetCode
111 AttachBufferQueue(int streamId, const OHOS::sptr<OHOS::IBufferProducer>
112 &producer)</td>
113 <td class=xl65 width=363 style='width:272pt'>绑定生产者句柄和指定流<br>
114 <br>
115 如果在{@link CreateStreams}创建流时已经指定了生产者句柄，则不需要调用该接口。如果需要重新绑定，<br>
116 <span
117 style='mso-spacerun:yes'> </span>对于一些IOT设备，可能不需要或者不支持预览流的图像数据缓存流转，那么不需要绑定生产者句柄，<br>
118 此时在创建流时{@link CreateStreams} 的 {@link StreamInfo} 参数的生产者句柄bufferQueue_为空，而<br>
119 <span style='mso-spacerun:yes'> </span>tunneledMode_需设置为false。</td>
120 </tr>
121 <tr height=19 style='height:14.0pt'>
122 <td height=19 class=xl65 width=568 style='height:14.0pt;width:426pt'>CamRetCode
123 DetachBufferQueue(int streamId)</td>
124 <td>解除生产者句柄和指定流的绑定关系</td>
125 </tr>
126 <tr height=205 style='height:154.0pt'>
127 <td height=205 class=xl65 width=568 style='height:154.0pt;width:426pt'>CamRetCode
128 Capture(int captureId,<br>
129 <span style='mso-spacerun:yes'>
130 </span>const std::shared_ptr<CaptureInfo> &info,<span
131 style='mso-spacerun:yes'> </span>bool isStreaming)</td>
132 <td class=xl65 width=363 style='width:272pt'>捕获图像<br>
133 <span style='mso-spacerun:yes'> </span>本接口必须在调用 {@link CommitStreams}
134 配置流之后调用。<br>
135 <span
136 style='mso-spacerun:yes'> </span>图像捕获有两种模式，分别是连续捕获和单次捕获。连续捕获即触发之后模块内部进行连续的捕获，<br>
137 消费者可以连续收到图像数据，不需要多次调用本接口，若再次调用了本接口，<br>
138 <span
139 style='mso-spacerun:yes'> </span>则停止当前捕获，更新捕获信息，再进行一次新的捕获，多用于预览、录像或者连拍场景。<br>
140 <span style='mso-spacerun:yes'> </span>单次捕获即触发之后只捕获一帧图像数据，用于单次拍照场景</td>
141 </tr>
142 <tr height=19 style='height:14.0pt'>
143 <td height=19 class=xl65 width=568 style='height:14.0pt;width:426pt'>CamRetCode
144 CancelCapture(int captureId)</td>
145 <td>取消捕获</td>
146 </tr>
147 <tr height=56 style='height:42.0pt'>
148 <td height=56 class=xl65 width=568 style='height:42.0pt;width:426pt'>CamRetCode
149 ChangeToOfflineStream(const std::vector<int> &streamIds,<br>
150 <span style='mso-spacerun:yes'>
151 </span>OHOS::sptr<IStreamOperatorCallback> &callback,<br>
152 <span style='mso-spacerun:yes'>
153 </span>OHOS::sptr<IOfflineStreamOperator> &offlineOperator)</td>
154 <td class=xl65 width=363 style='width:272pt'>将指定流转换成离线流</td>
155 </tr>
156 <tr height=19 style='height:14.0pt'>
157 <td rowspan=2 height=38 class=xl66 style='height:28.0pt'>icamera_device_callback.h</td>
158 <td class=xl65 width=568 style='width:426pt'>void OnError(ErrorType type,
159 int32_t errorCode)</td>
160 <td colspan=2 style='mso-ignore:colspan'>设备发生错误时调用，由调用者实现，用于返回错误信息给调用者</td>
161 </tr>
162 <tr height=19 style='height:14.0pt'>
163 <td height=19 class=xl65 width=568 style='height:14.0pt;width:426pt'>void
164 OnResult(uint64_t timestamp, const std::shared_ptr<CameraMetadata>
165 &result)</td>
166 <td class=xl65 width=363 style='width:272pt'>上报camera设备相关的metadata的回调</td>
167 </tr>
168 <tr height=19 style='height:14.0pt'>
169 <td rowspan=5 height=150 class=xl66 style='height:112.0pt'>icamera_host.h</td>
170 <td class=xl65 width=568 style='width:426pt'>CamRetCode SetCallback(const
171 OHOS::sptr<ICameraHostCallback> &callback)</td>
172 <td>设置ICameraHost回调接口</td>
173 </tr>
174 <tr height=19 style='height:14.0pt'>
175 <td height=19 style='height:14.0pt'>CamRetCode
176 GetCameraIds(std::vector<std::string> &cameraIds)</td>
177 <td>获取当前可用的Camera设备ID列表</td>
178 </tr>
179 <tr height=37 style='height:28.0pt'>
180 <td height=37 class=xl65 width=568 style='height:28.0pt;width:426pt'>CamRetCode
181 GetCameraAbility(const std::string &cameraId,<br>
182 <span style='mso-spacerun:yes'>
183 </span>std::shared_ptr<CameraAbility> &ability)</td>
184 <td>获取Camera设备能力集合</td>
185 </tr>
186 <tr height=56 style='height:42.0pt'>
187 <td height=56 class=xl65 width=568 style='height:42.0pt;width:426pt'>CamRetCode
188 OpenCamera(const std::string &cameraId,<br>
189 <span style='mso-spacerun:yes'>
190 </span>const OHOS::sptr<ICameraDeviceCallback> &callback,<br>
191 <span style='mso-spacerun:yes'>
192 </span>OHOS::sptr<ICameraDevice> &device)</td>
193 <td>打开Camera设备</td>
194 </tr>
195 <tr height=19 style='height:14.0pt'>
196 <td height=19 class=xl65 width=568 style='height:14.0pt;width:426pt'>CamRetCode
197 SetFlashlight(const std::string &cameraId, bool &isEnable)</td>
198 <td>打开或关闭闪光灯</td>
199 </tr>
200 <tr height=19 style='height:14.0pt'>
201 <td rowspan=2 height=38 class=xl66 style='height:28.0pt'>icamera_host_callback.h</td>
202 <td class=xl65 width=568 style='width:426pt'>void OnCameraStatus(const
203 std::string &cameraId, CameraStatus status)</td>
204 <td>Camera设备状态变化上报</td>
205 </tr>
206 <tr height=19 style='height:14.0pt'>
207 <td height=19 class=xl65 width=568 style='height:14.0pt;width:426pt'>void
208 OnFlashlightStatus(const std::string &cameraId, FlashlightStatus status)</td>
209 <td>闪光灯状态变化回调</td>
210 </tr>
211 <tr height=19 style='height:14.0pt'>
212 <td rowspan=3 height=57 class=xl66 style='height:42.0pt'>ioffline_stream_operator.h</td>
213 <td class=xl65 width=568 style='width:426pt'><span
214 style='mso-spacerun:yes'> </span>CamRetCode CancelCapture(int captureId)</td>
215 <td>取消捕获请求</td>
216 </tr>
217 <tr height=19 style='height:14.0pt'>
218 <td height=19 class=xl65 width=568 style='height:14.0pt;width:426pt'>CamRetCode
219 ReleaseStreams(const std::vector<int> &streamIds)</td>
220 <td>释放流</td>
221 </tr>
222 <tr height=19 style='height:14.0pt'>
223 <td height=19 class=xl65 width=568 style='height:14.0pt;width:426pt'>CamRetCode
224 Release()</td>
225 <td>释放所有离线流</td>
226 </tr>
227 <tr height=93 style='height:70.0pt'>
228 <td rowspan=10 height=783 class=xl66 style='height:588.0pt'>istream_operator.h</td>
229 <td class=xl65 width=568 style='width:426pt'>CamRetCode
230 IsStreamsSupported(<br>
231 <span style='mso-spacerun:yes'>
232 </span>OperationMode mode,<br>
233 <span style='mso-spacerun:yes'>
234 </span>const std::shared_ptr<CameraMetadata> &modeSetting,<br>
235 <span style='mso-spacerun:yes'>
236 </span>const std::vector<std::shared_ptr<StreamInfo>> &info,<br>
237 <span style='mso-spacerun:yes'>
238 </span>StreamSupportType &type)</td>
239 <td>查询是否支持添加参数对应的流</td>
240 </tr>
241 <tr height=37 style='height:28.0pt'>
242 <td height=37 class=xl65 width=568 style='height:28.0pt;width:426pt'>CamRetCode
243 CreateStreams(const std::vector<std::shared_ptr<StreamInfo>>
244 &streamInfos)</td>
245 <td>创建流</td>
246 </tr>
247 <tr height=19 style='height:14.0pt'>
248 <td height=19 class=xl65 width=568 style='height:14.0pt;width:426pt'>CamRetCode
249 ReleaseStreams(const std::vector<int> &streamIds)</td>
250 <td>释放流</td>
251 </tr>
252 <tr height=37 style='height:28.0pt'>
253 <td height=37 class=xl65 width=568 style='height:28.0pt;width:426pt'>CamRetCode
254 CommitStreams(OperationMode mode,<br>
255 <span style='mso-spacerun:yes'>
256 </span>const std::shared_ptr<CameraMetadata> &modeSetting)</td>
257 <td class=xl65 width=363 style='width:272pt'><br>
258 配置流</td>
259 </tr>
260 <tr height=37 style='height:28.0pt'>
261 <td height=37 class=xl65 width=568 style='height:28.0pt;width:426pt'>CamRetCode
262 GetStreamAttributes(<br>
263 <span style='mso-spacerun:yes'>
264 </span>std::vector<std::shared_ptr<StreamAttribute>>
265 &attributes)</td>
266 <td>获取流的属性</td>
267 </tr>
268 <tr height=37 style='height:28.0pt'>
269 <td height=37 class=xl65 width=568 style='height:28.0pt;width:426pt'>CamRetCode
270 AttachBufferQueue(int streamId, const OHOS::sptr<OHOS::IBufferProducer>
271 &producer)</td>
272 <td>绑定生产者句柄和指定流</td>
273 </tr>
274 <tr height=19 style='height:14.0pt'>
275 <td height=19 class=xl65 width=568 style='height:14.0pt;width:426pt'><span
276 style='mso-spacerun:yes'> </span>CamRetCode DetachBufferQueue(int
277 streamId)</td>
278 <td>解除生产者句柄和指定流的绑定关系</td>
279 </tr>
280 <tr height=429 style='height:322.0pt'>
281 <td height=429 class=xl65 width=568 style='height:322.0pt;width:426pt'>CamRetCode
282 Capture(int captureId,<br>
283 <span style='mso-spacerun:yes'>
284 </span>const std::shared_ptr<CaptureInfo> &info,<span
285 style='mso-spacerun:yes'> </span>bool isStreaming)</td>
286 <td class=xl65 width=363 style='width:272pt'>捕获图像<br>
287 <span style='mso-spacerun:yes'> </span>*<br>
288 <span style='mso-spacerun:yes'> </span>* 本接口必须在调用
289 {@link CommitStreams} 配置流之后调用。<br>
290 <span style='mso-spacerun:yes'> </span>*
291 图像捕获有两种模式，分别是连续捕获和单次捕获。连续捕获即触发之后模块内部进行连续的捕获，<br>
292 * 消费者可以连续收到图像数据，不需要多次调用本接口，若再次调用了本接口，<br>
293 * 则停止当前捕获，更新捕获信息，再进行一次新的捕获，多用于预览、录像或者连拍场景。<br>
294 <span style='mso-spacerun:yes'> </span>*
295 单次捕获即触发之后只捕获一帧图像数据，用于单次拍照场景。<br>
296 <span style='mso-spacerun:yes'> </span>* 捕获启动时，会调用
297 {@link OnCaptureStarted}来通知调用者捕获已经启动。<br>
298 <span style='mso-spacerun:yes'> </span>* 连续捕获需调用
299 {@link CancelCapture} 来停止捕获。<br>
300 <span style='mso-spacerun:yes'> </span>* 捕获结束时，会调用
301 {@link OnCaptureEnded}来通知调用者捕获的帧计数等信息。<br>
302 <span style='mso-spacerun:yes'> </span>* {@link
303 CaptureInfo} 的 enableShutterCallback_ 使能 {@link OnFrameShutter}，使能后每次捕获触发
304 {@link OnFrameShutter}<br>
305 <span style='mso-spacerun:yes'> </span>*
306 对于多个流同时捕获的场景，本模块内部保证同时上报多路流捕获数据。</td>
307 </tr>
308 <tr height=19 style='height:14.0pt'>
309 <td height=19 class=xl65 width=568 style='height:14.0pt;width:426pt'>CamRetCode
310 CancelCapture(int captureId)</td>
311 <td>取消捕获</td>
312 </tr>
313 <tr height=56 style='height:42.0pt'>
314 <td height=56 class=xl65 width=568 style='height:42.0pt;width:426pt'>CamRetCode
315 ChangeToOfflineStream(const std::vector<int> &streamIds,<br>
316 <span style='mso-spacerun:yes'>
317 </span>OHOS::sptr<IStreamOperatorCallback> &callback,<br>
318 <span style='mso-spacerun:yes'>
319 </span>OHOS::sptr<IOfflineStreamOperator> &offlineOperator)</td>
320 <td>将指定流转换成离线流</td>
321 </tr>
322 <tr height=19 style='height:14.0pt'>
323 <td rowspan=4 height=130 class=xl66 style='height:98.0pt'>istream_operator_callback.h</td>
324 <td class=xl65 width=568 style='width:426pt'>void OnCaptureStarted(int32_t
325 captureId, const std::vector<int32_t> &streamIds)</td>
326 <td>捕获开始回调，在捕获开始时调用</td>
327 </tr>
328 <tr height=37 style='height:28.0pt'>
329 <td height=37 class=xl65 width=568 style='height:28.0pt;width:426pt'>void
330 OnCaptureEnded(int32_t captureId,<br>
331 <span style='mso-spacerun:yes'>
332 </span>const std::vector<std::shared_ptr<CaptureEndedInfo>>
333 &infos)</td>
334 <td>捕获结束回调，在捕获结束时调用</td>
335 </tr>
336 <tr height=37 style='height:28.0pt'>
337 <td height=37 class=xl65 width=568 style='height:28.0pt;width:426pt'>void
338 OnCaptureError(int32_t captureId,<br>
339 <span style='mso-spacerun:yes'>
340 </span>const std::vector<std::shared_ptr<CaptureErrorInfo>>
341 &infos)</td>
342 <td>捕获错误回调，在捕获过程中发生错误时调用</td>
343 </tr>
344 <tr height=37 style='height:28.0pt'>
345 <td height=37 class=xl65 width=568 style='height:28.0pt;width:426pt'>void
346 OnFrameShutter(int32_t captureId,<br>
347 <span style='mso-spacerun:yes'>
348 </span>const std::vector<int32_t> &streamIds, uint64_t timestamp)</td>
349 <td>帧捕获回调</td>
350</table>
351
352## 使用方法
353
354### 获取CameraHost
355
356 std::shared_ptr<Camera::CameraHost> cameraHost = Camera::CameraHost::CreateCameraHost();
357
358### 获取配置的cameraId
359
360 std::vector<std::string> cameraIds;
361cameraHost->GetCameraIds(cameraIds); #
362
363### 打开camera设备并获取到device
364
365 const std::shared_ptr<Camera::ICameraDeviceCallback> callback = std::make_shared<Camera::ICameraDeviceCallback>();
366
367 std::shared_ptr<Camera::CameraDevice> device;
368
369 std::cout << "cameraIds.front() = " << cameraIds.front() << std::endl;
370
371 Camera::CamRetCode rc = cameraHost->OpenCamera(cameraIds.front(), callback, device);
372
373
374### 调用device的GetStreamOperator函数获取streamOperator
375
376 std::make_shared<Camera::IStreamOperatorCallback>();
377 std::shared_ptr<Camera::StreamOperator> streamOperator = nullptr;
378 rc = device->GetStreamOperator(streamOperatorCallback, streamOperator);`
379### 批量创建数据流
380 std::vector<std::shared_ptr<Camera::StreamInfo>> streamInfos;
381 std::shared_ptr<Camera::StreamInfo> streamInfo = std::make_shared<Camera::StreamInfo>();
382 streamInfo->streamId_ = 1001;
383 streamInfo->width_ = 1280;
384 streamInfo->height_ = 720;
385 streamInfo->format_ = 2;
386 streamInfo->datasapce_ = 10;
387 streamInfo->intent_ = Camera::PREVIEW;
388 streamInfo->tunneledMode_ = 5;
389 streamInfos.push_back(streamInfo);
390 rc = streamOperator->CreateStreams(streamInfos);
391### 配流起流
392 rc = streamOperator->CommitStreams(Camera::NORMAL, nullptr);
393
394## 相关仓<a name="section1371113476307"></a>
395[驱动子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/%E9%A9%B1%E5%8A%A8%E5%AD%90%E7%B3%BB%E7%BB%9F.md)
396
397[vendor_hisilicon/tree/master/Hi3516DV300/hdf_config](https://gitee.com/openharmony/vendor_hisilicon/blob/master/README_zh.md)
398
399[drivers\_peripheral](https://gitee.com/openharmony/drivers_peripheral)
400
