UIImage

A UIImage can source its texture either directly via textureId, or by referencing a named sub-rect of a sprite sheet via spriteId. A Sprite is a named rectangle (with its own pivot and nine-slice border) cut out of a Texture2D asset whose usage is Sprite2D; sprites are authored in the Sprite Editor and requested by name via request_sprite(path_to_asset, name_in_asset).

When spriteId is set it overrides textureId, uvRegion, and nineGrid – the sprite supplies its own UV rect and border, so those three fields have no effect while it’s assigned.

In the editor

The UIImage has a custom inspector: alongside the usual fields it adds an Apply Texture Size button that appears when a texture is assigned and resizes the frame to the assigned texture’s pixel size.

textureId/uvRegion/nineGrid and spriteId are mutually exclusive in the inspector: assigning one greys out the other(s), so you never end up editing a value that’s silently ignored. Clear whichever one is currently set to switch to the other.

Enumerations

FillMode

Fill mode for image rendering.

Values:

  • None = 0 - Default image render

  • Horizontal = 1 - Render image with horizontal filling

  • Vertical = 2 - Render image with vertical filling

  • Radial90 = 3 - Render image with radial filling, with center in corners

  • Radial180 = 4 - Render image with radial filling, with center in middles of edges

  • Radial360 = 5 - Render image with radial filling, with center in middle of image

FillOrigin

Origin edge or corner for the fill direction.

Values:

  • Bottom = 0 - Anchor filling mode to bottom

  • Left = 1 - Anchor filling mode to left

  • Top = 2 - Anchor filling mode to top

  • Right = 3 - Anchor filling mode to right

Classes

UIImage : NativeComponent

Note

UIFrame component is automatically added to the node if it is not already present

This component is used to render UI image in Canvas.

The image is positioned in pixels from the center of the viewport. +X is to the right, +Y is to the top.

Note

Don’t forget to set the size or the image will not be seen

Example:

let canvas = create_node()
add_component(canvas, new UICanvas())

let image = create_node(NodeData(parent = canvas,
    position = float3(100.0, 100.0, 0.0)
))
add_component(image, new UIImage(
    textureId = request_texture("image.png"),
    size = float2(100., 100.)
))

Or, driven by a named Sprite sub-resource instead of a raw texture:

add_component(image, new UIImage(
    spriteId = request_sprite("ui_atlas.png", "close_button"),
    size = float2(64., 64.)
))
Properties:

UIImage.textureId: TextureId
UIImage.textureId =(value: TextureId)

Texture of the image. Default is null. Ignored while spriteId is set (spriteId supplies the texture instead), so its inspector field is disabled – clear spriteId to edit this.

Arguments:
UIImage.spriteId: SpriteId
UIImage.spriteId =(value: SpriteId)

Named sub-rect (Sprite) resource. If set, overrides textureId/uvRegion/nineGrid. Its inspector field is disabled while textureId is set, to keep the two mutually exclusive in the editor – clear textureId first to assign a sprite.

Arguments:
UIImage.color: float4
UIImage.color =(value: float4)

Color of the image. Default is white.

Arguments:

  • value : float4

UIImage.pivot: float2
UIImage.pivot =(value: float2)

Node’s origin relative to it’s content. Left-top of the content is (0,0), right-bottom is (1,1). Default is (0.5, 0.5).

Arguments:

  • value : float2

UIImage.size: float2
UIImage.size =(value: float2)

Size of the image. This field can only be accessed in code. The same effect can be achieved by changing UIFrame.size property.

To change the value in editor use UIFrame.size of the node.

Arguments:

  • value : float2

UIImage.localPosition2D: float2
UIImage.localPosition2D =(value: float2)

Local position of the image. Default is (0, 0).

Arguments:

  • value : float2

UIImage.uvRegion: float4
UIImage.uvRegion =(value: float4)

UV region of the image(X offset, Y offset, X size, Y size). Used for atlas usage. Default is (0, 0, 1, 1). Ignored while spriteId is set (spriteId supplies its own UV region instead), so its inspector field is disabled.

Arguments:

  • value : float4

UIImage.nineGrid: float4
UIImage.nineGrid =(value: float4)

Nine-slice border widths (left, top, right, bottom) in pixels, for stretchable UI frames. Default is (0, 0, 0, 0). Ignored while spriteId is set (spriteId supplies its own border instead), so its inspector field is disabled.

Arguments:

  • value : float4

UIImage.pixelMultiplier: float
UIImage.pixelMultiplier =(value: float)

Pixel multiplier. Used for global UI scaling. Default is 1.0.

Arguments:

  • value : float

UIImage.fillMode: FillMode
UIImage.fillMode =(value: FillMode)

Fill mode of the image. Default is None.

Arguments:
UIImage.fillOrigin: FillOrigin
UIImage.fillOrigin =(value: FillOrigin)

Fill origin of the image. Default is Bottom.

Arguments:
UIImage.fillAmount: float
UIImage.fillAmount =(value: float)

Fill amount of the image. Default is 1.0.

Arguments:

  • value : float

UIImage.fillClockwise: bool
UIImage.fillClockwise =(value: bool)

Fill clockwise of the image. Default is true.

Arguments:

  • value : bool

UIImage.grayScale: bool
UIImage.grayScale =(value: bool)

Enable grayscale rendering. Default is false.

Arguments:

  • value : bool

UIImage.grayScaleFactor: float
UIImage.grayScaleFactor =(value: float)

Grayscale factor. Used if grayScale is true. Default is 1.0.

Arguments:

  • value : float