HexText

From Second Life Wiki
Jump to navigation Jump to search

About

HexText Sample Display.png

HexText is an LSL script to display Unicode text on 8 faced prims within Second Life. Supported is included for Japanese/Chinese, as well as many other languages and symbols. It is not all-inclusive. There are some code pages that are missing. It does cover the majority of characters that avatars use in Unicode enhanced display names.

There are two display scripts. One is optimized for general usage, the other is optimized for Japanese/Chinese.

The primary font used is Google's Noto Monospace (Bold & Regular), supplemented with other open source or public domain fonts for code pages not covered by Noto.

The character set is broken up into ~113 individual textures for each supported Unicode code page, covering roughly 28,000 characters. Each texture is a 16 x 16 matrix of characters. To minimize texture memory usage, the majority of textures are rendered at 512 x 256 pixels. Kanji is rendered at 512 x 384 which gets reduced to 512 x 256 at upload. As the textures are 512 x 256, it takes 8 of them to equal the amount of GPU texture memory used by a single 1024 x 1024 texture. I have found that unless you are displaying Kanji, it is rare to use more memory than 2 - 1024 x 1024 textures.

Acknowledgments

Thanks go to Ochi Wolfe for his excellent FURWARE_text display sytem and documentation. Without his, and his contributors efforts, HexText would have been significantly more difficult to create.

HexText is released under the MIT license.

HexText uses a subset of the FURWARE_text/Reference command set. HexText does not support virtual text boxes, inline styles or touch queries.

HexText can use displays set up by the FURWARE_text/Tutorial#Creating_displays, however it can only use the 8 faced prim displays. HexText uses display prims with the same description format used by FURWARE text. HexText only supports a single display set per linkset, unlike FURWARE text that can handle multiple displays per linkset.

The HexText texture set was created with FURWARE_text/TextureCreator.

Use of both HexText and the FURWARE text scripts in the same linkset is not recommended.

Although it is technically possible to combine the FURWARE text engine, and HexText to create a Unicode display system with the features of both, I was concerned that it would not fit in a single script, and would therefore suffer performance issues.

Setup

The following was taken from the FURWARE text manual, edited to remove limitations imposed by HexText. All credit for FURWARE text tools to Ochi Wolfe and his contributors. Hexadeci Mole is only responsible for the alternative HexText Unicode display script and its documentation.

Creating displays

HexText uses displays created with the FURWARE text display creator available here: https://marketplace.secondlife.com/p/FURWARE-text/141379

You may (and should) use the "FURWARE display creator" to have a perfectly aligned grid of display prims automatically created for you. Every prim will be automatically assigned a special object name that is used internally by the text script so that it knows how to order them correctly, independently of the link order.

Creating a display is simple:

  • Rez the display creator on a parcel where you have sufficient permissions.
  • Touch the creator object. A dialog appears where you can set some parameters of the new display:
    • A name for the display. You will use this name to identify which display you wish to manipulate when using multiple displays within one linkset.
    • The number of rows and columns of the display (the columns are counted in prims here, not in characters).
    • The number of faces per prim. There are mesh prims from 1 to 8 faces available. HexText can only use the 8 face display prims.
  • When you're happy with the settings, click "Create" to start rezzing the prims. Link them to your creation as appropriate. (I would not recommend that any display prim be link #1 in a linkset)

Setup and initialization

When you have created your display and linked it together with your creation, put a single copy of the HexText Script (listed below) into the linkset instead of the FURWARE text script. The script does not have to be in the root prim.

Important hint:

You may wish to send some initial commands to the text script as soon as its initialization is done. A reset of the text script may happen in a number of cases:

  • The script was just put into the object.
  • The object in which the script resides was shift-copied.
  • The linkset has changed (then the script needs to search for display prims again).
  • The script was reset manually (for instance using the "fw_reset" command).

In order to know when exactly the script is ready to take commands, it sends a link message to the whole set with the "id" parameter set to "fw_ready". It is good practice to watch for these messages and send your initialization commands when receiving this message. Your code could look something like this: 


