프레젠테이션 - 화면 공유

프레젠테이션이란 발표자가 다른 참여자에게 슬라이드 같은 자료를 보여주기 위해 자신의 화면을 공유하는 것을 말합니다. 이 페이지에서는 통화 유형에 따라 프레젠테이션 기능을 사용하는 방법을 설명합니다.

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

Note

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()를 호출할 때 애플리케이션 요구사항으로 정의한 이유 중 하나를 설정할 수 있습니다. 허용되는 값은 0부터 39까지의 정수이며, 직접 이유와 값을 정의하고 서로 다른 플랫폼의 애플리케이션에서 일관되게 사용해야 합니다. 이유가 유효한 값으로 설정된 경우 OnPeerStoppedScreenShare 이벤트가 이 값을 전달합니다.

샘플 코드

1대1 통화의 화면 공유 기능에 대한 샘플 코드입니다.

Tip

더 완전한 예제 코드는 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::OnPeerScreenShareUpdated IPeerControlEvent::OnScreenShareUpdated (state=ENABLED)	발표자의 화면 공유가 시작됨
-	-	PeerControl::SetScreenShareView()	애플리케이션이 생성한 뷰 인스턴스를 설정
-	-	PeerControl::StartScreenShare()	화면 공유 뷰에 화면 공유 비디오 렌더링 시작
StopMyScreenShare()	발표자가 화면 공유 종료	IConferenceEvent::OnPeerScreenShareUpdated IPeerControlEvent::OnScreenShareUpdated (state=DISABLED)	발표자의 화면 공유가 종료됨
-	-	PeerControl::ClearScreenShareView()	해제 전에 뷰 인스턴스 제거
-	-	PeerControl::StopScreenShare()	화면 공유 뷰에서 화면 공유 비디오 렌더링 중지
ChangeMyScreenShareDestination() ChangeMyScreenShareDestinationToMainRoom()	화면을 공유할 대상 서브그룹 변경	IConferenceEvent::OnPeerScreenShareUpdated IPeerControlEvent::OnScreenShareUpdated (state=ENABLED 또는 DISABLED)	특정 서브그룹으로의 화면 공유가 시작되거나 종료됨

Note

피어의 화면 공유 뷰에서 화면 공유 비디오를 제어하기 위해 PeerControl의 메서드를 사용할 수 있습니다. 화면 공유 비디오 제어를 위해 PeerControl을 사용하는 방법에 대한 자세한 내용은 그룹 통화 화면 공유 예제 코드를 참조하세요.

IConferenceEvent::OnPeerScreenShareUpdated 이벤트 또는 IPeerControlEvent::OnScreenShareUpdated 이벤트를 받아 프레젠테이션이 시작되었음을 알게 되면(state=ENABLED), 카운터파트 측에서는 반드시 PeerControl::SetScreenShareView()로 뷰를 설정하고 PeerControl::StartScreenShare()를 호출해 PlanetKit이 화면을 렌더링하게 해야 합니다.

Note

1대1 통화와 달리 프레젠테이션 비디오 데이터를 자동으로 참여자들에게 스트리밍하지 않습니다. 따라서 그룹 통화의 카운터파트 측에서는 공유 화면 비디오를 수신하기 위해 반드시 PeerControl::StartScreenShare()를 호출해야 합니다.

그룹 통화 프레젠테이션 흐름

그룹 통화에서 프레젠테이션을 시작하는 흐름은 다음과 같습니다.

그룹 통화에서 프레젠테이션을 중지하는 흐름은 다음과 같습니다.

그룹 통화에서 프레젠테이션이 시작된 후 참여한 사용자의 흐름은 다음과 같습니다.

화면 공유 종료 이유

StopMyScreenShare()를 호출할 때 애플리케이션 요구사항으로 정의한 이유 중 하나를 설정할 수 있습니다. 허용되는 값은 0부터 39까지의 정수이며, 직접 이유와 값을 정의하고 서로 다른 플랫폼의 애플리케이션에서 일관되게 사용해야 합니다. 이유가 유효한 값으로 설정된 경우 OnPeerScreenShareUpdated와 OnScreenShareUpdated 이벤트가 이 값을 전달합니다.

서브그룹 내 프레젠테이션

dataSession 속성을 true로 설정하고 서브그룹에 가입하면 서브그룹 내에서 프레젠테이션을 사용할 수 있습니다. 서브그룹 범위 내에서 프레젠테이션을 시작하면 프레젠테이션 비디오 데이터는 서브그룹 멤버에게만 공유됩니다.

화면 공유 대상 서브그룹을 변경하려면 ChangeMyScreenShareDestination() 또는 ChangeMyScreenShareDestinationToMainRoom()을 사용하세요. 자세한 내용은 서브그룹 흐름 - 화면 공유를 참조하세요.

Tip

PlanetKit은 동시에 2개 화면을 공유받는 기능을 지원합니다. 프레젠테이션 비디오를 2개 받으면 UX가 혼란스러워지거나 트래픽이 많아질 수 있지만, 서브그룹 기능과 관련해서 유용하게 쓸 수 있습니다.

예를 들어, 첫 번째 발표자가 모든 참여자에게 프레젠테이션을 진행하고, 두 번째 발표자가 서브그룹 범위로 프레젠테이션을 진행한다고 생각해 봅시다. 서브그룹 멤버는 PeerControl::StartScreenShare()를 조절해서 그중 한 화면을 받거나 둘 다 받는 것을 선택할 수 있습니다.

샘플 코드

그룹 통화의 화면 공유 기능에 대한 샘플 코드입니다.

Tip

더 완전한 예제 코드는 그룹 통화 화면 공유를 참조하세요.

화면 공유 시작하기

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

수신자 측에서 화면 공유 이벤트 처리하기

Using IConferenceEvent

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
        }
    }
}

Using IPeerControlEvent

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

관련 문서

• 그룹 통화 흐름
• 서브그룹 흐름

관련 예제 코드

• 1대1 통화 화면 공유
• 그룹 통화 화면 공유