Documentation menu

image_buffer

Reference an imported pixel buffer as a view with source dimensions.

An image view places pixels that have already been imported into the client's connection. Construct it with image_buffer(buffer_id, width, height) -> Image, supplying the imported ID and source dimensions. Loading a file, decoding its format, and registering its backing storage remain responsibilities of the application or host service.

Imported Image Content

use hera_kit::{BufferId, View, ViewExt, image_buffer};

fn thumbnail(buffer: BufferId, width: u32, height: u32) -> impl View {
    image_buffer(buffer, width, height)
        .frame(160.0, 120.0)
        .clipped()
}

The thumbnail function composes a frame and clip around a buffer already valid in the connection's namespace. Its caller must complete the import before using the view; constructing the description does not itself upload or register pixels.

Image Sizing

An image begins layout with its source width and height as intrinsic dimensions. A surrounding frame can change the proposed and resolved region, but the public Image API has no dedicated aspect-fit or content-mode policy. Choose the source dimensions and surrounding layout according to the current image-node behavior rather than assuming the frame specifies a separate scaling mode.

Choose source dimensions and surrounding layout according to the current image node semantics. Use a custom backend description when specialized image placement is required.

Resource Lifetime

The image's retained reference connects its view lifetime to resources managed through the protocol. Backing storage can remain in use after commit acceptance or GPU submission, so importing, descriptor passing, and retirement must follow their own ownership rules.

For an immutable frame import, wait for BufferReleased before changing its pixels. An ordinary buffer release instead begins by removing retained references and completing the release handshake. In either case, a frame notification alone does not establish that the server has retired the imported resource.

Application Assets

Keep source image assets and licenses under the application's assets directory. Loading those assets into imported buffers belongs to the application or a specialized host service.

See buffers and ownership and backend integration.

Component-Specific Reference

fn image_buffer(buffer: BufferId, width: u32, height: u32) -> Image

The buffer ID and source dimensions are construction inputs, and Image exposes no additional component-specific builder methods. Supply a new description when those inputs change. A common frame configures the surrounding layout region, while clipped or clip establishes a visible boundary. Those wrappers do not add an aspect-fit policy or perform the buffer import.

See View Modifiers for the complete common modifier reference.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/kit/src/view/primitives.rs
  • crates/protocol/src/scene/nodes.rs
  • crates/protocol/src/buffers.rs