カメラ制御

このガイドでは、PlanetKitにおけるカメラの動作と管理について説明します。

• ビデオ送信、アクティブなプレビュー、通話状態に基づいてPlanetKitが内部的にカメラのオン/オフを決定する仕組み
• アプリケーションが制御できるカメラ機能

対応通話タイプ	最小SDKバージョン
1対1通話、グループ通話（カンファレンス）	PlanetKit 5.5

カメラのオン/オフ動作

PlanetKitは、以下の条件のうち少なくとも1つが満たされた場合にカメラをオンにします。

• リモートピアにビデオが送信されている。
• 少なくとも1つのカメラプレビューがアクティブである。

カメラがオフになるのは、どちらの条件も満たされていない場合のみです。

条件：1つ以上のプレビューがアクティブ	条件：ビデオが送信中	結果：カメラデバイスの状態
いいえ	いいえ	オフ
はい	いいえ	オン
いいえ	はい	オン
はい	はい	オン

以下の機能もカメラの状態に影響します。

• ビデオの初期状態
  • 初期ビデオ送信状態は、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()はGetCapturerInfo()が返った直後、ChangeCamera()が呼び出される前に正確な値を返します。列挙中の一時的なアクティベーションによって、カメラ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()は手動フォーカス値のみを設定します。フォーカスモードは変更しません。
• 手動フォーカス値は0〜100の正規化された値で、PlanetKitはこれをカメラのネイティブフォーカス範囲に線形にマッピングします。

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ビデオ通話
• グループビデオ通話
• ビデオ通話の有効化
• 通話の一時停止
• 応答者の準備状態
• カスタムビデオソース
• バーチャル背景