Plfapi Connection Management

MG-R PlfApi Connection ManagementAppendix

MG-R

Software Document

PlfApi Connection Management

Antoine Op de Laak

Version 0.3(44)

July 2, 2008

Status: Proposal

Approved by:

1Introduction......

1.1Purpose......

1.2Scope......

1.3Notes......

1.4Open issues......

2Interface description......

2.1IPlfApiSourceId......

int SrcInvalid......

int SrcNone......

int SrcTuner......

int SrcFront......

int SrcAv1 – int SrcAv10......

int SrcHdmi1 – int SrcHdmi5......

int SrcUrl......

int SrcBolton......

int SrcSpdif1 – int SrcSpdif2......

int SrcAnalogLr1 – int SrcAnalogLr2......

2.2IPlfApiDesignatorId......

Nat32 DesignatorNone......

Nat32 DesignatorAll......

Nat32 DesignatorAnalog......

Nat32 DesignatorDigital......

Nat32 DesignatorMpeg2......

Nat32 DesignatorMpeg4......

Nat32 DesignatorWm......

Nat32 DesignatorJpg......

Nat32 DesignatorMp3......

2.3IPlfApiConnectionConfiguration......

int MonitorOutModeProcessed......

int MonitorOutModeUnprocessed......

int MediumCable......

int MediumTerrestrial......

FResult IsAssociateSoundInputAllowed (int source, int assoc, Bool* retval)......

FResult AssociateSoundInput (int source, int assoc)......

FResult GetAssociatedSoundInput (int source, int* assoc)......

FResult SetMonitorOutMode (int mode)......

FResult GetMonitorOutMode (int* mode)......

FResult SetTunerMedium (int medium)......

FResult EnablePcMode (int source, Bool ena)......

2.4IPlfApiSourceSetup......

FResult IsVideoSelectionAllowed (int winid, int source, Nat32 designator, Bool* retval).

FResult IsAudioSelectionAllowed (int audionodeid, int source, Nat32 designator, Bool* retval)

FResult SelectVideoSource (int winid, int source, Nat32 designator, Bool* retval)......

FResult SelectAudioSource (int audionodeid, int source, Nat32 designator, Bool* retval).

FResult GetCurrentVideoSelection (int winid, int* source, Nat32* designator)......

FResult GetCurrentAudioSelection (int audionodeid, int* source, Nat32* designator)....

FResult ApplySourceSettings (int winid, Bool* retval)......

2.5IPlfApiSourceSetupNotify......

void OnVideoSourceSelected (int winid, int source)......

void OnAudioSourceSelected (int audionodeid, int source)......

void OnSourceSettingsApplied (void)......

2.6IPlfApiDestinationSetup......

const int VideoOutputModeSingle......

const int VideoOutputModeDual......

const int VideoStream1......

const int VideoStream2......

const int DestinationVideoMain

const int DestinationVideoSub

const int DestinationAudioSpeaker

const int DestinationAudioHeadPhone

const int NoWindowId......

FResult SetVideoOutputMode (int mode, Bool* retval)......

FResult SetVideoCoordinates (int streamid, int ul_x, int ul_y, int lr_x, int lr_y, Bool* retval)

FResult SetDestination (int destid, int windowid, Bool IsBorder)......

FResult AttachClient (int destid, int windowid, Bool IsBorder)......

FResult DetachClient (int destid, int windowid)......

2.7IPlfApiDestinationSetupNotify......

void OnVideoOutputModeSet (int mode)......

void OnVideoCoordinatesSet (int streamid)......

3Scenarios......

3.1Startup......

3.1.1Destination setup......

3.1.2Initial source setup and connection configuration......

3.2Source selection......

3.2.1Tuner......

3.2.2Front / AvX / HdmiX......

3.2.3Url......

3.2.4Audio association......

3.2.5Monitor out mode......

4Appendix......

4.1ApplySourceSettings......

Revision History

Version / Date / By / Remarks
0.1 / 10072007 / Antoine Op de Laak / Initial version
0.2 / 01112007 / Antoine Op de Laak / Update after review 2721
0.3 / 02072008 / Antoine Op de Laak / Update after review 2862

