ncca-ngl 0.1.1__py3-none-any.whl → 0.1.4__py3-none-any.whl

ncca/ngl/shaders/checker_fragment.glsl

@@ -0,0 +1,35 @@
+#version 410 core
+in vec3 fragmentNormal;
+in vec2 uv;
+
+layout (location =0) out vec4 fragColour;
+uniform vec4 colour1;
+uniform vec4 colour2;
+
+uniform vec3 lightPos;
+uniform vec4 lightDiffuse;
+uniform float checkSize=10.0;
+uniform bool checkOn;
+
+vec4 checker( vec2 uv )
+{
+  if(checkOn == false)
+    return colour1;
+  else
+  {
+  float v = floor( checkSize * uv.x ) +floor( checkSize * uv.y );
+  if( mod( v, 2.0 ) < 1.0 )
+     return colour2;
+  else
+     return colour1;
+
+  }
+}
+
+void main ()
+{
+  fragColour= vec4(0.);
+  vec3 N = normalize(fragmentNormal);
+  vec3 L = normalize(lightPos);
+  fragColour += checker(uv)*lightDiffuse *dot(L, N);
+}

ncca/ngl/shaders/checker_vertex.glsl

@@ -0,0 +1,19 @@
+#version 410 core
+
+
+/// @brief the vertex passed in
+layout (location = 0) in vec3 inVert;
+/// @brief the normal passed in
+layout (location = 1) in vec3 inNormal;
+/// @brief the in uv
+layout (location = 2) in vec2 inUV;
+out vec3 fragmentNormal;
+out vec2 uv;
+uniform mat4 MVP;
+uniform mat3 normalMatrix;
+void main()
+{
+  fragmentNormal = (normalMatrix*inNormal);
+  uv=inUV;
+  gl_Position = MVP*vec4(inVert,1.0);
+}

ncca/ngl/shaders/colour_fragment.glsl

@@ -0,0 +1,8 @@
+#version 410 core
+uniform vec4 Colour;
+layout(location=0) out vec4 outColour;
+
+void main ()
+{
+  outColour = Colour;
+}

ncca/ngl/shaders/colour_vertex.glsl

@@ -0,0 +1,11 @@
+#version 410 core
+
+uniform mat4 MVP;
+
+layout(location=0) in vec3 inVert;
+uniform vec4 Colour;
+
+void main(void)
+{
+  gl_Position = MVP*vec4(inVert, 1.0);
+}

ncca/ngl/shaders/diffuse_fragment.glsl

@@ -0,0 +1,21 @@
+#version 410
+in vec3 fragmentNormal;
+in vec3 fragmentPosition; // Receive fragment position
+
+layout (location =0) out vec4 fragColour;
+
+uniform vec4 Colour;
+uniform vec3 lightPos; // Light's position in view space
+uniform vec4 lightDiffuse;
+
+void main ()
+{
+    // Ensure fragment normal is unit length
+    vec3 N = normalize(fragmentNormal);
+    // Calculate vector from fragment to light
+    vec3 L = normalize(lightPos - fragmentPosition);
+    // Calculate diffuse factor, ensuring it's not negative
+    float diffuse = max(dot(L, N), 0.0);
+    // Final colour
+    fragColour = Colour * lightDiffuse * diffuse;
+}

ncca/ngl/shaders/diffuse_vertex.glsl

@@ -0,0 +1,24 @@
+#version 410
+out vec3 fragmentNormal;
+out vec3 fragmentPosition;
+
+layout(location=0) in vec3 inVert;
+layout(location=1) in vec3 inNormal;
+
+uniform mat4 MVP;
+uniform mat4 MV;
+uniform mat3 normalMatrix;
+
+void main()
+{
+  // Transform normal into view space but DO NOT normalize it here.
+  // The interpolation and per-fragment normalization is key to smooth shading.
+  fragmentNormal = normalMatrix * inNormal;
+
+  // Transform vertex position into view space
+  vec4 viewPosition = MV * vec4(inVert, 1.0);
+  fragmentPosition = viewPosition.xyz;
+
+  // Transform vertex to clip space
+  gl_Position = MVP * vec4(inVert, 1.0);
+}

ncca/ngl/shaders/text_fragment.glsl

@@ -0,0 +1,10 @@
+#version 410 core
+in vec2 v_uv;
+uniform sampler2D textureID;
+uniform vec4 textColour;
+out vec4 fragColor;
+void main()
+{
+    float a = texture(textureID, v_uv).a;
+    fragColor = vec4(textColour.rgb, textColour.a * a);
+}

