카메라 제어

이 가이드에서는 PlanetKit의 카메라 동작 및 관리 방법을 설명합니다.

• 비디오 전송, 미리보기 상태, 통화 상태에 따라 PlanetKit이 내부적으로 카메라 켜짐/꺼짐을 결정하는 방식
• 애플리케이션에서 제어할 수 있는 카메라 기능

지원 통화 유형	최소 SDK 버전
1대1 통화, 그룹 통화(컨퍼런스)	PlanetKit 5.5

카메라 켜짐/꺼짐 동작

PlanetKit은 다음 조건 중 하나 이상이 충족되면 카메라를 켭니다.

• 원격 피어에게 비디오가 전송 중인 경우
• 하나 이상의 카메라 미리보기가 활성화된 경우

카메라는 두 조건 모두 충족되지 않을 때만 꺼집니다.

조건: 하나 이상의 미리보기가 활성화됨	조건: 비디오가 전송 중임	결과: 카메라 장치 상태
아니오	아니오	꺼짐
예	아니오	켜짐
아니오	예	켜짐
예	예	켜짐

다음 기능도 카메라 상태에 영향을 줍니다.

• 초기 비디오 상태
  • 초기 비디오 전송 상태는 MakeCall(), AcceptCall(), JoinConference(), 또는 EnableVideo()에 전달되는 EInitialMyVideoState 유형의 속성/파라미터 값으로 제어합니다.
    • PLNK_INITIAL_MY_VIDEO_STATE_RESUME(기본값): 비디오가 활성 상태로 시작되며, 통화 시작 시 카메라가 켜집니다.
    • PLNK_INITIAL_MY_VIDEO_STATE_PAUSE: 비디오가 일시 정지 상태로 시작되며, ResumeMyVideo()가 호출될 때까지 카메라가 꺼진 상태를 유지합니다.
  • 초기 비디오 상태 설정에 관한 자세한 내용은 초기 비디오 상태를 참조하세요.
• 통화 일시 중지/재개
  • Hold()를 호출하면 카메라가 꺼지고 비디오 전송이 비활성화됩니다.
  • Unhold()를 호출하면 카메라가 다시 켜지고 비디오 전송이 활성화됩니다.
  • 통화 일시 중지/재개에 관한 자세한 내용은 통화 일시 중지를 참조하세요.
• 비디오 일시 정지/재개
  • PauseMyVideo()를 호출하면 카메라가 꺼지고 비디오 전송이 비활성화됩니다.
  • ResumeMyVideo()를 호출하면 카메라가 다시 켜지고 비디오 전송이 활성화됩니다.

Note

1대1 영상 통화에서 수신자가 통화가 완전히 연결되기 전에 응답자 준비 상태에 진입하면, PlanetKit은 비디오가 네트워크에 전송되기 전에 카메라를 켤 수 있습니다. 이 단계에서도 PauseMyVideo()와 ResumeMyVideo()는 카메라를 정상적으로 끄거나 켜지만, 실제 비디오 전송은 준비가 완료된 후에만 시작됩니다.

카메라 제어 기능

PlanetKit은 카메라 장치 목록 조회, 선택, 설정을 위한 카메라 관리 API를 제공합니다.

• 카메라 전환, 미리보기 시작/종료, 카메라 관련 이벤트 처리에는 PlanetKit::CameraController를 사용하세요. 캡처 해상도 및 프레임 레이트 설정에는 PlanetKit::CameraInfo를 사용하세요.
• 포커스 제어에는 PlanetKit::CameraInfo의 API를 사용하세요.

Note

포커스 제어 기능은 PlanetKit 7.1 이상 버전에서 사용 가능합니다.

카메라 목록 조회 및 선택

GetCapturerInfo()를 호출하여 사용 가능한 카메라를 조회한 후, ChangeCamera()를 호출하여 카메라를 활성화합니다.

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]);
}

선호 해상도 및 프레임 레이트 설정

ChangeCamera()를 호출하기 전후에 CameraInfo에서 SetPreferredResolution()과 SetPreferredMaxFps()를 설정합니다.

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);

사용 가능한 ECameraResolution 값은 다음과 같습니다.

값	크기
PLNK_CAMERA_RESOLUTION_VGA	640×480
PLNK_CAMERA_RESOLUTION_VGA_16_9	640×360
PLNK_CAMERA_RESOLUTION_HD	1280×720(기본값)
PLNK_CAMERA_RESOLUTION_FHD	1920×1080

사용 가능한 EVideoCaptureFps 값은 다음과 같습니다.

값	프레임 레이트
PLNK_VIDEO_CAPTURE_FPS_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(최대)

카메라 미리보기

StartPreview()와 StopPreview()를 사용하여 통화와 독립적으로 카메라 미리보기를 시작하고 중지할 수 있습니다.

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

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

