feat: adds text splitting functionality (#11496)

* feat: add Text.split / BitmapText.split

* Feat: Adds origin point for container transformations

Adds an 'origin' property to the container, providing a way to specify the point around which the container rotates and scales without affecting its position.

This allows for more flexible and intuitive control over container transformations, particularly when rotating or scaling around a specific point.

* update API

* add warning and tests

* ensure origin works with scaled containers

* Update name

* Apply suggestions from code review

Co-authored-by: Mat Groves <[email protected]>

---------

Co-authored-by: Mat Groves <[email protected]>

Author: Zyie

src/scene/SceneMixins.d.ts

@@ -70,6 +70,11 @@ declare global
         interface HTMLText {}
         interface HTMLTextOptions {}
 
+        interface SplitText {}
+        interface SplitTextOptions {}
+        interface SplitBitmapText {}
+        interface SplitBitmapTextOptions {}
+
     }
 }
 

src/scene/index.ts

@@ -128,6 +128,7 @@ export * from './text-bitmap/BitmapFontManager';
 export * from './text-bitmap/BitmapText';
 export * from './text-bitmap/BitmapTextPipe';
 export * from './text-bitmap/DynamicBitmapFont';
+export * from './text-bitmap/utils/bitmapTextSplit';
 export * from './text-bitmap/utils/getBitmapTextLayout';
 export * from './text-bitmap/utils/resolveCharacters';
 export * from './text-html/BatchableHTMLText';
@@ -145,6 +146,10 @@ export * from './text-html/utils/loadFontCSS';
 export * from './text-html/utils/loadSVGImage';
 export * from './text-html/utils/measureHtmlText';
 export * from './text-html/utils/textStyleToCSS';
+export * from './text-split/AbstractSplitText';
+export * from './text-split/SplitBitmapText';
+export * from './text-split/SplitText';
+export * from './text-split/types';
 export * from './text/AbstractText';
 export * from './text/canvas/BatchableText';
 export * from './text/canvas/CanvasTextGenerator';
@@ -158,6 +163,7 @@ export * from './text/sdfShader/shader-bits/localUniformMSDFBit';
 export * from './text/sdfShader/shader-bits/mSDFBit';
 export * from './text/Text';
 export * from './text/TextStyle';
+export * from './text/utils/canvasTextSplit';
 export * from './text/utils/generateTextStyleKey';
 export * from './text/utils/getPo2TextureFromSource';
 export * from './text/utils/updateTextBounds';

src/scene/text-bitmap/utils/bitmapTextSplit.ts

@@ -0,0 +1,111 @@
+import { Container } from '../../container/Container';
+import { CanvasTextMetrics } from '../../text/canvas/CanvasTextMetrics';
+import { type TextStyle } from '../../text/TextStyle';
+import { type SplitOptions } from '../../text-split/SplitText';
+import { type TextSplitOutput } from '../../text-split/types';
+import { BitmapFontManager } from '../BitmapFontManager';
+import { BitmapText } from '../BitmapText';
+import { getBitmapTextLayout } from './getBitmapTextLayout';
+
+/**
+ * Splits a Text object into segments based on the text's layout and style,
+ * and adds these segments as individual Text objects to a specified container.
+ *
+ * This function handles word wrapping, alignment, and letter spacing,
+ * ensuring that each segment is rendered correctly according to the original text's style.
+ * @param options - Configuration options for the text split operation.
+ * @returns An array of Text objects representing the split segments.
+ * @internal
+ */
+export function bitmapTextSplit(
+    options: Pick<SplitOptions, 'text' | 'style'> & { chars: BitmapText[] },
+): TextSplitOutput<BitmapText>
+{
+    const { text, style, chars: existingChars } = options;
+    const textStyle = style as TextStyle;
+    const font = BitmapFontManager.getFont(text, textStyle);
+
+    const segments = CanvasTextMetrics.graphemeSegmenter(text);
+    const layout = getBitmapTextLayout(segments, textStyle, font, true);
+    const scale = layout.scale;
+    const chars: BitmapText[] = [];
+    const words: Container[] = [];
+    const lines: Container[] = [];
+
+    let yOffset = 0;
+
+    for (const line of layout.lines)
+    {
+        // if the line is empty, skip it
+        if (line.chars.length === 0) continue;
+
+        const lineContainer = new Container({ label: 'line' });
+
+        lineContainer.y = yOffset;
+        lines.push(lineContainer);
+
+        let currentWordContainer = new Container({ label: 'word' });
+        let currentWordStartIndex = 0;
+
+        for (let i = 0; i < line.chars.length; i++)
+        {
+            const char = line.chars[i];
+
+            if (!char) continue;
+
+            const charData = font.chars[char];
+
+            if (!charData) continue;
+
+            const isSpace = char === ' ';
+            const isLastChar = i === line.chars.length - 1;
+
+            let charInstance: BitmapText;
+
+            if (existingChars.length > 0)
+            {
+                charInstance = existingChars.shift();
+                charInstance.text = char;
+                charInstance.style = textStyle;
+                charInstance.label = `char-${char}`;
+                charInstance.x = (line.charPositions[i]! * scale) - (line.charPositions[currentWordStartIndex]! * scale);
+            }
+            else
+            {
+                // Create a new BitmapText instance if no existing one is available
+                charInstance = new BitmapText({
+                    text: char,
+                    style: textStyle,
+                    label: `char-${char}`,
+                    x: (line.charPositions[i]! * scale) - (line.charPositions[currentWordStartIndex]! * scale),
+                });
+            }
+
+            if (!isSpace)
+            {
+                chars.push(charInstance);
+                // Add to word container
+                currentWordContainer.addChild(charInstance);
+            }
+
+            // Handle word breaks
+            if (isSpace || isLastChar)
+            {
+                if (currentWordContainer.children.length > 0)
+                {
+                    currentWordContainer.x = line.charPositions[currentWordStartIndex]! * scale;
+                    words.push(currentWordContainer);
+                    lineContainer.addChild(currentWordContainer);
+
+                    // Start new word container
+                    currentWordContainer = new Container({ label: 'word' });
+                    currentWordStartIndex = i + 1;
+                }
+            }
+        }
+
+        yOffset += font.lineHeight * scale;
+    }
+
+    return { chars, lines, words };
+}