Version: 7.0

Presentation - Screen share

Presentation means sharing a screen of a user (presenter) to show a material such as slides to the other call peers. This page describes how to use the presentation function based on the call type.

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

Note

PlanetKit uses HD resolution in its presentation feature, so it can provide an optimized service when the client's network conditions meet or exceed the recommended bandwidth.

1-to-1 call presentation

To start or end a presentation in a 1-to-1 call, use StartMyScreenShare() or StopMyScreenShare() of PlanetKitCall.

The following table shows APIs related to screen share in a 1-to-1 call, where a counterpart means a peer to whom to show the presentation.

Presenter-side API	Description	Counterpart-side API	Description
`StartMyScreenShare()`	Starts screen share by a presenter	`OnPeerStartedScreenShare`	Screen share by a presenter has been started
-	-	`AddPeerScreenShareVideoView()`	Sets a view instance created by an application
`StopMyScreenShare()`	Ends screen share by the presenter	`OnPeerStoppedScreenShare`	Screen share by the presenter has been stopped
-	-	`RemovePeerScreenShareVideoView()`	Removes the view instance before release

After being notified by OnPeerStartedScreenShare that a presentation has started, the counterpart side must create a view instance and call AddPeerScreenShareVideoView() to let PlanetKit render the shared screen.

The presentation video data is automatically streamed to the peer.

1-to-1 call presentation flow

The following diagram shows the flow for starting a presentation in 1-to-1 calls.

The following diagram shows the flow for stopping a presentation in 1-to-1 calls.

When you call StopMyScreenShare(), you can set one of the reasons defined by application requirements. Allowed values are integers from 0 to 39, and you must define the reasons and values and use them consistently across applications on different platforms. If a valid reason is set, the OnPeerStoppedScreenShare event delivers this value.

Sample code

The following is sample code for the screen share feature in a 1-to-1 call.

Tip

For a more complete code example, refer to Screen share in a 1-to-1 call.

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

Group call presentation

To start or end a presentation in a group call, use StartMyScreenShare() or StopMyScreenShare() of PlanetKitConference.

The following table shows APIs related to screen share in a group call, where counterparts mean participants in a group call to whom to show the presentation.

Presenter-side API	Description	Counterpart-side API	Description
`StartMyScreenShare()`	Starts screen share by a presenter	`IConferenceEvent::OnPeerScreenShareUpdated` `IPeerControlEvent::OnScreenShareUpdated` (state=ENABLED)	Screen share by a presenter has been started
-	-	`PeerControl::SetScreenShareView()`	Sets a view instance created by an application
-	-	`PeerControl::StartScreenShare()`	Starts rendering the screen share video on a screen share view
`StopMyScreenShare()`	Ends screen share by the presenter	`IConferenceEvent::OnPeerScreenShareUpdated` `IPeerControlEvent::OnScreenShareUpdated` (state=DISABLED)	Screen share by the presenter has been stopped
-	-	`PeerControl::ClearScreenShareView()`	Removes the view instance before release
-	-	`PeerControl::StopScreenShare()`	Stops rendering the screen share video on a screen share view
`ChangeMyScreenShareDestination()` `ChangeMyScreenShareDestinationToMainRoom()`	Changes the destination subgroup of the screen share.	`IConferenceEvent::OnPeerScreenShareUpdated` `IPeerControlEvent::OnScreenShareUpdated` (state=ENABLED or DISABLED)	Screen share to a specific subgroup has been started or stopped

Note

You can use the methods of PeerControl to control screen share video on a peer's screen share view. For more information on how to use PeerControl, refer to the group call screen share code example.

After being notified by IConferenceEvent::OnPeerScreenShareUpdated or IPeerControlEvent::OnScreenShareUpdated that a presentation has started (state=ENABLED), the counterpart side must set the view with PeerControl::SetScreenShareView() and call PeerControl::StartScreenShare() to let PlanetKit render the shared screen.

Note

Unlike 1-to-1 calls, presentation video data is not automatically streamed to participants. Therefore, the counterpart side in group calls must call PeerControl::StartScreenShare() to receive the presentation video data.

Group call presentation flow

The following diagram shows the flow for starting a presentation in group calls.

The following diagram shows the flow for stopping a presentation in group calls.

The following diagram shows the flow for a user who joined after a presentation started in a group call.

Presentation within a subgroup

A presentation feature is available within a subgroup when the presenter subscribed to the subgroup with the "dataSession" attribute set to true. If the presenter starts a presentation within a subgroup scope, the presentation video data is only shared with the members of the subgroup.

To change the destination subgroup of the screen share, use ChangeMyScreenShareDestination() or ChangeMyScreenShareDestinationToMainRoom(). For more information, see Subgroup flow - Screen share.

Tip

PlanetKit supports the function to receive two screen share streams at the same time. Receiving two presentation videos might cause confusing UX or heavy traffic. However, it can be useful in relation to the subgroup feature.

For example, let's say the first presenter started a presentation to all participants, and the second presenter started a presentation within a subgroup scope. Subgroup members can choose to receive one of them or both by controlling PeerControl::StartScreenShare().

Sample code

The following is sample code for the screen share feature in a group call.

Tip

For a more complete code example, refer to Screen share in a group call

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

Desktop considerations

A desktop application allows the presenter to select either the full screen of the monitor or a window of an application. Therefore, applications on Windows and macOS must determine which screen to share before calling StartMyScreenShare(). PlanetKit provides a list of available screens for your application. For details, refer to the sample code.

To handle the view change by a presenter, such as running a slideshow, you must call the following method:

OS	Related API
macOS	`change(device:completion:)` of `PlanetKitScreen`
Windows	`ScreenShareController::StartScreenShareCapture()`

1-to-1 call presentation​

Related APIs​

1-to-1 call presentation flow​

Reason to stop screen share​

Sample code​

Starting screen share​

Stopping screen share​

Handling screen share events on the receiver side​

Rendering a screen share video on the receiver side​

Removing a screen share video on the receiver side​

Group call presentation​

Related APIs​

Group call presentation flow​

Reason to stop screen share​

Presentation within a subgroup​

Sample code​

Starting screen share​

Stopping screen share​

Changing screen share destination​

Handling screen share events on the receiver side​

Starting a screen share video on the receiver side​

Stopping a screen share video on the receiver side​

Desktop considerations​

Related documents​

Related code examples​

1-to-1 call presentation

Related APIs

1-to-1 call presentation flow

Reason to stop screen share

Sample code

Starting screen share

Stopping screen share

Handling screen share events on the receiver side

Rendering a screen share video on the receiver side

Removing a screen share video on the receiver side

Group call presentation

Related APIs

Group call presentation flow

Reason to stop screen share

Presentation within a subgroup

Sample code

Starting screen share

Stopping screen share

Changing screen share destination

Handling screen share events on the receiver side

Starting a screen share video on the receiver side

Stopping a screen share video on the receiver side

Desktop considerations

Related documents

Related code examples