ncca/ngl/shaders/text_geometry.glsl

@@ -0,0 +1,53 @@
+#version 410 core
+layout(points) in;
+layout(triangle_strip, max_vertices=4) out;
+
+uniform vec2 screenSize;
+uniform float fontSize;
+
+in VS_OUT
+{
+    vec2 pos;
+    vec4 uvRect;
+    vec2 size;
+}
+gs_in[];
+
+out vec2 v_uv;
+
+vec2 toNDC(vec2 screenPos)
+{
+    return vec2(
+        (screenPos.x / screenSize.x) * 2.0 - 1.0,
+        1.0 - (screenPos.y /screenSize.y) * 2.0
+    );
+}
+
+void main()
+{
+    vec2 base = gs_in[0].pos;
+    vec2 gsize = gs_in[0].size * fontSize;
+    vec4 uv = gs_in[0].uvRect;
+    // generate a quad
+    // Top Left
+    gl_Position = vec4(toNDC(base), 0.0, 1.0);
+    v_uv = uv.xy;
+    EmitVertex();
+
+    // Bottom Left
+    gl_Position = vec4(toNDC(base + vec2(0.0, gsize.y)), 0.0, 1.0);
+    v_uv = vec2(uv.x, uv.w);
+    EmitVertex();
+
+    // Top Right
+    gl_Position = vec4(toNDC(base + vec2(gsize.x, 0.0)), 0.0, 1.0);
+    v_uv = vec2(uv.z, uv.y);
+    EmitVertex();
+
+    // Bottom Right
+    gl_Position = vec4(toNDC(base + gsize), 0.0, 1.0);
+    v_uv = uv.zw;
+    EmitVertex();
+
+    EndPrimitive();
+}

ncca/ngl/shaders/text_vertex.glsl

@@ -0,0 +1,18 @@
+#version 410 core
+layout(location=0) in vec2 position;
+layout(location=1) in vec4 uvRect;
+layout(location=2) in vec2 size;
+
+out VS_OUT
+{
+    vec2 pos;
+    vec4 uvRect;
+    vec2 size;
+} vs_out;
+
+void main()
+{
+    vs_out.pos = position;
+    vs_out.uvRect = uvRect;
+    vs_out.size = size;
+}

ncca/ngl/simple_index_vao.py

@@ -0,0 +1,65 @@
+import numpy as np
+import OpenGL.GL as gl
+
+from .abstract_vao import AbstractVAO, VertexData
+from .log import logger
+
+
+class IndexVertexData(VertexData):
+    def __init__(self, data, size, indices, index_type, mode=gl.GL_STATIC_DRAW):
+        super().__init__(data, size, mode)
+        gl.GL_to_numpy_type = {
+            gl.GL_UNSIGNED_INT: np.uint32,
+            gl.GL_UNSIGNED_SHORT: np.uint16,
+            gl.GL_UNSIGNED_BYTE: np.uint8,
+        }
+        numpy_dtype = gl.GL_to_numpy_type.get(index_type)
+        if numpy_dtype is None:
+            logger.error("SimpleIndexVAO: Unsupported index type")
+            raise TypeError(f"Unsupported index type: {index_type}")
+
+        self.indices = np.array(indices, dtype=numpy_dtype)
+        self.index_type = index_type
+
+
+class SimpleIndexVAO(AbstractVAO):
+    def __init__(self, mode=gl.GL_TRIANGLES):
+        super().__init__(mode)
+        self.buffer = gl.glGenBuffers(1)
+        self.idx_buffer = gl.glGenBuffers(1)
+        self.index_type = gl.GL_UNSIGNED_INT
+
+    def draw(self):
+        if self.bound and self.allocated:
+            gl.glDrawElements(self.mode, self.indices_count, self.index_type, None)
+        else:
+            logger.error("SimpleIndexVAO not bound or not allocated")
+
+    def set_data(self, data):
+        if not isinstance(data, IndexVertexData):
+            logger.error("SimpleIndexVAO: Unsupported index type")
+            raise TypeError("data must be of type IndexVertexData")
+
+        gl.glBindBuffer(gl.GL_ARRAY_BUFFER, self.buffer)
+        gl.glBufferData(gl.GL_ARRAY_BUFFER, data.data.nbytes, data.data, data.mode)
+
+        gl.glBindBuffer(gl.GL_ELEMENT_ARRAY_BUFFER, self.idx_buffer)
+        gl.glBufferData(
+            gl.GL_ELEMENT_ARRAY_BUFFER, data.indices.nbytes, data.indices, data.mode
+        )
+
+        self.allocated = True
+        self.indices_count = len(data.indices)
+        self.index_type = data.index_type
+
+    def remove_vao(self):
+        gl.glDeleteBuffers(1, [self.buffer])
+        gl.glDeleteBuffers(1, [self.idx_buffer])
+        gl.glDeleteVertexArrays(1, [self.id])
+
+    def get_buffer_id(self, index=0):
+        return self.buffer
+
+    def map_buffer(self, index=0, access_mode=gl.GL_READ_WRITE):
+        gl.glBindBuffer(gl.GL_ARRAY_BUFFER, self.buffer)
+        return gl.glMapBuffer(gl.GL_ARRAY_BUFFER, access_mode)

