Image Components

Images likely make up a significant portion of your app. Some quick points to note:

  • The following image formats are supported:
    • PNG (use if you need image transparency)
    • JPG
    • WebP
    • GIF (first frame only)
    • SVG (only when rasterized; consider integrating rasterization as an automatic tooling step)
  • To make sure your images can be displayed on all devices, and to keep memory consumption down, we suggest a maximum resolution of 2048x2048. A 2048x2048 PNG file takes about 32 MB of memory.

Dynamic Images

Dynamic images require a composition with the layer called ImageNode. The ImageNode layer is typically a solid, but can also be a static asset, such as PNG or JPG. The color of the solid typically does not matter because it is replaced by a dynamic image. The composition is of type Image, with a class of CYIImageView or NetworkImageView.

Static Images

Store the images in <MyApp>/AE/assets/drawable/default.

Interactivity in Images

If a layer is over a button or list, by default it intercepts the touch input. You can control whether or not the touch input can “go through” the layer with the Event property. See Layer Properties.

Another important aspect of images is the n-patch image, which are images that have been reduced to the smallest possible size. Store the images in <MyApp>/AE/assets/drawable/default. See below for a fuller description of n-patch images.

N-Patch Images

N-patch images are compact PNG files that can be scaled without causing distortion or loss of quality. The biggest advantage of n-patch images is that they save memory. For example, instead of using multiple images for a border, you can use one n-patch and stretch it to fit different situations.

To Make an N-Patch Image:

  1. Start with a small 64px x 64px canvas and slowly build to the desired look.
  2. Optimize your bitmap to make it as small as possible while preserving the quality of the image (n-patches do not like to be scaled down).
  3. Add a 1-pixel border all around it to make room for the markers.
  4. Add your top and left markers to indicate which part of your bitmap will stretch.
  5. Leave the remaining border transparent.
  6. Save as .9.png.

The following animation illustrates how to create an n-patch image using draw9patch software available with Android Studio:

Animated sequence that shows how to make a 9-patch image using draw9patch.4

The following diagram illustrates an original .png file scaled without using N-patch:

Diagram depicting a square asset with a thick border, the border is distorted in various directions as the asset is stretched non-uniformly.

As n-patch images are raster images, they are rendered to a pixel grid. The illustration below shows the stretchable area delineated in an n-patch, and how an n-patch is drawn against the pixel grid. Note the pixel rendering of corners.

A closeup look at the corners vs stretchable areas in an n-patch image.

N-Patch Requirements

To implement n-patch images, ensure you meet the following requirements:

  • Name your files <name>.9.png.
  • Retain a 1-pixel space around the n-patch image.

    A left side diagram depicting an n-patch image with no spacing, and a right side diagram that includes the 1 pixel spacing.

  • Draw straight 1-pixel black lines around the edge of the image.

    Diagram depicting black lines around the straight (stretchable) edges of the image.
  • Save versions of the n-patch image for each required dpi.

    Diagram depicting the same image at four sizes from 0.75 times to 2 times the original image.

Adding N-Patch to After Effects

Do the following:

  1. Drag and drop the .9.png file into the assets folder of the After Effects project you are working on.
  2. Add it to a composition as any other .png image.
  3. Scale up the n-patch image to a desired size.
  4. Preview it using the AE preview tool.

N-Patch Considerations

  • If the n-patch image lacks the 1-pixel space around the edge, it will not export properly.
  • The straight 1-pixel black lines around the edge are cropped when the image is exported. Because of this, n-patch images that appear to be aligned to other elements may be misaligned in the app.
  • The left and top black pixels determine the scalable area of the n-patch image. The right and bottom black pixels determine the fill area.

Diagram depicting how an n-patch image scales correctly even when deformed.

N-patch images may look stretched in After Effects, but they present correctly in the Preview tool.

N-Patch Limitations

Following are some of the limitations of n-patch images:

  • Do not scale down an n-patch image. N-patch works best when it is scaled up. Therefore, you should make an n-patch image for the smallest form factor first, then stretch it for other form factors.
  • N-patch images should not be assigned together or be placed parallel as they leave a two-pixel gap.

Roku Cloud Considerations

Consider the following for images on You.i Roku Cloud:

  • Solids aren’t supported for the ImageNode and won’t display any image when the ImageNode layer is a solid.
  • Static image assets are supported as the ImageNode.
  • ImageNode-Outgoing isn’t supported.
  • Roku Cloud apps can display placeholder or failedImageUri images while an image is loading or when an image URL fails to load.