Image
img is not a normal box. It is replaced content: layout must
know the image's intrinsic size before it can place anything, and paint must
upload, cache and fit the decoded bitmap. Donkeh treats it as a first-class
primitive rather than an empty element with a background.
Why it is special
| Pipeline stage | What the image primitive does |
|---|---|
| Source resolution | Resolves a file path, a data: URI or an embedded asset declared with [Image]. A plain path probes disk first, then packed assets; the packed:, embedded: and asset: prefixes force the embedded lookup. |
| Intrinsic sizing | Reads the encoded header, or rasterises an SVG, to get pixel dimensions. Layout uses those dimensions to preserve aspect ratio before CSS constraints apply. |
| Decoding and upload | Decodes RGBA pixels and uploads one OpenGL texture per source. Encoded bytes, decoded dimensions and textures are cached separately. |
| Painting | Draws the bitmap through the same instanced renderer as shapes and text, applying object-fit and object-position. |
| CSS backgrounds | background-image: url(...) shares the same encoded-byte and texture cache, so an image used both as a layer and as img is decoded once. |
Decoding on the layout thread would stall every frame, and letting an
img collapse to zero height would break flex and grid layouts.
That is why the host owns the cache and reports intrinsic dimensions back to
layout.
Declare an embedded image
Add the file as an EmbeddedResource, then declare it with
[Image]. The attribute is metadata only; the file still has to
be embedded in the same assembly.
<ItemGroup>
<EmbeddedResource Include="Assets/logo.png" />
</ItemGroup>
using Donkeh.UILab;
using static Donkeh.UILab.HtmlHelper;
[assembly: Image("Assets/logo.png")]
[AppRoot(Width = 1000, Height = 700, Title = "My app")]
public sealed class App : Component
{
public override Node Render() =>
Img(new()
{
Src = "packed:Assets/logo.png",
Alt = "Donkeh logo",
Attributes = new Dictionary<string, string>
{
["width"] = "160",
["height"] = "160"
}
});
}
Other/logo.png from resolving to Assets/logo.png.
When two declarations match, the result is treated as unavailable instead of
picking one arbitrarily.
Supported sources
| Source | Example | Notes |
|---|---|---|
| Relative or absolute file | Assets/logo.png | Probed on disk first. Relative paths resolve against the process working directory at first use. |
| Embedded asset | packed:Assets/logo.png | Uses the [Image] declaration and manifest resource in a loaded assembly. |
| Data URI | data:image/png;base64,... | Decoded directly, with no disk access. |
| SVG | Assets/icon.svg | Rasterised on first use, whether it comes from disk, a data URI or an embedded resource. |
Sizing and fitting
The intrinsic size comes from the decoded pixels, not CSS pixels. If the
header cannot be read, the width and height
attributes are used. The user-agent sheet gives images
max-width: 100%, so a large image shrinks with its container
while preserving aspect ratio.
.hero-image {
width: 100%;
height: 240px;
object-fit: cover;
object-position: center 35%;
border-radius: 18px;
}
object-fit accepts fill, contain,
cover, none and scale-down.
cover crops by shrinking the UV rectangle rather than clipping
the quad; contain and scale-down centre the image
in the box.
Cache behaviour
| Behaviour | Detail |
|---|---|
| No eviction | Every successfully used source stays in memory until the window is disposed. |
| No file watching | Replacing a file on disk does not refresh the image. Restart the window, or use a new source string. |
| Failures are cached | A missing or corrupt source resolves to a zero texture and is not retried every frame. |
| Frame-thread upload | Textures are created and deleted on the render thread. Intrinsic-size queries can happen earlier. |
Browser host
On WebAssembly the tree is mirrored to a native img, and the
browser owns loading, decoding and layout. Use a URL or data:
URI there. The packed: and embedded: source forms
are for the desktop and Android GL hosts, which implement the packed-asset
resolver.
Image.Load("Assets/logo.png") or
Image.TryGetBytes(...) when you need the encoded file for an
upload, a custom cache or a non-img path. The element pipeline
uses the same declarations internally.