RedGPU V4.4.0-Alpha

English

한국어

English

한국어

Appearance

TextField3D ​

TextField3D is a text object placed at actual coordinates (x, y, z) in 3D space. It is useful for creating signposts in the world, name tags above character heads, or explanatory text attached to specific objects.

1. Basic Usage ​

TextField3D is treated the same as a general Mesh and is physically located in 3D space.

javascript
const textField = new RedGPU.Display.TextField3D(redGPUContext, "3D World Text");
textField.y = 5; // Place in the air
scene.addChild(textField);

2. Billboard and Size Control ​

3D text can be seen from the side or back depending on the camera position. To make the text always visible from the front, activate the Billboard feature, and you can set the world unit size or fixed pixel size as needed.

Property NameDescriptionDefault Value
useBillboardWhen activated, the text always faces the front even if the camera rotates.true
worldSizeVertical size in world space (Unit). Horizontal size is automatically adjusted according to text length.1
usePixelSizeWhether to use fixed pixel size mode. If true, it is displayed at the rendered physical pixel size regardless of distance.false
javascript
// 1. Set world unit size (shrinks with distance)
textField.worldSize = 2;

// 2. Set fixed pixel size (maintains readability regardless of distance)
textField.usePixelSize = true;

3. Relationship between World Size and Pixel Size (Font) ​

It is important to understand the relationship between the three key properties that determine the size and clarity of text in TextField3D.

3.1 Font Size (fontSize) ​

  • Role: Determines the resolution (quality) when rendering text into a bitmap internally.
  • Features: A larger fontSize produces a larger and clearer source texture. Rather than directly determining the physical size in 3D space, it should be understood as a factor determining the 'image quality' of the output.

3.2 World Size (worldSize) ​

  • Role: Determines the physical vertical height (in Units) within the 3D world space.
  • Behavior: Operates when usePixelSize is false, and the size changes as perspective is applied according to the distance from the camera.

3.3 Fixed Pixel Mode (usePixelSize) ​

  • Role: Placed in 3D space, but displayed on the screen at the actual rendered pixel size.
  • Relationship with Font: When this mode is activated, worldSize is ignored, and the actual height of the texture generated by fontSize becomes the output size on the screen. Therefore, it is very useful when constant readability must be maintained regardless of distance, such as for icons or name tags.

[Optimization Tip]

If the text appears too large or small when using usePixelSize, adjust the fontSize instead of the worldSize. Conversely, if it should behave like a general 3D object, it is recommended to set fontSize to an appropriately high value (e.g., 24-48) for texture clarity and adjust the actual size with worldSize.

4. Practical Example: Style and Sizing Mode Comparison ​

Explore various font style options and see the differences between world size (worldSize) mode and fixed pixel (usePixelSize) mode.

Next Steps ​

Learn about the interaction system to create dynamic content that reacts to user input.