link_message(integer sender, integer num, string str, key id) {
    if (id == "fw_ready") {
        // Set your default color, alignment, wrapping, trim, etc.
        llMessageLinked(sender, 0, "c=red;a=center;w=word", "fw_conf");
         // If your default display is not blank, send the default text
        llMessageLinked(sender, 0, "Default text", "fw_data");

        // ...
    }
}

LSL Scripts

There are two variants of HexText. The generic version allocates one prim face for each character. The 2XKanji version allocates 2 faces for Kanji/Katakana. This makes C/J/K characters easier to read, but the script is a little more convoluted. Oddly, performance of the 2XKanji version sometimes surpasses the Generic version. Only use one of the scripts below in your linkset. Do not use the FURWARE text script in the same linkset that one of these scripts occupy.

Reference Manual

Commands supported in HexText (a subset of the FURWARE text command set.)

Commands

The following commands can be issued from othere scripts in your linkset to control HexText.

fw_data

Display a string on the screen. The entire screen is overwritten with the text message. If you wish to only overwrite a portion of the display, consider fw_direct. 

llMessageLinked(LINK_SET, 0, "Some text to draw.", "fw_data");

fw_direct

This command is not supported by FURWARE text. It is unique to HexText to display text at specific display coordinates. It does not erase the display when called, instead, it overwrites existing characters in the display. Trim is ignored with fw_direct. 

llMessageLinked(LINK_SET, 0, "Some text to draw.", "fw_direct:10:2");

Display the string "Some text to draw." starting at the 10th column, 2nd row (both start at 0.)

fw_conf & fw_defaultconf

Sets the global style preference for the display. Unlike FURWARE text, fw_conf is treated the same as fw_defaultconf. 

llMessageLinked(LINK_SET, 0, "c=red; a=center", "fw_conf");
llMessageLinked(LINK_SET, 0, "c=red; a=center", "fw_defaultconf");

fw_notify

Enable or disable link message notifications when the script has completed rendering. Off by default. 

llMessageLinked(LINK_SET, 0, "on", "fw_notify");
llMessageLinked(LINK_SET, 0, "off", "fw_notify");

A link message will be sent to the linkset after rendering is complete with the key value of "fw_done"

fw_memory

Tells the owner how much memory is available. 

llMessageLinked(LINK_SET, 0, "", "fw_memory");

fw_reset

Performs a full reset on the text script. 

llMessageLinked(LINK_SET, 0, "", "fw_reset");

A link message will be sent to the linkset after reset is complete with the key value of "fw_ready"

Style settings

Text styles and format settings are specified using special strings. They are used for global settings ("fw_conf").

A single setting is given as a key=value pair, for example c=red.

Multiple settings are separated by ";", for example c=red; a=center; w=none.

In the following table: Italic = Default

Setting Key Values Description
Font color c R,G,B Font color as red, green, blue (each in range 0.0-1.0)
R,G,B,A Font color as red, green, blue, alpha (each in range 0.0-1.0)
rand Random color (with alpha = 1)
(predefined) Predefined color, see table below (default is White)
Alignment a left Alignment left
center Alignment centered
right Alignment right
Wrapping w word Wrap after words, if possible
char Wrap at any position
none No wrapping; cuts overlong lines
Trimming t on Trims whitespace from beginning and end of lines
off Keeps whitespace (except with wrap=word)
Force refresh force on Enables forced refresh of all faces (disables optimizations!)
off Disables forced refresh of all faces (enables optimizations)

Predefined colors

You may use the following names in place of color vectors in styles.

red green blue cyan magenta yellow white silver
darkred darkgreen darkblue darkcyan darkmagenta darkyellow black gray

Bugs

Probably a lot. Let Hexadeci Mole know.

Retrieved from "https://wiki.secondlife.com/w/index.php?title=HexText&oldid=1209655"