Crate emblema_hal 

Rendering HAL trait: the backend-agnostic contract every rendering backend implements.

The HAL answers how draw commands become pixels in a GPU image. Presentation — how a finished image reaches a display, and how the frame loop is paced — is a separate, orthogonal axis and lives in emblema-present.

Shape of the trait

Deliberately Vulkan-leaning. Recording commands and replaying them as GL calls works; extracting Vulkan-grade explicitness from an immediate-mode abstraction does not. GLES pays a small CPU cost for command recording, and that is the accepted trade. The trait is never reduced to a lowest common denominator to accommodate a weaker backend: backends implement, emulate, or capability-gate.

Two requirements present from day one

Both exist for the sake of the DRM presentation path, and both are here before any DRM code, because retrofitting either is a breaking redesign:

1. External render targets — ExternalImageDesc lets the renderer draw into images it did not allocate, carrying dma-buf fd, DRM fourcc, and format modifier.
2. Exportable sync — HalFence::export_sync_file converts GPU completion into a sync_file fd that can ride an atomic commit as IN_FENCE_FD.

Branch on capabilities, never on backend identity

Capabilities is the only thing layers above the HAL are allowed to condition on. A Mali GPU lacking fence export and a desktop Vulkan driver lacking VK_KHR_external_fence_fd are the same problem, and code asking “is this GLES?” instead of “can this export a fence?” gets both wrong.

Re-exports

pub use batch::Batch;

pub use batch::BatchDraw;

pub use batch::ClipRole;

pub use batch::ClipState;

pub use batch::Vertex;

pub use blend::BlendFactor;

pub use blend::BlendFactors;

pub use blend::BlendMode;

pub use capabilities::Capabilities;

pub use capabilities::Capability;

pub use capabilities::DmaBufSupport;

pub use capabilities::SampleCounts;

pub use capabilities::SyncSupport;

pub use capabilities::Withheld;

pub use error::Error;

pub use error::Result;

pub use format::Extent2D;

pub use format::FormatModifierSet;

pub use format::Fourcc;

pub use format::Modifier;

pub use format::PixelFormat;

pub use material::ColorFilter;

pub use material::ColorForm;

pub use material::Gamma;

pub use material::Material;

pub use material::MaterialVariant;

pub use material::Sampling;

pub use material::Stop;

pub use material::TileMode;

pub use material::MATERIAL_FLOATS;

pub use material::MAX_EFFECT_TEXTURES;

pub use material::MAX_STOPS;

pub use material::MORPHOLOGY_TAPS;

pub use material::RUNTIME_FLOATS;

pub use resource::mip_levels_for;

pub use resource::BufferDescriptor;

pub use resource::BufferUsage;

pub use resource::TextureDescriptor;

pub use resource::TextureUsage;

pub use scissor::Scissor;

pub use sync::HalFence;

pub use sync::FRAME_WAIT_TIMEOUT;

pub use resource::DmaBufPlane;

pub use resource::ExternalImageDesc;

Modules

batch

Draws accumulated for one submission.

blend

How a draw combines with what a target already holds.

capabilities

What a device can actually do.

error

Error types shared across every backend.

format

Geometry and pixel format types shared by the rendering and presentation axes.

material

What fills a shape.

occlusion

What is left of a rectangle once other rectangles are taken out of it.

resource

Resource descriptions: what the renderer asks a backend to allocate.

scissor

The rectangle a draw is confined to, in device pixels.

sync

GPU completion, and handing it to something outside this process.

Structs

PassDescriptor

How a pass is configured, beyond the draws themselves.

PassViewport

A clip space larger than the target it lands in, and where it lands.

RuntimeProgram

A caller’s fragment program, in the forms each backend can take one.

Traits

Hal

A rendering backend, as a family of associated types.

HalContext

A device, and the resources created from it.

HalTexture

What a target must be able to tell the layers above it.