Roku Design and Performance Considerations

The following limitations and restrictions apply because of limitations with the Roku BrightScript language and the limited resources provided by some Roku devices. Keep them in mind if you are designing an app to run on Roku devices.

General Considerations

• Render order is determined using a different method on Roku and it’s not completely compatible with the method used by You.i Platform. Although the You.i AE Exporter attempts to translate between both formats, You.i TV recommends the following:
  • Keep adjacent all layers that have a layout.
  • When parenting a set of layers to another layer, keep the parent layer below and adjacent to the child layers and keep the child layers adjacent to each other.
• The Cloud Solution currently exports only in the HD screen resolution for the Roku apps.

Font Considerations

General Considerations

• All fonts used by the Cloud Solution server must be in the components directory of the Roku client in order to be used. If a font loaded on the server isn’t present on the client, the text won’t render, and there’s no fallback.
• Animations that scale a font may be visually unappealing.

Supported Fonts

The Roku client supports TrueType (.ttf) and OpenType (.otf) fonts only.

Memory Considerations

• Loading a single font with many sizes may not save memory when substituting some of these fonts with different ones, because each member and size of a font family allocates its own block of texture memory when loaded.
• Observed texture memory allocated per font family and per size ranges from ~32KB to ~88KB, which is minimal when compared to the texture memory available on the low-end Roku devices. To observe the texture memory allocated by fonts and images at a given moment, connect your device via telnet on port 8080 and run the r2d2_bitmaps command.
• The Roku client supports loading and rendering of any number of fonts. Using many fonts seems to have minimal impact on texture memory usage.
• Fonts are loaded into texture memory on the Roku client whenever they’re set to render. Therefore, only the fonts currently used in your scene should be loaded.
  • Each style and size of font loaded allocates texture memory.
  • Loading Arial-Regular with a font size of 32 and Arial-Regular with a font size of 30 loads the font twice into texture memory. The amount of memory allocated depends on the size of the font (20pt might allocate 32kb, where 40pt might allocate 64kb).

Cloud Solution Server and Roku Client Differences

• Roku doesn’t support True Type Collection (.ttc) font files.

  • If the Cloud Solution server references a .ttc font file, the Roku client searches for a .ttf equivalent based on the style used. For example, yi_Arial.ttc loaded with the regular style results in a search for yi_Arial-Regular.ttf on the Roku client.

  • If your project uses any .ttc font files, unpack them into .ttf files and place them into the Roku client’s components directory instead of the .ttc files. Ensure that the unpacked .ttf files match the naming convention used for the .ttc file. For example, yi_Helvetica-Regular.ttc loaded with the bold oblique style will be referenced by yi_Helvetica-Regular-Bold Oblique.ttf on the Roku client.

• Fonts may render differently on the server and the client. Some sizes may differ enough that the text height needs some padding to accommodate how it renders on the Roku client. Text rendering also seems to differ among devices.
  • An example of a font which has been observed to render differently is yi_Zapfino-Regular.ttf. This font only renders one or two lines of text on the Roku client, while three lines are rendered on the Cloud Solution server and don’t render at all when the Cloud Solution server is set to render two lines. In such cases, it’s best to experiment with different heights for your text node to find one which looks correct on all Roku clients.
• Some fonts styles may not appear the same on the Roku client as they appear on the Cloud Solution server. Bold fonts have been observed to appear very similar to their regular counterpart when set to smaller font sizes.

Layout Considerations

• In general, Roku supports only row layout (horizontal lists), column layout (vertical lists), and grid layout. However some of these layouts may not be available depending on the particulars of your app.
• Dynamic layout support is limited. A row layout or column layout exports as a BrightScript LayoutGroup by default. None of the per-item attributes (such as gravity, margin, padding, and so on) are supported.
• Arbitrary rotations other than 0, 90, 180, 270 degrees aren’t supported on some Roku hardware, and so can’t be used.
• After Effects 3D (2.5D) rotations aren’t supported.
• Turning off clipping isn’t supported except for lists in the scrolling direction.

List Considerations

