Module background_image 

The backgroundImage style: an image painted as part of a node’s own background stack — over backgroundColor and backgroundGradient, under the node’s content (bevy_ui’s fixed per-node paint order) — by inserting an ImageNode on the same entity. Never NodeImageMode::Auto, so the image contributes nothing to layout and a late-loading asset causes no reflow.

The build needs AssetServer, which apply_style_masked doesn’t hold, so apply_background_image is called from the reconcile sites (and the interaction restyle systems) instead of from an apply_style_masked arm — the same split as an image element’s image_node build. Elements that own their entity’s ImageNode (image, canvas, portal) are guarded by JsBridge::foreign_images at those call sites.

Structs

BackgroundTileScale

The logical tile scale of a repeat-mode background image (scale, default 1.0). sync_background_tile_scale multiplies it by the node’s scale factor into NodeImageMode::Tiled.stretch_value, so 1.0 tiles at the texture’s own size in logical px on every display (CSS semantics).

RBackgroundTexture

Marks a node whose background image samples a render target registered in crate::portal::RenderTargets. bind_background_textures keeps the entity’s ImageNode pointed at the registry’s texture for this name (transparent placeholder while unregistered — the node binds late, like a <portal>). Unlike a portal, a background never becomes the target’s binder, so Resolution::Auto targets stay at their initial size unless a portal also shows them — prefer Resolution::Fixed targets here.

Functions

apply_background_image

Apply the style’s backgroundImage onto the entity: insert/update or remove the ImageNode (plus the RBackgroundTexture / BackgroundTileScale markers) per the spec. Skips entirely unless the BG_IMAGE group is dirty. Callers guarantee the entity’s ImageNode is not element-owned (see JsBridge::foreign_images); on a node that never had the style, the removes are no-ops (same pattern as the BackgroundColor arm in apply_style_masked).

bind_background_textures

Point every background-texture node’s ImageNode at the registry texture for its RBackgroundTexture name (or the shared transparent placeholder while unregistered) — the backgroundImage analogue of bind_portals, minus the binder recording (that is portal Resolution::Auto sizing semantics; a background never sizes its target). Only writes on change; a real swap marks layer content dirty so an enclosing cached layer repaints the late-bound pixels.

sync_background_tile_scale

Keep a repeat-mode background’s stretch_value equal to scale × scale factor, so scale: 1 tiles at the texture’s own size in logical px on every display (CSS semantics; bevy’s tiling is in physical terms). Reacts to Changed<ImageNode> too — every restyle (delta, hover flip) re-inserts the node with the logical value — and settles via compare-before-write (the corrected write’s own Changed echo no-ops on the next pass).