Buffers and Ownership
Import complete image storage with explicit metadata, immutable frame lifetime, and server-confirmed retirement.
Image pixels enter Hera separately from scene structure. A client imports their backing storage with layout metadata and one file descriptor, then refers to the resulting BufferId from an image node. This separation lets scene diffs change image placement without carrying the pixel data again.
Layout Validation
BufferDescriptor admits dimensions from 1 through 8192 pixels, RGBA8888 or BGRA8888 pixels, and a stride that covers each row and is a multiple of four bytes. The full backing span, including row padding, must not exceed 64 MiB.
The allowed storage layout also depends on the import path. CPU-memory imports cannot carry a DRM format modifier, while DMA-BUF imports must match the device's supported import and layout capabilities. Although BufferFormat includes Nv12, the current shared validator accepts only the packed formats described above.
Both metadata and actual backing storage must satisfy import requirements. A valid width and stride do not prove that an arbitrary descriptor has enough bytes or a compatible GPU layout.
Import Lifecycles
For a connection-local buffer registered through ImportBuffer, release begins by removing its retained scene references. The client can then request ReleaseBuffer and wait for BufferReleased before reusing its identity or backing under that lifecycle.
Frame producers use ImportFrameBuffer to supply immutable image content under fresh, monotonically increasing connection-local IDs. Each imported frame's pixels must remain unchanged until BufferReleased arrives, even if the server has already acknowledged the scene commit that references it.
BufferReleased means that the namespace entry and its GPU resources have retired. A client commit outcome and a frame presentation event are not substitutes for resource retirement.
Frame Damage
A frame import can also describe how its complete image differs from a successfully imported immutable predecessor. The FrameDamage field names that predecessor and lists the changed regions in top-left pixel coordinates. The client still supplies the entire new image; the regions help the server track changes rather than serving as sparse pixel patches.
The damage list can contain at most 64 nonempty rectangles, each contained within the image bounds with overflow-safe coordinates. When the producer cannot provide that relationship, it can omit damage to report a full or unknown change.
Server Display Authority
Imported buffers support image content and external producers such as embedded web content. The server still decides how that content is transformed, clipped, composed with other surfaces, and presented. Buffer import does not grant a client direct scanout ownership.
See image_buffer for the authoring API and presentation for server-owned output images.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
crates/protocol/src/buffers.rscrates/protocol/src/messages.rscrates/server/src/client/buffers.rscrates/composer/src/composer/frame_buffers.rs