raygui Terminal 风格接入指南:Mecha 字体驱动的终端复古 UI 主题与五种加载方式
raygui Terminal 风格接入指南:Mecha 字体驱动的终端复古 UI 主题与五种加载方式
raygui 内置的 Terminal 风格(styles/terminal/README.md)以暗色背景、荧光绿文字还原经典命令行终端观感,并配套自定义字体 "Mecha"。本文围绕该风格的使用展开:先介绍其配色与文件清单,再逐一讲解二进制 .rgs、文本 .rgs、嵌入 .h、样式表 PNG 等五种接入方式,并结合 src/raygui.h 的 GuiLoadStyle() / GuiLoadStyleFromMemory() 实现剖析 rgs 文件格式与字体数据压缩原理,最后给出字体信息与版本注意事项。读完即可在自己的 raygui 应用中快速启用 Terminal 风格,并理解不同接入方式的取舍。
风格概览:暗底亮绿的终端美学
Terminal 风格的定位十分明确:"启动你的终端,敲入命令,感受数据流动的连接感"。它采用典型的终端配色——极暗背景(0x0c1505,接近纯黑的墨绿色)、荧光绿文字(0x38f620)与深绿/浅绿交织的边框,控件在正常、聚焦、按下、禁用四种状态下呈现不同的绿色阶调,视觉上高度还原字符终端界面,适合命令行工具、调试面板、日志查看器等工具类应用。
下面是该风格的颜色表,展示了默认控件在各状态下的完整配色:
提供的文件清单
该风格的官方说明提供了多种接入方式,开发者可按项目需求选择其一。原文档文件清单如下(各文件位于 styles/terminal 目录):
| 文件名称 | 说明 |
|---|---|
style_terminal.rgs |
二进制样式文件(raygui 4.0 格式),字体数据已压缩(recs、glyphs) |
style_terminal.rgs.txt |
文本样式文件,不含字体数据,需要外部提供字体 |
style_terminal.old.rgs |
二进制样式文件(raygui 3.x 格式),字体数据未压缩(recs、glyphs) |
style_terminal.h |
可嵌入代码的样式文件,自包含,含字体数据 |
style_terminal.png |
样式表图片,内含 rGSf 数据块,携带二进制 rgs 文件数据 |
说明:以上清单以原 README 声明为准。以当前仓库实际内容核对,styles/terminal 目录下实际提供
style_terminal.rgs、style_terminal.rgs.txt、style_terminal.h、style_terminal.png以及字体Mecha.ttf、字符集charset.txt,并未包含style_terminal.old.rgs文件;若需 raygui 3.x 兼容格式,需自行转换或关注后续仓库更新。
除 Terminal 风格外,raygui 还提供了 dark、bluish、candy、cyber、jungle 等 20 款内置风格,统一入口与说明见 styles/README.md,这些风格均需 raylib 6.x 与 raygui 5.x 支持(见 styles/README.md)。
接入方式一:运行时加载二进制 .rgs 文件
最直接的接入方式是在初始化时调用 GuiLoadStyle() 加载 .rgs 文件(对应 src/raygui.h 的声明):
#include "raylib.h"
#define RAYGUI_IMPLEMENTATION
#include "raygui.h"
int main(void)
{
InitWindow(800, 600, "Terminal Style Demo");
// 在初始化阶段加载 Terminal 风格(.rgs 默认是二进制文件)
GuiLoadStyle("resources/styles/terminal/style_terminal.rgs");
while (!WindowShouldClose())
{
BeginDrawing();
ClearBackground(GetColor(GuiGetStyle(DEFAULT, BACKGROUND_COLOR)));
// ... 绘制 GuiButton()、GuiTextBox() 等控件
EndDrawing();
}
CloseWindow();
return 0;
}
GuiLoadStyle() 的实现位于 src/raygui.h,其加载策略是先尝试以文本方式打开:若文件首字符是 # 则按文本 rgs 解析;否则标记 tryBinary,再以二进制方式读取整个文件并转交 GuiLoadStyleFromMemory() 处理(src/raygui.h)。因此同一个 API 可同时兼容文本与二进制两种 rgs 文件。
二进制 rgs 文件格式剖析
GuiLoadStyleFromMemory() 的注释块完整定义了 rgs 二进制结构(src/raygui.h):
偏移 | 大小 | 类型 | 说明
0 | 4 | char | 签名:"rGS "(0x72 0x47 0x53 0x20)
4 | 2 | short | 版本号:200 / 400 / 600
6 | 2 | short | 保留字段
8 | 4 | int | 属性数量(仅记录与默认风格不同的属性)
之后是每 8 字节一条的属性记录(ControlId + PropertyId + PropertyValue),再往后是可选的字体数据:字体参数(版本 ≥600 时含 32 字节字体文件名、baseSize、glyphCount、字体类型、白色矩形)、字体 atlas 图像(可 DEFLATE 压缩)、字形矩形 recs 与字形信息 glyphs(版本 ≥400 支持压缩)。
以仓库中的 style_terminal.rgs 实测文件头验证:
72 47 53 20 -> "rGS " 签名
58 02 -> 0x0258 = 600(v600 格式)
00 00 -> 保留字段
11 00 00 00 -> 17 个属性
随后紧跟 17 条属性数据,与文本文件中的 17 行 p 记录一一对应;属性之后即为字体数据段(Mecha.ttf 文件名、baseSize=16、glyphCount=175 等)。这正是 style_terminal.h 中 TERMINAL_STYLE_PROPS_COUNT 17 的来源。
两种版本的压缩差异
- 版本 ≥400:recs 与 glyphs 数据段各带一个"压缩后大小"字段,支持 DEFLATE 压缩;加载时若
compSize != 原始大小则调用DecompressData()解压,并做解压尺寸安全检查(src/raygui.h)。 - raygui 3.x(版本 200):无压缩支持,recs/glyphs 原样存储——这正是原 README 中
style_terminal.old.rgs"字体数据未压缩(recs, glyphs)"注释的由来。
接入方式二:文本 .rgs 文件加载(外部字体)
若希望样式文件可读、可手工编辑,且能自行控制字体文件,可使用文本格式 style_terminal.rgs.txt。该文件不含字体数据,需要将 Mecha.ttf 与 charset.txt 一同随附。其完整内容如下:
#
# rgs style text file - raygui style file generated using rGuiStyler
#
# Provided info:
# f <fontGenSize> <fontFileName> <charsetFileName>
# p <controlId> <propertyId> <propertyValue> Property description
#
# WARNING: This style uses a custom font, must be provided with style file
#
v 600
f 16 Mecha.ttf charset.txt
p 00 00 0x1c8d00ff DEFAULT_BORDER_COLOR_NORMAL
p 00 01 0x161313ff DEFAULT_BASE_COLOR_NORMAL
p 00 02 0x38f620ff DEFAULT_TEXT_COLOR_NORMAL
p 00 03 0xc3fbc6ff DEFAULT_BORDER_COLOR_FOCUSED
p 00 04 0x43bf2eff DEFAULT_BASE_COLOR_FOCUSED
p 00 05 0xdcfadcff DEFAULT_TEXT_COLOR_FOCUSED
p 00 06 0x1f5b19ff DEFAULT_BORDER_COLOR_PRESSED
p 00 07 0x43ff28ff DEFAULT_BASE_COLOR_PRESSED
p 00 08 0x1e6f15ff DEFAULT_TEXT_COLOR_PRESSED
p 00 09 0x223b22ff DEFAULT_BORDER_COLOR_DISABLED
p 00 10 0x182c18ff DEFAULT_BASE_COLOR_DISABLED
p 00 11 0x244125ff DEFAULT_TEXT_COLOR_DISABLED
p 00 16 0x00000010 TEXT_SIZE
p 00 17 0x00000000 TEXT_SPACING
p 00 18 0xe6fce3ff LINE_COLOR
p 00 19 0x0c1505ff BACKGROUND_COLOR
p 00 20 0x00000008 TEXT_LINE_SPACING
语法说明(对应 GuiLoadStyle() 文本解析逻辑,src/raygui.h):
v 600:样式版本号,版本 ≥600 时字体行按f <字号> <字体文件> <字符集文件>顺序解析(旧版本顺序相反)。f 16 Mecha.ttf charset.txt:字体声明。加载时LoadFileText()读取同目录下的charset.txt,经LoadCodepoints()得到码点列表,再LoadFontEx()按指定字号(16)加载字体(src/raygui.h)。若字体纹理加载失败,会自动回退到默认字体并将 TEXT_SIZE 重置为 10、TEXT_SPACING 重置为 1(src/raygui.h)。p 00 00 0x1c8d00ff:属性行,格式为p <controlId> <propertyId> <propertyValue>,00表示 DEFAULT 控件。加载时通过GuiSetStyle()写入全局样式数组。
使用示例:
// 文本 rgs 需要与 Mecha.ttf、charset.txt 放在同一目录
GuiLoadStyle("resources/styles/terminal/style_terminal.rgs.txt");
接入方式三:嵌入 .h 源码文件(自包含,零外部资源)
若希望应用完全自包含、不依赖任何外部文件,推荐直接嵌入 style_terminal.h。该文件由 StyleAsCode exporter v2.0 生成,头部明确标注用法:"On init call: GuiLoadStyleTerminal();"。
在 style_selector.c 示例中即采用了这种方式:
#define RAYGUI_IMPLEMENTATION
#include "../../src/raygui.h"
// raygui embedded styles
#include "../styles/style_terminal.h" // raygui style: terminal
// ...
// 初始化阶段调用
GuiLoadStyleTerminal();
GuiLoadStyleTerminal() 的完整实现见 style_terminal.h,其内部流程清晰呈现了嵌入样式的自包含原理:
- 写入 17 条样式属性:遍历
terminalStyleProps<a href="https://link.gitcode.com/i/a627425100f1176c78554ce9ca943511" target="_blank">]数组逐条GuiSetStyle(),默认属性会自动传播到其余控件(与GuiLoadStyleFromMemory()中 controlId=0 时的传播行为一致,见 [src/raygui.h)。 - 解压字体 atlas:
terminalFontData<a href="https://link.gitcode.com/i/f08b9a550a4915ea6769b13eff184d90" target="_blank">]是 DEFLATE 压缩的 256×256 GRAY+ALPHA 字体图集(压缩后 1731 字节,定义于 [style_terminal.h),通过DecompressData()解压后构造Image。 - 组装字体:
baseSize = 16、glyphCount = 175;terminalFontRecs<a href="https://link.gitcode.com/i/1ab5baf7f4ca79e1fd1a782317a93654" target="_blank">](175 个 Rectangle)与terminalFontGlyphs[](175 个 GlyphInfo,含码点/偏移/步进)分别拷贝到RAYGUI_CALLOC分配的内存中——注释说明这是"为避免释放字体时出错"的必要拷贝([style_terminal.h)。 - 加载纹理并挂载字体:
LoadTextureFromImage()生成纹理后UnloadImage()释放解压数据,再GuiSetFont(font);同时SetShapesTexture()将形状绘制的白色矩形指向字体图集,实现 UI 形状与文字的单次绘制优化(style_terminal.h)。 - 记录字体名:通过
snprintf()将 "Mecha.ttf" 写入内部guiFontName(需 raygui 5.0,style_terminal.h)。
// 嵌入方式:无需任何外部文件
#include "style_terminal.h"
// 初始化阶段调用
GuiLoadStyleTerminal();
嵌入方式下若同时启用 RAYGUI_FONT_ICONS_BAKING,还会调用 GuiFontIconBaking() 将图标烘焙进字体图集并更新白色矩形位置(style_terminal.h)。
接入方式四与五:样式表 PNG 与运行时拖拽
- 样式表 PNG(
rGSfchunk):style_terminal.png 不仅用于预览,其图像数据内嵌了rGSfchunk,携带完整二进制rgs文件数据。可将 PNG 当作载体分发样式,运行时从中提取 rgs 数据后调用GuiLoadStyleFromMemory()(仅支持二进制,见 src/raygui.h 的声明注释)。 - 运行时热切换:
style_selector.c还演示了拖拽加载——检测到.rgs文件被拖入窗口即调用GuiLoadStyle(路径)(style_selector.c);切换风格前先调用GuiLoadStyleDefault()重置并卸载先前加载的字体纹理(style_selector.c),该 API 的声明位于 src/raygui.h。
配色方案参数全表
综合 style_terminal.h 与文本 rgs,Terminal 风格共修改 17 项默认属性(DEFAULT 控件,controlId=0),颜色均为 0xRRGGBBAA 格式:
| 属性(propertyId) | 值 | 含义 |
|---|---|---|
| BORDER_COLOR_NORMAL (0) | 0x1c8d00ff |
正常态边框:深绿 |
| BASE_COLOR_NORMAL (1) | 0x161313ff |
正常态底色:近黑 |
| TEXT_COLOR_NORMAL (2) | 0x38f620ff |
正常态文字:荧光绿 |
| BORDER_COLOR_FOCUSED (3) | 0xc3fbc6ff |
聚焦态边框:浅绿白 |
| BASE_COLOR_FOCUSED (4) | 0x43bf2eff |
聚焦态底色:中绿 |
| TEXT_COLOR_FOCUSED (5) | 0xdcfadcff |
聚焦态文字:近白绿 |
| BORDER_COLOR_PRESSED (6) | 0x1f5b19ff |
按下态边框:暗绿 |
| BASE_COLOR_PRESSED (7) | 0x43ff28ff |
按下态底色:亮绿 |
| TEXT_COLOR_PRESSED (8) | 0x1e6f15ff |
按下态文字:深绿 |
| BORDER_COLOR_DISABLED (9) | 0x223b22ff |
禁用态边框:暗墨绿 |
| BASE_COLOR_DISABLED (10) | 0x182c18ff |
禁用态底色:深墨绿 |
| TEXT_COLOR_DISABLED (11) | 0x244125ff |
禁用态文字:灰绿 |
| TEXT_SIZE (16) | 16 |
全局字号(由字体生成尺寸决定) |
| TEXT_SPACING (17) | 0 |
字符间距 |
| LINE_COLOR (18) | 0xe6fce3ff |
分隔线/面板线颜色:浅绿白 |
| BACKGROUND_COLOR (19) | 0x0c1505ff |
全局背景:极暗墨绿 |
| TEXT_LINE_SPACING (20) | 8 |
文本行间距 |
其中 TEXT_SIZE 由字体加载决定,因此在 GuiLoadStyleTerminal() 中直接取自 font.baseSize = 16,而文本 rgs 的 f 16 与二进制 rgs 中记录的 0x10(16)完全一致。若加载失败回退默认字体,TEXT_SIZE 会自动改为 10。
关于字体:Mecha
Terminal 风格使用 Mecha 字体,作者 Captain Falcon,为 100% 免费字体(原 README 注明可从 dafont.com 的 mecha-cf 页面下载)。该字体风格硬朗、几何感强,与终端主题的科技气质高度契合。
字体相关细节(可从 style_terminal.h 与 charset.txt 确认):
- 字符集:charset.txt 定义了 175 个码点,覆盖 ASCII 全量字符及 Latin-1 补充字符(含
¡ ¢ £ € ¥ Š § š © ª « ¬ ® ¯ ° ± ² ³ Ž µ ¶ · ž ¹ º » Œ œ Ÿ ¿ À … ÿ等),对应glyphCount = 175。 - 图集:256×256 GRAY+ALPHA,DEFLATE 压缩后仅 1731 字节;175 个字形矩形与字形度量信息随样式一并固化在头文件中。
- 字号与间距:baseSize 16、spacing 0。
注意事项与版本要求
- 版本依赖:Terminal 风格属 raygui 5.x / raylib 6.x 时代产物(styles/README.md 明确所有内置风格均要求 raylib 6.x 与 raygui 5.x);
guiFontName写入逻辑需 raygui 5.0(style_terminal.h)。 - rgs 版本兼容:二进制 rgs 支持 200 / 400 / 600 三个版本号(src/raygui.h)。Terminal 的二进制文件为 v600;若面向 raygui 3.x 旧版本,则需使用未压缩的
.old.rgs格式(本仓库未提供该文件)。 - 切换样式前重置:
GuiLoadStyleDefault()会卸载先前加载的自定义字体纹理并恢复默认样式,风格热切换时必须先调用它(参考 style_selector.c)。 - 文本 rgs 的字体路径:文本加载时字体与字符集文件按"rgs 所在目录"解析(
GetDirectoryPath(fileName)拼接,见 src/raygui.h),部署时需保证Mecha.ttf与charset.txt与文本 rgs 同目录。 - 嵌入头文件的代价:
.h方式自包含、无外部依赖,但把 1731 字节压缩图集与 175 条字形数据全部编入源码,会增加编译单元体积;对二进制体积敏感的项目可改用外部.rgs运行时加载。
综上,Terminal 风格为 raygui 开发者提供了"文件加载"与"代码嵌入"两条完整路径:前者适合资源目录化管理与运行期热切换,后者适合单文件分发与零依赖部署;配合 styles/terminal/README.md 提供的文件清单与 style_selector.c 的可运行示例,可在数分钟内为应用接入这一经典终端主题。

