- Main page : 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.
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();
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...
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)
returns the total number of lines in the full text.
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
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.
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.
"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.
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:
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
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.