Cangjie-SIG/RGF_CJ的编译与使用-优快云博客

Cangjie-SIG/RGF_CJ的编译与使用

【免费下载链接】RGF_CJ RGF是Windows系统下的通用渲染框架，其基于Direct3D、Direct2D、DXGI、DirectWrite、WIC、GDI、GDIplus等技术开发。RGF仓颉版（后续简称"RGF"）基于RGF(C/C++版)封装优化而来。RGF为开发者提供轻量化、安全、高性能以及高度一致性的2D渲染能力，并且提供对接Direct3D的相关接口，以满足开发者对3D画面渲染的需求。项目地址: https://gitcode.com/Cangjie-SIG/RGF_CJ

本文详细介绍了RGF_CJ渲染框架的编译环境配置、依赖管理、自动化构建脚本使用、功能示例以及项目约束与限制。主要内容包括：1) Windows平台下的环境要求与依赖配置；2) Python和Bat自动化脚本的使用方法；3) 窗口创建、图形渲染和事件处理等基础功能示例；4) 项目在操作系统支持、功能实现、性能优化和编译管理等方面的限制说明。

编译环境与依赖配置

在开始使用 RGF_CJ 之前，确保你的开发环境满足以下要求，并正确配置相关依赖。本节将详细介绍如何搭建编译环境以及管理项目依赖。

环境要求

操作系统

RGF_CJ 是一个专为 Windows 平台设计的渲染框架，因此需要运行在以下操作系统上：

Windows 10（推荐）
Windows 11

编译器与工具链

项目使用 Cangjie 编译器进行构建，确保已安装以下工具：

Cangjie 编译器：版本 0.58.3 或更高。
Cangjie 工具链：包括 cjpm（Cangjie 包管理器）和其他必要的构建工具。

运行时依赖

RGF_CJ 依赖于以下 Windows 系统库：

Direct3D、Direct2D、DXGI、DirectWrite、WIC、GDI、GDIplus 等图形库。
其他系统库如 user32、imm32、gdi32、ole32 等。

依赖配置

1. 安装 Cangjie 编译器

确保已正确安装 Cangjie 编译器，并将其添加到系统环境变量中。可以通过以下命令验证安装是否成功：

cj --version

2. 配置 `cjpm.toml`

项目的依赖和构建配置通过 cjpm.toml 文件管理。以下是一个典型的配置示例：

[package]
name = "rgf"
version = "2.3.7"
vendor = "Raozijun"
cjc-version = "0.58.3"
compile-option = "--disable-reflection -Oz -Woff unused --debug-macro"
link-option = "-L ./libs -l user32"
output-type = "static"
override-compile-option = "--cfg \"RGF_LANG=zh-cn\""
src-dir = "src"
target-dir = "target"

3. 安装依赖库

项目依赖的库文件（如 libRgf.dll）需要放置在 ./libs/ 目录下。确保以下文件已正确配置：

libRgf.dll：主库文件。
其他静态库（如 libuser32.a、libimm32.a）可根据需要添加。

4. 构建项目

使用以下命令构建项目：

cjpm update
cjpm build

常见问题与解决方案

问题 1：编译时缺少依赖库

解决方案：确保所有依赖库已正确放置在 ./libs/ 目录下，并在 cjpm.toml 中配置了正确的链接选项。

问题 2：运行时出现 DLL 缺失错误

解决方案：检查是否已将 libRgf.dll 和其他必要的动态链接库（DLL）放置在可执行文件的同级目录或系统路径中。

问题 3：语言配置不生效

解决方案：在 cjpm.toml 中确保 override-compile-option 参数已正确设置为 --cfg \"RGF_LANG=zh-cn\" 或 --cfg \"RGF_LANG=en\"。

总结

通过以上步骤，你可以顺利完成 RGF_CJ 的编译环境配置和依赖管理。如果在配置过程中遇到问题，可以参考项目的 README.md 或查阅相关文档。

自动化构建脚本的使用

RGF_CJ 项目提供了多种自动化构建脚本，帮助开发者快速完成编译、测试和清理工作。这些脚本主要位于 tool/bat 和 tool/python 目录下，支持多种语言和编码格式。以下将详细介绍这些脚本的功能和使用方法。

1. Python 工具脚本

`proj_clear_build_test.py`

