The video output service provides configuration functionality for the video outputs on the STB. An STB can have zero or more HD outputs and zero or more SD outputs. Since most chipsets have one data path for SD and one for HD, it is good to think in these terms for configuration as well.
When configuring the video ouputs of the STB, the default video mode should always be configured for each output. This is the video mode that is used by default when the box boots up. This can later be overridden in some cirtumstances such as when using the adaptive video mode functionality.
Setting up the default video modes is done using a transaction session. The application creates a new session, sets up the new video modes, commits the session and finally releases it. The last part is very important, since only one session can exist at a time. If the application fails to release the session, it will not be possible to use any functionality related to changing video modes again. As for the commit, it should never fail since all error checking is done during the session. The reason for having such a transaction behavior is to enable easy rollback of configuration changes since different configuration combinations might not be possible due to hardware limitations.
While default video modes are being set up, the primary display should always be set first. This is to ensure that there are no limitations on this display. This might however put limitations on other displays if the hardware can not handle all possible combinations of settings for different displays. E.g. for the VIP19x0-0, if the component connector is set as primary output and enabled, the TV SCART can not be configured to RGB mode. If the TV SCART is already configured as RGB when the component connector is set as primary, the TV SCART will automatically be set to a valid value (e.g. composite) and signaled to the application in an event.
The outputs need to be configured only once. The settings are stored in persistent memory and applied when KreaTV is started after a reboot.
Note: If SCART loop through is enabled the SCART aspect ratio pin cannot be set since this will be controlled by the external device (ex. VCR).
It is important for the STB to know what the aspect ratio of the customers TV sets are in order to scale images properly, particularily when using the FollowPixelAspectRatio tag in AVM 2.0. This is true for all kinds of outputs. It is not advisable to rely on the EDID for this information, since it is not always accurate.
To set the aspect ratio of a display, use the setDisplayInfo function. The default values are ASPECT_RATIO_4_3 for SCART and ASPECT_RATIO_16_9 for HD outputs. Note that setDisplayInfo also overrides the available video modes for the display and sets WSS signalling for SCART. It is currently not possible to set the aspect ratio of a screen without also performing these other unrelated actions.
In the examples below, we assume that the STB have two video connectors only, one HDMI and one SCART. The examples are given in pseudo code.
In this example, HDMI is configured to 720p as default mode, and the SCART output is configured to use PAL-B color system. Note that it is not possible to explicitly configure the video mode on a SCART output. The actual "video mode" (number of horizontal lines and interlacing) on SCART is controlled by the chosen color system.
var session = toiVideoOutput.CreateVideoOutputSession();
hdmiOutputId = <find HDMI output using GetVideoOutputs() and GetVideoOutputInfo()>
scartOutputId = <find TV SCART output using GetVideoOutputs() and GetVideoOutputInfo()>
session.setPrimaryVideoOutput(hdmiOutputId);
// Ensure that the output format is supported, otherwise,
// SetDefaultVideoMode might fail.
hdmiDisplayInfo = session.getDisplayInfo(hdmiOutputId);
// EDID information for HDMI is given in
// hdmiDisplayInfo.supportedVideoModes
// If you do not trust the EDID, use SetDisplayInfo to override it for
// this configuration session
session.setDefaultVideoMode(hdmiOutputId, VIDEO_MODE_720P50);
session.setColorSpace(hdmiOutputId, DIGITAL_COLOR_SPACE_SRGB);
session.setDviMode(hdmiOutputId, VALUE_MODE_DISABLED);
session.setColorSystem(scartOutputId, COLOR_SYSTEM_PAL_B);
session.setScartMode(scartOutputId, SCART_MODE_RGB);
// Enable 16:9 SCART widescreen signaling and scaling
// (video mode is not configurable on SCART outputs as
// this is controlled by the color system)
session.setDisplayInfo(scartOutputId, new array(NO_VIDEO_MODE), ASPECT_RATIO_16_9);
session.apply();
The AVM 2.0 interface has replaced the old adaptive video mode. The two interfaces have very little in common, so any application developer who used the old adaptive video mode should read this section carefully.
In order to give the best user experience, the KreaTV software can be configured to use adaptive video mode rules. These rules depend on the main video window: the size and content of that window dictate which rules are active, and rules which affect the video transform are applied to that window.
Individual rules in the AVM 2.0 interface consist of a name, an output to apply the rule to, and two sets of data: conditions and actions. Conditions are used to determine which rules should be considered active, while actions describe the changes that are applied when a certain rule is active. Conditions are divided into two categories: content conditions, which include resolution, aspect ratio, framerate etc of the main window content, and window conditions, which is the fullscreen status of the main video window. Some of these conditions also have delta values to allow them to cover an arbitrarily wide range of cases. Actions are similarily divided into video mode changes, which affect the video mode on the output if possible, and transforms, which affect the way content is stretched or zoomed in the main video window. Note that a rule with an empty set of conditions will always be considered matches. This is useful for having a specified default behaviour in a rule set if no other rule matches the current variables.
Rules are organized into rule lists, where each list is meant to describe an overall strategy. For example, there may be a "Pillarboxing of 4/3 content" list or a "Fullscreen video in native resolution" list, each containing any number of rules. Each list can only have one active rule at a time and the rules are listed in priority. This means that if the first rule in a list matches and becomes active, all the other rules in that list are disregarded, because they cannot become active even if they match the current KreaTV state. Of course, those disregarded rules can still become active if the situation changes and the higher priority rule no longer matches the KreaTV state.
Rule lists are specified in XML formatted files. The application developer should have access to an XML schema which describes the entirety of the rule list format. Each rule list contains a name which is used to load these lists into the system via the TOI2 API. More on that later. The XML files themselves need to be included in the build procedure when compiling an SDK into a bootimage.
Several rule lists can be loaded into the system at the same time. If several of those lists have matching rules, the highest priority rule in each list will become active and the actions in each rule will be applied. The order in which the actions are applied is the same as the order in which the rule lists were loaded into the system. The order of application is only relevant if there are several lists whose active rules are in conflict with each other, such as two rules whose actions change the video mode on an HD output. In such an event, the action of the latter rule will override the action of the previous one, meaning that the end result will reflect the action of the active rule in the list which was loaded last.
A rule must contain one or more conditions. Only when all conditions are matched can the rule become active. Omitted conditions are considered irrelevant, which means that rules can be made more or less general as needed. The list of possible conditions are as follows:
These conditions are matched to the content shown in the main video window.
Contains the elements Width, Height, WidthDelta and HeightDelta, all of which must be specified when using this condition. If the content width is within Width +/- WidthDelta AND its height is within Height +/- HeightDelta, the condition is considered to be satisfied.
Contains single value, which is one of "4_3", "16_9" or "UNKNOWN". This condition matches the specified aspect ratio of the content stream, NOT the ratio between the content width and height.
Since many streams do not match either of these values, it is generally recommended to rely on PixelAspectRatio instead.
Contains two elements, FrameRate and Delta. If the framerate specified in the content stream lies within FrameRate +/- Delta, this condition is considered to be satisfied.
Contains a single boolean value which is compared to whether the content stream is progressive or not.
Short for Active Format Description, this condition matches the AFD of the content. If the content AFD is equal to the one given in this condition, the condition is considered to be satisfied. Possible values are:
Contains two integers, Numerator and Denominator, which describe the pixel aspect ratio of the stream. This is the aspect ratio of each individual pixel as it should be when the stream is displayed in whatever aspect ratio was originally intended. It is described as Source Aspect Ratio (SAR) by the MPEG2 standard (see Video Demystified p.597) and can be found in the Aspect_ratio_information field.
The PixelAspectRatio, together with the dimensions of the stream, determine the final aspect ratio of the video window. There is an Action described below for using this information to handle aspect ratio in an optimal way, but if there is a need for exceptional cases the PixelAspectRatio condition can be used.
These conditions are matched to the main video window itself, regardless of content.
Contains a single boolean value. It is compared to whether the main video window covers the entire screen or not. Note that SetVideoTransform does not necessarily affect this condition.
A rule must contain one or more actions. When the rule becomes active, these actions are applied. The list of possible actions are as follows:
Contains either a transform expressed with four elements X, Y, Width, Height or a FollowPixelAspectRatio element. The transform is expressed in floating point coordinates, which means that they will result in the same visual effect regardless of what content or video mode is shown. The video window is considered to be of size (1.0, 1.0), so a transform with values X=0.0, Y=0.0, Width=1.0 and Height=1.0 would represent the whole window. This transform is applied to the video window itself, reshaping it according to the supplied coordinates.
If FollowPixelAspectRatio is present the video window transform is set to display the video with correct aspect ratio based on the pixel aspect ratio coded in the stream and the aspect ratio of the display as set by setDisplayInfo.
Contains either a source transform with six elements: X, Y, Width, Height, AdjustX and AdjustY or a FollowDisplayExtension element. The first four elements of the source transform are expressed in relative floating point coordinates. They are similar to the DestinationTransform values, except that they are applied to the content instead of the video window. The four coordinates describe a rectangle on the content stream which is to be displayed in the window, which means that the source transform enables the application developer to cut out parts of the content.
The AdjustX and AdjustY values are expressed in integer pixel coordinates. These allow the application developer to cut away an exact number of pixels from the top and bottom or left and right sides of the content. This is typically useful for removing overscan pixels.
If FollowDisplayExtension is present the source transform is set according to the MPEG sequence display extension height and width coded in the stream.
Contains at least one VideoOutputMode element. Currently, only the first element is supported; later implementations should support prioritization of several VideoOutputMode elements. Until that is implemented, this action sets the video mode for the output to which the rule is applied to the value of the first element.
Sets the WSS in the vertical blanking interval (VBI) on the SCART output. The value can be any of 4_3, 14_9_LETTERBOX, 14_9_LETTERBOX_TOP, 16_9_LETTERBOX, 16_9_LETTERBOX_TOP, MORE_THAN_16_9_LETTERBOX, 14_9, 16_9 or FOLLOW_SCREEN_ASPECT_RATIO. The latter is default, which makes the WSS follow the aspect ratio for each screen as set via setDisplayInfo.
Contains the value signalled in pin 8 on the SCART output. The value can be either OFF, 16_9 or 4_3.
The operative part of the API is the LoadAdaptiveRuleSets function, which takes as argument a sequence of strings. This sequence is the sequence of rule lists mentioned above, where each string is the name of one particular rule list. Calling this function will immediately remove any previously loaded rule lists and load the provided rule list names instead. If no names are provided to the function, any existing rule lists are simply cleared.
The result of LoadAdaptiveRuleSets is persistent, which means that when rebooting the box, the same rule sets will be automatically loaded again - assuming the corresponding XML files have not been removed from the bootimage between reboots.
Two additional functions exist in the AVM 2.0 API: GetAvailabelRuleSets and GetLoadedRuleSets. The former function returns the sequence of names of the rule lists which are available for loading, and the latter does the same for the rule lists which are currently loaded.
As an example, the application or portal might want to configure the HDMI output in a kind of pass-through mode, where the video output mode is set to the closest approximation of the resolution of the content being showed in fullscreen mode. Do note that this example is not recommended for live use, simply because changing the video mode on a modern LCD TV set takes several seconds and this example would do that every time the resolution of content shown in fullscreen changes.
To implement this example, a rule list needs to be created with three different rules: one each for 576, 720 and 1080 video modes. The rules could be set up as follows (sans XML notation):
| 576 rule | 720 rule | 1080 rule | |
|---|---|---|---|
| Conditions | Fullscreen=yes ContentWidth=1000 +/- 1000 ContentHeight=576 +/- 72 |
Fullscreen=yes ContentWidth=1000 +/- 1000 ContentHeight=720 +/- 72 |
Fullscreen=yes |
| Actions | VideoMode=576p50 | VideoMode=720p50 | VideoMode=1080i50 |
When this list of rules is loaded, the system will first try to match the 576 rule. The ContentWidth is given a very large delta value to match any reasonable stream because we are not really interested in its actual value; it is only there because it is part of the same Condition as ContentHeight, so we can't have one without the other. If the 576 rule does not match, the 720 rule is evaluated. If that one does not match, we are probably watching a full HD stream, so we switch to 1080 if the video is shown in fullscreen.
When playing 4:3 content, the application or portal might want the content to be pillar boxed when displayed on HDMI. This can achieved by configuring the adaptive mode to display the video using only the center 4:3 region of the display.
To implement this example, a rule list with one single rule needs to be created. It might look as follows:
| 4:3 rule | |
|---|---|
| Conditions | ContentAspectRatio=4/3 |
| Actions | DestinationTransformX=0.125 DestinationTransformY=0.0 DestinationTransformWidth=0.75 DestinationTransformHeight=1.0 |
This rule will match any content with an aspect ratio of 4/3. It will move the left side of the image 1/8th of the screen to the right and squeeze it to 4/3rds of the screen width.
It's quite possible to combine several lists of rules to fulfill a more comprehensive set of needs. For example, the rule list in the pillar boxing example may be loaded along with the rule list in the pass-through example, resulting in a combined behaviour which sets the resolution to match the content and pillarboxes it if it has an aspect ratio of 4:3.
In a browser environment, if a temporary zoom mode is desired, meaning that the zoom mode shall be applied only at one time reset itself every time the content changes, the <videoplane> element needs to be used. E.g. if the application wants to set a zoom mode when the user presses a button, but the next time the content format changes it shall go back to "normal" again.
HTML:
<videoplane id="plane"></videoplane>
JavaScript:
document.getElementById('plane').setVideoTransform(-640, -360, 2560, 1440);
See also: TOI Video Output Service Interface
See also: AdaptiveVideoMode