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    font_context: Mutex<Option<CachedFontContext>>,
97    #[cfg(test)]
98    font_context_build_count: AtomicU64,
99    layout_cache: Mutex<TextLayoutCache>,
100    persistent_layouts: Mutex<Arc<TextLayoutRegistry>>,
101    next_layout_handle: AtomicU64,
102}
103
104#[derive(Debug)]
105struct CachedFontContext {
106    registry_key: Vec<(sui_core::FontHandle, FaceCacheKey)>,
107    // Constructing a cosmic-text FontSystem clones and indexes the complete
108    // system font database. Keep that work outside individual layout misses.
109    context: FontContext,
110}
111
112impl Default for TextSystem {
113    fn default() -> Self {
114        Self {
115            state: OnceLock::new(),
116            font_context: Mutex::new(None),
117            #[cfg(test)]
118            font_context_build_count: AtomicU64::new(0),
119            layout_cache: Mutex::new(TextLayoutCache::default()),
120            persistent_layouts: Mutex::new(Arc::new(TextLayoutRegistry::default())),
121            next_layout_handle: AtomicU64::new(1),
122        }
123    }
124}
125
126impl TextSystem {
127    pub fn new() -> Self {
128        Self::default()
129    }
130
131    pub fn measure_text(
132        &self,
133        text: impl Into<String>,
134        style: TextStyle,
135        font_registry: &FontRegistry,
136    ) -> Result<TextMeasurement> {
137        self.measure_document(
138            TextDocument::from_plain_text(text.into(), style),
139            font_registry,
140        )
141    }
142
143    pub fn measure_document(
144        &self,
145        document: TextDocument,
146        font_registry: &FontRegistry,
147    ) -> Result<TextMeasurement> {
148        Ok(self
149            .layout_document(TextLayoutRequest::new(document), font_registry)?
150            .measurement())
151    }
152
153    pub fn shape_text(
154        &self,
155        text: impl Into<String>,
156        box_size: Size,
157        style: TextStyle,
158        font_registry: &FontRegistry,
159    ) -> Result<TextLayout> {
160        self.layout_document(
161            TextLayoutRequest::new(TextDocument::from_plain_text(text.into(), style))
162                .with_box_size(box_size),
163            font_registry,
164        )
165    }
166
167    pub fn layout_document(
168        &self,
169        request: TextLayoutRequest,
170        font_registry: &FontRegistry,
171    ) -> Result<TextLayout> {
172        self.shape_text_internal(request, font_registry)
173    }
174
175    pub fn shape_text_persistent(
176        &self,
177        handle: Option<TextLayoutHandle>,
178        text: impl Into<String>,
179        box_size: Size,
180        style: TextStyle,
181        font_registry: &FontRegistry,
182    ) -> Result<PersistentTextLayout> {
183        let layout = self.shape_text(text, box_size, style, font_registry)?;
184        Ok(self.pin_layout(handle, layout))
185    }
186
187    pub fn layout_document_persistent(
188        &self,
189        handle: Option<TextLayoutHandle>,
190        request: TextLayoutRequest,
191        font_registry: &FontRegistry,
192    ) -> Result<PersistentTextLayout> {
193        let layout = self.layout_document(request, font_registry)?;
194        Ok(self.pin_layout(handle, layout))
195    }
196
197    pub fn shape_text_run(
198        &self,
199        run: &TextRun,
200        font_registry: &FontRegistry,
201    ) -> Result<TextLayout> {
202        self.shape_text(
203            run.text.clone(),
204            run.rect.size,
205            run.style.clone(),
206            font_registry,
207        )
208    }
209
210    pub fn shape_text_run_persistent(
211        &self,
212        handle: Option<TextLayoutHandle>,
213        run: &TextRun,
214        font_registry: &FontRegistry,
215    ) -> Result<PersistentTextLayout> {
216        let layout = self.shape_text_run(run, font_registry)?;
217        Ok(self.pin_layout(handle, layout))
218    }
219
220    pub fn adopt_layout(&self, layout: TextLayout) -> PersistentTextLayout {
221        let handle = TextLayoutHandle::from_layout_id(layout.id());
222        self.store_persistent_layout(handle, layout)
223    }
224
225    pub fn touch_persistent_layout(&self, layout: &PersistentTextLayout) {
226        self.store_persistent_layout(layout.handle(), layout.layout().clone());
227    }
228
229    pub fn text_layout_registry(&self) -> Arc<TextLayoutRegistry> {
230        match self.persistent_layouts.lock() {
231            Ok(registry) => Arc::clone(&registry),
232            Err(poisoned) => Arc::clone(&poisoned.into_inner()),
233        }
234    }
235
236    pub fn retain_persistent_layouts(&self, handles: &HashSet<TextLayoutHandle>) {
237        match self.persistent_layouts.lock() {
238            Ok(mut registry) => Arc::make_mut(&mut registry).retain_handles(handles),
239            Err(poisoned) => {
240                let mut registry = poisoned.into_inner();
241                Arc::make_mut(&mut registry).retain_handles(handles);
242            }
243        }
244    }
245
246    pub fn layout_cache_snapshot(&self) -> TextLayoutCacheSnapshot {
247        self.layout_cache
248            .lock()
249            .ok()
250            .map(|cache| cache.snapshot())
251            .unwrap_or_default()
252    }
253
254    fn shape_text_internal(
255        &self,
256        request: TextLayoutRequest,
257        font_registry: &FontRegistry,
258    ) -> Result<TextLayout> {
259        let total_started = text_timing_enabled().then(Instant::now);
260        let TextLayoutRequest { document, box_size } = request;
261        let normalized_document = document.into_normalized();
262        let span_face_keys = self.resolve_span_face_keys(&normalized_document, font_registry)?;
263        let prelookup_time_us = total_started
264            .as_ref()
265            .map(|started| started.elapsed().as_micros() as u64)
266            .unwrap_or(0);
267
268        let lookup_started = text_timing_enabled().then(Instant::now);
269        if let Some(cached) = self.cached_layout(&normalized_document, &span_face_keys, box_size)? {
270            let cache_lookup_time_us = lookup_started
271                .as_ref()
272                .map(|started| started.elapsed().as_micros() as u64)
273                .unwrap_or(0);
274            let total_time_us = total_started
275                .as_ref()
276                .map(|started| started.elapsed().as_micros() as u64)
277                .unwrap_or(0);
278            record_text_timing(
279                total_time_us,
280                prelookup_time_us,
281                cache_lookup_time_us,
282                0,
283                true,
284            );
285            return Ok(cached.with_document(normalized_document));
286        }
287
288        let cache_lookup_time_us = lookup_started
289            .as_ref()
290            .map(|started| started.elapsed().as_micros() as u64)
291            .unwrap_or(0);
292
293        let layout_started = text_timing_enabled().then(Instant::now);
294        let flattened = FlattenedTextDocument::new(normalized_document.clone());
295        let layout_id = crate::cache::TextLayoutCacheKey::stable_layout_id(
296            &normalized_document,
297            &span_face_keys,
298            box_size,
299        );
300        let layout = self.with_font_context(font_registry, |font_context| {
301            let resolved_spans = self.resolve_span_inputs(&flattened, font_context)?;
302            layout_document(flattened, resolved_spans, box_size, font_context, layout_id)
303        })?;
304        let miss_layout_time_us = layout_started
305            .as_ref()
306            .map(|started| started.elapsed().as_micros() as u64)
307            .unwrap_or(0);
308        self.store_layout(
309            &normalized_document,
310            &span_face_keys,
311            box_size,
312            layout.clone(),
313        )?;
314        let total_time_us = total_started
315            .as_ref()
316            .map(|started| started.elapsed().as_micros() as u64)
317            .unwrap_or(0);
318        record_text_timing(
319            total_time_us,
320            prelookup_time_us,
321            cache_lookup_time_us,
322            miss_layout_time_us,
323            false,
324        );
325        Ok(layout.with_document(normalized_document))
326    }
327
328    fn pin_layout(
329        &self,
330        handle: Option<TextLayoutHandle>,
331        layout: TextLayout,
332    ) -> PersistentTextLayout {
333        let handle = handle.unwrap_or_else(|| self.alloc_layout_handle());
334        self.store_persistent_layout(handle, layout)
335    }
336
337    fn alloc_layout_handle(&self) -> TextLayoutHandle {
338        TextLayoutHandle::new(
339            self.next_layout_handle
340                .fetch_add(1, Ordering::Relaxed)
341                .max(1),
342        )
343    }
344
345    fn store_persistent_layout(
346        &self,
347        handle: TextLayoutHandle,
348        layout: TextLayout,
349    ) -> PersistentTextLayout {
350        match self.persistent_layouts.lock() {
351            Ok(mut registry) => Arc::make_mut(&mut registry).insert(handle, layout.clone()),
352            Err(poisoned) => {
353                let mut registry = poisoned.into_inner();
354                Arc::make_mut(&mut registry).insert(handle, layout.clone());
355            }
356        }
357        PersistentTextLayout::new(handle, layout)
358    }
359
360    fn resolve_span_inputs(
361        &self,
362        flattened: &FlattenedTextDocument,
363        font_context: &FontContext,
364    ) -> Result<Vec<ResolvedSpanInput>> {
365        flattened
366            .spans
367            .iter()
368            .map(|span| font_context.resolve_span(span.id.clone(), span.text.clone(), &span.style))
369            .collect()
370    }
371
372    fn resolve_span_face_keys(
373        &self,
374        document: &TextDocument,
375        font_registry: &FontRegistry,
376    ) -> Result<Vec<FaceCacheKey>> {
377        let state = self.text_system_state()?;
378        let default_face_key = state.default_face_key();
379        let total_spans = document
380            .paragraphs
381            .iter()
382            .map(|paragraph| paragraph.spans.len())
383            .sum();
384        let mut keys = Vec::with_capacity(total_spans);
385        let mut explicit_face_keys = HashMap::new();
386
387        for paragraph in &document.paragraphs {
388            for span in &paragraph.spans {
389                let face_key = match span.style.font {
390                    Some(handle) => {
391                        if let Some(face_key) = explicit_face_keys.get(&handle).copied() {
392                            face_key
393                        } else {
394                            let font = font_registry.get(handle).ok_or_else(|| {
395                                Error::new(format!(
396                                    "font handle {} is not registered",
397                                    handle.get()
398                                ))
399                            })?;
400                            let face_key = FaceCacheKey::from_registered_font(font);
401                            explicit_face_keys.insert(handle, face_key);
402                            face_key
403                        }
404                    }
405                    None => default_face_key,
406                };
407                keys.push(face_key);
408            }
409        }
410
411        Ok(keys)
412    }
413
414    fn cached_layout(
415        &self,
416        document: &TextDocument,
417        span_face_keys: &[FaceCacheKey],
418        box_size: Option<Size>,
419    ) -> Result<Option<TextLayout>> {
420        let mut cache = self
421            .layout_cache
422            .lock()
423            .map_err(|_| Error::new("text layout cache lock was poisoned"))?;
424        Ok(cache.get(document, span_face_keys, box_size))
425    }
426
427    fn store_layout(
428        &self,
429        document: &TextDocument,
430        span_face_keys: &[FaceCacheKey],
431        box_size: Option<Size>,
432        layout: TextLayout,
433    ) -> Result<()> {
434        let mut cache = self
435            .layout_cache
436            .lock()
437            .map_err(|_| Error::new("text layout cache lock was poisoned"))?;
438        cache.insert(document, span_face_keys, box_size, layout);
439        Ok(())
440    }
441
442    fn text_system_state(&self) -> Result<&TextSystemState> {
443        let state = self
444            .state
445            .get_or_init(|| TextSystemState::new().map_err(|error| error.to_string()));
446        match state {
447            Ok(state) => Ok(state),
448            Err(message) => Err(Error::new(message.clone())),
449        }
450    }
451
452    fn with_font_context<T>(
453        &self,
454        font_registry: &FontRegistry,
455        operation: impl FnOnce(&mut FontContext) -> Result<T>,
456    ) -> Result<T> {
457        let registry_key = font_registry.cache_key();
458        let mut cached = self
459            .font_context
460            .lock()
461            .map_err(|_| Error::new("text font context cache lock was poisoned"))?;
462        let rebuild = cached
463            .as_ref()
464            .is_none_or(|cached| cached.registry_key != registry_key);
465        if rebuild {
466            *cached = Some(CachedFontContext {
467                registry_key,
468                context: self
469                    .text_system_state()?
470                    .build_font_context(font_registry)?,
471            });
472            #[cfg(test)]
473            self.font_context_build_count
474                .fetch_add(1, Ordering::Relaxed);
475        }
476
477        operation(
478            &mut cached
479                .as_mut()
480                .expect("font context was initialized")
481                .context,
482        )
483    }
484
485    #[cfg(test)]
486    pub(crate) fn font_context_build_count(&self) -> u64 {
487        self.font_context_build_count.load(Ordering::Relaxed)
488    }
489}