该脚本用于快速清理、编译和测试项目。它会自动清理 build 目录中的可执行文件和动态链接库，并根据需要重新编译项目。编译完成后，脚本会列出可测试的项目路径供用户选择。

使用方法：

python proj_clear_build_test.py -lang zh-cn --nsty

参数说明：

-lang zh-cn：指定输出语言为简体中文。
--nsty：禁用样式输出（适用于无颜色支持的终端）。

`proj_test_all.py`

该脚本用于批量执行所有单元测试，并生成测试报告。它会自动编译项目（如未编译），然后依次执行每个单元测试，并将结果汇总到 python/report 目录下的报告中。

使用方法：

python proj_test_all.py

`proj_ergodic_dir.py`

该脚本用于生成 src 目录的文件树图，并自动添加后缀备注。生成的文档保存在工具目录中，包含目录结构和简单的统计信息。

使用方法：

python proj_ergodic_dir.py

2. Bat 脚本工具

`build.bat` / `build_utf8_zh_cn.bat` / `build_gbk_zh_cn.bat`

这些脚本用于快速编译项目，支持不同语言和编码格式：

build.bat：英文版本。
build_utf8_zh_cn.bat：UTF-8 编码的简体中文版本。
build_gbk_zh_cn.bat：GBK 编码的简体中文版本。

使用方法：

build_utf8_zh_cn.bat

3. 工具依赖

所有 Python 脚本均依赖 python 和 cjpm 环境，请确保系统环境变量中已配置相关内容。Bat 脚本仅依赖 cjpm。

4. 工具功能对比

工具名称	主要功能	语言支持	输出报告
`proj_clear_build_test.py`	清理、编译、测试	中/英文	否
`proj_test_all.py`	批量执行单元测试并生成报告	中/英文	是
`proj_ergodic_dir.py`	生成目录树图	无特定语言要求	是
`build[*].bat`	快速编译项目	中/英文	否

5. 示例流程图

以下是一个典型的使用流程示例：

mermaid

通过这些自动化脚本，开发者可以高效地完成项目的构建和测试工作，提升开发效率。

功能示例与基础使用

RGF_CJ 提供了丰富的功能示例和基础使用方法，帮助开发者快速上手并理解其核心功能。以下是一些典型的功能示例和基础使用场景。

基础窗口创建

以下是一个简单的窗口创建示例，展示了如何使用 RGF_CJ 创建一个基本的窗口：

import rgf.rgf_core.*

let winClass: WinContext = WinContext()
let winExample: WinBase = WinBase()

rsMain(
    {=>
        // 注册窗口类
        rwRegister(winClass, "ExampleWindow", WS_OVERLAPPEDWINDOW)

        // 创建窗口
        winExample.createWin(winClass, "RGF_CJ 示例窗口", 100, 100, 800, 600, 0, WS_OVERLAPPEDWINDOW)
    },
    {=>
        // 释放资源
        winExample.destroyWin()
        rwUnregister(winClass)
    }
)

流程图

mermaid

渲染内容到窗口

RGF_CJ 支持在窗口中渲染图形和文本。以下是一个简单的渲染示例：

import rgf.rgf_core.*

let winClass: WinContext = WinContext()
let winExample: WinBase = WinBase()

rsMain(
    {=>
        // 注册窗口类
        rwRegister(winClass, "RenderWindow", WS_OVERLAPPEDWINDOW)

        // 创建窗口
        winExample.createWin(winClass, "RGF_CJ 渲染示例", 100, 100, 800, 600, 0, WS_OVERLAPPEDWINDOW)

        // 获取渲染表面
        let surface: Surface = winExample.getSurface()

        // 创建纯色画刷
        let brush: SolidColorBrush = SolidColorBrush(surface, Color(255, 0, 0, 255))

        // 绘制矩形
        surface.beginDraw()
        surface.fillRect(Rect(100, 100, 200, 200), brush)
        surface.endDraw()
    },
    {=>
        winExample.destroyWin()
        rwUnregister(winClass)
    }
)

渲染流程

mermaid

事件处理

RGF_CJ 提供了事件处理机制，开发者可以轻松监听和处理窗口事件。以下是一个事件处理的示例：

import rgf.rgf_core.*

let winClass: WinContext = WinContext()
let winExample: WinBase = WinBase()

