Skip to main content

MPEOS Disp clarifications

7 replies [Last post]
Joined: 2010-02-19

I am confused on the operation of some of the mpeos disp APIs. There is little to no documentation describing their operation in relation to values returned by other APIs. Inspecting the reference implementation offers no help as there are no comments. In some cases, the APIs are left not implemented. Comments in the header files as well as the mpeos porting guide offer no help.

First, the API mpeos_mpeos_dispGetCurVideoOutputConfiguration passes a type mpe_DispVideoConfig for *currConfig. No where is this type returned on any get call, nor is it explained anywhere what its value represents. It appears to be a handle when looking at the header files. The companion call, mpeos_dispSetCurVideoOutputConfiguration, also uses this type, but the reference implementation is missing.

The only connection I can make for what this "handle" should be relates back to the API mpeos_dispGetSupportedFixedVideoOutputConfigurations. The mpeos_dispGetCurVideoOutputConfiguration API above in the reference implementation seems to return a pointer to one of the actual structures in the array of mpe_DispFixedVideoOutputConfigInfo structures returned by the mpeos_dispGetSupportedFixedVideoOutputConfigurations call.

Is this what the type mpe_DispVideoConfig is supposed to represent?

How does the mpeos_dispSetCurrConfig API work with respect to the mpeos_dispSetCurVideoOutputConfiguration API?

If dynamic configurations are supported by the STB, there does not appear to be a complementary set/get APIs that allow for setting and getting the configuration/mappings as returned by the mpeos_dispGetSupportedDynamicVideoOutputConfigurations API.


Reply viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
Joined: 2009-04-11

From the bottom up...
Much of the device settings apis in the RI are stubbed/mocked at the RI_Platform layer, which is to say that although the apis are present, calls to them result in no action and/or returns of hard coded data.
The hardcoded data structures are declared in mpeos_disp.c, beginning at approximately line 381.

The structures are hard coded and look something like:
gVideoResolutionInfoSD -->|
gVideoResolutionInfoHD ----|-->gFixedConfigArray---->gDynamicVideoConfigurationMappings-->gDynamicConfigArray-->gVideoOutputConfigInfo

with the "final" result being that gVideoOutputConfigInfo contains the following:
mpe_DispFixedVideoOutputConfigInfo* fixedConfigs; /* array of fixed configs */ points to gFixedConfigArray
mpe_DispDynamicVideoOutputConfigInfo* dynamicConfigs; /* array of dynamic configs */ points to gDynamicConfigArray

/* what is being used now */
mpe_DispVideoConfig curConfig; points to gFixedConfigArray[0], cast to a mpe_DispVideoConfig

So, for the RI, mpe_DispVideoConfig curConfig is a pointer to a mpe_DispFixedVideoOutputConfigInfo.
During "bootstrap" initialization (see org_cablelabs_impl_ocap_hardware_device_VideoOutputSettingsProxy.c, Java_org_cablelabs_impl_ocap_hardware_device_VideoOutputSettingsProxy_nInitValues) this handle is used in the call to VideoOutputSettingsProxy_setCurrOutputConfigUsingHandle (which is the Java VideoOutputSettingsProxy.setCurrOutputConfigUsingHandle). This function expects the passed in handle to index a previously constructed VideoOutputConfiguration - the configurations were added earlier in the bootstrap process, and, of course, the current video configuration matches a previously added (fixed) configuration.

From the RI stack (Java/jni portion of the RI) perspective, a mpe_DispVideoConfig is an opaque pointer - it doesn't care what it points to. The RI stack only uses the pointer/handle to act as an index.

