Crate tessera_ui

Tessera UI Framework

Tessera is a declarative, immediate-mode UI framework for Rust that emphasizes performance, flexibility, and extensibility through a functional approach and pluggable shader system.

Architecture Overview

Tessera’s architecture is built around several core concepts:

• Declarative Components: UI components are defined as functions with the #[tessera] macro
• Immediate Mode: The UI is rebuilt every frame, ensuring consistency and simplicity
• Pluggable Shaders: Custom WGPU shaders are first-class citizens for advanced visual effects
• Parallel Processing: Core operations like measurement utilize parallel computation
• Explicit State Management: Components are stateless with explicit state passing

Getting Started by Developer Level

🟢 Beginner Users - Building Basic Applications

If you’re new to Tessera and want to build applications using existing components:

Start with these modules:

• renderer - Core renderer and application lifecycle management
• Dp, Px - Basic measurement units for layouts
• Color - Color system for styling components

Key concepts to understand:

• How to set up a Renderer and run your application
• Using tessera_basic_components for common UI elements
• Basic layout with row, column, and surface components

use tessera_ui::{Renderer, Color, Dp};
use tessera_ui_basic_components::*;
use tessera_ui_macros::tessera;

#[tessera]
fn my_app() {
    surface(
        SurfaceArgs {
            color: Color::WHITE,
            padding: Dp(20.0),
            ..Default::default()
        },
        None,
        || text("Hello, Tessera!"),
    );
}

🟡 Intermediate Users - Custom Layout and Interaction

For developers who want to create custom components and handle complex layouts:

Essential functions and types:

• measure_node - Measure child component sizes with constraints
• place_node - Position child components in the layout
• StateHandlerFn - Handle user interactions and state changes
• Constraint, DimensionValue - Layout constraint system
• ComputedData - Return computed size and layout information

Key concepts:

• Understanding the measurement and placement phase
• Creating custom layout algorithms
• Managing component state through explicit state handlers
• Working with the constraint-based layout system

use tessera_ui::{measure_node, place_node, ComputedData, Constraint, PxPosition};
use tessera_ui_macros::tessera;

#[tessera]
fn custom_layout() {
    measure(|input| {
        let mut total_width = 0;
        for (i, &child_id) in input.children_ids.iter().enumerate() {
            let child_size = measure_node(child_id, input.parent_constraint, input.metadatas)?;
            place_node(child_id, PxPosition::new(total_width.into(), 0.into()), input.metadatas);
            total_width += child_size.width.to_i32();
        }
        Ok(ComputedData::from_size((total_width.into(), input.parent_constraint.height.min_value())))
    });

    state_handler(|input| {
        // Handle user interactions here
    });
}

🔴 Advanced Users - Custom Rendering Pipelines

For developers building custom visual effects and rendering pipelines:

Advanced rendering modules:

• renderer::drawer - Custom drawable pipelines and draw commands
• renderer::compute - GPU compute pipelines for advanced effects
• DrawCommand, ComputeCommand - Low-level rendering commands
• DrawablePipeline, ComputablePipeline - Pipeline trait implementations
• PipelineRegistry, ComputePipelineRegistry - Pipeline management

Key concepts:

• Creating custom WGPU shaders and pipelines
• Managing GPU resources and compute operations
• Understanding the rendering command system
• Implementing advanced visual effects like lighting, shadows, and particles

use tessera_ui::renderer::{DrawCommand, DrawablePipeline};
use wgpu::{Device, Queue, RenderPass};

struct MyCustomPipeline {
    // Your pipeline state
}

impl DrawablePipeline for MyCustomPipeline {
    fn draw<'a>(&'a self, render_pass: &mut RenderPass<'a>) {
        // Custom rendering logic
    }
}

Core Modules

Essential Types and Functions

• Renderer - Main application renderer and lifecycle manager
• measure_node, place_node - Core layout functions
• Constraint, DimensionValue - Layout constraint system
• Dp, Px - Measurement units (device-independent and pixel units)
• Color - Color representation and utilities

