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

Sprite Sheets​

An image can contain multiple frames arranged in an even grid of row_count rows and column_count columns, e.g. the states of a button or the positions of a knob. Only the frame selected with row and column is displayed, and the component has the logical size of a single frame:

import { Image } from ui

// A sheet with 2 rows and 3 columns, displaying the frame in the second row and third column
export var main = Image("my_sprite_sheet.png", row: 1, row_count: 2, column: 2, column_count: 3)

Rows are counted from the top and columns from the left, both starting at 0. Selecting a frame outside the grid is an error.

Constructors​

Which constructor is available depends on the Kontakt target version of your instrument.

Current (8.14)​

constructor(_ path: String, row: Int = 0, row_count: Int = 1, column: Int = 0, column_count: Int = 1, resizable: Bool = false)
_ path: String

An image file path relative to the main file.

row: Int = 0

The row of the displayed frame, if the image is a sprite sheet. Must be less than row_count.

row_count: Int = 1

The number of rows, if the image is a sprite sheet.

column: Int = 0

The column of the displayed frame, if the image is a sprite sheet. Must be less than column_count.

column_count: Int = 1

The number of columns, if the image is a sprite sheet.

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.

Legacy (until 8.13)​

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

Supports only sprites with frames stacked vertically. Image("sprite.png", frame: 1, frame_count: 4) is equivalent to Image("sprite.png", row: 1, row_count: 4).

_ 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 (or of a single frame, if the image is a sprite sheet), 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 with many frames might do, especially when all frames are stacked along one dimension.

To avoid the issue, keep images below 16000 pixels per dimension, ideally even below 8000. Since Kontakt 8.14, the frames of a sprite can be arranged in a grid of rows and columns, which keeps both dimensions small.