CParticleSamplerText

From PopcornFX
Jump to: navigation, search

Particle sampler text - Main page : Particle samplers Particle samplers


Available since v1.7.0
The text sampler allows you to sample a text file or text string set in the sampler itself, and get the ASCII code of each character. Useful to use as a TextureID and index a texture atlas to display text particles.


NOTE: a future iteration of the text sampler might allow to actually sample random positions on a text as if it was a 3D mesh sampler.


Sampler Text Viewport.png


Particle sampler text Node properties

Field name Default value Description
Particle sampler text General
SamplerName Auto-generated name Name of the sampler, published to the rest of the effect
SamplerDescription Empty Sampler Description (optional)
UserData Empty Use this if you need to pass custom data to your game engine's integration (custom PopcornFX SDK). If you're Using UE4 or Unity, you can ignore this.
DataSource Inline Specifies where the sampler fetches the text data
  • Inline : text is specified directly in the sampler properties
  • External : sampler will load an external text file
InlineText Text to be sampled
ExternalResource Path to the text file containing the text to be sampled
FontFile Path to the font file to be used for font metrics (width / kerning)
UseKerning true If disabled, will not use kerning information, but still use glyph widths contained in the kerning file
Text sampler properties


Particle sampler text Script bindings

for each sampler, the following functions are published to scripts:

int	charCode(int charId);
int	charCode(int2 lineAndCharId);
int	charCount();
int	charCount(int lineId);
int	lineCount();

charCode

int charCode(int charId);

'charId' is the index of the character to sample.
The function will return the ASCII code of the character. Pass 0 to get the first character, 14 to get the 15th character, etc...


int charCode(int2 lineAndCharId);

'lineAndCharId' is an int2, containing in its 'x' component, the index of the line to sample, and in its 'y' component, the index of the character to sample inside that line.
The function will return the ASCII code of the character. Pass int2(0,0) to get the first character of the first line, int2(3,14) to get the 15th character of the 4th line, etc...


charCount

int charCount();

returns the total number of characters in the full text (includes special characters like line-separators)


int charCount(int lineId);

returns the total number of characters of the line at index 'lineId'. (does not count line-separators)


lineCount

int lineCount();

returns the total number of lines in the full text.


charLineId

NewIcon.png v1.12.0
int2 charLineId(int charId);

returns an int2 vector containing the 0-based line index of the specified character in 'x' and the 0-based character index relative to the start of the line in 'y'. 'charId' is the global character index in the [0, totalCharCount] range


charOffset

NewIcon.png v1.12.0
int charOffset(int lineId, int charId);

Returns the horizontal distance between charId and the beginning of the line in displayable units, where '1.0' is the average glyph size.
Takes kerning into account if a font file has been provided in the text sampler and its 'UseKerning' property is enabled.
Only works for characters whose charCode is in the [0-255] range.
If you need to work with some unicode characters, you will need to reencode the text string to map them in free slots of the [0,255] range, and remap their entries in the cached kerning file generated from the font file. Please contact our support channels for more details.


lineOffset

NewIcon.png v1.12.0
int lineOffset(int lineId);

Returns the vertical distance between lineId and the beginning of the text in displayable units, where '1.0' is the average glyph size. Defaults to 3.0 if no metrics file has been provided in the text sampler.


Particle sampler text Kerning

"In typography, kerning is the process of adjusting the spacing between characters in a proportional font, usually to achieve a visually pleasing result."
The PopcornFX text sampler allows you to retreive character spacings that take proper kerning into account.


Without Kerning
Text sampler used without kerning
With Kerning
Text sampler used with kerning


Using kerning information to display text through billboard-rendered particles requires a specific setup.

You will need to setup a billboard renderer with a proper atlas, work out the proper TextureID from the character code returned from the text sampler, and use the text sampler's functions properly to position the particles based on the way they have been rasterized in the texture atlas. To help with this process, we provide an example psd file already setup where you just have to change the font.
You can then setup the billboard renderer to use a texture saved from the .psd, and use the .pkat texture atlas.
Then, setup the text sampler to use the .ttf file of the font used in the .psd file.


PSD template : TextAtlasTemplate.psd
Texture atlas : TextAtlas.pkat
Example FX : TextKerning.pkkg

Dealing with extra padding in the texture atlas

For ease of use, the texture atlas and font size is not tightly fit to each glyph. Doing so would require a different .pkat per font.
Instead, each atlas tile is the same size, and the font size in the .psd file needs to be setup so that all glyphs fit in those rects.

The .psd file is designed so that each glyph starting cursor is located precisely 8 pixels from the left corner of a 64x64 tile.
Due to the way photoshop draws text however, we cannot safely setup the psd to have the text baseline at a fixed location.
Likewise, we cannot know in advance the amount of wasted space in each tile.
Therefore, these two things need measurement, and you'll need to apply those two numbers in the particle script to properly offset/scale the particles to get correct font rendering.


Pre-steps: select all glyph layers, then set the font you want:

Select all glyph layers Select font


Then, measure the pixel width of the lowercase 'm' glyph, here, 41 pixels.
This gives the texture atlas to font ratio, computing using 'widthOfLowercaseM / tileSize', which in this case is 41.0/64.0 ~= 0.6406.
The text sampler uses the lowercase 'm' glyph width reported by the .ttf font to normalize all the other glyph sizes, so the lowercase 'm' will have a reported width (not advance!) of exactly 1.0
lowercase m width in pixels to compute atlas to font ratio


Then, measure the distance in pixels between the top of the tile and the baseline (this will depend on your font, it's easier to do this on a glyph whose bottom pixels naturally sit on the baseline, such as an 'e' or an 'o', in this case, 'm' is also fine. Here, 51 pixels.
This gives the baseline position, that we'll use to offset the billboard's vertical position.
lowercase m width in pixels to compute atlas to font ratio