Skip to main content

sui_text/
system.rs

1use std::{
2    cell::RefCell,
3    collections::{HashMap, HashSet},
4    sync::atomic::{AtomicU64, Ordering},
5    sync::{Arc, Mutex, OnceLock},
6    time::Instant,
7};
8
9use sui_core::{Error, Result, Size};
10
11use crate::{
12    FontRegistry,
13    cache::{TextLayoutCache, TextLayoutCacheSnapshot},
14    flatten::FlattenedTextDocument,
15    font::{FaceCacheKey, FontContext, ResolvedSpanInput, TextSystemState},
16    layout::layout_document,
17    model::{
18        PersistentTextLayout, TextDocument, TextLayout, TextLayoutHandle, TextLayoutRegistry,
19        TextLayoutRequest, TextMeasurement, TextRun, TextStyle,
20    },
21};
22
23#[derive(Debug, Clone, Copy, PartialEq, Default)]
24pub struct RuntimeTextTimingDiagnostics {
25    pub request_count: usize,
26    pub cache_hit_count: usize,
27    pub cache_miss_count: usize,
28    pub total_time_us: u64,
29    pub prelookup_time_us: u64,
30    pub cache_lookup_time_us: u64,
31    pub miss_layout_time_us: u64,
32}
33
34thread_local! {
35    static TEXT_TIMING_COLLECTOR: RefCell<Option<RuntimeTextTimingDiagnostics>> =
36        const { RefCell::new(None) };
37}
38
39fn text_timing_enabled() -> bool {
40    static ENABLED: OnceLock<bool> = OnceLock::new();
41    *ENABLED.get_or_init(|| std::env::var_os("SUI_PROFILE_TEXT_TIMINGS").is_some())
42}
43
44pub fn begin_text_timing_collection() {
45    if !text_timing_enabled() {
46        return;
47    }
48
49    TEXT_TIMING_COLLECTOR.with(|collector| {
50        *collector.borrow_mut() = Some(RuntimeTextTimingDiagnostics::default());
51    });
52}
53
54pub fn take_text_timing_collection() -> RuntimeTextTimingDiagnostics {
55    if !text_timing_enabled() {
56        return RuntimeTextTimingDiagnostics::default();
57    }
58
59    TEXT_TIMING_COLLECTOR
60        .with(|collector| collector.borrow_mut().take())
61        .unwrap_or_default()
62}
63
64fn record_text_timing(
65    total_time_us: u64,
66    prelookup_time_us: u64,
67    cache_lookup_time_us: u64,
68    miss_layout_time_us: u64,
69    cache_hit: bool,
70) {
71    if !text_timing_enabled() {
72        return;
73    }
74
75    TEXT_TIMING_COLLECTOR.with(|collector| {
76        let mut collector = collector.borrow_mut();
77        let Some(diagnostics) = collector.as_mut() else {
78            return;
79        };
80        diagnostics.request_count += 1;
81        diagnostics.total_time_us += total_time_us;
82        diagnostics.prelookup_time_us += prelookup_time_us;
83        diagnostics.cache_lookup_time_us += cache_lookup_time_us;
84        diagnostics.miss_layout_time_us += miss_layout_time_us;
85        if cache_hit {
86            diagnostics.cache_hit_count += 1;
87        } else {
88            diagnostics.cache_miss_count += 1;
89        }
90    });
91}
92
93#[derive(Debug)]
94pub struct TextSystem {
95    state: OnceLock<std::result::Result<TextSystemState, String>>,
96    layout_cache: Mutex<TextLayoutCache>,
97    persistent_layouts: Mutex<Arc<TextLayoutRegistry>>,
98    next_layout_handle: AtomicU64,
99}
100
101impl Default for TextSystem {
102    fn default() -> Self {
103        Self {
104            state: OnceLock::new(),
105            layout_cache: Mutex::new(TextLayoutCache::default()),
106            persistent_layouts: Mutex::new(Arc::new(TextLayoutRegistry::default())),
107            next_layout_handle: AtomicU64::new(1),
108        }
109    }
110}
111
112impl TextSystem {
113    pub fn new() -> Self {
114        Self::default()
115    }
116
117    pub fn measure_text(
118        &self,
119        text: impl Into<String>,
120        style: TextStyle,
121        font_registry: &FontRegistry,
122    ) -> Result<TextMeasurement> {
123        self.measure_document(
124            TextDocument::from_plain_text(text.into(), style),
125            font_registry,
126        )
127    }
128
129    pub fn measure_document(
130        &self,
131        document: TextDocument,
132        font_registry: &FontRegistry,
133    ) -> Result<TextMeasurement> {
134        Ok(self
135            .layout_document(TextLayoutRequest::new(document), font_registry)?
136            .measurement())
137    }
138
139    pub fn shape_text(
140        &self,
141        text: impl Into<String>,
142        box_size: Size,
143        style: TextStyle,
144        font_registry: &FontRegistry,
145    ) -> Result<TextLayout> {
146        self.layout_document(
147            TextLayoutRequest::new(TextDocument::from_plain_text(text.into(), style))
148                .with_box_size(box_size),
149            font_registry,
150        )
151    }
152
153    pub fn layout_document(
154        &self,
155        request: TextLayoutRequest,
156        font_registry: &FontRegistry,
157    ) -> Result<TextLayout> {
158        self.shape_text_internal(request, font_registry)
159    }
160
161    pub fn shape_text_persistent(
162        &self,
163        handle: Option<TextLayoutHandle>,
164        text: impl Into<String>,
165        box_size: Size,
166        style: TextStyle,
167        font_registry: &FontRegistry,
168    ) -> Result<PersistentTextLayout> {
169        let layout = self.shape_text(text, box_size, style, font_registry)?;
170        Ok(self.pin_layout(handle, layout))
171    }
172
173    pub fn layout_document_persistent(
174        &self,
175        handle: Option<TextLayoutHandle>,
176        request: TextLayoutRequest,
177        font_registry: &FontRegistry,
178    ) -> Result<PersistentTextLayout> {
179        let layout = self.layout_document(request, font_registry)?;
180        Ok(self.pin_layout(handle, layout))
181    }
182
183    pub fn shape_text_run(
184        &self,
185        run: &TextRun,
186        font_registry: &FontRegistry,
187    ) -> Result<TextLayout> {
188        self.shape_text(
189            run.text.clone(),
190            run.rect.size,
191            run.style.clone(),
192            font_registry,
193        )
194    }
195
196    pub fn shape_text_run_persistent(
197        &self,
198        handle: Option<TextLayoutHandle>,
199        run: &TextRun,
200        font_registry: &FontRegistry,
201    ) -> Result<PersistentTextLayout> {
202        let layout = self.shape_text_run(run, font_registry)?;
203        Ok(self.pin_layout(handle, layout))
204    }
205
206    pub fn adopt_layout(&self, layout: TextLayout) -> PersistentTextLayout {
207        let handle = TextLayoutHandle::from_layout_id(layout.id());
208        self.store_persistent_layout(handle, layout)
209    }
210
211    pub fn touch_persistent_layout(&self, layout: &PersistentTextLayout) {
212        self.store_persistent_layout(layout.handle(), layout.layout().clone());
213    }
214
215    pub fn text_layout_registry(&self) -> Arc<TextLayoutRegistry> {
216        match self.persistent_layouts.lock() {
217            Ok(registry) => Arc::clone(&registry),
218            Err(poisoned) => Arc::clone(&poisoned.into_inner()),
219        }
220    }
221
222    pub fn retain_persistent_layouts(&self, handles: &HashSet<TextLayoutHandle>) {
223        match self.persistent_layouts.lock() {
224            Ok(mut registry) => Arc::make_mut(&mut registry).retain_handles(handles),
225            Err(poisoned) => {
226                let mut registry = poisoned.into_inner();
227                Arc::make_mut(&mut registry).retain_handles(handles);
228            }
229        }
230    }
231
232    pub fn layout_cache_snapshot(&self) -> TextLayoutCacheSnapshot {
233        self.layout_cache
234            .lock()
235            .ok()
236            .map(|cache| cache.snapshot())
237            .unwrap_or_default()
238    }
239
240    fn shape_text_internal(
241        &self,
242        request: TextLayoutRequest,
243        font_registry: &FontRegistry,
244    ) -> Result<TextLayout> {
245        let total_started = text_timing_enabled().then(Instant::now);
246        let TextLayoutRequest { document, box_size } = request;
247        let normalized_document = document.into_normalized();
248        let span_face_keys = self.resolve_span_face_keys(&normalized_document, font_registry)?;
249        let prelookup_time_us = total_started
250            .as_ref()
251            .map(|started| started.elapsed().as_micros() as u64)
252            .unwrap_or(0);
253
254        let lookup_started = text_timing_enabled().then(Instant::now);
255        if let Some(cached) = self.cached_layout(&normalized_document, &span_face_keys, box_size)? {
256            let cache_lookup_time_us = lookup_started
257                .as_ref()
258                .map(|started| started.elapsed().as_micros() as u64)
259                .unwrap_or(0);
260            let total_time_us = total_started
261                .as_ref()
262                .map(|started| started.elapsed().as_micros() as u64)
263                .unwrap_or(0);
264            record_text_timing(
265                total_time_us,
266                prelookup_time_us,
267                cache_lookup_time_us,
268                0,
269                true,
270            );
271            return Ok(cached.with_document(normalized_document));
272        }
273
274        let cache_lookup_time_us = lookup_started
275            .as_ref()
276            .map(|started| started.elapsed().as_micros() as u64)
277            .unwrap_or(0);
278
279        let layout_started = text_timing_enabled().then(Instant::now);
280        let flattened = FlattenedTextDocument::new(normalized_document.clone());
281        let font_context = self.font_context(font_registry)?;
282        let resolved_spans = self.resolve_span_inputs(&flattened, &font_context)?;
283        let layout_id = crate::cache::TextLayoutCacheKey::stable_layout_id(
284            &normalized_document,
285            &span_face_keys,
286            box_size,
287        );
288        let layout = layout_document(flattened, resolved_spans, box_size, font_context, layout_id)?;
289        let miss_layout_time_us = layout_started
290            .as_ref()
291            .map(|started| started.elapsed().as_micros() as u64)
292            .unwrap_or(0);
293        self.store_layout(
294            &normalized_document,
295            &span_face_keys,
296            box_size,
297            layout.clone(),
298        )?;
299        let total_time_us = total_started
300            .as_ref()
301            .map(|started| started.elapsed().as_micros() as u64)
302            .unwrap_or(0);
303        record_text_timing(
304            total_time_us,
305            prelookup_time_us,
306            cache_lookup_time_us,
307            miss_layout_time_us,
308            false,
309        );
310        Ok(layout.with_document(normalized_document))
311    }
312
313    fn pin_layout(
314        &self,
315        handle: Option<TextLayoutHandle>,
316        layout: TextLayout,
317    ) -> PersistentTextLayout {
318        let handle = handle.unwrap_or_else(|| self.alloc_layout_handle());
319        self.store_persistent_layout(handle, layout)
320    }
321
322    fn alloc_layout_handle(&self) -> TextLayoutHandle {
323        TextLayoutHandle::new(
324            self.next_layout_handle
325                .fetch_add(1, Ordering::Relaxed)
326                .max(1),
327        )
328    }
329
330    fn store_persistent_layout(
331        &self,
332        handle: TextLayoutHandle,
333        layout: TextLayout,
334    ) -> PersistentTextLayout {
335        match self.persistent_layouts.lock() {
336            Ok(mut registry) => Arc::make_mut(&mut registry).insert(handle, layout.clone()),
337            Err(poisoned) => {
338                let mut registry = poisoned.into_inner();
339                Arc::make_mut(&mut registry).insert(handle, layout.clone());
340            }
341        }
342        PersistentTextLayout::new(handle, layout)
343    }
344
345    fn resolve_span_inputs(
346        &self,
347        flattened: &FlattenedTextDocument,
348        font_context: &FontContext,
349    ) -> Result<Vec<ResolvedSpanInput>> {
350        flattened
351            .spans
352            .iter()
353            .map(|span| font_context.resolve_span(span.id.clone(), span.text.clone(), &span.style))
354            .collect()
355    }
356
357    fn resolve_span_face_keys(
358        &self,
359        document: &TextDocument,
360        font_registry: &FontRegistry,
361    ) -> Result<Vec<FaceCacheKey>> {
362        let state = self.text_system_state()?;
363        let default_face_key = state.default_face_key();
364        let total_spans = document
365            .paragraphs
366            .iter()
367            .map(|paragraph| paragraph.spans.len())
368            .sum();
369        let mut keys = Vec::with_capacity(total_spans);
370        let mut explicit_face_keys = HashMap::new();
371
372        for paragraph in &document.paragraphs {
373            for span in &paragraph.spans {
374                let face_key = match span.style.font {
375                    Some(handle) => {
376                        if let Some(face_key) = explicit_face_keys.get(&handle).copied() {
377                            face_key
378                        } else {
379                            let font = font_registry.get(handle).ok_or_else(|| {
380                                Error::new(format!(
381                                    "font handle {} is not registered",
382                                    handle.get()
383                                ))
384                            })?;
385                            let face_key = FaceCacheKey::from_registered_font(font);
386                            explicit_face_keys.insert(handle, face_key);
387                            face_key
388                        }
389                    }
390                    None => default_face_key,
391                };
392                keys.push(face_key);
393            }
394        }
395
396        Ok(keys)
397    }
398
399    fn cached_layout(
400        &self,
401        document: &TextDocument,
402        span_face_keys: &[FaceCacheKey],
403        box_size: Option<Size>,
404    ) -> Result<Option<TextLayout>> {
405        let mut cache = self
406            .layout_cache
407            .lock()
408            .map_err(|_| Error::new("text layout cache lock was poisoned"))?;
409        Ok(cache.get(document, span_face_keys, box_size))
410    }
411
412    fn store_layout(
413        &self,
414        document: &TextDocument,
415        span_face_keys: &[FaceCacheKey],
416        box_size: Option<Size>,
417        layout: TextLayout,
418    ) -> Result<()> {
419        let mut cache = self
420            .layout_cache
421            .lock()
422            .map_err(|_| Error::new("text layout cache lock was poisoned"))?;
423        cache.insert(document, span_face_keys, box_size, layout);
424        Ok(())
425    }
426
427    fn text_system_state(&self) -> Result<&TextSystemState> {
428        let state = self
429            .state
430            .get_or_init(|| TextSystemState::new().map_err(|error| error.to_string()));
431        match state {
432            Ok(state) => Ok(state),
433            Err(message) => Err(Error::new(message.clone())),
434        }
435    }
436
437    fn font_context(&self, font_registry: &FontRegistry) -> Result<FontContext> {
438        self.text_system_state()?.build_font_context(font_registry)
439    }
440}