epaint/
texture_atlas.rs

1use ecolor::Color32;
2use emath::{Rect, remap_clamp};
3
4use crate::{ColorImage, ImageDelta, TextOptions};
5
6#[derive(Clone, Copy, Debug, Eq, PartialEq)]
7struct Rectu {
8    /// inclusive
9    min_x: usize,
10
11    /// inclusive
12    min_y: usize,
13
14    /// exclusive
15    max_x: usize,
16
17    /// exclusive
18    max_y: usize,
19}
20
21impl Rectu {
22    const NOTHING: Self = Self {
23        min_x: usize::MAX,
24        min_y: usize::MAX,
25        max_x: 0,
26        max_y: 0,
27    };
28    const EVERYTHING: Self = Self {
29        min_x: 0,
30        min_y: 0,
31        max_x: usize::MAX,
32        max_y: usize::MAX,
33    };
34}
35
36#[derive(Copy, Clone, Debug)]
37struct PrerasterizedDisc {
38    r: f32,
39    uv: Rectu,
40}
41
42/// A pre-rasterized disc (filled circle), somewhere in the texture atlas.
43#[derive(Copy, Clone, Debug)]
44pub struct PreparedDisc {
45    /// The radius of this disc in texels.
46    pub r: f32,
47
48    /// Width in texels.
49    pub w: f32,
50
51    /// Where in the texture atlas the disc is.
52    /// Normalized in 0-1 range.
53    pub uv: Rect,
54}
55
56/// Contains font data in an atlas, where each character occupied a small rectangle.
57///
58/// More characters can be added, possibly expanding the texture.
59#[derive(Clone)]
60pub struct TextureAtlas {
61    image: ColorImage,
62
63    /// What part of the image that is dirty
64    dirty: Rectu,
65
66    /// Used for when allocating new rectangles.
67    cursor: (usize, usize),
68
69    row_height: usize,
70
71    /// Set when someone requested more space than was available.
72    overflowed: bool,
73
74    /// pre-rasterized discs of radii `2^i`, where `i` is the index.
75    discs: Vec<PrerasterizedDisc>,
76
77    /// Controls how to convert glyph coverage to alpha.
78    options: TextOptions,
79}
80
81impl TextureAtlas {
82    pub fn new(size: [usize; 2], options: TextOptions) -> Self {
83        assert!(size[0] >= 1024, "Tiny texture atlas");
84        let mut atlas = Self {
85            image: ColorImage::filled(size, Color32::TRANSPARENT),
86            dirty: Rectu::EVERYTHING,
87            cursor: (0, 0),
88            row_height: 0,
89            overflowed: false,
90            discs: vec![], // will be filled in below
91            options,
92        };
93
94        // Make the top left pixel fully white for `WHITE_UV`, i.e. painting something with solid color:
95        let (pos, image) = atlas.allocate((1, 1));
96        assert_eq!(
97            pos,
98            (0, 0),
99            "Expected the first allocation to be at (0, 0), but was at {pos:?}"
100        );
101        image[pos] = Color32::WHITE;
102
103        // Allocate a series of anti-aliased discs used to render small filled circles:
104        // TODO(emilk): these circles can be packed A LOT better.
105        // In fact, the whole texture atlas could be packed a lot better.
106        // for r in [1, 2, 4, 8, 16, 32, 64] {
107        //     let w = 2 * r + 3;
108        //     let hw = w as i32 / 2;
109        const LARGEST_CIRCLE_RADIUS: f32 = 8.0; // keep small so that the initial texture atlas is small
110        for i in 0.. {
111            let r = 2.0_f32.powf(i as f32 / 2.0 - 1.0);
112            if r > LARGEST_CIRCLE_RADIUS {
113                break;
114            }
115            let hw = (r + 0.5).ceil() as i32;
116            let w = (2 * hw + 1) as usize;
117            let ((x, y), image) = atlas.allocate((w, w));
118            for dx in -hw..=hw {
119                for dy in -hw..=hw {
120                    let distance_to_center = ((dx * dx + dy * dy) as f32).sqrt();
121                    let coverage =
122                        remap_clamp(distance_to_center, (r - 0.5)..=(r + 0.5), 1.0..=0.0);
123                    image[((x as i32 + hw + dx) as usize, (y as i32 + hw + dy) as usize)] =
124                        options.alpha_from_coverage.color_from_coverage(coverage);
125                }
126            }
127            atlas.discs.push(PrerasterizedDisc {
128                r,
129                uv: Rectu {
130                    min_x: x,
131                    min_y: y,
132                    max_x: x + w,
133                    max_y: y + w,
134                },
135            });
136        }
137
138        atlas
139    }
140
141    pub fn options(&self) -> &TextOptions {
142        &self.options
143    }
144
145    pub fn size(&self) -> [usize; 2] {
146        self.image.size
147    }
148
149    /// Returns the locations and sizes of pre-rasterized discs (filled circles) in this atlas.
150    pub fn prepared_discs(&self) -> Vec<PreparedDisc> {
151        let size = self.size();
152        let inv_w = 1.0 / size[0] as f32;
153        let inv_h = 1.0 / size[1] as f32;
154        self.discs
155            .iter()
156            .map(|disc| {
157                let r = disc.r;
158                let Rectu {
159                    min_x,
160                    min_y,
161                    max_x,
162                    max_y,
163                } = disc.uv;
164                let w = max_x - min_x;
165                let uv = Rect::from_min_max(
166                    emath::pos2(min_x as f32 * inv_w, min_y as f32 * inv_h),
167                    emath::pos2(max_x as f32 * inv_w, max_y as f32 * inv_h),
168                );
169                PreparedDisc { r, w: w as f32, uv }
170            })
171            .collect()
172    }
173
174    fn max_height(&self) -> usize {
175        // the initial width is set to the max size
176        self.image.height().max(self.image.width())
177    }
178
179    /// When this get high, it might be time to clear and start over!
180    pub fn fill_ratio(&self) -> f32 {
181        if self.overflowed {
182            1.0
183        } else {
184            (self.cursor.1 + self.row_height) as f32 / self.max_height() as f32
185        }
186    }
187
188    /// The texture options suitable for a font texture
189    #[inline]
190    pub fn texture_options() -> crate::textures::TextureOptions {
191        crate::textures::TextureOptions::LINEAR
192    }
193
194    /// The full font atlas image.
195    #[inline]
196    pub fn image(&self) -> &ColorImage {
197        &self.image
198    }
199
200    /// Call to get the change to the image since last call.
201    pub fn take_delta(&mut self) -> Option<ImageDelta> {
202        let texture_options = Self::texture_options();
203
204        let dirty = std::mem::replace(&mut self.dirty, Rectu::NOTHING);
205        if dirty == Rectu::NOTHING {
206            None
207        } else if dirty == Rectu::EVERYTHING {
208            Some(ImageDelta::full(self.image.clone(), texture_options))
209        } else {
210            let pos = [dirty.min_x, dirty.min_y];
211            let size = [dirty.max_x - dirty.min_x, dirty.max_y - dirty.min_y];
212            let region = self.image.region_by_pixels(pos, size);
213            Some(ImageDelta::partial(pos, region, texture_options))
214        }
215    }
216
217    /// Returns the coordinates of where the rect ended up,
218    /// and invalidates the region.
219    pub fn allocate(&mut self, (w, h): (usize, usize)) -> ((usize, usize), &mut ColorImage) {
220        /// On some low-precision GPUs (my old iPad) characters get muddled up
221        /// if we don't add some empty pixels between the characters.
222        /// On modern high-precision GPUs this is not needed.
223        const PADDING: usize = 1;
224
225        assert!(
226            w <= self.image.width(),
227            "Tried to allocate a {} wide glyph in a {} wide texture atlas",
228            w,
229            self.image.width()
230        );
231        if self.cursor.0 + w > self.image.width() {
232            // New row:
233            self.cursor.0 = 0;
234            self.cursor.1 += self.row_height + PADDING;
235            self.row_height = 0;
236        }
237
238        self.row_height = self.row_height.max(h);
239
240        let required_height = self.cursor.1 + self.row_height;
241
242        if required_height > self.max_height() {
243            // This is a bad place to be - we need to start reusing space :/
244
245            log::warn!("epaint texture atlas overflowed!");
246
247            self.cursor = (0, self.image.height() / 3); // Restart a bit down - the top of the atlas has too many important things in it
248            self.overflowed = true; // this will signal the user that we need to recreate the texture atlas next frame.
249        } else if resize_to_min_height(&mut self.image, required_height) {
250            self.dirty = Rectu::EVERYTHING;
251        }
252
253        let pos = self.cursor;
254        self.cursor.0 += w + PADDING;
255
256        self.dirty.min_x = self.dirty.min_x.min(pos.0);
257        self.dirty.min_y = self.dirty.min_y.min(pos.1);
258        self.dirty.max_x = self.dirty.max_x.max(pos.0 + w);
259        self.dirty.max_y = self.dirty.max_y.max(pos.1 + h);
260
261        (pos, &mut self.image)
262    }
263}
264
265fn resize_to_min_height(image: &mut ColorImage, required_height: usize) -> bool {
266    while required_height >= image.height() {
267        image.size[1] *= 2; // double the height
268    }
269
270    if image.width() * image.height() > image.pixels.len() {
271        image
272            .pixels
273            .resize(image.width() * image.height(), Color32::TRANSPARENT);
274        true
275    } else {
276        false
277    }
278}
epaint/texture_atlas.rs

epaint/
texture_atlas.rs
