プレゼンテーション - 画面共有
プレゼンテーションとは、発表者が他の参加者にスライドなどの資料を見せるために自分の画面を共有することを指します。ここでは、通話タイプによるプレゼンテーション機能の使い方について説明します。
| 対応する通話タイプ | SDKの最低バージョン |
|---|---|
| 1対1通話、グループ通話（カンファレンス） | PlanetKit 3.0 |
PlanetKitは、プレゼンテーション機能でHD解像度を使用しているため、クライアントのネットワーク条件が推奨帯域幅を上回っている場合に最適化されたサービスを提供できます。
1対1通話プレゼンテーション
発表者は、PlanetKitCallのStartMyScreenShare()とStopMyScreenShare()を呼び出し、プレゼンテーションを開始／終了するタイミングを決定します。
関連API
1対1通話で画面共有に関連するAPIは次のとおりです。カウンターパートとは、プレゼンテーションを見せるピアのことをいいます。
| 発表者側のAPI | 説明 | カウンターパート側のAPI | 説明 |
|---|---|---|---|
StartMyScreenShare() | 発表者が画面共有を開始する | OnPeerStartedScreenShare | 発表者の画面共有が開始される |
| - | - | AddPeerScreenShareVideoView() | アプリケーションが作成したビューインスタンスを設定する |
StopMyScreenShare() | 発表者が画面共有を終了する | OnPeerStoppedScreenShare | 発表者の画面共有が終了される |
| - | - | RemovePeerScreenShareVideoView() | 解除する前にビューインスタンスを除去する |
カウンターパート側では、OnPeerStartedScreenShareイベントを受け取ってプレゼンテーションが開始されたことが分かったら、必ずビューインスタンスを作成してAddPeerScreenShareVideoView()を呼び出し、PlanetKitに画面をレンダリングさせる必要があります。
プレゼンテーションビデオのデータは、ピアに自動でストリーミングされます。
1対1通話プレゼンテーションの流れ
1対1通話でプレゼンテーションを開始する流れは次のとおりです。
1対1通話でプレゼンテーションを中止する流れは次のとおりです。
画面共有終了の理由
StopMyScreenShare()を呼び出す際に、アプリケーションの要求事項で定義した理由のうち1つを設定できます。許容される値は0から39までの整数であり、理由と値を独自に定義し、異なるプラットフォームのアプリケーション間で一貫性をもって使用する必要があります。理由が有効な値に設定されている場合、OnPeerStoppedScreenShareイベントがこの値を渡します。
サンプルコード
1対1通話の画面共有機能に関するサンプルコードです。
より完全なサンプルコードは、1対1通話の画面共有を参照してください。
画面共有を開始する
// Start screen share
// pScreenShareInfo: Screen share information including capture source
void StartMyScreenShareExample(PlanetKit::PlanetKitCallPtr pCall, PlanetKit::ScreenShareInfoPtr pScreenShareInfo)
{
pCall->StartMyScreenShare(pScreenShareInfo, nullptr, [](void*, bool bSuccess) {
std::wcout
<< L"StartMyScreenShare result: " << (bSuccess ? L"true" : L"false")
<< std::endl;
});
}
画面共有を中止する
// Stop screen share
void StopMyScreenShareExample(PlanetKit::PlanetKitCallPtr pCall)
{
pCall->StopMyScreenShare(nullptr, [](void*, bool bSuccess) {
std::wcout
<< L"StopMyScreenShare result: " << (bSuccess ? L"true" : L"false")
<< std::endl;
});
}
// Stop screen share with specific reason
// nUserReason: User-defined reason code for stopping screen share
void StopMyScreenShareWithReasonExample(PlanetKit::PlanetKitCallPtr pCall, int nUserReason)
{
pCall->StopMyScreenShare(nUserReason, nullptr, [](void*, bool bSuccess) {
std::wcout
<< L"StopMyScreenShare result: " << (bSuccess ? L"true" : L"false")
<< std::endl;
});
}
受信者側で画面共有イベントを処理する
class CallEventListener : public PlanetKit::ICallEvent {
public:
...
void OnPeerStartedScreenShare(PlanetKitCallPtr pPlanetKitCall) override {
// This is called when the peer started screen share.
// Write you own code here.
}
void OnPeerStoppedScreenShare(PlanetKitCallPtr pPlanetKitCall, IntOptional nDisabledReason) override {
// This is called when the peer stopped screen share.
// Write you own code here.
}
}
受信者側で画面共有ビデオをレンダリングする
void RenderPeerScreenShareVideoExample(PlanetKit::PlanetKitCallPtr pCall, WindowHandle hScreenShareRenderWnd) {
pCall->AddPeerScreenShareVideoView(hScreenShareRenderWnd);
}
受信者側で画面共有ビデオを削除する
void RemovePeerScreenShareVideoExample(PlanetKit::PlanetKitCallPtr pCall, WindowHandle hScreenShareRenderWnd) {
pCall->RemovePeerScreenShareVideoView(hScreenShareRenderWnd);
}
グループ通話プレゼンテーション
発表者は、PlanetKitConferenceのStartMyScreenShare()とStopMyScreenShare()を呼び出し、プレゼンテーションを開始／終了するタイミングを決定します。
関連API
グループ通話で画面共有に関連するAPIは次のとおりです。カウンターパートとはグループ通話でプレゼンテーションを見せる参加者のことをいいます。
| 発表者側のAPI | 説明 | カウンターパート側のAPI | 備考 |
|---|---|---|---|
StartMyScreenShare() | 発表者が画面共有を開始する | IConferenceEvent::OnPeerScreenShareUpdatedIPeerControlEvent::OnScreenShareUpdated(state=ENABLED) | 発表者の画面共有が開始される |
| - | - | PeerControl::SetScreenShareView() | アプリケーションが作成したビューインスタンスを設定する |
| - | - | PeerControl::StartScreenShare() | 画面共有ビューで画面共有ビデオのレンダリングを開始する |
StopMyScreenShare() | 発表者が画面共有を終了する | IConferenceEvent::OnPeerScreenShareUpdatedIPeerControlEvent::OnScreenShareUpdated(state=DISABLED) | 発表者の画面共有が終了される |
| - | - | PeerControl::ClearScreenShareView() | 解除する前にビューインスタンスを除去する |
| - | - | PeerControl::StopScreenShare() | 画面共有ビューで画面共有ビデオのレンダリングを中断する |
ChangeMyScreenShareDestination()ChangeMyScreenShareDestinationToMainRoom() | 画面を共有する対象のサブグループを変更する | IConferenceEvent::OnPeerScreenShareUpdatedIPeerControlEvent::OnScreenShareUpdated(state=ENABLED または DISABLED) | 特定のサブグループへの画面共有が開始／終了される |
ピアの画面共有ビューで画面共有ビデオを制御するために、PeerControlのメソッドを使用することができます。画面共有ビデオ制御のためにPeerControlを使用する方法について詳しくは、グループ通話画面共有のサンプルコードを参照してください。
IConferenceEvent::OnPeerScreenShareUpdatedイベントまたはIPeerControlEvent::OnScreenShareUpdatedイベントを受信してプレゼンテーションが開始されたことが分かったら（state=ENABLED）、カウンターパート側では必ずPeerControl::SetScreenShareView()でビューを設定してPeerControl::StartScreenShare()を呼び出し、PlanetKitに画面をレンダリングさせる必要があります。
1対1通話とは異なり、プレゼンテーションのビデオデータを参加者に自動でストリーミングすることはありません。したがって、グループ通話のカウンターパート側は共有画面ビデオを受信するために、必ずPeerControl::StartScreenShare()を呼び出す必要があります。
グループ通話プレゼンテーションの流れ
グループ通話でプレゼンテーションを開始する流れは次のとおりです。
グループ通話でプレゼンテーションを中止する流れは次のとおりです。
グループ通話でプレゼンテーションが開始された後に参加したユーザーの流れは次のとおりです。
画面共有終了の理由
StopMyScreenShare()を呼び出す際に、アプリケーションの要求事項で定義した理由のうち1つを設定できます。許容される値は0から39までの整数であり、理由と値を独自に定義し、異なるプラットフォームのアプリケーション間で一貫性をもって使用する必要があります。理由が有効な値に設定されている場合、OnPeerScreenShareUpdatedとOnScreenShareUpdatedイベントがこの値を渡します。
サブグループ内のプレゼンテーション
「dataSession」プロパティをtrueに設定してサブグループに加入すると、サブグループ内でプレゼンテーションを使用できます。サブグループ範囲内でプレゼンテーションを開始すると、プレゼンテーションビデオのデータはサブグループメンバーだけに共有されます。
画面共有の対象となるサブグループを変更するには、ChangeMyScreenShareDestination()またはChangeMyScreenShareDestinationToMainRoom()を使用します。詳しくは、サブグループフロー - 画面共有を参照してください。
PlanetKitは同時に2つの画面を共有する機能を提供します。2つのプレゼンテーションビデオを受信すると、UXが混乱したり、トラフィックが多くなったりする可能性はありますが、サブグループ機能と連携して便利な使い方ができます。
たとえば、最初の発表者が参加者全員に対してプレゼンテーションを実施し、次の発表者がサブグループ範囲内でプレゼンテーションを実施するとします。サブグループのメンバーは、PeerControl::StartScreenShare()を調整して、いずれかの画面を受信するか、または両方とも受信するかを選択できます。
サンプルコード
グループ通話の画面共有機能に関するサンプルコードです。
より完全なサンプルコードは、グループ通話の画面共有を参照してください。
画面共有を開始する
// Start screen share to main room
// pScreenShareInfo: Screen share information including capture source
void StartMyScreenShareExample(PlanetKit::PlanetKitConferencePtr pConference, PlanetKit::ScreenShareInfoPtr pScreenShareInfo)
{
pConference->StartMyScreenShare(pScreenShareInfo, PlanetKit::NullOptional, nullptr, [](void*, bool bSuccess) {
std::wcout
<< L"StartMyScreenShare result: " << (bSuccess ? L"true" : L"false")
<< std::endl;
});
}
// Start screen share to specific subgroup
// strSubgroupName: Target subgroup name, or NullOptional for main room
void StartMyScreenShareToSubgroupExample(
PlanetKit::PlanetKitConferencePtr pConference,
PlanetKit::ScreenShareInfoPtr pScreenShareInfo,
const PlanetKit::WStringOptional& strSubgroupName
)
{
pConference->StartMyScreenShare(pScreenShareInfo, strSubgroupName, nullptr, [](void*, bool bSuccess) {
std::wcout
<< L"StartMyScreenShare(subgroup) result: " << (bSuccess ? L"true" : L"false")
<< std::endl;
});
}
画面共有を中止する
// Stop screen share
void StopMyScreenShareExample(PlanetKit::PlanetKitConferencePtr pConference)
{
pConference->StopMyScreenShare(nullptr, [](void*, bool bSuccess) {
std::wcout
<< L"StopMyScreenShare result: " << (bSuccess ? L"true" : L"false")
<< std::endl;
});
}
// Stop screen share with specific reason
// nUserReason: User-defined reason code for stopping screen share
void StopMyScreenShareWithReasonExample(PlanetKit::PlanetKitConferencePtr pConference, int nUserReason)
{
pConference->StopMyScreenShare(nUserReason, nullptr, [](void*, bool bSuccess) {
std::wcout
<< L"StopMyScreenShare result: " << (bSuccess ? L"true" : L"false")
<< std::endl;
});
}
画面共有のターゲットを変更する
// Change screen share destination to a specific subgroup
// strToSubgroupName: Target subgroup name to change to
void ChangeScreenShareDestinationExample(PlanetKit::PlanetKitConferencePtr pConference, const PlanetKit::WString& strToSubgroupName)
{
pConference->ChangeMyScreenShareDestination(strToSubgroupName, nullptr, [](void*, bool bSuccess) {
std::wcout
<< L"ChangeMyScreenShareDestination result: " << (bSuccess ? L"true" : L"false")
<< std::endl;
});
}
// Change screen share destination to main room
void ChangeScreenShareDestinationToMainRoomExample(PlanetKit::PlanetKitConferencePtr pConference)
{
pConference->ChangeMyScreenShareDestinationToMainRoom(nullptr, [](void*, bool bSuccess) {
std::wcout
<< L"ChangeMyScreenShareDestinationToMainRoom result: " << (bSuccess ? L"true" : L"false")
<< std::endl;
});
}
受信者側で画面共有イベントを処理する
class ConferenceEventListener : public PlanetKit::IConferenceEvent {
public:
...
void OnPeerScreenShareUpdated(ConferencePeerScreenShareUpdatedParamPtr pPeerScreenShareUpdateInfo) override {
// This is called when a peer's screen share state changes.
auto eState = pPeerScreenShareUpdateInfo->ScreenShareState();
if (eState == PlanetKit::EScreenShareState::PLNK_SCREEN_SHARE_STATE_ENABLED) {
std::wcout << L"Peer started screen share" << std::endl;
// Add your own code here
} else {
std::wcout << L"Peer stopped screen share" << std::endl;
// Add your own code here
}
}
}
class PeerControlEventListener : public PlanetKit::IPeerControlEvent {
public:
...
void OnScreenShareUpdated(
PeerControlPtr pPeerControl,
SubgroupPtr pSubgroup,
EScreenShareState eState,
IntOptional nDisabledReason
) override {
// This is called when the peer's screen share state changes.
if (eState == PlanetKit::EScreenShareState::PLNK_SCREEN_SHARE_STATE_ENABLED) {
std::wcout << L"Peer screen share enabled" << std::endl;
// Add your own code here
} else {
std::wcout << L"Peer screen share disabled" << std::endl;
// Add your own code here
}
}
}
受信者側で画面共有ビデオを開始する
class YourApplication {
public:
void StartPeerScreenShareVideoExample(PlanetKit::PeerControlPtr pPeerControl, PlanetKit::SubgroupPtr pSubgroup) {
auto callback = [](void* pUserData, bool bSuccess) {
YourApplication* pApp = (YourApplication*)pUserData;
if(bSuccess == true) {
// Render peer's screen share.
pApp->m_pScreenSharePeerControl->SetScreenShareView(m_hScreenShareRenderWnd);
}
}
// You can keep instance of PeerControl for the peer who is performing screen share.
m_pScreenSharePeerControl = pPeerControl;
// Start peer's screen share.
pPeerControl->StartScreenShare(pSubgroup->GetSubgroupName(), this, callback);
}
private:
PlanetKit::PeerControlPtr m_pScreenSharePeerControl;
}
受信者側で画面共有ビデオを中止する
class YourApplication {
public :
void StopPeerScreenShareVideoExample() {
// Remove render.
m_pScreenSharePeerControl->ClearScreenShareView();
// Request to stop screen share.
m_pScreenSharePeerControl->StopScreenShare(nullptr, [](void*, bool bSuccess) {
std::wcout
<< L"StopScreenShare result: " << (bSuccess ? L"true" : L"false")
<< std::endl;
});
}
}
デスクトップに関する考慮事項
デスクトップアプリケーションでは、発表者がモニターの全画面表示またはアプリケーションウィンドウを選択できます。したがって、WindowsおよびmacOSのアプリケーションでは、StartMyScreenShare()を呼び出す前にどの画面を共有するかを決定する必要があります。使用できる画面リストはPlanetKitが提供します。サンプルコードでその内容が確認できます。
発表者がスライドショーを実行するなど、ビューを変更する時は次のようなAPIを呼び出す必要があります。
| OS | 関連API |
|---|---|
| macOS | PlanetKitScreenのchange(device:completion:) |
| Windows | ScreenShareController::StartScreenShareCapture() |