ncca/ngl/simple_vao.py

@@ -0,0 +1,42 @@
+import OpenGL.GL as gl
+
+from .abstract_vao import AbstractVAO, VertexData
+from .log import logger
+
+
+class SimpleVAO(AbstractVAO):
+    def __init__(self, mode=gl.GL_TRIANGLES):
+        super().__init__(mode)
+        self.buffer = gl.glGenBuffers(1)
+
+    def draw(self):
+        if self.bound and self.allocated:
+            gl.glDrawArrays(self.mode, 0, self.indices_count)
+        else:
+            logger.error("SimpleVAO not bound or not allocated")
+
+    def set_data(self, data):
+        if not isinstance(data, VertexData):
+            logger.error("SimpleVAO: Invalid data type")
+            raise TypeError("data must be of type VertexData")
+        if not self.bound:
+            logger.error("SimpleVAO not bound")
+            raise RuntimeError("SimpleVAO not bound")
+        gl.glBindBuffer(gl.GL_ARRAY_BUFFER, self.buffer)
+        gl.glBufferData(gl.GL_ARRAY_BUFFER, data.data.nbytes, data.data, data.mode)
+        self.allocated = True
+        self.indices_count = data.size
+
+    def num_indices(self):
+        return self.indices_count
+
+    def remove_vao(self):
+        gl.glDeleteBuffers(1, [self.buffer])
+        gl.glDeleteVertexArrays(1, [self.id])
+
+    def get_buffer_id(self, index=0):
+        return self.buffer
+
+    def map_buffer(self, index=0, access_mode=gl.GL_READ_WRITE):
+        gl.glBindBuffer(gl.GL_ARRAY_BUFFER, self.buffer)
+        return gl.glMapBuffer(gl.GL_ARRAY_BUFFER, access_mode)

ncca/ngl/text.py

