pixi.js

Version:

pixijs.com

pixijs/pixijs

1 lines • 9.1 kB

Source Map (JSON)

View Raw

{"version":3,"file":"BitmapText.mjs","sources":["../../../src/scene/text-bitmap/BitmapText.ts"],"sourcesContent":["import { warn } from '../../utils/logging/warn';\nimport { AbstractText, ensureTextOptions } from '../text/AbstractText';\nimport { TextStyle } from '../text/TextStyle';\nimport { BitmapFontManager } from './BitmapFontManager';\nimport { type BitmapTextGraphics } from './BitmapTextPipe';\n\nimport type { View } from '../../rendering/renderers/shared/view/View';\nimport type { TextOptions, TextString } from '../text/AbstractText';\nimport type { TextStyleOptions } from '../text/TextStyle';\n\n// eslint-disable-next-line requireExport/require-export-jsdoc, requireMemberAPI/require-member-api-doc\nexport interface BitmapText extends PixiMixins.BitmapText, AbstractText<\n TextStyle,\n TextStyleOptions,\n TextOptions,\n BitmapTextGraphics\n> {}\n\n/**\n * A BitmapText object creates text using pre-rendered bitmap fonts.\n * It supports both loaded bitmap fonts (XML/FNT) and dynamically generated ones.\n *\n * To split a line you can use '\\n' in your text string, or use the `wordWrap` and\n * `wordWrapWidth` style properties.\n *\n * Key Features:\n * - High-performance text rendering using pre-generated textures\n * - Support for both pre-loaded and dynamic bitmap fonts\n * - Compatible with MSDF/SDF fonts for crisp scaling\n * - Automatic font reuse and optimization\n *\n * Performance Benefits:\n * - Faster rendering compared to Canvas/HTML text\n * - Lower memory usage for repeated characters\n * - More efficient text changes\n * - Better batching capabilities\n *\n * Limitations:\n * - Full character set support is impractical due to the number of chars (mainly affects CJK languages)\n * - Initial font generation/loading overhead\n * - Less flexible styling compared to Canvas/HTML text\n * @example\n * ```ts\n * import { BitmapText, BitmapFont } from 'pixi.js';\n *\n * // Dynamic font generation\n * const dynamicText = new BitmapText({\n * text: 'Hello Pixi!',\n * style: {\n * fontFamily: 'Arial',\n * fontSize: 24,\n * fill: 0xff1010,\n * align: 'center',\n * }\n * });\n *\n * // Pre-installed font usage\n * BitmapFont.install({\n * name: 'myFont',\n * style: {\n * fontFamily: 'Arial',\n * }\n * });\n *\n * const preinstalledText = new BitmapText({\n * text: 'Hello Pixi!',\n * style: {\n * fontFamily: 'myFont',\n * fontSize: 24,\n * fill: 0xff1010,\n * align: 'center',\n * }\n * });\n *\n * // Load and use external bitmap font, if the font supports MSDF/SDF then it will be used\n * const font = await Assets.load('fonts/myFont.fnt');\n *\n * const loadedFontText = new BitmapText({\n * text: 'Hello Pixi!',\n * style: {\n * fontFamily: 'myLoadedFont', // Name from .fnt file\n * fontSize: 24,\n * fill: 0xff1010,\n * align: 'center',\n * }\n * });\n *\n * // Multiline text with word wrap\n * const wrappedText = new BitmapText({\n * text: 'This is a long text that will wrap automatically',\n * style: {\n * fontFamily: 'Arial',\n * fontSize: 24,\n * wordWrap: true,\n * wordWrapWidth: 200,\n * }\n * });\n * ```\n *\n * Font Types:\n * 1. Pre-loaded Bitmap Fonts:\n * - Load via Asset Manager (XML/FNT formats)\n * - Support for MSDF/SDF fonts\n * - Create using tools like https://msdf-bmfont.donmccurdy.com/\n *\n * 2. Dynamic Bitmap Fonts:\n * - Generated at runtime from system fonts\n * - Automatic font reuse and optimization\n * - Smart scaling for similar font sizes\n *\n * Font Management:\n * - Automatic font generation when needed\n * - Manual pre-installation via `BitmapFont.install`\n * - Smart font reuse to optimize memory\n * - Scale existing fonts instead of generating new ones when possible\n * @category text\n * @standard\n * @see {@link BitmapFont} For font installation and management\n * @see {@link Text} For canvas-based text rendering\n * @see {@link HTMLText} For HTML/CSS-based text rendering\n */\nexport class BitmapText extends AbstractText<\n TextStyle,\n TextStyleOptions,\n TextOptions,\n BitmapTextGraphics\n> implements View\n{\n /** @internal */\n public override readonly renderPipeId: string = 'bitmapText';\n\n /**\n * **Note:** Our docs parser struggles to properly understand the constructor signature.\n * This is the correct signature.\n * ```ts\n * new BitmapText(options?: TextOptions);\n * ```\n * @param { TextOptions } options - The options of the bitmap text.\n */\n constructor(options?: TextOptions);\n /** @deprecated since 8.0.0 */\n constructor(text?: TextString, options?: Partial<TextStyle>);\n constructor(...args: [TextOptions?] | [TextString, Partial<TextStyle>])\n {\n const options = ensureTextOptions(args, 'BitmapText');\n\n options.style ??= options.style || {};\n options.style.fill ??= 0xffffff;\n\n super(options, TextStyle);\n }\n\n /** @private */\n protected updateBounds()\n {\n const bounds = this._bounds;\n const anchor = this._anchor;\n\n const bitmapMeasurement = BitmapFontManager.measureText(this.text, this._style);\n const scale = bitmapMeasurement.scale;\n const offset = bitmapMeasurement.offsetY * scale;\n\n let width = bitmapMeasurement.width * scale;\n let height = bitmapMeasurement.height * scale;\n\n const stroke = this._style._stroke;\n\n if (stroke)\n {\n width += stroke.width;\n height += stroke.width;\n }\n\n bounds.minX = (-anchor._x * width);\n bounds.maxX = bounds.minX + width;\n bounds.minY = (-anchor._y * (height + offset));\n bounds.maxY = bounds.minY + height;\n }\n\n /**\n * The resolution / device pixel ratio for text rendering.\n * Unlike other text types, BitmapText resolution is managed by the BitmapFont.\n * Individual resolution changes are not supported.\n * @example\n * ```ts\n * // ❌ Incorrect: Setting resolution directly (will trigger warning)\n * const text = new BitmapText({\n * text: 'Hello',\n * resolution: 2 // This will be ignored\n * });\n *\n * // ✅ Correct: Set resolution when installing the font\n * BitmapFont.install({\n * name: 'MyFont',\n * style: {\n * fontFamily: 'Arial',\n * },\n * resolution: 2 // Resolution is set here\n * });\n *\n * const text = new BitmapText({\n * text: 'Hello',\n * style: {\n * fontFamily: 'MyFont' // Uses font's resolution\n * }\n * });\n * ```\n * @default 1\n * @see {@link BitmapFont.install} For setting font resolution\n * @throws {Warning} When attempting to change resolution directly\n * @readonly\n */\n override set resolution(value: number)\n {\n // #if _DEBUG\n if (value !== null)\n {\n warn(\n // eslint-disable-next-line max-len\n '[BitmapText] dynamically updating the resolution is not supported. Resolution should be managed by the BitmapFont.'\n );\n }\n // #endif\n }\n\n override get resolution(): number\n {\n return this._resolution;\n }\n}\n"],"names":[],"mappings":";;;;;;AAyHO,MAAM,mBAAmB,YAMhC,CAAA;AAAA,EAeI,eAAe,IACf,EAAA;AA/IJ,IAAA,IAAA,EAAA,CAAA;AAgJQ,IAAM,MAAA,OAAA,GAAU,iBAAkB,CAAA,IAAA,EAAM,YAAY,CAAA,CAAA;AAEpD,IAAA,OAAA,CAAQ,KAAR,KAAA,OAAA,CAAQ,KAAU,GAAA,OAAA,CAAQ,SAAS,EAAC,CAAA,CAAA;AACpC,IAAQ,CAAA,EAAA,GAAA,OAAA,CAAA,KAAA,EAAM,IAAd,KAAA,EAAA,CAAc,IAAS,GAAA,QAAA,CAAA,CAAA;AAEvB,IAAA,KAAA,CAAM,SAAS,SAAS,CAAA,CAAA;AApB5B;AAAA,IAAA,IAAA,CAAyB,YAAuB,GAAA,YAAA,CAAA;AAAA,GAqBhD;AAAA;AAAA,EAGU,YACV,GAAA;AACI,IAAA,MAAM,SAAS,IAAK,CAAA,OAAA,CAAA;AACpB,IAAA,MAAM,SAAS,IAAK,CAAA,OAAA,CAAA;AAEpB,IAAA,MAAM,oBAAoB,iBAAkB,CAAA,WAAA,CAAY,IAAK,CAAA,IAAA,EAAM,KAAK,MAAM,CAAA,CAAA;AAC9E,IAAA,MAAM,QAAQ,iBAAkB,CAAA,KAAA,CAAA;AAChC,IAAM,MAAA,MAAA,GAAS,kBAAkB,OAAU,GAAA,KAAA,CAAA;AAE3C,IAAI,IAAA,KAAA,GAAQ,kBAAkB,KAAQ,GAAA,KAAA,CAAA;AACtC,IAAI,IAAA,MAAA,GAAS,kBAAkB,MAAS,GAAA,KAAA,CAAA;AAExC,IAAM,MAAA,MAAA,GAAS,KAAK,MAAO,CAAA,OAAA,CAAA;AAE3B,IAAA,IAAI,MACJ,EAAA;AACI,MAAA,KAAA,IAAS,MAAO,CAAA,KAAA,CAAA;AAChB,MAAA,MAAA,IAAU,MAAO,CAAA,KAAA,CAAA;AAAA,KACrB;AAEA,IAAO,MAAA,CAAA,IAAA,GAAQ,CAAC,MAAA,CAAO,EAAK,GAAA,KAAA,CAAA;AAC5B,IAAO,MAAA,CAAA,IAAA,GAAO,OAAO,IAAO,GAAA,KAAA,CAAA;AAC5B,IAAA,MAAA,CAAO,IAAQ,GAAA,CAAC,MAAO,CAAA,EAAA,IAAM,MAAS,GAAA,MAAA,CAAA,CAAA;AACtC,IAAO,MAAA,CAAA,IAAA,GAAO,OAAO,IAAO,GAAA,MAAA,CAAA;AAAA,GAChC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmCA,IAAa,WAAW,KACxB,EAAA;AAEI,IAAA,IAAI,UAAU,IACd,EAAA;AACI,MAAA,IAAA;AAAA;AAAA,QAEI,oHAAA;AAAA,OACJ,CAAA;AAAA,KACJ;AAAA,GAEJ;AAAA,EAEA,IAAa,UACb,GAAA;AACI,IAAA,OAAO,IAAK,CAAA,WAAA,CAAA;AAAA,GAChB;AACJ;;;;"}