Struct UiSurface

pub struct UiSurface<Msg: Clone> { /* private fields */ }

A retained rendering target for code that wants ltk widgets without ltk::run.

A compositor can keep one UiSurface per decoration or panel, mutate focus/hover/pressed state from its own input routing, then call Self::render whenever it decides a repaint is needed.

Implementations

impl<Msg: Clone> UiSurface<Msg>

pub fn new(width: u32, height: u32) -> Self

Create a software-backed surface of the given physical size.

This is intentionally conservative for compositor integrations: an embedder typically already owns an EGL/GLES context, so new must not allocate a hidden offscreen context per decoration. Use Self::from_gles_context when the caller can provide an already-current GL context.

pub fn new_software(width: u32, height: u32) -> Self

Create a software-backed surface explicitly.

pub fn try_new_gles(width: u32, height: u32) -> Result<Self, String>

Create a GLES-backed surface with an ltk-owned offscreen EGL context.

The context is made current before render/resize operations. This is useful for runtime-free rendering; compositors that already own a GL context can instead build a Canvas::new_gles(...) and pass it to Self::from_canvas.

pub fn from_gles_context( gl: Arc<Context>, version: GlesVersion, width: u32, height: u32, ) -> Self

Create a GLES-backed surface from a caller-owned, already-current GL context.

This is the path intended for compositor embedders: no EGL display, EGL context, or pbuffer is allocated by ltk. The caller must keep the underlying GL context alive and current whenever this surface is created, rendered, resized, or dropped.

pub unsafe fn from_current_gles_loader<F>( loader: F, version: GlesVersion, width: u32, height: u32, ) -> Self

where F: FnMut(&str) -> *const c_void,

Create a GLES-backed surface from the GL function loader of the current context.

This is useful for renderers such as Smithay’s GlesRenderer, which keep their own EGL context and expose custom GL access through a callback. This constructor does not allocate an EGL context; it only builds ltk’s glow dispatch table and GPU canvas resources in the context that is current while this function runs.

Safety

loader must resolve symbols for the GL context that is current on this thread. That same context must remain alive, and must be made current before any call that touches the returned surface — including the implicit destructor: dropping the UiSurface releases GPU resources (textures, FBOs, programs) through the caller-owned context and will leak / corrupt state if that context is not current at drop time.

pub fn from_canvas(canvas: Canvas) -> Self

Wrap an existing canvas. This is the hook for compositor-owned GPU targets once the caller provides an already-current GL context. If canvas is Canvas::Gles, the caller remains responsible for making the matching GL context current before calling methods that touch the canvas — including the implicit destructor: dropping the UiSurface releases GPU resources (textures, FBOs, programs) through the caller-owned context and will leak / corrupt state if that context is not current at drop time.

pub fn canvas(&self) -> &Canvas

Access the backing canvas after a render pass.

pub fn canvas_mut(&mut self) -> &mut Canvas

Mutable access to the backing canvas for compositor-specific upload or presentation code. Mark content dirty afterwards if external drawing changes what ltk should preserve across partial redraws.

pub fn size(&self) -> (u32, u32)

Current canvas size in physical pixels.

pub fn resize(&mut self, width: u32, height: u32)

Resize the backing canvas and force the next render to redraw fully.

pub fn set_dpi_scale(&mut self, scale: f32)

Set the DPI scale used for text and font metrics.

pub fn mark_content_dirty(&mut self)

Mark the next render as content-changing, forcing a full repaint.

pub fn widget_rects(&self) -> &[LaidOutWidget<Msg>]

Current laid-out interactive widgets from the last render.

pub fn hit_test(&self, pos: Point) -> Option<usize>

Hit-test a physical point against the last rendered widget rects.

pub fn widget(&self, flat_idx: usize) -> Option<&LaidOutWidget<Msg>>

Lookup a laid-out widget by flat index.

pub fn handlers(&self, flat_idx: usize) -> Option<&WidgetHandlers<Msg>>

Lookup the handler snapshot for a laid-out widget.

pub fn set_focused(&mut self, idx: Option<usize>)

Update keyboard focus state. This is interaction-only, so the next render can use partial damage when layout/content did not change.

pub fn set_hovered(&mut self, idx: Option<usize>)

Update hover state. This is interaction-only.

pub fn set_pressed(&mut self, idx: Option<usize>)

Update pressed state. This is interaction-only.

pub fn focused(&self) -> Option<usize>

pub fn hovered(&self) -> Option<usize>

pub fn pressed(&self) -> Option<usize>

pub fn render( &mut self, element: &Element<Msg>, options: RenderOptions, ) -> RenderOutput

Render element into the backing canvas.

This does not commit, swap buffers, request frame callbacks, or talk to Wayland. The caller owns presentation and frame pacing.

Trait Implementations

impl<Msg: Clone> Drop for UiSurface<Msg>

fn drop(&mut self)

Executes the destructor for this type.