NinePatchImage

Displays an image or sprite with stretchable and scalable regions.

component NinePatchImage

The regions 1, 3, 7 and 9 are scaled according to their aspect ratio. Regions 2 and 8 are stretched horizontally. Regions 4 and 6 are stretched vertically. Region 5 is stretched in both dimensions.

Example

import { NinePatchImage } from ui

export var main = NinePatchImage(
    "my_nine_patch.png",
    fixed_left: 4,
    fixed_right: 4,
    fixed_top: 4,
    fixed_bottom: 4,
)

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

Like Image, a nine-patch image can be a sprite sheet with frames arranged in an even grid of row_count rows and column_count columns. Only the frame selected with row and column is displayed, and the fixed borders apply to each frame:

import { NinePatchImage } from ui

// A sheet with 2 rows (e.g. normal and hovered) and 1 column
export var main = NinePatchImage(
    "my_nine_patch_sheet.png",
    row: 1,
    row_count: 2,
    fixed_left: 4,
    fixed_right: 4,
    fixed_top: 4,
    fixed_bottom: 4,
)

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, fixed_left: Float = 0, fixed_right: Float = 0, fixed_top: Float = 0, fixed_bottom: Float = 0)

_ 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.

fixed_left: Float = 0

The width of the fixed left border (Width of regions 1, 4 & 7)

fixed_right: Float = 0

The width of the fixed right border (Width of regions 3, 6 & 9)

fixed_top: Float = 0

The height of the fixed top border (Height of regions 1, 2 & 3)

fixed_bottom: Float = 0

The height of the fixed bottom border (Height of regions 7, 8 & 9)

---

Legacy (until 8.13)

constructor(_ path: String, frame: Int = 0, frame_count: Int = 1, fixed_left: Float = 0, fixed_right: Float = 0, fixed_top: Float = 0, fixed_bottom: Float = 0)

Supports only sprites with frames stacked vertically. frame and frame_count behave like row and row_count.

_ 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.

fixed_left: Float = 0

The width of the fixed left border (Width of regions 1, 4 & 7)

fixed_right: Float = 0

The width of the fixed right border (Width of regions 3, 6 & 9)

fixed_top: Float = 0

The height of the fixed top border (Height of regions 1, 2 & 3)

fixed_bottom: Float = 0

The height of the fixed bottom border (Height of regions 7, 8 & 9)

Layout Behavior

Always stretches into the available area.

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.