Crate noesis_runtime

Expand description

Safe Rust bindings to the Noesis GUI native SDK, a XAML-based UI engine.

The crate builds UI trees, drives input, and ticks layout and animation. It does no drawing itself: Noesis renders through a render_device::RenderDevice you implement for your GPU API. The sibling crate noesis_bevy provides one for Bevy/wgpu.

§Getting started

Call init once at startup and shutdown once at exit, after every Noesis handle has been dropped. In between:

Install an asset source with xaml_provider::set_xaml_provider (and, optionally, font_provider and texture_provider sources).
Build a root element with view::FrameworkElement::load (from a URI) or view::FrameworkElement::parse (from a XAML string).
Host it in a view::View with view::View::create, then feed it the surface size, input events, and the current time each frame.
Register your device with render_device::register, bind it with view::Renderer::init, and render each frame.

use noesis_runtime::render_device::Registered;
use noesis_runtime::view::{FrameworkElement, View};

fn run(device: &Registered, time_seconds: f64) {
    noesis_runtime::init();

    let root = FrameworkElement::parse(
        r#"<Grid xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
               <TextBlock Text="Hello"/>
           </Grid>"#,
    )
    .expect("XAML parses");
    let mut view = View::create(root);
    view.set_size(1280, 720);
    view.renderer().init(device);

    // Each frame:
    view.update(time_seconds);
    let mut renderer = view.renderer();
    renderer.update_render_tree();
    renderer.render_offscreen();
    renderer.render(false, true);

    // Teardown: release device resources, drop every handle, then shut down.
    renderer.shutdown();
    drop(view);
    noesis_runtime::shutdown();
}

The prelude re-exports the types most code uses.

§Setup

Building requires the Noesis Native SDK 3.2.13. Set NOESIS_SDK_DIR to its root (the directory containing Include/ and Bin/). See README.md.

§Features

shim (default): compiles the C++ shim and links the Noesis library. Everything except render_device needs it. Turn default features off to get only the render-device types and the RenderDevice trait, with no SDK, no C++ build and no link. That is for a render device used by a host that loads Noesis some other way, such as the managed (C#) SDK.
test-utils: compiles the shim’s test entry points and the tests that use them. Implies shim.

§Thread affinity

Noesis objects are thread-affine: every call on an object, and on the view::View that owns it, must come from the one thread that drives that view. Owning handles in this crate are therefore Send but not Sync:

Send is sound because Noesis reference counts are atomic, so the release in Drop is safe on any thread. You can move a handle to the view’s thread and use it there.
Sync would be unsound because many &self methods call into Noesis, and some mutate engine state lazily. Shared references across threads would race.

The unsafe impl Send blocks throughout the crate rely on this contract. render_device::RenderDevice is the exception: implementations must be Send + Sync because Noesis may call them from a dedicated render thread.

Modules§

animation: Animations built in code: storyboards, From/To/By and key-frame animations, and easing functions.
binding: Data binding: drive XAML from Rust-owned data.
brushes: Brushes and effects built in code, for painting elements without XAML.
classes: Custom XAML classes implemented in Rust.
collection_view: Collection views: a cursor over a list for current-item navigation.
commands: Commands: ICommand implementations backed by Rust, routed commands, and command bindings.
converters: Value converters written in Rust, for data binding.
diagnostics: Error and assert handlers, and Noesis memory counters.
drawing: Immediate-mode drawing from a custom element’s render callback.
element_tree: Build and change element trees from code: panel children and Grid rows and columns.
events: Subscribe Rust callbacks to Noesis events.
font_provider: Serve font files to Noesis from your own asset pipeline.
formatted_text: Measure and lay out a string in a given font from code, without XAML or a TextBlock.
geometry: Build geometries from code: StreamGeometry, PathGeometry (made of PathFigures and segments), EllipseGeometry, RectangleGeometry, LineGeometry, CombinedGeometry and GeometryGroup. All of them implement the Geometry trait.
gui: Process-global Noesis::GUI helpers: application-wide resource dictionaries and loading XAML into an existing object.
imaging: Image sources built from code: BitmapImage (an image file by URI), CroppedBitmap, TextureSource and DynamicTextureSource.
input: Keyboard shortcuts, mouse gestures, and focus navigation.
integration: Process-global host hooks from NsGui/IntegrationAPI.h: Noesis calls back into your app to change the OS cursor, show or hide the on-screen keyboard, open a URL, or play a sound. The default culture is set here too (set_culture).
markup: Custom XAML markup extensions backed by Rust callbacks.
mesh: Triangle meshes built in code.
multi_binding: Bindings that combine several sources into one value.
name_scope: XAML namescopes: the tables that map x:Name values to objects.
plain_vm: View models that expose Rust data to XAML bindings.
prelude: Re-exports of the most-used items: views and elements, brushes, transforms, geometry, data binding, custom classes and markup extensions, the asset-provider traits, the lifecycle functions, and common enums.
reflection: Enums, routed events, and type metadata registered with Noesis reflection at runtime, plus XAML’s string-to-value conversion.
render_device: Render Noesis through your own GPU backend.
resources: Build resource dictionaries in code and install application resources.
shapes: Build Rectangle, Ellipse and Line elements in code.
styles: Build styles, triggers and templates in code.
svg: SVG parsing and geometry queries. Everything here runs on the CPU and needs no RenderDevice or view, so it works in tests, tooling, and hit-testing code without a renderer.
text_inlines: Build TextBlock inline content from Rust: create Run, Span, Bold, Italic, Underline, Hyperlink, LineBreak, and InlineUIContainer elements and add them to a TextBlock’s (text_block_inlines) or a Span’s (Span::inlines) InlineCollection.
texture_provider: Supply image pixels to Noesis from Rust. Implement TextureProvider to resolve Image.Source / ImageBrush.ImageSource URIs into RGBA8 images, then register it with set_texture_provider or one of the scoped variants (set_scheme_texture_provider, set_assembly_texture_provider, set_scheme_assembly_texture_provider). It works like crate::xaml_provider and crate::font_provider.
transforms: Build 2D and 3D transforms from Rust and apply them to elements.
typography: Font and text properties on elements:
view: UI elements, views, and renderers: the core loop of hosting Noesis UI.
xaml: XAML loading beyond FrameworkElement::load.
xaml_provider: Tell Noesis where to find your XAML.

Functions§

disable_hot_reload: Disables Hot Reload. Call before init.
disable_inspector: Disables remote Inspector connections. Call before init.
disable_socket_init: Skips the Inspector’s socket initialization (WSAStartup on Windows). Call before init, and only when the host has already initialized sockets.
init: Initializes Noesis. Call exactly once per process, before creating any Noesis object. Noesis cannot be initialized again after shutdown.
is_inspector_connected: Returns whether a remote Inspector is connected. Always false on a Release SDK build.
set_license: Applies Noesis license credentials. Call before init; without a license Noesis runs in trial mode and draws a watermark.
shutdown: Shuts Noesis down. Call once at exit, after every handle from this crate has been dropped; dropping one afterwards touches freed engine state.
update_inspector: Keeps the Inspector connection alive. View::update does this internally, so you only need it while no view exists. No-op on a Release SDK build.
version: Returns the version of the linked Noesis runtime, such as "3.2.13", or an empty string if Noesis reports none.