• A Roku list can use only one template. If needed, separate a list into multiple lists, one for each template used. Lists of lists are an exception. The individual child lists can use only one template each. The template can vary from child list to child list. The parent list can use multiple templates.
• An ideal Roku list item template consist of 2-4 views.
• Each list item template must contain only one PushButtonView.
• Lists on Roku always hard clip items that exceed the top boundary. Ensure list item layouts don’t exceed the bounds of the root list composition.
• Padding between list items isn’t supported. You.i TV recommends you create empty space within the list item template.
• No items should exceed the boundaries of the root list composition. For example, don’t animate any element outside the root list composition boundary. Although there is no clipping in between list items, adjacent list items can overlap in undesirable ways if boundaries are exceeded. For example, a gradient image may overlap an adjacent list item if its width is too large.
• List item views for a given list must be of the same size.
• ImageNodeIn animations on list items should be removed in AE.
• You.i TV recommends using non-animated scrolling when scrolling across many list items, as animated scrolling causes a poor user experience.

Text Considerations

Text scaling is supported other than the following use cases:

• Text can be scaled directly or via its parent when done as a property update, however text scaling through animations has some rendering issues.
• Scaling a single text node in a hierarchy works with any scale value, but certain combinations may cause problems when multiple nodes are scaled. For example, TextNodeScale: 1.5 and ParentNodeScale: 1.5 will result in an error. You can try one of the following ways to resolve the error:
  • Reduce the number of text nodes with non-one scales — that is, nodes with their scale changed in at least one axis, such as {1.2, 1.0, 1.0}.
  • Make slight adjustments to the scale of nodes in a hierarchy, such as TextNodeScale: 1.5 and ParentNodeScale: 1.49.
• Modifying a text node’s x and y scales to different values isn’t supported. For example, don’t set a text node’s scale to {1.2, 2.2, 1.0} as it may cause issues in text rendering, positioning, or font size calculations.
• Scaling nodes in a scene causes rendering issues for text nodes, especially if multiple parent nodes are scaled.

The same text displayed in the server renders with a different size on the Roku client. This happens for the following reasons:

• The Roku client renders the same size text slightly larger than the server-side text renderer. There can be rendering differences between various supported Roku devices as not every Roku device uses the same renderer. For example, the Roku 3 device renders text differently than the Roku Ultra device.
• The server application renders scaled fonts, but the Roku client doesn’t. You have to multiply the scale into the font size on the Roku client. The resulting font size is then rounded to the nearest integer because fractional font sizes are not supported by Roku devices.

In most cases, rendering size differences will be less than 0.5 font size. If scaled text is avoided, the rendering differences are smaller.

Text Input Considerations

The Roku Cloud Solution supports both the PinPad and ParentalControlPinPad nodes.

The ParentalControlPinPad is a variant of the PinPad that enables the password mode. Both nodes allow entering a fixed-length numeric string.

The Roku Cloud Solution supports these nodes through the following API calls of CYITextEditView.

PinPad:

m_pTextEditView->SetInputType(CYIKeyboardInputBridge::InputType::Number);

ParentalControlPinPad:

 m_pTextEditView->EnablePasswordMode(true);
 m_pTextEditView->SetInputType(CYIKeyboardInputBridge::InputType::Number);

To open the numeric keyboard, you must call EnablePasswordMode before SetInputType. Otherwise, a regular QWERTY keyboard will open.

Animation Considerations

• Except for FocusIn and FocusOut, AE animations for list items are not supported. In particular, ImageNodeIn animations on list items should be removed in AE. Transitioning through list items triggers focus animations to be played locally on the Roku device. All other AE animations are ignored.

  Note: You.i TV recommends that you avoid using unsupported AE animations. For example, if you use an unsupported animation for opacity, the animated element may never become visible.

• Playing an animation in reverse is supported.
• For performance reasons, we recommend you keep animations simple on Roku. For more information, see Roku Performance FAQ.
• The XML files, which are part of Roku Component Library and used for export, contain Focus animations only.
• Stop(), Pause(), Abort(), and Seek() are not supported.

• As promises complete immediately on Cloud Solution instead of waiting for animation to finish, chaining animations are not supported on Cloud Solution. For example, the following chaining animation is not supported on Cloud Solution:

  this.outTimeline.play().then(() => this.inTimeline.play());
  

Static Asset Considerations

• PNG images with transparency that were exported from Sketch may present a thin black edge. Export the PNG images from Photoshop as non-interlaced and with no compression.

Shader Considerations

