Images and styling
Style UI nodes: background and border colours, rounded corners, outlines, box shadows and gradients, images with ImageNode, nine-slicing, custom UI materials and viewports.
On this page
A Node on its own is invisible: it only takes up space. Its look comes from separate components that you add next to it. This page lists them, from plain colours to images and custom shaders.
Colours and borders#
| Component | What it draws |
|---|---|
BackgroundColor(color) | Fills the node. Transparent by default. |
BorderColor | Colours the border, whose thickness is Node::border. BorderColor::all(color) sets every side; the struct also has top, right, bottom and left. |
Outline { width, offset, color } | A line outside the border that doesn't affect layout. Good for focus rings. |
Rounded corners are a Node field, border_radius, so they apply to the background, border, outline, shadow and image together:
commands.spawn((
Node {
width: px(150),
height: px(65),
border: px(5).all(),
border_radius: BorderRadius::all(px(12)),
..default()
},
BackgroundColor(Color::srgb(0.15, 0.15, 0.15)),
BorderColor::all(Color::BLACK),
));BorderRadius:: | Corners |
|---|---|
all(px(8)) | All four the same. |
top(..), bottom(..), left(..), right(..) | Two corners on one side. |
px(tl, tr, br, bl) | Each corner in pixels. |
MAX | As round as possible: pills, and circles for square nodes. |
Shadows#
BoxShadow draws one or more shadows behind a node. BoxShadow::new(color, x_offset, y_offset, spread_radius, blur_radius) makes one; BoxShadow(vec![ShadowStyle { .. }, ..]) stacks several.
BoxShadow::new(Color::BLACK.with_alpha(0.8), px(4), px(4), px(0), px(8))Add BoxShadowSamples(n) to a camera to trade shadow quality for speed.
Gradients#
BackgroundGradient and BorderGradient take a list of gradients drawn on top of each other: LinearGradient, RadialGradient and ConicGradient. Colour stops are ColorStops (or plain colours, spaced evenly).
use neo::ui::ColorStop;
commands.spawn((
Node { width: px(300), height: px(60), ..default() },
BackgroundGradient::from(LinearGradient::to_right(vec![
ColorStop::new(Color::srgb(0.9, 0.2, 0.3), percent(0)),
ColorStop::new(Color::srgb(0.2, 0.4, 0.9), percent(100)),
])),
));LinearGradient::new(angle, stops) takes an angle in radians, with constants such as LinearGradient::TO_RIGHT. RadialGradient::new(position, shape, stops) and ConicGradient::new(position, stops) place the centre with a UiPosition such as UiPosition::CENTER.
Images#
ImageNode draws an image in a node. By default the node takes the image's size; set width and height on the Node to size it yourself.
commands.spawn((
ImageNode::new(asset_server.load("branding/icon.png")),
Node { width: px(256), height: px(256), ..default() },
));| Field | What it does |
|---|---|
image | The Handle<Image>. |
color | A tint multiplied with the image. |
texture_atlas | One frame of a sprite sheet. ImageNode::from_atlas_image(image, atlas) sets it; see Texture atlases. |
flip_x, flip_y | Mirror the image. |
rect | Draw only part of the image. |
image_mode | How it fills the node: NodeImageMode::Auto, Stretch, Sliced(TextureSlicer) or Tiled { .. }. |
Nine-slicing (NodeImageMode::Sliced) keeps a panel's corners sharp at any size, with the same TextureSlicer sprites use; see Sprites.
Images can also sit inside a line of text with InlineImage; the inline_image example shows how.
Transparency#
Colours with alpha below 1.0 blend with what's behind them. A node's children aren't made transparent by its colour: fade a whole panel by changing the alpha of each part.
Custom UI materials#
For effects the built-in components can't draw, write a UI material: a struct that derives Asset, TypePath and AsBindGroup, implements UiMaterial with a fragment shader, and is registered with UiMaterialPlugin::<YourMaterial>::default(). Put it on a node with MaterialNode(materials.add(YourMaterial { .. })). The ui_material example animates one. Shaders are covered in Custom materials and shaders.
Show a camera in the UI#
ViewportNode::new(camera_entity) shows what a camera renders, inside a node: a minimap, a character preview, a picture-in-picture view. The camera renders to an image that the node displays, and picking works through it. See the viewport_node example. To do the opposite, drawing UI onto a texture used in the 3D world, see the render_ui_to_texture example.
Examples#
| Example | What it shows |
|---|---|
borders | Border widths, colours and radii. |
box_shadow | Shadows. Needs --features neo_feathers for its controls. |
gradients, stacked_gradients | Linear, radial and conic gradients. |
transparency_ui | Transparent nodes and text. |
image_node, image_node_resizing | Images and how they size. |
ui_texture_slice, ui_texture_slice_flip_and_tile, ui_texture_atlas_slice | Nine-slicing. |
ui_material | A custom UI material. |
viewport_node | A camera's view in a node. |
Run one from the engine core's workspace: cargo run --example borders.