1Introduction

1.1Purpose

This document describes the semantics, usage and the dynamic behavior of the connection management related PlfApi interfaces. The next interfaces will be described in this document:

IPlfApiSourceId
IPlfApiDesignatorId
IPlfApiConnectionConfiguration
IPlfApiSourceSetup
IPlfApiSourceSetupNotify
IPlfApiDestinationSetup
IPlfApiDestinationSetupNotify

1.2Scope

1.3Notes

In the sequence diagrams: the return value of functions is the output parameter retval rather than the FResult.
Single window scope
Single client scope

1.4Open issues

Difference master/slave setup
Elaborate on IsBorder client?

2Interface description

2.1IPlfApiSourceId

The interface IplfApiSourceId summarizes all sources that can be used in the interfaces IPlfApiConnectionConfiguration and IPlfApiSourceSetup. Below an overview of the defined sources is given. Note that the sources are grouped; the group IDs are used in the interface descriptions.

int SrcInvalid

Invalid source (source group ID I).

int SrcNone

Source none (source group ID II).

int SrcTuner

Tuner source (source group ID III).

int SrcFront

Front audio/video source, aka side input or Av0 (source group ID III).

int SrcAv1 – int SrcAv10

Analog audio/video source, Av1-Av10 (source group ID III).

int SrcHdmi1 – int SrcHdmi5

Digital audio/video sources, Hdmi1-hdmi5 (source group ID III).

int SrcUrl

Connectivity source (source group ID III).

int SrcBolton

Bolt-on source (source group ID III).

int SrcSpdif1 – int SrcSpdif2

Digital association source, spdif1 and spdif2 (source group ID IV).

int SrcAnalogLr1 – int SrcAnalogLr2

Analog association source, lr1 and lr2(source group ID IV).

2.2IPlfApiDesignatorId

The interface IPlfApiDesignatorId lists the designators which can be used when selecting a source. By default, plfApp does not need a designator (it knows what is in a source). For some sources however a designator is needed. The next designators are defined.

Nat32 DesignatorNone

Designator none.

Nat32 DesignatorAll

Mask for all designators.

Nat32 DesignatorAnalog

Analog designator (used with the Tuner source).

Nat32 DesignatorDigital

Digital designator (used with the Tuner source).

Nat32 DesignatorMpeg2

MPEG2 designator (used with the Url source).

Nat32 DesignatorMpeg4

MPEG4 designator (used with the Tuner/Url sources).

Nat32 DesignatorWm

Windows Media designator (used with the Url source).

Nat32 DesignatorJpg

JPG designator (used with the Url source).

Nat32 DesignatorMp3

MP3 designator (used with the Url source).

2.3IPlfApiConnectionConfiguration

This interface is resource unaware; hence no window ID is specified. If a resource gets a new owner, the connection configuration settings are inherited.

int MonitorOutModeProcessed

int MonitorOutModeUnprocessed

Indicates processed respectively unprocessed monitor output.

int MediumCable

int MediumTerrestrial

Indicates Tuner medium cable respectively Tuner medium terrestrial.

FResultIsAssociateSoundInputAllowed (int source, int assoc, Bool* retval)

Checks whether a particular sound input association with a source is allowed.

Parameters

sourceThe source to which the sound input is associated, one of the sources from Source group ID III.

assocThe sound input / associated source, one of the sources from Source IV (to associate). Use SrcNone to disassociate.

*retvalBool to indicate allowed or not.

Return value

FResult.

FResultAssociateSoundInput(int source, int assoc)

Associates a particular sound input association with a source. The association can be done for all sources at start-up time already, even if that source is not selected. Platform caches it, and applies the setting if the source is selected later on. If the source is already selected, the association is done immediately.

Parameters

sourceThe source to which the sound input is associated, one of the sources from Source group ID III.

assocThe sound input / associated source, one of the sources from Source group ID II (to de-associate) or IV (to associate).

Return value

FResult.

Remarks

The association must be allowed.

FResultGetAssociatedSoundInput(int source, int* assoc)

Returns the sound input that is associated to a source.

Parameters

sourceThe source to which the sound input is associated, one of the sources from Source group ID III.

