PIXI.BitmapText

class BitmapText extends PIXI.Container

A BitmapText object will create a line or multiple lines of text using bitmap font.

The primary advantage of this class over Text is that all of your textures are pre-generated and loading, meaning that rendering is fast, and changing text has no performance implications.

Supporting character sets other than latin, such as CJK languages, may be impractical due to the number of characters.

To split a line you can use '\n', '\r' or '\r\n' in your string.

PixiJS can auto-generate fonts on-the-fly using BitmapFont or use fnt files provided by: http://www.angelcode.com/products/bmfont/ for Windows or http://www.bmglyph.com/ for Mac.

You can also use SDF, MSDF and MTSDF BitmapFonts for vector-like scaling appearance provided by: https://github.com/soimy/msdf-bmfont-xml for SDF and MSDF fnt files or https://github.com/Chlumsky/msdf-atlas-gen for SDF, MSDF and MTSDF json files

A BitmapText can only be created when the font is loaded.

// in this case the font is in a file called 'desyrel.fnt'
let bitmapText = new PIXI.BitmapText("text using a fancy font!", {
  fontName: "Desyrel",
  fontSize: 35,
  align: "right"
});

Constructor

new PIXI.BitmapText(text: string, style: Partial<IBitmapTextStyle>) → {}

Parameters:
Name	Type	Attributes	Default	Description
text	string			A string that you would like the text to display.
style	Partial<IBitmapTextStyle>			The style parameters.
style.fontName	string			The installed BitmapFont name.
style.fontSize	number	<optional>		The size of the font in pixels, e.g. 24. If undefined, . this will default to the BitmapFont size.
style.align	string	<optional>	'left'	Alignment for multiline text ('left', 'center', 'right' or 'justify'), does not affect single line text.
style.tint	number	<optional>	0xFFFFFF	The tint color.
style.letterSpacing	number	<optional>	0	The amount of spacing between letters.
style.maxWidth	number	<optional>	0	The max width of the text before line wrapping.

Summary

Properties from BitmapText

number	_resolution = PIXI.settings.RESOLUTION The resolution / device pixel ratio of the canvas.
string	align = 'left'
PIXI.ObservablePoint	anchor The anchor sets the origin point of the text.
boolean	dirty Set to `true` if the BitmapText needs to be redrawn.
string	fontName The name of the BitmapFont.
number	fontSize The size of the font to display.
number	letterSpacing Additional space between characters.
number	maxLineHeight
number	maxWidth
number	resolution = 1 The resolution / device pixel ratio of the canvas.
boolean	roundPixels = PIXI.settings.ROUND_PIXELS
string	text The text of the BitmapText object.
number	textHeight
number	textWidth
number	tint = 0xffffff
PageMeshData[]	protected _activePagesMeshData Collection of page mesh data.
boolean	protected _roundPixels = PIXI.settings.ROUND_PIXELS

Methods from BitmapText

PIXI.Rectangle

getLocalBounds()

void

renderCanvas(renderer: PIXI.CanvasRenderer)

void

updateText()

Renders text and updates it when needed. This should only be called if the BitmapFont is regenerated.

Properties inherited from Container

T[]	children
number	height The height of the Container, setting this will actually modify the scale to achieve the value set.
boolean	interactiveChildren = true
boolean	sortableChildren
boolean	sortDirty Should children be sorted by zIndex at the next updateTransform call.
number	width The width of the Container, setting this will actually modify the scale to achieve the value set.

Properties inherited from DisplayObject

boolean	_accessibleActive = false
boolean	_accessibleDiv = undefined
PIXI.Bounds	_bounds The bounds object, this is used to calculate and store the bounds of the displayObject.
PIXI.Bounds	_localBounds Local bounds object, swapped with `_bounds` when using `getLocalBounds()`.
boolean	accessible = false
boolean	accessibleChildren = true
string	accessibleHint = undefined
string	accessiblePointerEvents = 'auto'
?string	accessibleTitle = undefined
string	accessibleType = 'button'
number	alpha The opacity of the object.
number	angle
boolean	buttonMode
boolean	cacheAsBitmap
number	cacheAsBitmapMultisample = PIXI.MSAA_QUALITY.NONE
number	cacheAsBitmapResolution = null
boolean	cullable Should this object be rendered if the bounds of this object are out of frame?
PIXI.Rectangle	cullArea
string	cursor = undefined
boolean	destroyed Readonly flag for destroyed display objects.
PIXI.Rectangle	filterArea
PIXI.Filter[] \| null	filters
PIXI.IHitArea	hitArea = undefined
boolean	interactive = false
boolean	isMask Does any other displayObject use this object as a mask?
boolean	isSprite Used to fast check if a sprite is.. a sprite!
PIXI.Matrix	localTransform
PIXI.Container \| PIXI.MaskData \| null	mask
string	name = undefined
PIXI.Container	parent The display object container that contains this display object.
PIXI.ObservablePoint	pivot
PIXI.ObservablePoint	position
boolean	renderable
number	rotation
PIXI.ObservablePoint	scale The scale factors of this object along the local coordinate axes.
PIXI.ObservablePoint	skew
PIXI.DisplayObject	smartMask = undefined
PIXI.Transform	transform
boolean	visible
number	worldAlpha
PIXI.Matrix	worldTransform
boolean	worldVisible
number	x
number	y
number	zIndex The zIndex of the displayObject.
number	protected _boundsID Flags the cached bounds as dirty.
PIXI.Rectangle	protected _boundsRect Cache of this display-object's bounds-rectangle.
boolean	protected _destroyed If the object has been destroyed via destroy(). If true, it should not be used.
PIXI.Filter[]	protected _enabledFilters
number	protected _lastSortedIndex
PIXI.Rectangle	protected _localBoundsRect Cache of this display-object's local-bounds rectangle.
PIXI.Container \| PIXI.MaskData	protected _mask
PIXI.Container	protected _tempDisplayObjectParent
number	protected _zIndex