@@ -0,0 +1,342 @@
+"""
+A module for rendering text in OpenGL using pre-rendered font atlases.
+
+This implementation uses the 'freetype-py' library to rasterize characters
+from a given font file into a single texture atlas. This atlas is then
+used by a set of shaders (vertex, geometry, and fragment) to render
+text efficiently.
+
+The process is as follows:
+1.  FontAtlas class:
+    -   Loads a font file.
+    -   Renders glyphs for a range of characters (ASCII ' ' to '~').
+    -   Packs these glyphs into a single large texture atlas in memory.
+    -   Calculates and stores metadata for each glyph (size, bearing,
+        advance, and UV coordinates within the atlas).
+    -   Generates a single OpenGL texture for the atlas.
+
+2.  _Text class (exported as Text):
+    -   Manages multiple fonts by creating and storing FontAtlas objects.
+    -   Provides a `render_dynamic_text` method to draw text strings.
+    -   `_build_instances`: For a given string, this method generates a
+        list of vertex attributes for each character. Each character is
+        represented as a single point with attributes for position, UVs,
+        and size.
+    -   `render_dynamic_text`: This method sends the generated instance
+        data to the GPU and draws it using GL_POINTS.
+
+3.  Shaders:
+    -   Vertex Shader: A simple pass-through shader that sends point
+        data to the geometry shader.
+    -   Geometry Shader: Receives points and generates a textured quad
+        for each character on the fly.
+    -   Fragment Shader: Samples the font atlas texture to color the
+        quad, effectively drawing the character.
+"""
+
+from typing import Any, Dict, List
+
+import freetype
+import numpy as np
+import OpenGL.GL as gl
+
+from .log import logger
+from .shader_lib import DefaultShader, ShaderLib
+from .simple_vao import VertexData
+from .vao_factory import VAOFactory, VAOType
+from .vec3 import Vec3
+
+
+class FontAtlas:
+    """
+    Manages the creation of a font texture atlas for efficient text rendering.
+
+    This class uses FreeType to render glyphs for a specified font and packs them
+    into a single texture. It also stores metadata for each glyph.
+    """
+
+    def __init__(self, font_path: str, font_size: int = 48, debug: bool = False):
+        """
+        Initializes the FontAtlas.
+
+        Args:
+            font_path: The file path to the font (e.g., a .ttf file).
+            font_size: The font size in pixels to be used for rendering the atlas.
+            debug: If True, saves the generated atlas as a PNG for debugging.
+        """
+        try:
+            self.face = freetype.Face(font_path)
+            self.face.set_pixel_sizes(0, font_size)
+            self.font_size: int = font_size
+            self.glyphs: Dict[str, Dict[str, Any]] = {}
+            self.texture: int = 0
+            self.atlas_w: int = 0
+            self.atlas_h: int = 0
+            self.atlas: np.ndarray | None = None
+            self.build_atlas(debug)
+
+        except freetype.FT_Exception as e:
+            logger.error(f"{font_path} could not be loaded {e}")
+
+    def __str__(self) -> str:
+        """Returns a string representation of the FontAtlas."""
+        return f"TextureID: {self.texture}, FontSize: {self.font_size}"
+
+    def build_atlas(self, debug: bool = False) -> None:
+        """
+        Renders characters and packs them into a texture atlas.
+
+        This method iterates through ASCII characters 32-126, renders each one
+        using FreeType, and arranges them in a single large numpy array which
+        will later be used to create an OpenGL texture.
+
+        Args:
+            debug: If True, saves the generated atlas as 'debug_atlas.png'.
+        """
+        padding = 2  # Padding between glyphs in the atlas
+        atlas_w = 1024  # Fixed width for the atlas texture
+        x, y, row_h = 0, 0, 0
+        bitmaps_data = []
+
+        # Iterate through printable ASCII characters
+        for charcode in range(ord(" "), ord("~")):
+            self.face.load_char(chr(charcode), freetype.FT_LOAD_RENDER)
+            bmp = self.face.glyph.bitmap
+            w, h = bmp.width, bmp.rows
+
+            # Move to the next row if the current glyph doesn't fit
+            if x + w + padding > atlas_w:
+                x = 0
+                y += row_h + padding
+                row_h = 0
+
+            # Copy bitmap data as the buffer is overwritten for each glyph
+            if w > 0 and h > 0:
+                buffer_copy = np.array(bmp.buffer, dtype=np.ubyte).reshape(h, w)
+                bitmaps_data.append((buffer_copy, x, y))
+
+            # Store glyph metadata
+            self.glyphs[chr(charcode)] = {
+                "size": (w, h),
+                "bearing": (self.face.glyph.bitmap_left, self.face.glyph.bitmap_top),
+                "advance": self.face.glyph.advance.x >> 6,  # Advance is in 1/64 pixels
+                "uv": (x, y, x + w, y + h),  # UVs in pixel coordinates
+            }
+            x += w + padding
+            row_h = max(row_h, h)
+
+        atlas_h = y + row_h + padding
+        self.atlas_w, self.atlas_h = atlas_w, atlas_h
+        atlas = np.zeros((atlas_h, atlas_w), dtype=np.ubyte)
+
+        # Blit all the individual glyph bitmaps onto the atlas
+        for arr, dest_x, dest_y in bitmaps_data:
+            h, w = arr.shape
+            atlas[dest_y : dest_y + h, dest_x : dest_x + w] = arr
+
+        self.atlas = atlas
+        if debug:
+            from PIL import Image
+
+            img = Image.fromarray(self.atlas, mode="L")
+            img.save("debug_atlas.png")
+            print(f"Saved debug_atlas.png, size: {self.atlas.shape}")
+
+    def generate_texture(self) -> None:
+        """Generates and configures the OpenGL texture for the font atlas."""
+        if self.atlas is None:
+            return
+        tex = gl.glGenTextures(1)
+        gl.glPixelStorei(gl.GL_UNPACK_ALIGNMENT, 1)
+
+        gl.glBindTexture(gl.GL_TEXTURE_2D, tex)
+        # Create a single-channel RED texture from our numpy atlas
+        gl.glTexImage2D(
+            gl.GL_TEXTURE_2D,
+            0,
+            gl.GL_RED,
+            self.atlas_w,
+            self.atlas_h,
+            0,
+            gl.GL_RED,
+            gl.GL_UNSIGNED_BYTE,
+            self.atlas,
+        )
+
+        gl.glTexParameteri(gl.GL_TEXTURE_2D, gl.GL_TEXTURE_MIN_FILTER, gl.GL_LINEAR)
+        gl.glTexParameteri(gl.GL_TEXTURE_2D, gl.GL_TEXTURE_MAG_FILTER, gl.GL_LINEAR)
+        gl.glTexParameteri(gl.GL_TEXTURE_2D, gl.GL_TEXTURE_WRAP_S, gl.GL_CLAMP_TO_EDGE)
+        gl.glTexParameteri(gl.GL_TEXTURE_2D, gl.GL_TEXTURE_WRAP_T, gl.GL_CLAMP_TO_EDGE)
+
+        # Use texture swizzling to use the RED channel as ALPHA.
+        # This allows us to color the font using a uniform in the shader,
+        # while using the glyph's intensity for transparency.
+        # We set the texture's RGB channels to 1.0, and the A channel to the
+        # value from the RED channel of the source.
+        gl.glTexParameteri(gl.GL_TEXTURE_2D, gl.GL_TEXTURE_SWIZZLE_R, gl.GL_ONE)
+        gl.glTexParameteri(gl.GL_TEXTURE_2D, gl.GL_TEXTURE_SWIZZLE_G, gl.GL_ONE)
+        gl.glTexParameteri(gl.GL_TEXTURE_2D, gl.GL_TEXTURE_SWIZZLE_B, gl.GL_ONE)
+        gl.glTexParameteri(gl.GL_TEXTURE_2D, gl.GL_TEXTURE_SWIZZLE_A, gl.GL_RED)
+
+        self.texture = tex
+
+
+class _Text:
+    """
+    Main class for managing and rendering text.
+
+    This class acts as a controller, loading fonts and providing methods
+    to render text strings to the screen. It is designed to be used as a
+    singleton instance.
+    """
+
+    def __init__(self) -> None:
+        """Initializes the Text renderer."""
+        self._fonts: Dict[str, FontAtlas] = {}
+        self._static_text: List[Any] = []  # Reserved for future use
+
+    def add_font(self, name: str, font_file: str, size: int) -> None:
+        """
+        Loads a font and makes it available for rendering.
+
+        Args:
+            name: A unique name to identify this font (e.g., "main_font").
+            font_file: The path to the font file.
+            size: The font size in pixels.
+        """
+        if not hasattr(self, "vao"):
+            self.vao = VAOFactory.create_vao(VAOType.SIMPLE, gl.GL_POINTS)
+        font = FontAtlas(font_file, size)
+        font.generate_texture()
+        print(f"Font '{name}' added with texture ID: {font.texture}")
+        self._fonts[name] = font
+
+    def set_screen_size(self, w: int, h: int) -> None:
+        """
+        Sets the screen dimensions for the text shader.
+
+        This should be called whenever the window is resized.
+
+        Args:
+            w: The width of the screen in pixels.
+            h: The height of the screen in pixels.
+        """
+        ShaderLib.use(DefaultShader.TEXT)
+        ShaderLib.set_uniform("textureID", 0)
+        ShaderLib.set_uniform("screenSize", float(w), float(h))
+        ShaderLib.set_uniform("fontSize", 1.0)
+        ShaderLib.set_uniform("textColour", 1.0, 1.0, 1.0, 1.0)
+
+    def render_text(self, font: str, x: int, y: int, text: str, colour: Vec3 = Vec3(1.0, 1.0, 1.0)) -> None:
+        """
+        Renders a string of text to the screen.
+
+        Args:
+            font: The name of the font to use (previously added with add_font).
+            x: The x-coordinate of the starting position (baseline).
+            y: The y-coordinate of the starting position (baseline).
+            text: The string of text to render.
+            colour: The color of the text as a Vec4.
+        """
+        render_data = self._build_instances(font, text, x, y)
+        if not render_data:
+            return
+
+        buffer_data = np.array(render_data, dtype=np.float32)
+        atlas = self._fonts[font]
+
+        # Enable blending for transparency
+        gl.glEnable(gl.GL_BLEND)
+        gl.glBlendFunc(gl.GL_SRC_ALPHA, gl.GL_ONE_MINUS_SRC_ALPHA)
+
+        # Ensure text is rendered filled and restore state afterwards.
+        polygon_mode = gl.glGetIntegerv(gl.GL_POLYGON_MODE)[0]
+        if polygon_mode != gl.GL_FILL:
+            gl.glPolygonMode(gl.GL_FRONT_AND_BACK, gl.GL_FILL)
+
+        # Disable depth testing to ensure text is always drawn on top
+        depth_test_enabled = gl.glIsEnabled(gl.GL_DEPTH_TEST)
+        if depth_test_enabled:
+            gl.glDisable(gl.GL_DEPTH_TEST)
+
+        with self.vao as vao:
+            data = VertexData(data=buffer_data, size=buffer_data.nbytes)
+            stride = 32  # 8 floats * 4 bytes
+            vao.set_data(data)
+            # Vertex Attributes:
+            # 0: vec2 a_position (screen position of the glyph)
+            # 1: vec4 a_uvRect (u0, v0, u1, v1)
+            # 2: vec2 a_size (width, height of the glyph quad)
+            vao.set_vertex_attribute_pointer(0, 2, gl.GL_FLOAT, stride, 0)
+            vao.set_vertex_attribute_pointer(1, 4, gl.GL_FLOAT, stride, 8)
+            vao.set_vertex_attribute_pointer(2, 2, gl.GL_FLOAT, stride, 24)
+
+            gl.glActiveTexture(gl.GL_TEXTURE0)
+            gl.glBindTexture(gl.GL_TEXTURE_2D, atlas.texture)
+            ShaderLib.use(DefaultShader.TEXT)
+            ShaderLib.set_uniform("textColour", float(colour.x), float(colour.y), float(colour.z), 1.0)
+            # We are drawing one point per character
+            vao.set_num_indices(len(render_data) // 8)
+            vao.draw()
+
+        # Restore OpenGL state
+        gl.glDisable(gl.GL_BLEND)
+        if depth_test_enabled:
+            gl.glEnable(gl.GL_DEPTH_TEST)
+        if polygon_mode != gl.GL_FILL:
+            gl.glPolygonMode(gl.GL_FRONT_AND_BACK, polygon_mode)
+
+    def _build_instances(self, font: str, text: str, start_x: int, start_y: int) -> List[float]:
+        """
+        Generates vertex attribute data for each character in a string.
+
+        This data is sent to the GPU as a single buffer. The geometry shader
+        then uses this data to construct a quad for each character.
+
+        Args:
+            font: The name of the font to use.
+            text: The string to process.
+            start_x: The initial x-coordinate for the text baseline.
+            start_y: The initial y-coordinate for the text baseline.
+
+        Returns:
+            A list of floats representing the packed vertex data for all characters.
+        """
+        inst = []
+        atlas = self._fonts.get(font)
+        if atlas:
+            x, y = float(start_x), float(start_y)  # Use floats for positioning
+
+            for ch in text:
+                if ch not in atlas.glyphs:
+                    continue
+                g = atlas.glyphs[ch]
+                w, h = g["size"]
+                adv = g["advance"]
+                bearing_x, bearing_y = g["bearing"]
+
+                # UV coordinates from atlas (in pixels)
+                u0_px, v0_px, u1_px, v1_px = g["uv"]
+
+                # Normalize UVs to the range [0, 1]
+                u0 = u0_px / atlas.atlas_w
+                v0 = v0_px / atlas.atlas_h
+                u1 = u1_px / atlas.atlas_w
+                v1 = v1_px / atlas.atlas_h
+
+                # Calculate the screen position for the top-left corner of the quad.
+                # FreeType's origin is at the baseline, with +y going up.
+                # Screen coordinates usually have +y going down, so we adjust.
+                pos_x = x + bearing_x
+                pos_y = y - bearing_y
+
+                # Each character is defined by 8 floats:
+                # pos_x, pos_y, u0, v0, u1, v1, w, h
+                inst.extend([pos_x, pos_y, u0, v0, u1, v1, float(w), float(h)])
+                # Advance the cursor for the next character
+                x += adv
+        return inst
+
+
+# Create a singleton instance of the Text class for global use.
+Text = _Text()