*assocThe sound input / associated source, one of the sources from Source group ID II or IV.

Return value

FResult.

FResultSetMonitorOutMode (int mode)

Sets the monitor out mode to processed or unprocessed. If processed is selected, the currently selected video source for main destination is the same as the source for monitor out. If unprocessed is selected, the unprocessed tuner signal is the source for monitor out.

Parameters

modeThe mode of monitor out, MonitorOutModeProcessed or MonitorOutModeUnprocessed.

Return value

FResult.

FResult GetMonitorOutMode (int* mode)

Returns the current monitor out mode.

Parameters

*modeThe mode of monitor out, MonitorOutModeProcessed or MonitorOutModeUnprocessed.

Return value

FResult.

FResultSetTunerMedium (int medium)

Sets the Tuner medium, cable or terrestrial.

Parameters

mediumThe Tuner medium, MediumCable or MediumTerrestrial.

Return value

FResult.

FResultEnablePcMode (int source, Bool ena)

Enables or disables PC mode for a specific source.

Parameters

sourceThe source to which the sound input is associated, one of the sources from Source group ID III.

enaFALSE=disable PC mode, TRUE= enable PC mode.

Return value

FResult.

2.4IPlfApiSourceSetup

The interface IPlfApiSourceSetup is used to do source selection. It is used by the client applications, to connect a source to their destination:

Depending on winid, the source will be connected to the relevant output window (main or sub) as specified by destination setup.
Depending on audionodeid, audio will be connected to speaker or headphone as specified by destination setup. The audionodeid for headphone is not used; when selecting a source for speaker, this source is routed to speaker as well as headphone.

FResultIsVideoSelectionAllowed (int winid, int source, Nat32 designator, Bool* retval)

Checks whether the source/designator combination is a valid video selection.

Parameters

winidThe window ID on which the video selection is applicable.

sourceThe video source.

designatorThe video designator.

*retvalFALSE=not allowed, TRUE=allowed.

Return value

FResult.

FResultIsAudioSelectionAllowed (int audionodeid, int source, Nat32 designator, Bool* retval)

Checks whether the source/designator combination is a valid audio selection.

Parameters

audionodeidThe audio node ID on which the audio selection is applicable.

sourceThe audio source.

designatorThe audio designator.

*retvalFALSE=not allowed, TRUE=allowed.

Return value

FResult.

FResultSelectVideoSource (int winid, int source, Nat32 designator, Bool* retval)

Selects the video source/designator for this winid.

Parameters

winidThe window ID on which the video selection is applicable.

sourceThe video source.

designatorThe video designator.

*retvalFALSE=wait for notification, TRUE=synchronous.

Return value

FResult.

Remarks

The video source selection must be allowed.
If the function returns FALSE, no other call with the same winid may be done until the notification OnVideoSourceSelected() is received.

FResultSelectAudioSource (int audionodeid, int source, Nat32 designator, Bool* retval)

Selects the audio source/designator for this audionodeid.

Parameters

audionodeidThe audio node ID on which the audio selection is applicable.

sourceThe audio source.

designatorThe audio designator.

*retvalFALSE=wait for notification, TRUE=synchronous.

Return value

FResult.

Remarks

The audio source selection must be allowed.
If the function returns FALSE, no other call with the same audionodeid may be done until the notification OnAudioSourceSelected() is received.

FResultGetCurrentVideoSelection (int winid, int* source, Nat32* designator)

Observer function to get the current selected video source/designator for this winid.

Parameters

winidThe window ID of the requested source/designator.

*sourceThe current video source.

*designatorThe current video designator.

Return value

FResult.

FResultGetCurrentAudioSelection (int audionodeid, int* source, Nat32* designator)

Observer function to get the current selected audio source/designator for this audionodeid.

Parameters

audionodeidThe audio node ID of the requested source/designator.

*sourceThe current audio source.

*designatorThe current audio designator.

Return value

FResult.

FResultApplySourceSettings (int winid, Bool* retval)

The function ApplySourceSettings must be used to apply the source settings and the connection configuration settings to hardware (see Appendix 4.1 for more information).