Because the RI_Platform stubs/mocks the actual implementation of the Device Settings extensions, a more meaningful definition of a mpe_DispVideoConfig is not currently necessary. The only important part is that the handle/pointer/index matchup to a previously constructed VideoOutputConfiguration (in the RI's case via a jni called back member function, addFixedConfig).

Does that help?

Joined: 2010-02-19

I am afraid that this does not clear it up. I refer readers to the first post in this thread for a description of what was being asked. I will try to summarize below:

1) There is little to no documentation describing the handles returned by mpeos disp APIs. Nor is there any information on how the handles returned in one call are used in other calls. Once specific example is the type mpe_DispVideoConfig. No where is this value returned explicitly. Instead, it appears to be the index, or perhaps a pointer (?) into an array that was returned by another "get" call?

2) How does the mpeos_dispSetCurrConfig API work with respect to the mpeos_dispSetCurVideoOutputConfiguration API?

3) How are dynamic configurations, those returned by mpeos_dispGetSupportedDynamicVideoOutputConfigurations, used. There does not appear to be any explicit "set" call like mpeos_dispSetCurVideoOutputConfiguration.


Joined: 2009-04-11

1) The reason there is no documentation is because most handles (I'm not sure about all of them) are opaque - the exact interpretation is up to the platform. In the specific case of mpe_DispVideoConfig, the platform populates (through a jni call) a hash of allowed configurations. The mpe_DispVideoConfig is the key into that hash. The stack does not perform any interpretation of said value.

2) Currently, mpeos_dispSetCurVideoOutputConfiguration is stubbed - it has no effect (and doesn't, to my knowledge, interact with mpeos_dispSetCurrConfig). The implementation of mpeos_dispSetCurrConfig has a comment that indicates that it will return an error unless the configuration is unchanging. Not sure about that...

3) I can only refer you to the OCAP Device Settings Extension, OC-SP-OCAP-DS-EXT-I03-091217:

5.2.4 Dynamic configuration of video output port setting
An OCAP host MAY support automatically setting the video output resolution for a video output port based on the
video resolution/aspect ratio of the input video. This functionality MAY be used by applications to use the zoommode
settings of a TV connected to the video output port instead of using the zoom-mode settings of the STB. This
functionality is available only on a main Video Output Port. When resolution of the video output port is
dynamically changed, the aspect ratio of the HScreen and the resolution of HScreen devices are also changed,
according to the rules specified in Section 5.2.3 of this specification.

And, in the Javadoc:
Class DynamicVideoOutputConfiguration
An instance of this class may be used to represent a dynamic selection of video output configurations based upon
specified input video. An instance of DynamicVideoOutputConfiguration would mainly be used to allow
for the HScreen resolution and the video output port resolution to closely match the resolution of the input video,
generally with the intention of letting the display monitor connected to the output port manage aspect ratio
Such configurations are only valid for the current main video output port for a given HScreen. If a video output
port is not the current main output port or ceases to be the main, then this configuration setting SHALL be
effectively ignored and output resolution settings SHALL revert to an implementation-specific configuration.
Application of the input-to-output video resolution mapping described by an instance of
DynamicVideoOutputConfiguration MAY result in configuration changes for the component
HScreenDevices of the relevant HScreen as if the output resolution were selected via a static

I believe that there is no "set" because supported configurations are determined by the platform - the stack is allowed to choose between the previously determined (set by the platform via jni) allowed/supported configurations. Again, this code is entirely mocked/stubbed. I do not currently know of any implementation using the Dynamic Video Output configuration capabilities....

Joined: 2010-04-29

In /ri/RI_Stack/java/src/base/org/cablelabs/impl/havi/package.html there is the following reference:
For additional information, please see:
* CableLabs HAVi Porting Guide
I have been unable to locate this file. Is this still in existence and valid? If so, where can we get it?

Joined: 2008-04-23

This is a (misleading) reference to the old Vidiom Porting Guide, located here:
Vidiom was changed to CableLabs in the Renaming process we performed on a previous release of the RI.

To repeat a point made elsewhere in this Forum, the information in this document is several years out of date, and unfortunately there are no project resources available currently to do an update of it.

Joined: 2009-04-11

I'm working up a somewhat more detailed description of how this works in the RI. Its just taking a little longer than I anticipated. Stay tuned...

Joined: 2010-01-05

I just want to add a thank you in advance.