Skip to main content

Image

Displays an image or sprite.

component Image

Example​

import { Image } from ui

export var main = Image("my_background.png")

Supported File Formats​

  • PNG
  • JPEG
  • WEBP (we highly recommend using this format for large images, because it loads significantly faster and produces smaller files)
  • SVG (limited to static features of SVG 1.2 Tiny)
  • TIFF

Constructor​

constructor(_ path: String, frame: Int = 0, frame_count: Int = 1, resizable: Bool = false)
_ path: String

An image file path relative to the main file.

frame: Int = 0

Selects which frame in a sprite is displayed.

frame_count: Int = 1

The number of frames, if the image is a sprite.

resizable: Bool = false

Whether the image is allowed to stretch to fit into the available area.

If this property is set to false the component has the logical size of the loaded image file.

This doesn't preserve aspect ratio and might distort the image.

Layout Behavior​

Always reflects the logical size of the loaded image, unless resizable is set to true in which it will automatically stretch into the available area.

High-DPI Support​

In the case of raster images (i.e. the non-SVG ones), high-DPI image files are detected and used automatically if they use the @2x postfix. To enable use of a double resolution image in the context of a high-DPI screen, or when a scaling factor is used in the application, provide both image assets like so:

  • Single resolution: myimage.png
  • High resolution: myimage@2x.png

Known Issues​

Large sprites rendered blurry​

Images are uploaded to the GPU as-is. When an image exceeds the GPU's maximum texture size, the GPU stores a downscaled version of it, which is then upscaled again when rendering. This causes the image to appear blurry (low-res).

The maximum texture size depends on the platform and cannot be controlled by Kontakt. On desktop systems it is usually around 16000×16000 pixels, sometimes 32000×32000. Most images never get this big, but sprites might do, because all frames are stacked along one dimension.

To avoid the issue, keep images below 16000 pixels per dimension, ideally even below 8000.