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.

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.

Billboard Setup

• useBillboard: When activated, the text always faces the front even if the camera rotates.

Size and Rendering Mode

Property Name	Description	Default Value
worldSize	Vertical size in world space (Unit). Horizontal size is automatically adjusted according to text length.	1
usePixelSize	Whether to use fixed pixel size mode. If true, it is displayed at the rendered physical pixel size regardless of distance.	false

// 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: Configuring 3D Text

Let's configure 3D text placed together with a GLTF model.

import * as RedGPU from "https://redcamel.github.io/RedGPU/dist/index.js";

RedGPU.init(canvas, (redGPUContext) => {
    const scene = new RedGPU.Display.Scene();
    
    // 1. Create and Place 3D Text
    const text3D = new RedGPU.Display.TextField3D(redGPUContext, "Damaged Helmet");
    text3D.y = 2.5;
    text3D.fontSize = 24;
    text3D.background = "rgba(0, 204, 153, 0.8)";
    text3D.padding = 10;
    text3D.useBillboard = true; // Rotate with camera
    text3D.worldSize = 1.2;     // Set world size
    
    scene.addChild(text3D);

    // 2. Setup Model and Environment
    const ibl = new RedGPU.Resource.IBL(redGPUContext, 'https://redcamel.github.io/RedGPU/examples/assets/hdr/2k/the_sky_is_on_fire_2k.hdr');
    const controller = new RedGPU.Camera.OrbitController(redGPUContext);
    controller.distance = 5;
    
    const view = new RedGPU.Display.View3D(redGPUContext, scene, controller);
    view.ibl = ibl;
    redGPUContext.addView(view);

    new RedGPU.GLTFLoader(redGPUContext, 'https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/DamagedHelmet/glTF-Binary/DamagedHelmet.glb', (loader) => {
        scene.addChild(loader.resultMesh);
    });

    new RedGPU.Renderer().start(redGPUContext);
});

Live Demo

Check out the differences between text fields based on setting combinations in the example below.

Key Summary

• TextField3D: A text object placed at actual coordinates in world space.
• CSS Styles: Web standard styles such as color, background, and border can be applied as is.
• Billboard: Can be set so that 3D text always faces the camera to improve readability.

---

Next Steps

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

• Interaction