1# Photographing Development
2
3
4## When to Use
5
6Use the camera module APIs to capture frames (photographing).
7
8
9## Available APIs
10
11**Table 1** APIs for photographing
12
13| Class| API| Description|
14| -------- | -------- | -------- |
15| CameraKit | int32_t GetCameraIds(std::list<string> cameraList) | Obtains IDs of cameras that are currently available.|
16| CameraKit | CameraAbility& GetCameraAbility(string cameraId) | Obtains the camera capability.|
17| CameraKit | void RegisterCameraDeviceCallback(CameraDeviceCallback\* callback, EventHandler\* handler) | Registers a camera callback for camera status changes.|
18| CameraKit | void UnregisterCameraDeviceCallback(CameraDeviceCallback\* callback) | Unregisters a camera callback.|
19| CameraKit | void CreateCamera(string cameraId, CameraStateCallback\* callback, EventHandler\* handler) | Creates a **Camera** instance.|
20| Camera | string GetCameraId() | Obtains the camera ID.|
21| Camera | CameraConfig& GetCameraConfig() | Obtains the camera configuration.|
22| Camera | FrameConfig& GetFrameConfig(int32_t type) | Obtains the frame configuration.|
23| Camera | void Configure(CameraConfig& config) | Configures the camera using a **CameraConfig** instance.|
24| Camera | void Release() | Releases the **Camera** object and associated resources.|
25| Camera | int TriggerLoopingCapture(FrameConfig& frameConfig) | Starts looping-frame capture.|
26| Camera | void StopLoopingCapture() | Stops looping-frame capture.|
27| Camera | int32_t TriggerSingleCapture(FrameConfig& frameConfig) | Starts single-frame capture.|
28| CameraConfig | void SetFrameStateCallback(FrameStateCallback\* callback, EventHandler\* handler); | Sets a frame state callback to respond to state changes.|
29| CameraConfig | static CameraConfig\* CreateCameraConfig() | Creates a **CameraConfig** instance.|
30| CameraAbility | std::list<Size> GetSupportedSizes(int format) | Obtains the supported image sizes for a specified image format.|
31| CameraAbility | std::list<T> GetParameterRange(uint32_t key) | Obtains the parameter value range based on a specified parameter key.|
32| CameraDevice | CameraDeviceCallback() | A constructor used to create a **CameraDeviceCallback** instance.|
33| CameraDevice | void OnCameraStatus​(std::string cameraId, int32_t status) | Called when the camera device status changes.|
34| CameraStateCallback | CameraStateCallback​() | A constructor used to create a **CameraStateCallback** instance.|
35| CameraStateCallback | void OnConfigured​(Camera& camera) | Called when the camera is configured successfully.|
36| CameraStateCallback | void OnConfigureFailed​(Camera& camera,int32_t errorCode) | Called when the camera fails to be configured.|
37| CameraStateCallback | void OnCreated​(Camera& camera) | Called when the camera is created successfully.|
38| CameraStateCallback | void OnCreateFailed​(std::string cameraId,int32_t errorCode) | Called when the camera fails to be created.|
39| CameraStateCallback | void OnReleased​(Camera& camera) | Called when the camera is released.|
40| FrameStateCallback | FrameStateCallback​() | A constructor used to create a **FrameStateCallback** instance.|
41| FrameStateCallback | void OnFrameFinished(Camera& camera, FrameConfig& frameConfig, FrameResult& frameResult) | Called when the frame capture is completed.|
42| FrameStateCallback | void OnFrameError​(Camera& camera, FrameConfig& frameConfig, int32_t errorCode, FrameResult& frameResult) | Called when the frame capture fails.|
43| FrameConfig | int32_t GetFrameConfigType() | Obtains the frame configuration type.|
44| FrameConfig | std::list<OHOS::Surface> GetSurfaces() | Obtains a list of surface objects.|
45| FrameConfig | void AddSurface(OHOS::AGP::UISurface& surface); | Adds a surface.|
46| FrameConfig | void RemoveSurface(OHOS::AGP::UISurface& surface); | Removes a surface.|
47
48
49## Constraints
50
51None
52
53
54## How to Develop
55
561. Implement the **CameraDeviceCallback** class and call **OnCameraStatus** to customize operations when the camera device changes, for example, when a camera becomes available or unavailable.
57
58   ```
59   class SampleCameraDeviceCallback : public CameraDeviceCallback {
60       void OnCameraStatus(std::string cameraId, int32_t status) override
61       {
62           //do something when camera is available/unavailable
63       }
64   };
65   ```
66
672. Implement the **FrameStateCallback** class. After obtaining the frame data, save the data as a file.
68
69   ```
70   static void SampleSaveCapture(const char *p, uint32_t size)
71   {
72       cout << "Start saving picture" << endl;
73       struct timeval tv;
74       gettimeofday(&tv, NULL);
75       struct tm *ltm = localtime(&tv.tv_sec);
76       if (ltm != nullptr) {
77           ostringstream ss("Capture_");
78           ss << "Capture" << ltm->tm_hour << "-" << ltm->tm_min << "-" << ltm->tm_sec << ".jpg";
79
80           ofstream pic("/sdcard/" + ss.str(), ofstream::out | ofstream::trunc);
81           cout << "write " << size << " bytes" << endl;
82           pic.write(p, size);
83           cout << "Saving picture end" << endl;
84       }
85   }
86
87   class TestFrameStateCallback : public FrameStateCallback {
88       void OnFrameFinished(Camera &camera, FrameConfig &fc, FrameResult &result) override
89       {
90           cout << "Receive frame complete inform." << endl;
91           if (fc.GetFrameConfigType() == FRAME_CONFIG_CAPTURE) {
92               cout << "Capture frame received." << endl;
93               list<Surface *> surfaceList = fc.GetSurfaces();
94               for (Surface *surface : surfaceList) {
95                   SurfaceBuffer *buffer = surface->AcquireBuffer();
96                   if (buffer != nullptr) {
97                       char *virtAddr = static_cast<char *>(buffer->GetVirAddr());
98                       if (virtAddr != nullptr) {
99                           SampleSaveCapture(virtAddr, buffer->GetSize());
100                       }
101                       surface->ReleaseBuffer(buffer);
102                   }
103                   delete surface;
104               }
105               delete &fc;
106           }
107       }
108   };
109   ```
110
1113. Implement the **CameraStateCallback** class and customize operations when the camera state changes (configuration successful or failed, and creation successful or failed).
112
113   ```
114   class SampleCameraStateMng : public CameraStateCallback {
115   public:
116       SampleCameraStateMng() = delete;
117       SampleCameraStateMng(EventHandler &eventHdlr) : eventHdlr_(eventHdlr) {}
118       ~SampleCameraStateMng()
119       {
120           if (recordFd_ != -1) {
121               close(recordFd_);
122           }
123       }
124       void OnCreated(Camera &c) override
125       {
126           cout << "Sample recv OnCreate camera." << endl;
127           auto config = CameraConfig::CreateCameraConfig();
128           config->SetFrameStateCallback(&fsCb_, &eventHdlr_);
129           c.Configure(*config);
130           cam_ = &c;
131       }
132       void OnCreateFailed(const std::string cameraId, int32_t errorCode) override {}
133       void OnReleased(Camera &c) override {}
134   };
135   ```
136
1374. Create a **CameraKit** instance to set and obtain camera information.
138
139   ```
140   CameraKit *camKit = CameraKit::GetInstance();
141   list<string> camList = camKit->GetCameraIds();
142   string camId;
143   for (auto &cam : camList) {
144       cout << "camera name:" << cam << endl;
145       const CameraAbility *ability = camKit->GetCameraAbility(cam);
146       /* find camera which fits user's ability */
147       list<CameraPicSize> sizeList = ability->GetSupportedSizes(0);
148       if (find(sizeList.begin(), sizeList.end(), CAM_PIC_1080P) != sizeList.end()) {
149           camId = cam;
150           break;
151       }
152   }
153   ```
154
1555. Create a **Camera** instance.
156
157   ```
158   EventHandler eventHdlr; // Create a thread to handle callback events
159   SampleCameraStateMng CamStateMng(eventHdlr);
160
161   camKit->CreateCamera(camId, CamStateMng, eventHdlr);
162   ```
163
1646. Based on the callback design in steps 1, 2, and 3, perform related operations until the **OnCreated** callback obtains **cam_**.
165
166   ```
167   void OnCreated(Camera &c) override
168   {
169       cout << "Sample recv OnCreate camera." << endl;
170       auto config = CameraConfig::CreateCameraConfig();
171       config->SetFrameStateCallback(&fsCb_, &eventHdlr_);
172       c.Configure(*config);
173       cam_ = &c;
174   }
175
176   void Capture()
177   {
178       if (cam_ == nullptr) {
179           cout << "Camera is not ready." << endl;
180           return;
181       }
182       FrameConfig *fc = new FrameConfig(FRAME_CONFIG_CAPTURE);
183       Surface *surface = Surface::CreateSurface();
184       if (surface == nullptr) {
185           delete fc;
186           return;
187       }
188       surface->SetWidthAndHeight(1920, 1080); /* 1920:width,1080:height */
189       fc->AddSurface(*surface);
190       cam_->TriggerSingleCapture(*fc);
191   }
192   ```
193