View source

class ImageElement

package s.markup.elements

extends DrawableElement

@:build(s.shortcut.ShortcutMacro.build())@:autoBuild(s.shortcut.ShortcutMacro.build())@:build(s.shortcut.ShortcutMacro.mixinBuild())@:allow(s.markup.graphics.ImageElementDrawer)

Image-based drawable markup element.

ImageElement renders a s.resource.Image inside the rectangular bounds inherited from Element. The image is loaded through an internal ImageAsset, can be restricted to a source sub-rectangle with sourceClipRect, fitted by fillMode, aligned by alignment, and sampled with configurable texture sampling through smooth, mipmap, or the higher-level sampling preset.

Fill-mode behavior overview:

  • Pad Keeps the source at its natural size relative to the element. This may leave empty space around the image or cause the image to extend beyond the element if the source is larger than the destination.
  • Stretch Scales the sampled source rectangle to exactly match the element bounds.
  • Cover Scales uniformly to fill the element bounds, cropping the source rectangle when aspect ratios differ.
  • Contain Scales uniformly to fit inside the element bounds without cropping, potentially leaving empty space.
  • Tile Repeats the source horizontally and vertically.
  • TileVertically Stretches horizontally and repeats vertically.
  • TileHorizontally Repeats horizontally and stretches vertically.

Alignment behavior overview:

  • in Pad and Contain, alignment places the image inside the remaining free space
  • in Cover, alignment selects which part of the cropped source remains visible
  • in tiled modes, alignment offsets the tile phase when the element size is not an integer multiple of the tile size
  • in Stretch, alignment has no visible effect because the image always fills the full destination area

The final sampled color is multiplied by the color property and by the element opacity during rendering.

Typical usage:

var image = new ImageElement("ui/logo");
image.width = 320;
image.height = 180;
image.fillMode = Contain;
image.alignment = AlignCenter;
image.sampling = Trilinear;

Example using a texture atlas region:

var icon = new ImageElement("atlas/ui");
icon.width = 32;
icon.height = 32;
icon.sourceClipRect = new Rect(64, 0, 32, 32);
icon.fillMode = Stretch;

Loading is asynchronous from the point of view of the element API. Until the asset is available, isLoaded is false and the element skips rendering.

ImageElement otherwise behaves like any other DrawableElement: it participates in layout, anchoring, z-ordering, color modulation, visibility, opacity, and child rendering.

See also:

  • s.resource.Image

  • s.assets.ImageAsset

  • s.markup.FillMode

  • s.markup.Alignment

  • s.geometry.Rect

Constructor

new(source:String)

Creates a new image element bound to the given source asset.

Parameters:

source

Resource key or path used to resolve the image asset.

Variables

@:value(AlignCenter)alignment:Alignment = AlignCenter

Alignment policy used together with fillMode.

Horizontal flags (AlignLeft, AlignHCenter, AlignRight) and vertical flags (AlignTop, AlignVCenter, AlignBottom) are interpreted according to the active fill mode:

  • Pad and Contain: place the rendered image inside the leftover space
  • Cover: choose the visible side of the cropped source
  • Tile*: offset the repeated texture pattern phase

Stretch ignores alignment because the image always covers the whole destination area.

@:value(Stretch)fillMode:FillMode = Stretch

Defines how the image is fitted, cropped, or tiled inside the element.

The chosen mode affects the derived destination rectangle (rect), the derived source rectangle (clipRect), and the sampler addressing mode used at draw time.

read onlyisLoaded:Bool

Whether the image referenced by source has been loaded.

When this is false, the element has no texture to draw and therefore contributes no pixels.

mipmap:Bool

Whether the image should use mipmaps when sampled smaller than its native size.

When enabled, the element generates a mip chain for the current image and uses linear mip selection. When disabled, mip levels are removed and only the base image is sampled.

sampling:ImageSampling

Convenience preset that configures smooth and mipmap together.

Use this when you want a named sampling mode instead of managing the two low-level flags separately.

smooth:Bool

Whether the image should use linear filtering inside each sampled mip level.

When false, sampling remains pixel-sharp. When true, the image is filtered smoothly.

source:String

Resource key or path of the image to display.

Assigning this field forwards the value to the internal ImageAsset. The exact naming scheme depends on the project's resource pipeline, but it typically matches the engine's image identifiers such as "ui/logo" or "atlas/icons".

@:value(null)sourceClipRect:Rect = null

Optional source-space clipping rectangle in image pixels.

When null, the full source image is used. When non-null, the element first restricts sampling to this rectangle and only then applies the current fill-mode logic.

Coordinates are expressed in source image pixels:

  • x, y: top-left corner within the image
  • width, height: size of the source region

This is primarily useful for atlas-backed UI icons, spritesheet frames, or reusable image slices.