Name	Name	Last commit message	Last commit date
parent directory ..
assets/shaders	assets/shaders
CMakeLists.txt	CMakeLists.txt
README.md	README.md
text.cpp	text.cpp

📝 Text Component - 文本渲染组件

状态：✅ 已完成
难度：⭐
代码行数：~239 行

📋 组件概述

Text 是一个文本渲染展示组件，演示了不同字体大小、颜色和动画效果的文本渲染。

核心功能

✅ 多种字体大小：从 8px 到 28px
✅ 颜色显示：7 种预设颜色
✅ 动画效果：脉冲、彩虹、滚动
✅ 多行文本：支持多行文本渲染
✅ 文本对齐：左对齐和缩进
✅ 装饰效果：下划线、删除线、阴影
✅ 实时统计：显示运行时间和状态
✅ 动画控制：暂停/继续、重置

🎨 视觉效果

字体大小演示

8px  - Tiny text
12px - Small text
16px - Normal text
20px - Large text
28px - Huge text

颜色预设

颜色	RGB 值	用途
White	(1.0, 1.0, 1.0)	标准文本
Gray	(0.6, 0.6, 0.6)	次要文本
Red	(0.9, 0.3, 0.3)	错误/警告
Green	(0.3, 0.9, 0.3)	成功/正常
Blue	(0.3, 0.7, 1.0)	信息/链接
Yellow	(1.0, 0.9, 0.2)	警告/暂停
Cyan	(0.2, 0.9, 0.9)	标题
Magenta	(0.9, 0.3, 0.9)	强调

组件布局

┌────────────────────────────────────────┐
│  Text Rendering Demo                   │
│  [Space] Pause/Resume   [R] Reset      │
│                                        │
│  Font Sizes:                           │
│    8px - Tiny text                     │
│    12px - Small text                   │
│    16px - Normal text                  │
│    20px - Large text                   │
│    28px - Huge                         │
│                                        │
│  Colors:                               │
│    Red  Green  Blue  Yellow  Magenta   │
│                                        │
│  Animated:                             │
│    Pulsing text    (动态大小+透明度)    │
│    Rainbow text    (彩虹颜色)          │
│    Scrolling text... (水平滚动)        │
│                                        │
│  Multi-line Text:                      │
│    This is the first line of text.    │
│    This is the second line.           │
│    And this is the third line!        │
│                                        │
│  Statistics:                           │
│    Time: 10.5s  FPS: ~240  Status: Running │
└────────────────────────────────────────┘

⌨️ 交互演示

键盘控制

按键	功能
Space	暂停/继续动画
R	重置所有动画
ESC	退出程序

🎯 核心实现

1. 字体大小演示

// 不同大小的文本
renderer->drawText("8px - Tiny text", x, y, colorWhite, 8.0f);
renderer->drawText("12px - Small text", x, y, colorWhite, 12.0f);
renderer->drawText("16px - Normal text", x, y, colorWhite, 16.0f);
renderer->drawText("20px - Large text", x, y, colorWhite, 20.0f);
renderer->drawText("28px - Huge", x, y, colorWhite, 28.0f);

2. 颜色预设

// 定义颜色数组
float colorRed[4] = {0.9f, 0.3f, 0.3f, 1.0f};
float colorGreen[4] = {0.3f, 0.9f, 0.3f, 1.0f};
float colorBlue[4] = {0.3f, 0.7f, 1.0f, 1.0f};

// 使用不同颜色
renderer->drawText("Red", x, y, colorRed, 14.0f);
renderer->drawText("Green", x, y, colorGreen, 14.0f);
renderer->drawText("Blue", x, y, colorBlue, 14.0f);

3. 动画效果

脉冲动画

// 大小和透明度同时变化
float pulseSize = 14.0f + 4.0f * std::sin(time * 3.0f);
float pulseAlpha = 0.5f + 0.5f * std::sin(time * 3.0f);
float colorPulse[4] = {1.0f, 0.8f, 0.2f, pulseAlpha};
renderer->drawText("Pulsing text", x, y, colorPulse, pulseSize);

彩虹动画

