Image¶

Inherits: UILayout
C++ type: Image

Description¶

The foundational 2D UI visual element. Image renders a textured or colour-filled rectangle with optional 9-patch scaling. It is the base class for Button, Panel, Progressbar, Scrollbar, and TextEdit.

9-patch scaling (also called scale-9 or nine-slice) divides the image into a 3×3 grid. The four corner pieces are never stretched, while the edges and centre fill the available space. This allows buttons and panel backgrounds to scale to any size without distorting the corners.

All UI elements also expose a rich set of pointer/focus callback events (inherited via UIComponent). See the Callback events section.

Properties¶

Methods¶

Callback events¶

Property details¶

color¶

• Setter: void setColor(Vector4 color)
• Setter: void setColor(float red, float green, float blue, float alpha)
• Setter: void setColor(float red, float green, float blue)
• Setter: void setAlpha(float alpha)
• Getter: Vector4 getColor() const
• Getter: float getAlpha() const

The tint colour multiplied with the texture, in sRGB. (1,1,1,1) renders the texture as-is. Changing the colour is a cheap way to create hover/pressed states without separate textures.

It is stored linear internally, so the value read back is the sRGB form of the stored one. Writing UIComponent.color instead skips the conversion and takes the linear value directly — which is also what a colour authored in a .scene file is.

flipY¶

• Setter: void setFlipY(bool flipY)
• Getter: bool isFlipY() const

Flips the texture vertically. Useful when a texture is loaded upside-down or for certain rendering passes.

patchMargin¶

• Setter: void setPatchMargin(unsigned int margin)
• Setter: void setPatchMargin(unsigned int left, unsigned int right, unsigned int top, unsigned int bottom)
• Individual getters: getPatchMarginLeft, getPatchMarginRight, getPatchMarginTop, getPatchMarginBottom

Sets the 9-patch insets. When all four margins are zero (the default), the image is scaled uniformly. Setting the margins enables 9-patch mode where the corners are preserved.

Image panel(&scene);
panel.createImage();
panel.setTexture("ui/panel_bg.png");
panel.setPatchMargin(20);  // 20px on all sides
panel.setSize(300, 200);

local panel = Image(scene)
panel:setTexture("ui/panel_bg.png")
panel:setPatchMargin(20)
panel:setSize(300, 200)

textureScaleFactor¶

• Setter: void setTextureScaleFactor(float textureScaleFactor)
• Getter: float getTextureScaleFactor() const

Insets the UV rectangle by this many texels on every side, 0.0 by default. A small value such as 0.5 pulls the sampled area away from the edges of a packed atlas cell, hiding the neighbouring pixels that bilinear filtering would otherwise bleed in.

Method details¶

createImage¶

• bool createImage()

Explicitly builds the image geometry and GPU buffers. This method is C++ only and is normally optional because the UI system builds and rebuilds images automatically. Use it when C++ code needs the geometry immediately.

setTexture¶

• void setTexture(const std::string& path)
• void setTexture(const std::string& id, TextureData data)
• void setTexture(Framebuffer* framebuffer)

Assigns the texture to display. Pass a file path, in-memory pixel data with a cache id, or a framebuffer for render-to-texture UI.

getAABB / getWorldAABB¶

• AABB getAABB() const
• AABB getWorldAABB() const

Returns the axis-aligned bounding box in local or world space. Useful for hit-testing or layout calculations.

customShader¶

• Setter: void setCustomShader(const std::string& path)
• Getter: std::string getCustomShader() const

Project-relative base path of a forked shader ("shaders/glow" resolves to shaders/glow.vert and shaders/glow.frag, or "a.vert|b.frag" names the files separately). Empty (default) uses the scene default shader for this type, or the engine built-in. Changing it reloads the component. Same semantics as Mesh.customShader; see Custom Shaders.

setShaderUniform¶

• void setShaderUniform(const std::string& name, const Vector4& value)
• void setShaderUniform(const std::string& name, const Vector3& value)
• void setShaderUniform(const std::string& name, const Vector2& value)
• void setShaderUniform(const std::string& name, float value)
• Vector4 getShaderUniform(const std::string& name) const
• bool removeShaderUniform(const std::string& name)

Values for the members of the custom shader's u_vs_customParams / u_fs_customParams blocks, by member name. Setting a value only rewrites the uploaded block, so it can run every frame; a member with no value reads zero, or the scene's value under a scene default shader, and time (seconds since startup) and resolution (render target size) are reserved for the engine. Same semantics as Mesh.setShaderUniform; see Custom Shaders — Shader uniforms.

image.setCustomShader("shaders/glow");
image.setShaderUniform("strength", 0.8f);
image.setShaderUniform("glowColor", Vector4(1.0f, 0.8f, 0.2f, 1.0f));

image.customShader = "shaders/glow"
image:setShaderUniform("strength", 0.8)
image:setShaderUniform("glowColor", Vector4(1, 0.8, 0.2, 1))

Callback event details¶

onGetFocus / onLostFocus¶

• Property: FunctionSubscribe<void()> onGetFocus
• Property: FunctionSubscribe<void()> onLostFocus

Called when this element gains or loses keyboard focus.

onPointerEnter / onPointerLeave¶

• Property: FunctionSubscribe<void(float,float)> onPointerEnter
• Property: FunctionSubscribe<void(float,float)> onPointerLeave
• Callback: void(float x, float y)

Called when the mouse pointer enters or leaves the element boundary.

Image btn(&scene);
btn.createImage();
btn.getComponent<UIComponent>().onPointerEnter.add("enter", [&](float x, float y){
    btn.setColor(Vector4(0.8f, 0.8f, 1.0f, 1.0f));  // highlight
});
btn.getComponent<UIComponent>().onPointerLeave.add("leave", [&](float x, float y){
    btn.setColor(Vector4(1.0f, 1.0f, 1.0f, 1.0f));  // reset
});

local ui = btn:getUIComponent()
ui.onPointerEnter = function(x, y)
    btn.color = Vector4(0.8, 0.8, 1.0, 1.0)
end
ui.onPointerLeave = function(x, y)
    btn.color = Vector4(1.0, 1.0, 1.0, 1.0)
end

onPointerMove¶

• Property: FunctionSubscribe<void(float,float)> onPointerMove
• Callback: void(float x, float y)

Called each frame the pointer moves while over this element.

onPointerDown / onPointerUp¶

• Property: FunctionSubscribe<void(float,float)> onPointerDown
• Property: FunctionSubscribe<void(float,float)> onPointerUp
• Callback: void(float x, float y)

Called on mouse/touch press and release.

onClick / onDoubleClick¶

• Property: FunctionSubscribe<void(float,float)> onClick
• Property: FunctionSubscribe<void(float,float)> onDoubleClick
• Callback: void(float x, float y)

Called on a complete click (press + release inside the element) or double click.

onDragStart / onDrag / onDragEnd¶

• Property: FunctionSubscribe<void(float,float)> onDragStart
• Property: FunctionSubscribe<void(float,float)> onDrag
• Property: FunctionSubscribe<void(float,float)> onDragEnd
• Callback: void(float x, float y)

Fired when the user begins dragging, continues dragging, or releases while dragging this element.