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::clipboard::Clipboard;

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 crate::runtime::TesseraRuntime;

pub use wgpu;

pub use winit;

Modules

clipboard

Provides a cross-platform clipboard manager for text manipulation.

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

runtime

Tessera Runtime System

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).

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.