Methods inherited from Container

PIXI.DisplayObject	addChild(children: PIXI.DisplayObject) Adds one or more children to the container.
PIXI.DisplayObject	addChildAt(child: PIXI.DisplayObject, index: number)
void	calculateBounds() Recalculates the bounds of the container.
	containerUpdateTransform()
void	destroy(options: IDestroyOptions \| boolean)
T	getChildAt(index: number)
PIXI.DisplayObject	getChildByName(name: string, deep: boolean) Returns the display object in the container.
number	getChildIndex(child: T)
PIXI.DisplayObject	removeChild(children: PIXI.DisplayObject)
T	removeChildAt(index: number)
T[]	removeChildren(beginIndex: number, endIndex)
void	render(renderer: PIXI.Renderer) Renders the object using the WebGL renderer.
void	setChildIndex(child: T, index: number)
void	sortChildren() Sorts children by zIndex. Previous order is maintained for 2 children with the same zIndex.
void	swapChildren(child: T, child2: T)
void	updateTransform() Updates the transform on all children of this container for rendering.
void	protected _calculateBounds()
void	protected _render(_renderer: PIXI.Renderer)
void	protected _renderCanvas(_renderer: PIXI.CanvasRenderer)
void	protected _renderWithCulling(renderer: PIXI.Renderer)
void	protected onChildrenChange(_length: number)
void	protected renderAdvanced(renderer: PIXI.Renderer)

Methods inherited from DisplayObject

	addEventListener(type: string, listener: EventListenerOrEventListenerObject, options: boolean \| AddEventListenerOptions)
void	disableTempParent(cacheParent: PIXI.Container)
boolean	dispatchEvent(e: Event) Dispatch the event on this PIXI.DisplayObject using the event's PIXI.EventBoundary.
	displayObjectUpdateTransform()
PIXI.Container	enableTempParent() Used in Renderer, cacheAsBitmap and other places where you call an `updateTransform` on root
PIXI.Rectangle	getBounds(skipUpdate: boolean, rect: PIXI.Rectangle) Calculates and returns the (world) bounds of the display object as a Rectangle.
PIXI.Point	getGlobalPosition(point: PIXI.Point, skipUpdate: boolean)
	removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options: boolean \| AddEventListenerOptions)
PIXI.Container	setParent(container: PIXI.Container)
this	setTransform(x: number, y: number, scaleX: number, scaleY: number, rotation: number, skewX: number, skewY: number, pivotX: number, pivotY: number)
P	toGlobal(position: IPointData, point: P, skipUpdate: boolean)
P	toLocal(position: IPointData, from: PIXI.DisplayObject, point: P, skipUpdate: boolean)
PIXI.Rectangle	updateSmartMask(recursive: boolean, skipUpdate: boolean)
void	protected _recursivePostUpdateTransform() Recursively updates transform of all objects from the root to this one internal function for toLocal()

Inherited Events from Container

childAdded