Parameters

winidThe window ID.

*retvalFALSE=wait for notification, TRUE=synchronous

Return value

FResult.

Remarks

If the function returns FALSE, and another function call to ApplySourceSettings() is done and this function also returns FALSE, only 1 notification OnSourceSettingsApplied() should be expected.

2.5IPlfApiSourceSetupNotify

voidOnVideoSourceSelected (int winid, int source)

This function is sent whenthe corresponding SelectVideoSource() has returned FALSEandthe video source has been selected.

Parameters

winidThe window ID.

sourceThe video source which has been selected

voidOnAudioSourceSelected (int audionodeid, int source)

This function is sent when the corresponding SelectAudioSource() has returned FALSEandthe audio source has been selected.

Parameters

audionodeidThe audio node ID.

sourceThe audio source which has been selected

void OnSourceSettingsApplied (void)

This function is sent when the function ApplySourceSettings() has returned FALSEandthe source settings and the applicable connection configuration settings have been applied to the hardware.

2.6IPlfApiDestinationSetup

const int VideoOutputModeSingle

const int VideoOutputModeDual

Defines video output mode single window respectively video output mode dual window.

const int VideoStream1

const int VideoStream2

Defines video stream 1 (main) respectively video stream 2 (sub).

const int DestinationVideoMain

const int DestinationVideoSub

const int DestinationAudioSpeaker

const int DestinationAudioHeadPhone

These constants define the different destination IDs that can be used.

const int NoWindowId

Defines the “no window ID”.

FResultSetVideoOutputMode (int mode, Bool* retval)

This function sets the output mode to either single or dual window.

Parameters

modeVideo output mode, VideoOutputModeSingle or VideoOutputModeDual.

*retvalFALSE=wait for notification, TRUE=synchronous.

Return value

FResult.

Remarks

If the function returns FALSE, no other call to SetVideoOutputMode may be done until the notification OnVideoOutputModeSet() is received.

FResultSetVideoCoordinates (int streamid, int ul_x, int ul_y, int lr_x, int lr_y, Bool* retval)

This function sets for a particular stream ID the border window size and position. These coordinates are relative with regard to screen size: (0,0) is top left, (10000, 10000) is bottom right.

Parameters

streamidThe stream ID, VideoStream1 or VideoStream2.

ul_xUpper left x coordinate.

ul_yUpper left y coordinate.

lr_xLower right x coordinate.

lr_yLower right x coordinate.

*retvalFALSE=wait for notification, TRUE=synchronous.

Return value

FResult.

Remarks

If the function returns FALSE, no other call to SetVideoCoordinates() with the same stream IDmay be done until the notification OnVideoCoordinatesSet() is received for that stream ID.

FResultSetDestination (int destid, int windowid, Bool IsBorder)

This function sets the “master” client to a destination.If this function is called, the internal client administration is reset.

Parameters

destidThe destination ID, one of DestinationVideoMain, DestinationVideoSub, DestinationAudioSpeaker, DestinationAudioHeadPhone.

windowidThe window or audio node ID that must be related to the destination. The parameter NoWindowId can be used to free the destination.

IsBorderFALSE=not border client, TRUE=border client. In case the client is a border client plfApp will pass overscan and viewmode information to DirectFB (needed for video/graphics alignment).

Return value

FResult.

FResultAttachClient (int destid, int windowid, Bool IsBorder)

This function adds a “slave” client to a destination.

Parameters

destidThe destination ID, one of DestinationVideoMain, DestinationVideoSub, DestinationAudioSpeaker, DestinationAudioHeadPhone.

windowidThe window or audio node ID that must be related to the destination.

IsBorderFALSE=not border client, TRUE=border client. In case the client is a border client plfApp will pass overscan and viewmode information to DirectFB (needed for video/graphics alignment).

Return value

FResult.

FResultDetachClient (int destid, int windowid)

This function removes a client from a destination.

Parameters

destidThe destination ID, one of DestinationVideoMain, DestinationVideoSub, DestinationAudioSpeaker, DestinationAudioHeadPhone.

windowidThe window or audio node ID that must be removed from the destination.

Return value

FResult.