Component System

• ComponentTree - Component tree management
• ComponentNode - Individual component node representation
• ComputedData - Layout computation results
• StateHandlerFn - State management and event handling

Event Handling

• CursorEvent - Mouse and touch input events
• Focus - Focus management system
• PressKeyEventType - Keyboard input handling

Rendering System

• renderer::drawer - Drawing pipeline system
• renderer::compute - Compute pipeline system
• DrawCommand, ComputeCommand - Rendering commands

Examples

Check out the example crate in the workspace for comprehensive examples demonstrating:

• Basic component usage
• Custom layouts and interactions
• Advanced shader effects
• Cross-platform deployment (Windows, Linux, macOS, Android)

Performance Considerations

Tessera is designed for high performance through:

• Parallel measurement computation using Rayon
• Efficient GPU utilization through custom shaders
• Minimal allocations in hot paths
• Optimized component tree traversal

Re-exports

pub use crate::color::Color;

pub use crate::dp::Dp;

pub use crate::focus_state::Focus;

pub use crate::px::Px;

pub use crate::px::PxPosition;

pub use crate::px::PxSize;

pub use crate::renderer::Command;

pub use crate::renderer::Renderer;

pub use crate::renderer::compute;

pub use crate::renderer::compute::ComputablePipeline;

pub use crate::renderer::compute::ComputeCommand;

pub use crate::renderer::compute::ComputePipelineRegistry;

pub use crate::renderer::compute::ComputeResource;

pub use crate::renderer::compute::ComputeResourceManager;

pub use crate::renderer::compute::ComputeResourceRef;

pub use crate::renderer::drawer;

pub use crate::renderer::drawer::BarrierRequirement;

pub use crate::renderer::drawer::DrawCommand;

pub use crate::renderer::drawer::DrawablePipeline;

pub use crate::renderer::drawer::PipelineRegistry;

pub use crate::renderer::drawer::command;

pub use wgpu;

pub use winit;

Modules

color

Color utilities for the Tessera UI framework.

dp

Density-Independent Pixels (Dp)

focus_state

Focus State Management

px

Physical pixel coordinate system for Tessera UI framework.

renderer

Tessera Renderer

tokio_runtime

Structs

Arena

An Arena structure containing certain Nodes.

ComponentNode

A ComponentNode is a node in the component tree. It represents all information about a component.

ComponentNodeMetaData

Contains metadata of the component node.

ComponentTree

Respents a component tree

ComputedData

Layout information computed at the measure stage, representing the size of a node.

Constraint

Represents layout constraints for a component node.

CursorEvent

Represents a single cursor or touch event with timing information.

ImeRequest

A request to the windowing system to open an Input Method Editor (IME). This is typically used for text input components.

NodeId

A node identifier within a particular Arena.

ScrollEventConent

Contains scroll movement data for scroll events.

StateHandlerInput

Input for the state handler function (StateHandlerFn).

TesseraRuntime

Central runtime state container for the Tessera UI framework.

Enums

CursorEventContent

Enumeration of all possible cursor event types.

DimensionValue

Defines how a dimension (width or height) should be calculated.

MeasurementError

Represents errors that can occur during node measurement.

PressKeyEventType

Represents the different types of cursor buttons or touch interactions.

Functions

measure_node

Measures a single node recursively, returning its size or an error.

measure_nodes

Concurrently measures multiple nodes using Rayon for parallelism.

place_node

Places a node at the specified relative position within its parent.

Type Aliases

ComponentNodeMetaDatas

Contains all component nodes’ metadatas, using a thread-safe DashMap.

ComponentNodeTree

A tree of component nodes, using indextree::Arena for storage.

MeasureFn

A MeasureFn is a function that takes an input Constraint and its children nodes, finishes placementing inside, and returns its size (ComputedData) or an error.

StateHandlerFn

A StateHandlerFn is a function that handles state changes for a component.