Photographing

When to Use

Use the camera module APIs to capture frames (photographing).

Available APIs

Table 1 APIs for photographing

Class

Function

Description

CameraKit

int32_t GetCameraIds(std::list<string> cameraList)

Obtains IDs of cameras that are currently available.

CameraKit

CameraAbility& GetCameraAbility(string cameraId)

Obtains the camera capability

CameraKit

void RegisterCameraDeviceCallback(CameraDeviceCallback* callback, EventHandler* handler)

Registers a camera callback for camera status changes.

CameraKit

void UnregisterCameraDeviceCallback(CameraDeviceCallback* callback)

Unregisters a camera callback.

CameraKit

void CreateCamera(string cameraId, CameraStateCallback* callback, EventHandler* handler)

Creates a Camera instance.

Camera

string GetCameraId()

Obtains the camera ID.

Camera

CameraConfig& GetCameraConfig()

Obtains the camera configuration.

Camera

FrameConfig& GetFrameConfig(int32_t type)

Obtains the frame configuration.

Camera

void Configure(CameraConfig& config)

Configures the camera using the CameraConfig object.

Camera

void Release()

Releases the Camera object and associated resources.

Camera

int TriggerLoopingCapture(FrameConfig& frameConfig)

Starts looping-frame capture.

Camera

void StopLoopingCapture()

Stops looping-frame capture.

Camera

int32_t TriggerSingleCapture(FrameConfig& frameConfig)

Starts single-frame capture.

CameraConfig

void SetFrameStateCallback(FrameStateCallback* callback, EventHandler* handler);

Sets a frame state callback to respond to state changes.

CameraConfig

static CameraConfig* CreateCameraConfig()

Creates a CameraConfig instance.

CameraAbility

std::list<Size> GetSupportedSizes(int format)

Obtains the supported image sizes for a specified image format.

CameraAbility

std::list<T> GetParameterRange(uint32_t key)

Obtains the parameter value range based on a specified parameter key.

CameraDevice

CameraDeviceCallback()

A constructor used to create a CameraDeviceCallback instance.

CameraDevice

void OnCameraStatus​(std::string cameraId, int32_t status)

Called when the camera device status changes.

CameraStateCallback

CameraStateCallback​()

A constructor used to create a CameraStateCallback instance.

CameraStateCallback

void OnConfigured​(Camera& camera)

Called when the camera is configured.

CameraStateCallback

void OnConfigureFailed​(Camera& camera,int32_t errorCode)

Called when the camera fails to be configured.

CameraStateCallback

void OnCreated​(Camera& camera)

Called when the camera is successfully created.

CameraStateCallback

void OnCreateFailed​(std::string cameraId,int32_t errorCode)

Called when the camera fails to be created.

CameraStateCallback

void OnReleased​(Camera& camera)

Called when the camera is released.

FrameStateCallback

FrameStateCallback​()

A constructor used to create a FrameStateCallback instance.

FrameStateCallback

void OnFrameFinished(Camera& camera, FrameConfig& frameConfig, FrameResult& frameResult)

Called when the frame capture is completed.

FrameStateCallback

void OnFrameError​(Camera& camera, FrameConfig& frameConfig, int32_t errorCode, FrameResult& frameResult)

Called when the frame capture fails.

FrameConfig

int32_t GetFrameConfigType()

Obtains the frame configuration type.

FrameConfig

std::list<OHOS::Surface> GetSurfaces()

Obtains a list of surface objects (shared memories).

FrameConfig

void AddSurface(OHOS::AGP::UISurface& surface);

Adds a surface.

FrameConfig

void RemoveSurface(OHOS::AGP::UISurface& surface);

Removes a surface.

Limitations and Constraints

None