// 使用正弦波生成彩虹色
float hue = time * 0.5f;
float r = 0.5f + 0.5f * std::sin(hue);
float g = 0.5f + 0.5f * std::sin(hue + 2.0f);
float b = 0.5f + 0.5f * std::sin(hue + 4.0f);
float colorRainbow[4] = {r, g, b, 1.0f};
renderer->drawText("Rainbow text", x, y, colorRainbow, 14.0f);

滚动动画

// 水平移动文本
scrollOffset += deltaTime * 20.0f;  // 滚动速度
if (scrollOffset > 200.0f) {
    scrollOffset = -200.0f;  // 循环
}
float scrollX = startX + scrollOffset;
renderer->drawText("Scrolling text...", scrollX, y, colorCyan, 14.0f);

4. 多行文本

const char* lines[] = {
    "This is the first line of text.",
    "This is the second line.",
    "And this is the third line!",
    "Multiple lines are easy to render."
};

float lineHeight = 18.0f;
float currentY = startY;

for (int i = 0; i < 4; i++) {
    renderer->drawText(lines[i], x, currentY, colorWhite, 12.0f);
    currentY += lineHeight;
}

5. 装饰效果

下划线

renderer->drawText("Underlined", x, y, colorWhite, 14.0f);
// 使用矩形绘制下划线
float underlineY = y + 16;
renderer->drawRectangle(x, underlineY, 80, 1, colorWhite);

删除线

renderer->drawText("Strikethrough", x, y, colorGray, 14.0f);
// 使用矩形绘制删除线
float strikeY = y + 7;
renderer->drawRectangle(x, strikeY, 90, 1, colorGray);

阴影效果

// 先绘制阴影（偏移 2 像素）
renderer->drawText("Shadow", x + 2, y + 2, colorGray, 14.0f);
// 再绘制正常文本
renderer->drawText("Shadow", x, y, colorWhite, 14.0f);

🔬 技术要点

1. 文本渲染 API

void drawText(const char* text, 
              float x, 
              float y, 
              const float color[4], 
              float fontSize);

参数说明：

text: 要显示的文本（C 字符串）
x, y: 文本位置（左下角）
color: RGBA 颜色数组
fontSize: 字体大小（像素）

2. 颜色管理

RGBA 格式：

R（红）：0.0 - 1.0
G（绿）：0.0 - 1.0
B（蓝）：0.0 - 1.0
A（透明度）：0.0（全透明）- 1.0（不透明）

颜色混合：

// 插值两种颜色
float t = 0.5f;  // 混合比例
float r = color1[0] * (1.0f - t) + color2[0] * t;
float g = color1[1] * (1.0f - t) + color2[1] * t;
float b = color1[2] * (1.0f - t) + color2[2] * t;

3. 动画技巧

正弦波动画：

// 周期性变化
value = base + amplitude * std::sin(time * frequency);

// 示例：
// - base: 基础值
// - amplitude: 振幅
// - frequency: 频率（越大越快）

相位偏移：

// 创建相位差（彩虹效果）
float r = std::sin(time);
float g = std::sin(time + 2.0f);  // 120° 相位差
float b = std::sin(time + 4.0f);  // 240° 相位差

4. 布局管理

垂直布局：

float currentY = startY;
float lineHeight = 20.0f;

// 绘制多行
renderer->drawText("Line 1", x, currentY, color, size);
currentY += lineHeight;
renderer->drawText("Line 2", x, currentY, color, size);
currentY += lineHeight;

水平布局：

float currentX = startX;
float spacing = 60.0f;

// 绘制多列
renderer->drawText("Column 1", currentX, y, color, size);
currentX += spacing;
renderer->drawText("Column 2", currentX, y, color, size);

📊 性能分析

渲染调用统计

这个组件演示了大量文本渲染：

标题和说明：3 次
字体大小演示：5 次
颜色演示：5 次
动画文本：3 次
多行文本：4 次
对齐演示：3 次
装饰效果：6 次
统计信息：3 次

总计：约 32 次文本渲染调用 + 3 次矩形调用 = ~35 次渲染调用/帧

🎓 学习要点

初学者

文本渲染基础
- 如何调用 drawText API
- 字体大小的选择
- 颜色的设置
简单动画
- 基于时间的动画
- 正弦波的应用
- 循环动画
布局技巧
- 多行文本的间距
- 对齐和缩进