2.7IPlfApiDestinationSetupNotify

void OnVideoOutputModeSet (int mode)

This function is sent when the corresponding SetVideoOutputMode() has returned FALSEandthe video output mode has been selected.

Parameters

modeThe video output mode that has been set.

void OnVideoCoordinatesSet (int streamid)

This function is sent when the corresponding SetVideoCoordinates () has returned FALSEandthe video coordinates has been selected.

Parameters

streamidThe stream ID, VideoStream1 or VideoStream2.

3Scenarios

3.1Startup

3.1.1Destination setup

Notes:

The video output mode, which is set at [3], will become active after the first use case selection. This is the case after the initial source selection in [9]. See next paragraphs on source selection.

3.1.2Initial source setup and connection configuration

Notes:

The monitor out mode in [1] must be conncfg_MonitorOutModeProcessed orconncfg_MonitorOutModeUnprocessed.
The tuner medium in [3] must be conncfg_MediumCable or conncfg_MediumTerrestrial.
Typically, the function calls [5], [7] and [9] will be called for each source at startup.

3.2Source selection

3.2.1Tuner

This paragraph shows the source selection to Analog Tuner.

The source selection to Digital Tuner is equal to the source selection to Analog Tuner, except for the designator: instead of dsgid_DesignatorAnalog the designator dsgid_DesignatorDigital should be used.

3.2.2Front / AvX / HdmiX

The source selection to 1 of the external inputs Front / AvX / HdmiX is depicted in the next sequence diagram. As an example the source Front is used, the source selection to the other external inputs is comparableto this one (which means also the usage of dsgid_DesignatorNone).

3.2.3Url

The source selection to Url is depicted in the next diagram. In this case a source selection to an MPEG2 use case is visualized.

The next table gives an overview of the choice of designators in relation with the use case selection.

Use Case / SelectVideoSource / SelectAudioSource
source / designator / source / designator
MPEG2 / SrcUrl / DesignatorMpeg2 / SrcUrl / DesignatorMpeg2
MPEG4 / SrcUrl / DesignatorMpeg4 / SrcUrl / DesignatorMpeg4
Windows Media / SrcUrl / DesignatorWm / SrcUrl / DesignatorWm
Content Browsing / SrcUrl / DesignatorJpg / SrcUrl / DesignatorMp3

3.2.4Audio association

When a source selection is done plfApp will check whether the selected source has an audio association to be able to select the correct use case. An audio association can also change runtime when the user changes this in the menu. Two examples are given

User changes audio association of Av1, but current source selection is not Av1.

User changes audio association of Av1, which is also the current selected source.

3.2.5Monitor out mode

The monitor out mode selection is typically used when switching to a Canal+ channel. This paragraph explains the steps when switching to a scrambled Canal+ channel by giving an example when switching from channel 5 to channel 6. Channel 5 is a digital tuner channel, channel 6 is an analog Canal+ channel and the user has configured in the menu that Av1 is linked to channel 6.

The first sequence diagram depicts the first step when switching from channel 5 to channel 6. Note that the tuning itself is not depicted.

The Canal+ decoder now starts to decode the signal and when it succeeds, the decoder raises Pin8. This will cause a break-in. Now the Tv should switch over to Av1 (with the monitor output mode still on Unprocessed).

If now the user switches back to channel 5, the next diagram applies:

4Appendix

4.1ApplySourceSettings

The function ApplySourceSettings must be used to apply the source settings and the connection configuration settings to hardware. The reasons to only apply the connection configuration settings to hardware with this function are:

This will prevent plfApp from checking if there is a use case switch on all calls to AssociateSoundInput() and EnablePcMode(). Note that these functions will be called (typically at startup) for all sources.
In this case unnecessary use case switches can be avoided. This will be explained with an example: going from the Av1 source with unprocessed monitor out to Tuner with processed monitor out. Note that for plfApi this step can be done in 1 use case switch.

If a connection configuration setting is applied to hardware immediately, the sequence diagram looks as follows:

If a connection configuration setting is applied to hardware on ApplySourceSettings(), the sequence diagram looks as follows:

Version 0.3ProposalPage 1 of 21