Camera control

This guide explains camera behavior and management in PlanetKit, including:

• How PlanetKit internally determines when the camera turns on or off based on video transmission, active previews, and call state
• Camera functions that applications can control

Supported call type	Minimum SDK version
1-to-1 call, group call (conference)	PlanetKit 5.5

Camera on/off behavior

PlanetKit turns the camera on when at least one of the following conditions is met:

• Video is being transmitted to the remote peer.
• At least one camera preview is active.

The camera turns off only when neither condition is met.

Condition: One or more previews are active	Condition: Video is being transmitted	Result: Camera device status
No	No	Off
Yes	No	On
No	Yes	On
Yes	Yes	On

The following functions also affect the camera status:

• Initial video state
  • The initial video transmission state is controlled by the value of EInitialMyVideoState type property/parameter passed to MakeCall(), AcceptCall(), JoinConference(), or EnableVideo().
    • PLNK_INITIAL_MY_VIDEO_STATE_RESUME (default): Video starts active, camera turns on at call start.
    • PLNK_INITIAL_MY_VIDEO_STATE_PAUSE: Video starts paused, camera stays off until ResumeMyVideo() is called.
  • For more information on configuring the initial video state, see Initial video state.
• Hold/unhold
  • Calling Hold() turns the camera off and disables video transmission.
  • Calling Unhold() turns the camera back on and enables video transmission.
  • For more information on holding/unholding the call, see Call hold.
• Pause/resume video
  • Calling PauseMyVideo() turns the camera off and disables video transmission.
  • Calling ResumeMyVideo() turns the camera back on and enables video transmission.

note

In a 1-to-1 video call, when the callee enters the responder preparation status before the call is fully connected, PlanetKit may turn the camera on before video is transmitted to the network. PauseMyVideo() and ResumeMyVideo() toggle the camera normally during this phase, but actual video transmission only begins after preparation finishes.

Camera control functions

PlanetKit provides camera management APIs for enumerating, selecting, and configuring camera devices.

• Use PlanetKit::CameraController to switch cameras, start and stop previews, and handle camera-related events. Use PlanetKit::CameraInfo to configure capture resolution and frame rate.
• For focus control, use APIs of PlanetKit::CameraInfo.

Note

Focus control functionality is available in PlanetKit 7.1 or higher.

Enumerate and select a camera

Call GetCapturerInfo() to retrieve available cameras, then call ChangeCamera() to activate one.

auto pController = PlanetKit::PlanetKitManager::GetInstance()->GetCameraController();

PlanetKit::CameraInfoArray arrCameras;
pController->GetCapturerInfo(arrCameras);

for (const auto& pCamera : arrCameras) {
    std::wcout << L"Camera: " << pCamera->GetDeviceName() << std::endl;
}

// Select the first camera
if (!arrCameras.empty()) {
    pController->ChangeCamera(arrCameras[0]);
}

Set preferred resolution and frame rate

Configure SetPreferredResolution() and SetPreferredMaxFps() on a CameraInfo before or after calling ChangeCamera().

auto pCamera = arrCameras[0];

// Set preferred resolution (default: HD 1280x720)
pCamera->SetPreferredResolution(PlanetKit::PLNK_CAMERA_RESOLUTION_HD);

// Set preferred maximum FPS (default: device default)
pCamera->SetPreferredMaxFps(PlanetKit::PLNK_VIDEO_CAPTURE_FPS_30);

pController->ChangeCamera(pCamera);

Available ECameraResolution values are as follows:

Value	Dimensions
PLNK_CAMERA_RESOLUTION_VGA	640×480
PLNK_CAMERA_RESOLUTION_VGA_16_9	640×360
PLNK_CAMERA_RESOLUTION_HD	1280×720 (default)
PLNK_CAMERA_RESOLUTION_FHD	1920×1080

Available EVideoCaptureFps values are as follows:

Value	Frame rate
PLNK_VIDEO_CAPTURE_FPS_DEFAULT	Device default
PLNK_VIDEO_CAPTURE_FPS_5	5 fps
PLNK_VIDEO_CAPTURE_FPS_10	10 fps
PLNK_VIDEO_CAPTURE_FPS_15	15 fps
PLNK_VIDEO_CAPTURE_FPS_24	24 fps
PLNK_VIDEO_CAPTURE_FPS_30	30 fps (max)

Camera preview

You can start and stop a camera preview independently of a call using StartPreview() and StopPreview().

// Preview into a window handle
pController->StartPreview(hWnd);
pController->StopPreview(hWnd);

// Or preview into an IVideoReceiver
pController->StartPreview(pVideoReceiver);
pController->StopPreview(pVideoReceiver);

Handle device change events

Register an IVideoCaptureDeviceEvent to be notified when cameras are added or removed, or an error occurs.

class MyCameraDeviceEvent : public PlanetKit::IVideoCaptureDeviceEvent {
public:
    void OnDeviceAdded(PlanetKit::CameraInfoPtr pCameraInfo) override {
        std::wcout << L"Camera added: " << pCameraInfo->GetDeviceName() << std::endl;
    }

    void OnDeviceRemoved(PlanetKit::CameraInfoPtr pCameraInfo) override {
        std::wcout << L"Camera removed: " << pCameraInfo->GetDeviceName() << std::endl;
        // Switch to another camera if this was the active one
    }

    void OnCameraError(PlanetKit::ECameraControlResult eCameraControlResult) override {
        std::wcout << L"Camera error: " << eCameraControlResult << std::endl;
    }
};

auto pDeviceEvent = PlanetKit::MakeShared<MyCameraDeviceEvent>();
pController->RegisterDeviceEvent(pDeviceEvent);

// Deregister when no longer needed
pController->DeregisterDeviceEvent(pDeviceEvent);

Focus control

PlanetKit exposes focus APIs through PlanetKit::CameraInfo for cameras that support focus control. Focus settings are managed per CameraInfo instance, so each camera device has its own independent focus mode and manual focus value.

note

When GetCapturerInfo() is called, PlanetKit briefly activates each camera to query its focus capability and caches the result in CameraInfo. This means IsFocusModeSupported() returns accurate values immediately after GetCapturerInfo() returns, before ChangeCamera() is called. The brief activation during enumeration does not turn on the camera LED or trigger a "Camera On" notification.

Check focus support

Before calling any focus API, check whether the camera supports the desired focus mode. A fixed-focus camera returns false for all modes.

bool bAutoSupported   = pCamera->IsFocusModeSupported(PlanetKit::PLNK_FOCUS_MODE_AUTO);
bool bManualSupported = pCamera->IsFocusModeSupported(PlanetKit::PLNK_FOCUS_MODE_MANUAL);

if (!bAutoSupported && !bManualSupported) {
    // Fixed-focus camera — focus control is not available
}

Get and set focus mode

Use GetFocusMode() to read the current mode and SetFocusMode() to change it.

• On an active camera (the camera device is open and running), the change by SetFocusMode() takes effect on the next capture cycle without requiring a stop/start of the camera.
• If the camera is not active, the value is stored as a preferred setting and applied when the camera becomes active.

// Get current mode
PlanetKit::EFocusMode currentMode;
auto result = pCamera->GetFocusMode(currentMode);
if (result == PlanetKit::PLNK_FOCUS_CONTROL_RESULT_SUCCESS) {
    std::wcout << L"Current focus mode: " << currentMode << std::endl;
}

// Set to auto focus — enters auto mode and triggers autofocus in one call.
// Continuous-AF cameras focus continuously; one-shot AF cameras focus once.
if (bAutoSupported) {
    pCamera->SetFocusMode(PlanetKit::PLNK_FOCUS_MODE_AUTO);
}

// Set to manual focus — uses the last manual focus value
if (bManualSupported) {
    pCamera->SetFocusMode(PlanetKit::PLNK_FOCUS_MODE_MANUAL);
}