• The use of shaders to implement visual effects isn’t supported. For example:
  • You can’t use a blurred dynamic asset as a background image. Use a blurred static image for the background instead.
  • You can’t use a shader to tint the color of visual elements (such as icons or a progress bar). Use static images of different colors instead.

Roku Onscreen Keyboard Focus Considerations

• If the user moves focus to beyond the keyboard, focus moves to the background screen. For example, if focus is on the Return key on the onscreen keyboard and the Down arrow is pressed on the Roku remote, the keyboard is exited and focus shifts to the item beneath the keyboard. This is a known issue. Once focus exits the keyboard, the parent screen takes over and updates the focus.

Performance Considerations

Note the following:

• To improve performance, don’t export your navigation overlay to the client until the first screen that needs navigation is exported.
• Static assets (that is, images that are normally bundled with the app) downloaded from AWS S3 can degrade performance. You.i TV recommends that you reduce the number of large images to improve performance.
• Having large bitmaps (for example, 1920x1080) in a scene (either as static assets or from data models) can cause performance issues and deplete the memory of low-end Roku devices to such an extent that crashes occur when loading the scene. If such crashes occur, remove the large bitmaps or downsize them.
• Very large scenes (for example, with 3,000 lines of exported Component Library XML) can fail to load on the low-end Roku devices. In these cases, remove nodes from the scene by simplifying it.
• Visual elements consisting of multiple nodes (for example, button borders made out of four separate rectangles) incur a much larger load-time and run-time cost on Roku devices. Avoid such elements; use a single solid or texture instead.
• Some Roku devices (for example, Roku Express) have severe performance limitations. Avoid long animations for button focus state changes. For example, 333-ms focusIn animations make the app feel more sluggish.
• Excessive use of animations can lead to performance issues.

• Performance issues may be caused by the use of threads within an application. Thread ownership and the concept of rendezvous is important. To connect to the Roku Debug server and turn on rendezvous logging:

    telnet <roku device ip> 8080
  
    > enhanced_dev_log rendezvous on
  

VRAM Performance Considerations

High VRAM use can cause performance issues with some Roku hardware. Roku has built-in tools to check how VRAM is being used. You.i TV recommends that you use these tools regularly throughout development to ensure no problems are introduced. Do not leave this until problems become apparent, because at that point it can be much harder to find the root cause.

The best way to improve VRAM use is to request smaller images from the back-end service. This is especially useful for Roku because it has a 720p UI instead of 1080p, so images are rendered at 2/3 the resolution by default. Also avoid large images that can instead be stretched (gradients, for example). Another significant contributor to VRAM use is text. On devices with a GPU, the text atlas is cached, so each unique font and font size results in a large texture being kept in VRAM. Use the You.i AE Preview tool to help profile asset memory usage.

Performance Considerations for Lists

Consider the following when designing lists:

• Screens with many lists (for example, more than seven) result in noticeably increased load times on lower-end Roku devices. You.i TV recommends that you follow Roku guidance: design for high-end devices and then gracefully degrade the experience for low-end hardware. Avoid designing screens with many lists for lower-end Roku devices.
• A single list with multiple rows loads faster than multiple lists each having a single row. Multi-row lists are supported only when using a grid layout.
• Dense list item templates slow down low-end Roku devices. You may need to simplify list items to contain fewer nodes in these cases. In particular, minimize overdraw by reducing the number of large views.
• Dynamic layout on list item views degrades performance, particularly if you have many lists and list items.
• Reduce the amount of text and use the same font and font size throughout a given list item template.
• Avoid overdraw. (Overdraw refers to drawing the same pixel multiple times. For example, if a scene includes a full-screen solid covered by a full-screen image, there’s a full screen of overdraw as the base solid was not necessary.)
  • Overdraw incurs a performance penalty on Roku devices in general, and on Roku devices without GPUs in particular.
  • The Roku guidance is for 2.5x overdraw. This can be accomplished by carefully inspecting the generated SceneGraph and removing unneeded background elements and images. For example, don’t let a list extend underneath sidebars or similar cases; reduce the number of large views.
  • Scenes may need to be further simplified for low-end Roku devices.
• Adjust the list item size and gaps between items to reduce the number of items shown onscreen at a time.
• If you need to override the default focus when entering and leaving a list, see also our performance recommendations for React Native apps and C++ apps.