// 自定义窗口类，继承自 WinBase
class MyWindow <: WinBase {
    override onMouseMove(x: Int, y: Int) {
        println("鼠标移动到: (${x}, ${y})")
    }
}

let myWin: MyWindow = MyWindow()

rsMain(
    {=>
        rwRegister(winClass, "EventWindow", WS_OVERLAPPEDWINDOW)
        myWin.createWin(winClass, "RGF_CJ 事件示例", 100, 100, 800, 600, 0, WS_OVERLAPPEDWINDOW)
    },
    {=>
        myWin.destroyWin()
        rwUnregister(winClass)
    }
)

事件处理流程

mermaid

表格示例

以下是一些常用的 RGF_CJ 功能及其描述：

功能	描述
窗口创建	提供基础的窗口创建和管理功能
图形渲染	支持绘制矩形、圆形、文本等图形
事件处理	支持鼠标、键盘等事件的监听和处理
资源管理	提供画刷、位图等资源的创建和释放机制

约束与限制说明

在深入使用 Cangjie-SIG/RGF_CJ 项目时，开发者需要了解其约束与限制，以确保项目的顺利编译和运行。本节将详细说明项目在环境依赖、功能支持、性能优化等方面的限制，并提供相应的解决方案或替代方案。

环境依赖限制

操作系统支持
RGF_CJ 目前仅支持在 Windows 平台上运行，不支持 Linux 或 macOS。这是因为项目依赖了一些 Windows 特有的 API 和库文件（如 libRgf.dll）。
Python 版本
项目中的工具脚本（如 proj_test_all.py）需要 Python 3.7 或更高版本。低版本 Python 可能无法运行某些脚本。

Python 版本支持情况
< 3.7 不支持
>= 3.7 支持

Python 版本	支持情况
< 3.7	不支持
>= 3.7	支持

功能限制

图形渲染功能
RGF_CJ 的图形渲染功能（如 rgf_brush 和 rgf_image）依赖于 Direct2D 和 DirectWrite，因此需要安装 Windows SDK 和 DirectX 运行时。
多线程支持
项目中的某些模块（如 rgf_proc）对多线程的支持有限，开发者需避免在高并发场景下直接使用这些模块。

性能限制

内存占用
RGF_CJ 在处理大型图像或复杂路径时，内存占用较高。建议开发者在使用 rgf_bitmap 或 rgf_path 模块时，对资源进行合理管理。
实时渲染性能
实时渲染（如动态 UI）的性能受限于 Direct2D 的硬件加速能力。开发者可通过减少渲染层级或优化绘制逻辑来提升性能。

编译限制

依赖管理
项目的依赖通过 cjpm.toml 文件管理，但某些依赖（如 libRgf.dll）需要手动下载并放置在 libs/ 目录下。
```
# 示例：手动下载依赖
curl -o libs/libRgf.dll https://example.com/libRgf.dll
```
构建工具
项目的构建脚本（如 build_gbk_zh_cn.bat）仅支持 GBK 编码的中文环境，UTF-8 环境需使用 build_utf8_zh_cn.bat。

编码类型适用脚本
GBK build_gbk_zh_cn.bat
UTF-8 build_utf8_zh_cn.bat

编码类型	适用脚本
GBK	`build_gbk_zh_cn.bat`
UTF-8	`build_utf8_zh_cn.bat`

其他限制

文档完整性
项目的某些模块（如 rgf_cursor 和 rgf_menu）的文档尚未完善，开发者需通过阅读源码或示例代码来理解其功能。
测试覆盖率
项目的测试用例主要集中在基础功能（如 CT/base 和 HLT/base），高级功能的测试覆盖率较低，开发者需自行补充测试。

通过以上约束与限制的说明，开发者可以更好地规避潜在问题，并充分利用 RGF_CJ 的功能特性。

总结

RGF_CJ是一个专为Windows平台设计的渲染框架，提供了从环境配置到高级渲染功能的完整解决方案。尽管存在操作系统依赖、部分功能限制等约束，但通过合理的环境搭建和脚本自动化，开发者仍能高效利用其图形渲染能力。建议用户仔细阅读文档并参考示例代码，同时注意性能优化和测试覆盖，以充分发挥框架潜力。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Cangjie-SIG/RGF_CJ的编译与使用