Roku SDK Documentation : Specifying Display Resolution

Table of Contents


SceneGraph applications allow you to specify an intended display screen resolution for your user interface application. But SceneGraph applications also automatically scale the screen elements for screen displays and Roku players that do not support the intended screen resolution. This gives you greater control of the appearance quality of your application than in previous Roku firmware, and allows you to design your application for full high-definition display resolution.

SceneGraph Display Resolution Scaling Support

The following describes how SceneGraph applications support different display screen resolutions.

Supported Screen Resolutions

Roku players support up to three screen resolutions for the application user interface, depending on the specific Roku player.  Please note that SD only channels are not supported on Roku.

ResolutionPixel DimensionsPixel Shape
Full high-definition1920 x 1080square
High-definition1280 x 720square
Standard definition720 x 480non-square

Automatic Screen Element Scaling

SceneGraph applications can automatically scale screen elements, such as fonts and rectangles, to any specified supported resolution. This scaling is controlled by specifying the screen resolutions the application is intended to support. If support is only specified for high-definition, and not full high-definition, then the screen elements are scaled from 720 resolution to 1080 resolution if needed for the display resolution. If support is only specified for full high-definition, and not high definition, then the screen elements are scaled from 1080 resolution to 720 resolution if needed for the display resolution.

Automatic Selection of Supported Graphical Image Resolutions

SceneGraph applications can automatically select graphical images based on the supported resolution. The firmware can modify a special URI string with a variable that gets the correct graphical image for each supported and specified resolution. If this special URI string is not specified, the firmware will automatically scale graphical images to the display resolution from the specified intended resolution.

Recommended Intended Resolution

For SceneGraph applications, Roku recommends you design and develop for an intended 1080 screen resolution. But for performance reasons, for Roku players and display screens that do not support full high-definition resolution, you should supply both 1080 and 720 graphical images for your application. The SceneGraph application will scale the design elements and the graphical images for the actual supported resolution, but you can achieve the best appearance for all supported resolutions if you provide both resolutions of graphical images. If you can only provide one resolution of graphical images, provide 720 graphical images.

Manifest File Screen Resolution Specification

You specify the intended support for various screen display resolutions in special manifest file attributes for SceneGraph applications. The following describes the manifest file attributes to specify the supported screen resolutions for SceneGraph applications.

AttributeTypeDescriptionExample

ui_resolutions

option list string

A comma-separated list of up to three strings that identify the UI resolutions the application has been designed to support. The string can include the following options:

OptionSupport
sdApplications designed for standard definition displays (480)
hdApplications designed for high-definition displays (720)
fhdApplications designed for full high-definition displays (1080)

The example shows how to specify that the application is intended for all three possible supported resolutions, and will automatically scale and select graphical images (if provided) for all three. The default value is sd,hd.

sd,hd,fhd

 

uri_resolution_autosuboption list string

Provides a flexible way to specify graphical image URIs that are automatically modified to replace a specified string with a string that gets a resolution-specific graphical image.

The attribute value is a comma-separated list of four strings that specify the string to be replaced along with the replacement strings for SD, HD and FHD resolutions.

For example, suppose the manifest includes this line:

uri_resolution_autosub=$$RES$$,SD,720p,1080p

And the Roku player supports full high-definition resolution. Then if the application specifies a URI of:

http://www.roku.com/testChannel/assets/$$RES$$/rokuTV.jpg

At runtime that URI will be modified to:

http://www.roku.com/testChannel/assets/1080p/rokuTV.jpg

And the application will get the full-high definition version of the graphical image in the specified directory.

$$RES$$,SD,HD,FHD
splash_screen_fhduriURI of the FHD version of the splash screen."pkg:/images/sge_fhd_splash.jpg"
mm_icon_focus_fhduriURI of the FHD application icon."pkg:/images/sge_fhd_icon.jpg"

Autoscaling Guidelines

When creating layouts of visual components that take advantage of the Roku SceneGraph ability to autoscale layouts from one screen resolution to another (such as, from FHD/1080p to HD/720p), the best results will be obtained if you use the following simple rule.

When designing for FHD, positioning items on 3-pixel boundaries, and specifying width, height, and spacing values that are divisible by three will produce the best results. This allows each of those values to be autoscaled to integer values in HD, since the FHD to HD scaling factor is 2/3. This minimizes visual anomalies due to floating point rounding errors.

Similarly, when designing for HD, positioning items on 2-pixel boundaries, and specifying width, height, and spacing values that are divisible by two will produce the best results. This allows each those values to be autoscaled to integer values in FHD, since the HD to FHD scaling factor is 1.5.

Failing to follow these rules may result in some minor visual artifacts during animations when running at the autoscaled screen resolution. This is most noticeable when a user scrolls through grids by holding down a remote control direction pad key. The sizes and spacing between adjacent items may vary by one pixel as the grid items scroll across the screen.

In general, these visual anomalies are minimal, but following these simple guidelines will lead to better results. And of course, if you want precise control of the screen layouts in both resolutions, you can create separate layouts for HD and FHD, and set ui_resolutions=HD,FHD in the application manifest file.