进阶开发者

动画设计
- 多种动画效果的组合
- 相位偏移创造复杂效果
- 动画的节奏和速度控制
装饰效果
- 使用基础图元模拟复杂效果
- 阴影、下划线的实现
- 层次渲染
UI 组合
- 文本与图形的结合
- 信息的可视化呈现

🚀 扩展方向

简单扩展

文本对齐：中心对齐、右对齐
文本换行：自动换行到下一行
更多动画：旋转、缩放、弹跳

中等扩展

富文本：混合字体大小和颜色
文本输入：可编辑文本区域
文本选择：鼠标选择文本

高级扩展

字体系统：多种字体支持
Unicode：支持多语言
文本布局引擎：复杂的文本排版

🏗️ 构建与运行

构建步骤

# 1. 配置项目
cd examples/cpp/text
cmake -S . -B build -G "Visual Studio 17 2022" -A x64

# 2. 编译
cmake --build build --config Release

# 3. 复制 DLL 到运行时目录
copy build\Release\Release\text.dll ..\..\..\..\native\build\Release\

# 4. 编译着色器
cd assets\shaders
compile_shaders.bat

运行组件

cd ..\..\..\..\native
.\build\Release\bitui_native.exe .\build\Release\text.dll

📁 文件结构

text/
├── text.cpp                          # 组件实现（~239 行）
├── CMakeLists.txt                    # 构建配置
├── README.md                         # 本文档
├── assets/
│   └── shaders/                      # 着色器目录
│       ├── triangle.vert             # 顶点着色器（GLSL）
│       ├── triangle.frag             # 片段着色器（GLSL）
│       ├── compile_shaders.bat       # 着色器编译脚本
│       └── spv/                      # 编译后的 SPIR-V
│           ├── triangle_vert.spv
│           └── triangle_frag.spv
└── build/                            # 构建输出
    └── Release/
        └── Release/
            └── text.dll              # 组件库

🔗 相关组件

组件	关系	说明
Input	相关组件	输入框需要文本渲染
Button	相关组件	按钮需要文本标签
所有组件	依赖	几乎所有 UI 组件都需要文本

📚 参考资料

API 使用

IRenderer::drawText(text, x, y, color, size) - 绘制文本
IRenderer::drawRectangle(x, y, w, h, color) - 绘制矩形（用于装饰）
IInput::isKeyJustPressed(keyCode) - 检测按键

数学函数

std::sin(x) - 正弦函数（动画）
std::cos(x) - 余弦函数（动画）

💡 最佳实践

颜色使用
- 使用预设颜色保持一致性
- 注意对比度确保可读性
- Alpha 通道用于透明效果
字体大小
- 标题：20-28px
- 正文：12-16px
- 说明：8-10px
动画设计
- 不要过度使用动画
- 保持动画流畅（60 FPS）
- 提供暂停选项
布局规划
- 使用统一的行高
- 保持适当的间距
- 对齐提高可读性

🐛 调试建议

常见问题

文本不显示
- 检查颜色是否与背景对比明显
- 验证位置是否在屏幕内
- 确认字体大小不为 0
文本被截断
- 检查窗口边界
- 验证坐标系统
- 确认文本长度
动画卡顿
- 检查 deltaTime 是否正确
- 验证数学运算
- 确认帧率稳定
颜色异常
- 检查 RGBA 值范围（0.0-1.0）
- 验证 Alpha 通道
- 确认颜色数组大小为 4

📈 版本历史

v1.0 (2025-10-12) - 初始版本
- 实现多种字体大小
- 添加 8 种颜色预设
- 实现 3 种动画效果
- 添加多行文本支持
- 实现装饰效果
- 添加动画控制

📞 技术支持

项目主页：Bit HCI
文档：docs/guides/
示例：examples/cpp/

🎨 设计说明

本组件是一个展示型组件，主要目的是演示文本渲染的各种可能性：

教学价值：展示如何使用文本 API
参考价值：提供可复用的代码片段
视觉效果：展示文本的表现力

在实际应用中，文本渲染通常会结合其他组件使用，如按钮标签、输入提示、状态显示等。

Happy Coding! 🎉

FilesExpand file tree

text

Directory actions

More options