장치 변경 이벤트 처리

카메라가 추가되거나 제거될 때, 또는 오류가 발생할 때 알림을 받으려면 IVideoCaptureDeviceEvent를 등록합니다.

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);

포커스 제어

PlanetKit은 포커스 제어를 지원하는 카메라에 대해 PlanetKit::CameraInfo를 통해 포커스 API를 제공합니다. 포커스 설정은 CameraInfo 인스턴스별로 관리되므로, 각 카메라 장치는 독립적인 포커스 모드 및 수동 포커스 값을 갖습니다.

Note

GetCapturerInfo()가 호출되면 PlanetKit은 각 카메라를 잠깐 활성화하여 포커스 기능을 조회하고 그 결과를 CameraInfo에 캐시합니다. 따라서 IsFocusModeSupported()는 ChangeCamera()가 호출되기 전, GetCapturerInfo()가 반환된 직후에 정확한 값을 반환합니다. 조회 중 잠깐 활성화되는 동작은 카메라 LED를 켜거나 "카메라 켜짐" 알림을 발생시키지 않습니다.

포커스 지원 여부 확인

포커스 API를 호출하기 전에 카메라가 원하는 포커스 모드를 지원하는지 확인하세요. 고정 포커스 카메라는 모든 모드에 대해 false를 반환합니다.

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
}

포커스 모드 조회 및 설정

현재 모드를 읽으려면 GetFocusMode()를, 변경하려면 SetFocusMode()를 사용합니다.

• 카메라가 활성화된 상태(카메라 장치가 열려 있고 작동 중인 경우)에서 SetFocusMode()로 변경하면, 카메라를 중지했다가 다시 시작하지 않아도 다음 캡처 사이클에 변경이 적용됩니다.
• 카메라가 활성 상태가 아닌 경우, 값은 선호 설정으로 저장되며 카메라가 활성화될 때 적용됩니다.

// 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);
}

수동 포커스 값 조회 및 설정

수동 포커스 값을 설정하려면 SetManualFocusValue()를, 현재 수동 포커스 값을 조회하려면 GetManualFocusValue()를 사용합니다.

• SetManualFocusValue()는 수동 포커스 값만 설정합니다. 포커스 모드는 변경하지 않습니다.
• 수동 포커스 값은 PlanetKit이 카메라의 네이티브 포커스 범위에 선형적으로 매핑하는 0–100의 정규화된 값입니다.

Note

GetManualFocusValue()는 카메라 하드웨어에서 직접 값을 읽으므로, 다른 애플리케이션이 값을 변경한 경우 마지막으로 설정한 값과 다를 수 있습니다.

// 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();

상태에 따른 SetManualFocusValue()의 동작은 다음과 같습니다.

상태	효과
현재 모드가 MANUAL이고 카메라가 활성 상태	다음 캡처 사이클에 즉시 적용됨
현재 모드가 AUTO이고 카메라가 활성 상태	내부적으로 저장되며, SetFocusMode(MANUAL) 호출 시 적용됨
카메라가 활성 상태가 아님	선호 값으로 저장되며, 모드가 MANUAL인 경우 카메라가 활성화될 때 적용됨

카메라 시작 전 포커스 설정

카메라가 활성 상태가 아닐 때 CameraInfo에 포커스 모드와 값을 설정할 수 있습니다. PlanetKit은 카메라가 활성화될 때 저장된 설정을 적용합니다.

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

포커스 제어 결과 코드

GetFocusMode(), SetFocusMode(), SetManualFocusValue()는 모두 EFocusControlResult를 반환합니다. 지원되지 않는 하드웨어나 OS 수준의 오류를 감지하려면 반환 값을 확인하세요.

코드	의미
PLNK_FOCUS_CONTROL_RESULT_SUCCESS	작업 성공
PLNK_FOCUS_CONTROL_RESULT_NOT_SUPPORTED	요청한 포커스 모드가 지원되지 않거나, 카메라에 포커스 제어 기능이 없음
PLNK_FOCUS_CONTROL_RESULT_OUT_OF_RANGE	SetManualFocusValue()에 전달된 값이 0–100 범위를 벗어남
PLNK_FOCUS_CONTROL_RESULT_INTERNAL_ERROR	기본 OS API 호출 실패

관련 API

카메라 제어와 관련된 API는 다음과 같습니다.

클래스/인터페이스

• CameraController
• CameraInfo
• IVideoCaptureDeviceEvent

열거형

• ECameraResolution
• EVideoCaptureFps
• EFocusMode
• EFocusControlResult
• ECameraControlResult

메서드

• 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()

이벤트

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

관련 문서

• 초기 비디오 상태
• 1대1 영상 통화
• 그룹 영상 통화
• 영상 통화 활성화
• 통화 일시 중지
• 응답자 준비 상태
• 커스텀 비디오 소스
• 가상 배경