Inherited Events from DisplayObject

	added
	childRemoved
	click
	clickcapture Capture phase equivalent of `click`.
	destroyed
	mousedown
	mousedowncapture Capture phase equivalent of `mousedown`.
	mouseenter Fired when the mouse pointer is moved over a DisplayObject and its descendant's hit testing boundaries.
	mouseentercapture Capture phase equivalent of `mouseenter`
	mouseleave Fired when the mouse pointer exits a DisplayObject and its descendants.
	mouseleavecapture Capture phase equivalent of `mouseleave`.
	mousemove
	mousemovecature Capture phase equivalent of `mousemove`.
	mouseout
	mouseoutcapture Capture phase equivalent of `mouseout`.
	mouseover
	mouseovercapture Capture phase equivalent of `mouseover`.
	mouseup
	mouseupcature Capture phase equivalent of `mouseup`.
	mouseupoutside
	mouseupoutsidecapture Capture phase equivalent of `mouseupoutside`.
	pointercancel
	pointercancelcapture Capture phase equivalent of `pointercancel`.
	pointerdown
	pointerdowncapture Capture phase equivalent of `pointerdown`.
	pointerenter Fired when the pointer is moved over a DisplayObject and its descendant's hit testing boundaries.
	pointerentercapture Capture phase equivalent of `pointerenter`
	pointerleave Fired when the pointer leaves the hit testing boundaries of a DisplayObject and its descendants.
	pointerleavecapture Capture phase equivalent of `pointerleave`.
	pointermove
	pointermovecapture Capture phase equivalent of `pointermove`.
	pointerout
	pointeroutcapture Capture phase equivalent of `pointerout`.
	pointerover
	pointerovercapture Capture phase equivalent of `pointerover`.
	pointertap
	pointertapcapture Capture phase equivalent of `pointertap`.
	pointerup
	pointerupcapture Capture phase equivalent of `pointerup`.
	pointerupoutside
	pointerupoutsidecapture Capture phase equivalent of `pointerupoutside`.
	removed
	rightclick
	rightclickcapture Capture phase equivalent of `rightclick`.
	rightdown
	rightdowncapture Capture phase equivalent of `rightdown`.
	rightup
	rightupcapture Capture phase equivalent of `rightup`.
	rightupoutside
	rightupoutsidecapture Capture phase equivalent of `rightupoutside`.
	tap
	tapcapture Capture phase equivalent of `tap`.
	touchcancel
	touchcancelcapture Capture phase equivalent of `touchcancel`.
	touchend
	touchendcapture Capture phase equivalent of `touchend`.
	touchendoutside
	touchendoutsidecapture Capture phase equivalent of `touchendoutside`.
	touchmove
	touchmovecapture Capture phase equivalent of `touchmove`.
	touchstart
	touchstartcapture Capture phase equivalent of `touchstart`.
PIXI.FederatedWheelEvent	wheel Fired when a the user scrolls with the mouse cursor over a DisplayObject.
PIXI.FederatedWheelEvent	wheelcapture Capture phase equivalent of `wheel`.

Public Properties

_resolution BitmapText.ts:86

_resolution: number = PIXI.settings.RESOLUTION

The resolution / device pixel ratio of the canvas.

This is set to automatically match the renderer resolution by default, but can be overridden by setting manually.

align BitmapText.ts:684

align: string = 'left'

The alignment of the BitmapText object.

anchor BitmapText.ts:738

anchor: PIXI.ObservablePoint

The anchor sets the origin point of the text.

The default is (0,0), this means the text's origin is the top left.

Setting the anchor to (0.5,0.5) means the text's origin is centered.

Setting the anchor to (1,1) would mean the text's origin point will be the bottom right corner.

dirty BitmapText.ts:83

dirty: boolean

Set to true if the BitmapText needs to be redrawn.

fontName BitmapText.ts:703

fontName: string

The name of the BitmapFont.

fontSize BitmapText.ts:723

fontSize: number

The size of the font to display.

letterSpacing BitmapText.ts:826

letterSpacing: number

Additional space between characters.

maxLineHeight BitmapText.ts:802

maxLineHeight: number

The max line height. This is useful when trying to use the total height of the Text, i.e. when trying to vertically align.

maxWidth BitmapText.ts:782

maxWidth: number

The max width of this bitmap text in pixels. If the text provided is longer than the value provided, line breaks will be automatically inserted in the last whitespace. Disable by setting the value to 0.

resolution BitmapText.ts:874

resolution: number = 1

The resolution / device pixel ratio of the canvas.

This is set to automatically match the renderer resolution by default, but can be overridden by setting manually.

roundPixels BitmapText.ts:841

roundPixels: boolean = PIXI.settings.ROUND_PIXELS

If true PixiJS will Math.floor() x/y values when rendering, stopping pixel interpolation. Advantages can include sharper image quality (like text) and faster rendering on canvas. The main disadvantage is movement of objects may appear less smooth. To set the global default, change PIXI.settings.ROUND_PIXELS

text BitmapText.ts:764

text: string

The text of the BitmapText object.

textHeight BitmapText.ts:862

textHeight: number

The height of the overall text, different from fontSize, which is defined in the style object.

textWidth BitmapText.ts:814

textWidth: number

The width of the overall text, different from fontSize, which is defined in the style object.

tint BitmapText.ts:663

tint: number = 0xffffff

The tint of the BitmapText object.

Protected Properties

_activePagesMeshData BitmapText.ts:160

protected _activePagesMeshData: PageMeshData[]

Collection of page mesh data.

_roundPixels BitmapText.ts:169

protected _roundPixels: boolean = PIXI.settings.ROUND_PIXELS

If true PixiJS will Math.floor() x/y values when rendering.

Public Methods

getLocalBounds BitmapText.ts:639

getLocalBounds() → {PIXI.Rectangle}

Validates text before calling parent's getLocalBounds

Returns:
Type	Description
PIXI.Rectangle	The rectangular bounding area

renderCanvas Container.ts:17

renderCanvas(renderer: PIXI.CanvasRenderer) → {void}

Renders the object using the Canvas renderer

Parameters:
Name	Type	Description
renderer	PIXI.CanvasRenderer	The renderer

Returns:
Type	Description
void

updateText BitmapText.ts:222

updateText() → {void}

Renders text and updates it when needed. This should only be called if the BitmapFont is regenerated.

Returns:
Type	Description
void