How to Develop

  1. Extend the CameraDeviceCallback class and call OnCameraStatus to customize operations when the camera device changes, for example, when a camera becomes available or unavailable.

    class SampleCameraDeviceCallback : public CameraDeviceCallback {
        void OnCameraStatus(std::string cameraId, int32_t status) override
        {
            // Do something when camera is available or unavailable.
        }
    };
    
  2. Extend the FrameStateCallback class. After obtaining the frame data, save the data as a file.

    static void SampleSaveCapture(const char *p, uint32_t size)
    {
        cout << "Start saving picture" << endl;
        struct timeval tv;
        gettimeofday(&tv, NULL);
        struct tm *ltm = localtime(&tv.tv_sec);
        if (ltm != nullptr) {
            ostringstream ss("Capture_");
            ss << "Capture" << ltm->tm_hour << "-" << ltm->tm_min << "-" << ltm->tm_sec << ".jpg";
    
            ofstream pic("/sdcard/" + ss.str(), ofstream::out | ofstream::trunc);
            cout << "write " << size << " bytes" << endl;
            pic.write(p, size);
            cout << "Saving picture end" << endl;
        }
    }
    
    class TestFrameStateCallback : public FrameStateCallback {
        void OnFrameFinished(Camera &camera, FrameConfig &fc, FrameResult &result) override
        {
            cout << "Receive frame complete inform." << endl;
            if (fc.GetFrameConfigType() == FRAME_CONFIG_CAPTURE) {
                cout << "Capture frame received." << endl;
                list<Surface *> surfaceList = fc.GetSurfaces();
                for (Surface *surface : surfaceList) {
                    SurfaceBuffer *buffer = surface->AcquireBuffer();
                    if (buffer != nullptr) {
                        char *virtAddr = static_cast<char *>(buffer->GetVirAddr());
                        if (virtAddr != nullptr) {
                            SampleSaveCapture(virtAddr, buffer->GetSize());
                        }
                        surface->ReleaseBuffer(buffer);
                    }
                    delete surface;
                }
                delete &fc;
            }
        }
    };
    
  3. Extend the CameraStateCallback class and customize operations when the camera state changes (configuration successful or failed, and creation successful or failed).

    class SampleCameraStateMng : public CameraStateCallback {
    public:
        SampleCameraStateMng() = delete;
        SampleCameraStateMng(EventHandler &eventHdlr) : eventHdlr_(eventHdlr) {}
        ~SampleCameraStateMng()
        {
            if (recordFd_ != -1) {
                close(recordFd_);
            }
        }
        void OnCreated(Camera &c) override
        {
            cout << "Sample recv OnCreate camera." << endl;
            auto config = CameraConfig::CreateCameraConfig();
            config->SetFrameStateCallback(&fsCb_, &eventHdlr_);
            c.Configure(*config);
            cam_ = &c;
        }
        void OnCreateFailed(const std::string cameraId, int32_t errorCode) override {}
        void OnReleased(Camera &c) override {}
    };
    
  4. Create a CameraKit instance to set and obtain camera information.

    CameraKit *camKit = CameraKit::GetInstance();
    list<string> camList = camKit->GetCameraIds();
    string camId;
    for (auto &cam : camList) {
        cout << "camera name:" << cam << endl;
        const CameraAbility *ability = camKit->GetCameraAbility(cam);
        /* Find the camera that fits your ability. */
        list<CameraPicSize> sizeList = ability->GetSupportedSizes(0);
        if (find(sizeList.begin(), sizeList.end(), CAM_PIC_1080P) != sizeList.end()) {
            camId = cam;
            break;
        }
    }
    
  5. Create a Camera instance.

    EventHandler eventHdlr; // Create a thread to handle callback events.
    SampleCameraStateMng CamStateMng(eventHdlr);
    
    camKit->CreateCamera(camId, CamStateMng, eventHdlr);
    
  6. Based on the callback design in steps 1 to 3, perform related operations until the OnCreated callback obtains cam_.

    void OnCreated(Camera &c) override
    {
        cout << "Sample recv OnCreate camera." << endl;
        auto config = CameraConfig::CreateCameraConfig();
        config->SetFrameStateCallback(&fsCb_, &eventHdlr_);
        c.Configure(*config);
        cam_ = &c;
    }
    
    void Capture()
    {
        if (cam_ == nullptr) {
            cout << "Camera is not ready." << endl;
            return;
        }
        FrameConfig *fc = new FrameConfig(FRAME_CONFIG_CAPTURE);
        Surface *surface = Surface::CreateSurface();
        if (surface == nullptr) {
            delete fc;
            return;
        }
        surface->SetWidthAndHeight(1920, 1080); /* 1920:width,1080:height */
        fc->AddSurface(*surface);
        cam_->TriggerSingleCapture(*fc);
    }