Skip to main content
Version: 3.x

PandaGL 图形库

  • 开始日期:2022-04-11
  • 目标主要版本:3.x
  • 参考问题:无
  • 实现 PR:#292, #281

概括

将字体、文字处理、图像读写、图形绘制等功能模块整合为 PandaGL 图形库。

基本示例

#include <pandagl.h>

int main(void)
{
int ret;
pd_canvas_t img;
pd_pos_t pos = { 0, 80 };
pd_rect_t area = { 0, 0, 320, 240 };
pd_text_t *text = pd_text_create();
pd_text_style_t style;

/* 初始化字体处理功能 */
pd_font_library_init();

/* 创建一个图像,并使用灰色填充 */
pd_canvas_init(&img);
pd_canvas_create(&img, 320, 240);
pd_canvas_fill(&img, RGB(240, 240, 240));

/* 设置文本的字体大小 */
pd_text_style_init(&style);
style.pixel_size = 24;
style.has_pixel_size = TRUE;

/* 设置文本图层的固定尺寸、文本样式、文本内容、对齐方式 */
pd_text_set_fixed_size(text, 320, 240);
pd_text_set_style(text, &style);
pd_text_set_align(text, PD_TEXT_ALIGN_CENTER);
pd_text_write(text, L"这是一段测试文本\nHello, World!", NULL);
pd_text_update(text, NULL);

/* 将文本图层绘制到图像中,然后将图像写入至 png 文件中 */
pd_text_render_to(text, area, pos, &img);
ret = pd_write_png_file("test_string_render.png", &img);
pd_canvas_destroy(&img);

/* 释放字体处理功能相关资源 */
pd_font_library_destroy();
return ret;
}

动机

2.x 版本中的图形处理相关源文件比较分散,不利于查找和维护,而且按照 3.x 版本的架构设计思想,它们应该被整理为通用的图形库。

常见的开源图形库除了具备基本的图形绘制能力外,大都还具备文字渲染、图像读写能力,因此,新的图形库也应该具备这些能力。

详细设计

图形库命名为 PandaGL,标识符命名以 pd_ 开头。

模块分为以下几类:

  • 画布(Canvas):提供像素数据操作和基本图形绘制能力。
  • 字体库(FontLibrary):提供字体文件加载、字形渲染能力。
  • 文字(Text):提供文字排版和渲染能力。
  • 图像(Image):提供图像文件读写能力。

由于字体库和图像模块都依赖第三方库,出于可裁剪性和库体积上的考虑,在构建配置中将它们配置为可选模块,示例:

# 禁用图像模块
xmake config --with-pandagl-image=n

# 禁用字体库模块
xmake config --with-pandagl-font=n

# 禁用文字模块
xmake config --with-pandagl-text=n

LCUI_TextLayer 重命名为 pd_text_t,删除 UTF-8 和 ANSI 版本的文本操作函数,仅保留宽字符版本,示例:

- /** 插入文本内容(UTF-8版) */
- LCUI_API int TextLayer_InsertText(LCUI_TextLayer layer, const char *utf8_str);
-
- /** 追加文本内容(宽字符版) */
- LCUI_API int TextLayer_AppendTextW(LCUI_TextLayer layer, const wchar_t *wstr,
- LinkedList *tag_stack);
-
- /** 追加文本内容 */
- LCUI_API int TextLayer_AppendTextA(LCUI_TextLayer layer,
- const char *ascii_text);
+ PD_PUBLIC int pd_text_append(pd_text_t *text, const wchar_t *wstr, list_t *tag_stack);

缺点

无。

备选方案

删除图形处理相关模块,直接用成熟的开源图形库。不建议采用此方案,因为工作量较大,还需要投入成本去学习其它图形库。

采用策略

这是个破坏性改动,需要对所有用到 PandaGL 功能的代码进行修改。由于主要改动都在命名上,这些文件通常只需要全局替换名称即可。

未解决的问题

出于函数参数复杂度问题上的考虑,pd_text_write()pd_text_append()pd_text_insert() 的第三个参数 tag_stack 用处不大,应该重新考虑 tag_stack 的实现方式,例如:内置在 pd_text_t 中。

字体库和文字模块的接口有待重新设计。