Get and set manual focus value

Use SetManualFocusValue() to set manual focus value and GetManualFocusValue() to get the current manual focus value.

• SetManualFocusValue() sets the manual focus value only. It does not change the focus mode.
• The manual focus value is a normalized 0–100 value that PlanetKit maps linearly to the camera's native focus range.

note

GetManualFocusValue() reads the value directly from the camera hardware, so it may differ from the last value set if another application changed it.

// Set manual focus value (0–100)
auto result = pCamera->SetManualFocusValue(50);
if (result != PlanetKit::PLNK_FOCUS_CONTROL_RESULT_SUCCESS) {
    // Handle: NOT_SUPPORTED, OUT_OF_RANGE, or INTERNAL_ERROR
}

// Get manual focus value
unsigned int nValue = pCamera->GetManualFocusValue();

Behavior of SetManualFocusValue() depending on state:

State	Effect
Current mode is MANUAL, camera active	Applied immediately on the next capture cycle
Current mode is AUTO, camera active	Stored internally; applied when SetFocusMode(MANUAL) is called
Camera not active	Stored as preferred value; applied when the camera becomes active if mode is MANUAL

Configure focus before starting the camera

Focus mode and value can be set on a CameraInfo while the camera is not active. PlanetKit applies the stored settings when the camera becomes active.

PlanetKit::CameraInfoArray arrCameras;
pController->GetCapturerInfo(arrCameras);
auto pCamera = arrCameras[0];

if (pCamera->IsFocusModeSupported(PlanetKit::PLNK_FOCUS_MODE_MANUAL)) {
    pCamera->SetManualFocusValue(50);                              // store preferred value
    pCamera->SetFocusMode(PlanetKit::PLNK_FOCUS_MODE_MANUAL);     // set mode to manual
}

pController->ChangeCamera(pCamera);   // camera starts in manual mode at value 50

Focus control result codes

GetFocusMode(), SetFocusMode(), and SetManualFocusValue() all return an EFocusControlResult. Check the return value to detect unsupported hardware or OS-level failures.

Code	Meaning
PLNK_FOCUS_CONTROL_RESULT_SUCCESS	Operation succeeded
PLNK_FOCUS_CONTROL_RESULT_NOT_SUPPORTED	Requested focus mode is not supported, or the camera has no focus control at all
PLNK_FOCUS_CONTROL_RESULT_OUT_OF_RANGE	Value passed to SetManualFocusValue() is outside 0–100
PLNK_FOCUS_CONTROL_RESULT_INTERNAL_ERROR	Underlying OS API call failed

Related APIs

APIs related to camera control are as follows:

Classes/interfaces

• CameraController
• CameraInfo
• IVideoCaptureDeviceEvent

Enums

• ECameraResolution
• EVideoCaptureFps
• EFocusMode
• EFocusControlResult
• ECameraControlResult

Methods

• CameraController::GetCapturerInfo()
• CameraController::ChangeCamera()
• CameraController::StartPreview()
• CameraController::StopPreview()
• CameraController::RegisterDeviceEvent()
• CameraController::DeregisterDeviceEvent()
• CameraInfo::GetDeviceName()
• CameraInfo::SetPreferredResolution()
• CameraInfo::SetPreferredMaxFps()
• CameraInfo::IsFocusModeSupported()
• CameraInfo::GetFocusMode()
• CameraInfo::SetFocusMode()
• CameraInfo::GetManualFocusValue()
• CameraInfo::SetManualFocusValue()

Events

• IVideoCaptureDeviceEvent::OnDeviceAdded
• IVideoCaptureDeviceEvent::OnDeviceRemoved
• IVideoCaptureDeviceEvent::OnCameraError

Related documents

• Initial video state
• 1-to-1 video call
• Group video call
• Enabling video call
• Call hold
• Responder preparation status
• Custom video source
• Virtual background