图形学桌面应用【免费下载链接】RGF_CJRGF是仓颉Windows系统下的通用渲染框架兼应用开发框架。RGF仓颉版后续简称RGF基于RGF(C/C版)封装优化而来。RGF为开发者提供轻量化、安全、高性能以及高度一致性的2D渲染能力以及常用的桌面应用开发工具并且提供对接Direct3D的相关接口以满足开发者对3D画面渲染的需求。在Windows开发方面RGF在子包内也提供开箱即用的Windows API确保熟悉Win32的开发者快速上手。此外RGF还提供一些常用功能的封装如XAudio2、MF以辅助开发者实现音频、摄像头等扩展功能的管理。项目地址https://gitcode.com/Cangjie-SIG/RGF_CJ点击查看免费下载rgf.rgf_core是 RGF 仓颉版RGF_CJ的核心包承载了绘制库全局初始化、Win32 主消息循环、窗口类体系、渲染事件模型以及一批面向 Win32 互操作的底层工具函数。本文以 doc/api/rgf.rgf_core/readme.md 为骨架结合仓库源码系统讲解该包的 API 全貌、调用约定与源码级实现原理帮助读者掌握用仓颉语言构建 Windows 窗口应用与 2D 渲染程序的完整入口链路。一、包定位与 API 全景rgf.rgf_core是 RGF_CJ 项目中规模最大、职责最核心的包它既是窗口框架提供WinPure/WinCore窗口基类与全套窗口事件参数类也是渲染框架提供Surface、Bitmap、Brush、Path、TextLayout等绘制对象同时还承载着全局生命周期rsInitialize/rsDestroy/rsMain和 Win32 互操作ru*/rw*系列函数。从文档的 API 列表看该包公开成员可归为八大类类别数量代表成员函数22 个含重载rsMain、rsInitialize、rsCreateSysTimer、ruStrToWStr、rwBatchMove类90WinPure、WinCore、Surface、Color、Ev*事件参数类接口12IDraw、IEvent、IRenderEvent、IObjLink、IWinMethod等结构体2Context、ColorPct枚举40Substrate、RunMode、Antialias、WinStyle等类型别名3RgfHwnd、RgfHdc、RgfTimer变量与常量9rgfErrorWinUncreated、rgfMessageNote等错误/告警文案异常1WinException从源码结构看src/rgf_core该包对应的实现文件按职责拆分得十分清晰rgf_api.cjC 侧函数声明与包装、rgf_base.cj窗口基类与主入口封装、rgf_utils.cj工具函数、rgf_enum.cj枚举、rgf_struct.cj结构体与几何类、rgf_type.cj类型别名等读者可据此按图索骥深入阅读。二、全局生命周期初始化、释放与主入口RGF 绘制库的使用遵循“初始化 → 创建资源 → 消息循环 → 销毁”的生命周期所有入口都集中在rgf.rgf_core。2.1rsInitialize()与rsDestroy(token)public func rsInitialize(): ContextPtr public func rsDestroy(token: ContextPtr): BoolrsInitialize()完成 RGF 绘制库的全局初始化返回一个全局上下文ContextPtr令牌源码中为CPointerUnit类型别名见 src/rgf_core/rgf_type.cj。rsDestroy(token)执行全局释放传入rsInitialize返回的令牌返回是否成功。源码中两者的实现是直接的 C 侧调用包装rsInitialize调用rApiInitialize()rsDestroy调用rApiDestroy(token)见 src/rgf_core/rgf_api.cj。需要特别注意的是文档明确提示“本函数创建的上下文环境需要使用rsDestroy()方法释放”——即rsInitialize属于手动管理模式开发者自己rsInitialize后必须自行rsDestroy不能依赖 GC。2.2rsMain封装 Win32 主流程的入口函数public func rsMain(create:()-Unit, destroy:()-Unit, mode!:RunMode ...): Unit public func rsMain(create:()-Unit, mode!:RunMode): Unit public func rsMain(create:()-Unit): Unit public func rsMain(create:()-Unit, destroy:()-Unit): UnitrsMain是应用的主入口内部封装了 Win32 的标准流程获取模块句柄 → 初始化绘制库 → 创建Context→ 调用create创建窗口资源 → 进入GetMessageW/TranslateMessage/DispatchMessageW消息循环 → 主窗口关闭后调用destroy释放资源 → 释放上下文。源码 src/rgf_core/rgf_base.cj 中rsMainInner的实现揭示了几个关键细节主窗口判定消息循环以while(haveMainWin.load())为条件只要存在主窗口就持续分发消息WM_QUITbRet 0或主窗口销毁后循环退出。无效消息过滤循环内对hwnd 0或!wIsWindow(hwnd)的消息直接continue避免分发到已销毁窗口。中文说明文档注明“本函数内部封装了 Win 的主要流程若需要更高的自由度可参考此代码结构自行实现”即开发者完全可以参照rsMainInner的代码自行编写更精细的消息循环。2.3RunMode与调试/发布差异RunMode枚举定义了主函数执行模式源码 src/rgf_core/rgf_base.cj枚举值含义SysThreadAndAsyn新建系统线程异步不阻塞当前线程SysThreadAndWait新建系统线程并等待执行结束默认CJMainThread直接基于仓颉主线程运行rsMain有多个重载且带When[debug]/When[!debug]编译期条件注解调试与发布构建下的默认行为不同发布构建When[!debug]rsMain(create)/rsMain(create, destroy)默认走RunMode.SysThreadAndWait即新建 UI 线程并阻塞主线程等待结束。调试构建When[debug]同一签名的重载默认走RunMode.CJMainThread直接在仓颉主线程上执行窗口逻辑便于调试。显式传入mode的重载rsMain(create, destroy, mode)与rsMain(create, mode)则无编译期差异完全由开发者指定运行模式。若使用SysThreadAndAsyn配合ruFinished()判断 RGF 是否执行完成返回false表示正在执行true表示完成用于在其他线程阻塞等待。三、窗口类体系与窗口事件模型3.1 窗口类注册rwRegister/rwUnregisterpublic func rwRegister(ctxt: WinContext, className: String, style: UInt32, hbrBackground!: Int32 5): Bool public func rwUnregister(ctxt: WinContext): BoolrwRegister是 RGF 封装的窗口类注册方法hbrBackground默认值为5即NULL_BRUSH背景画刷为空。源码 src/rgf_core/rgf_api.cj 中注册成功后会将className记录进静态映射staticWinClassMap并回填ctxt.winClassCTxtPtr与ctxt._classNamerwUnregister注销成功后同步从映射移除。文档特别强调一个关键注意事项非本类注册的窗口类需要手动注入窗口过程函数否则 RGF 窗口类无法捕获系统事件。也就是说若开发者自行用原生 API 注册窗口类必须自行把消息路由到 RGF 的窗口过程事件系统才能工作。此外“凡注册的窗口类都应该由本方法注销”源码中还提供了rwClearAllWinClass()在rsMain销毁阶段统一清理所有记录在案、未被释放的窗口类。3.2 窗口句柄与类型别名public type RgfHwnd UIntNative // 窗口句柄 public type RgfHdc UIntNative // 设备上下文 public type RgfTimer HANDLE // Timer 句柄三个公开类型别名中RgfHwnd/RgfHdc是数值句柄RgfTimer直接映射到 Win32 的HANDLE见 src/rgf_core/rgf_type.cj。配套函数ruToHwnd(rgfHwnd)与ruToHdc(rgfHdc)负责把 RGF 句柄还原为 Win32 的HWND/HDC。3.3 窗口基类与渲染事件接口类体系的核心是WinPureRGF 窗口核心纯窗口见 doc/api/rgf.rgf_core/类/WinPure.md与WinCore继承WinPure具备渲染能力见 doc/api/rgf.rgf_core/类/WinCore.md。二者都实现渲染事件接口IRenderEvent/IRenderEventCore与绑定式事件接口IBindRenderEvent/IBindRenderEventCore。从源码 src/rgf_core/rgf_base.cj 可以看出窗口生命周期的完整顺序beforeCreate()调用createWin后最先触发此时渲染表面尚未创建created()窗口创建完成携带hwnd, x, y, nWidth, nHeightrendererCreated(surface)渲染表面就绪WinCore在此默认设置Antialias.HighQuality抗锯齿createDeviceResources()创建设备相关/渲染资源此事件可能在窗口周期内被多次调用onPaint(wRect)窗口需要重绘时触发参数为需要重绘的矩形destroyDeviceResources()销毁设备资源rendererDestroy()渲染表面释放前触发beforeDestroy()窗口销毁前destroyed()窗口生命周期终结。除了覆写式事件方法窗口类还提供一套绑定式lambda事件bindBeforeCreate、bindCreated、bindRendererCreated、bindCreateDeviceResources、bindOnPaint、bindDestroyDeviceResources、bindRendererDestroy、bindBeforeDestroy、bindDestroyed、bindWndProc。从GFBase.callWndProc的实现看绑定式事件优先于类自身方法满足“扩展修订类”的需求——即开发者不必继承窗口类直接给实例挂 lambda 即可自定义行为。此外rgf.rgf_core下还有 90 个Ev*事件参数类如EvMouse、EvKey、EvSize、EvTimer、EvDPIChanged等见 doc/api/rgf.rgf_core/类 目录它们把 Win32 消息转换为类型安全的仓颉对象是绑定式事件与wndProc处理时的参数载体。3.4 渲染相关辅助函数rwBatchMove(batch)批量移动窗口有三种重载分别接收(RgfHwnd,...)、(WinPure,...)、(IWinMethod,...)元组数组元组格式为[句柄/窗口, X, Y, 宽, 高]。源码实现使用BeginDeferWindowPos/DeferWindowPos/EndDeferWindowPos三件套保证一批窗口位置更新期间的重绘同步与性能。rwIsMainWin(rw/hWnd/IWinMethod)判断窗口是否为主窗口haveMainWin原子标志与mainWinHwnd全局句柄配合实现。rwGetRgfClass(rgfHwnd)通过句柄反向获取窗口类实例从staticMap永久映射中查找。rwDefWindowProc(hWnd, uMsg, wParam, lParam)DefWindowProc的包装用于未处理消息的默认处理。四、绘制对象与资源管理rgf.rgf_core同时暴露了完整的 2D 渲染对象体系按“设备相关/设备无关”和“手动释放/自释放”两个维度组织几何与颜色值类型Point/FPoint位置、Size/FSize尺寸、Rect/FRect矩形实现IRectT接口见 doc/api/rgf.rgf_core/类/Rect.md、Color色彩、Matrix/Matrix3X3。绘制对象Surface窗口渲染表面、BindSurface绑定式渲染表面、Bitmap/MemBitmap位图/内存位图、Brush及其子类SolidColorBrush、LinearGradientBrush、BitmapBrush、Path路径、StrokeStyle笔划风格、Layer图层、Image图像父类。文本体系TextCore、TextFormat、TextLayout、TextInlineObj、TextMetrics、LineMetrics、ClusterMetrics、OverhangMetrics、HitTestMetrics及Range*局部格式类。资源生命周期所有资源类都实现IObjLink接口isValid()有效性验证、release()释放、get/set底层对象访问基类SfcSubObjBase通过SfcSubObjType枚举区分对象类型并统一走rApiSfcSubObjRelease释放见 src/rgf_core/rgf_base.cj。带S前缀的类SBitmap、SPath、STextLayout等为自释放版本——它们被渲染表面接管释放表面时自动释放无需手动release()。五、系统工具函数定时器、字符串与内存互操作5.1 系统定时器public func rsCreateSysTimer(callback: CFunc(CPointerUnit, UInt8) - Unit, parameter: CPointerUnit, dueTime: UInt32, period: UInt32): RgfTimer public func rsDestroySysTimer(timer: RgfTimer): UnitrsCreateSysTimer基于 Win32 定时器队列创建定时器callback为C风格回调可传入CLambdaparameter为回调参数指针dueTime为首次执行等待时间毫秒period为每次间隔时间毫秒成功返回RgfTimer句柄。源码 src/rgf_core/rgf_utils.cj 中其底层调用wCreateTimerQueueTimer并附加WT_EXECUTEDEFAULT | WT_EXECUTELONGFUNCTION标志以支持长任务执行创建失败抛WinException。务必注意文档提示“凡是本函数创建的定时器都需要销毁”——用完调用rsDestroySysTimer(timer)注销底层wDeleteTimerQueueTimer失败抛WinException否则会造成句柄与回调资源泄漏。5.2 字符串与宽字符互操作RGF 在仓颉String与 Win32LPWSTRC 宽字符串之间提供了一组对称转换工具函数作用ruStrToWStr(str: String): LPWSTR仓颉字符串 → C 宽字符串含编码转换创建的字符串需用ruFree释放ruWStrToStr(str: LPWSTR): StringC 宽字符串 → 仓颉字符串含编码转换内部自动释放中间结果ruWStrlen(wcharPtr: LPWSTR): UInt32获取 C 宽字符串长度宽字符数ruFree(cPtr: CPointerUnit): Unit释放ruStrToWStr申请的宽字符串内存ruStrToCStrT(str, callback)字符串转换 回调内使用 自动释放一种更安全的便捷封装ruStrToCStr的实现源码 src/rgf_core/rgf_utils.cj为先ruStrToWStr转换执行用户回调最后rApiReleaseWcharStr释放——使用者在回调内使用cStr即可无需关心释放。推荐优先使用ruStrToCStr而非裸用ruStrToWStrruFree以规避忘记释放的风险。5.3 指针与内存工具ruUllToPtr(ptrVal: UIntNative): CPointerUnit将无符号数值如句柄地址值恢复为指针。ruLlToPtr(ptrVal: IntNative): CPointerUnit将有符号数值恢复为指针文档标注“极少数情况下使用”。ruRedefBitT1,T2(v): T2从内存比特层面重解释数据值类似 C 的联合体union。实现上取两个类型大小的最大值开临时缓冲区writeLittleEndian写入后readLittleEndian读回源码 src/rgf_core/rgf_utils.cj约束为T1/T2 : LittleEndianOrderT CType。ruSafeCStructT,RT(count, callback)自动创建count个T的 CType 内存、执行回调、自动释放回调收到CPointerT适合向 C 侧传入临时结构体数组。rsModRefToCurrDir()将当前程序的存储路径设为相对路径起点底层SetCurrentDirectoryToExe解决资源文件相对路径定位问题。rsGetMonitorFromPoint(x, y / Point / FPoint): Rect获取桌面坐标系下某点所在显示器的工作区矩形rcWork。源码通过EnumDisplayMonitors回调 PtInRect命中测试 GetMonitorInfoW获取工作区未命中时抛WinException。三个重载分别接受(Int32, Int32)、Point、FPoint。rsGetContext(): OptionContext获取全局上下文未初始化时返回None。rsEnd(exitCode: UInt32)结束进程底层ExitProcess用于主动终止应用。ruFinished(): Bool判断 RGF 是否执行完成配合SysThreadAndAsyn模式下的跨线程等待。六、结构体、常量与异常约定6.1 结构体Context技术上下文封装了ctxtPtrContextPtrRGF 全局上下文指针与hInstHINSTANCE程序模块实例句柄由rsMain内部创建并通过rsGetContext()获取。hInst在rwRegister注册窗口类时作为参数传给 C 侧rApiRegisterWinClass见 src/rgf_core/rgf_struct.cj 与 src/rgf_core/rgf_api.cj。ColorPct颜色及百分比值用于渐变色标/百分比配对等场景配合LinearGradientBrush使用。6.2 错误与告警常量包内定义了一组rgf*常量见 doc/api/rgf.rgf_core/变量与常量.md用于错误抛出与调试提示例如常量含义rgfErrorWinUncreated“访问未创建的窗口类”rgfErrorMainUiThreadinited“RGF 的主 UI 线程已被初始化”重复调用rsMain会抛出rgfErrorCpluapluaObjNotExist“底层对象未初始化或已经释放”rgfErrorWindowsApi“Windows Api 出现错误错误码”rgfErrorArrLenOverflow“数组长度超出最大限额”rgfWarnValidRdObj“异步调用渲染时请对类实例进行有效性验证”rgfMessageNote/rgfWarningNote调试消息/告警消息提示不影响正式程序执行rgfFunctionWillIgnored/rgfWrongAttribution“当前控件并未实现此绑定式事件传入的事件函数将被忽略”rgfNegativeReinter“当前正在进行负值相关的数值重解释”6.3 异常类WinException见 doc/api/rgf.rgf_core/异常/WinException.md是系统相关异常携带 Win32GetLastError错误码所有涉及 Windows API 调用的失败路径定时器创建失败、监视器查询失败、线程创建失败、消息循环错误等均抛出该异常。七、典型用法一个完整的 RGF 窗口应用骨架综合以上 API一个典型 RGF 窗口应用的最小骨架如下结构参考 test/CT/base/src/main.cj 等仓库内测试工程package main import rgf.rgf_core.* // 自定义渲染窗口继承 WinCore 获得渲染能力 class MyWin : WinCore { public override func createDeviceResources(): Bool { // 创建设备相关资源画刷、位图等 return true } public override func onPaint(wRect: Rect): Unit { // 在此执行绘制例如 // surface.clear(1.0, 1.0, 1.0, 1.0) } public override func destroyDeviceResources(): Bool { // 销毁设备相关资源 return true } } // 窗口类上下文全局 var winCtxt: WinContext WinContext() main() { // 注册窗口类hbrBackground 默认 NULL_BRUSH rwRegister(winCtxt, MyWindowClass, WinStyle.e2n(WinStyle.Default)) // RGF 主入口create 中创建窗口资源destroy 中释放 rsMain({ let win MyWin() win.createWin( winCtxt, RGF 示例窗口, 100, 100, 800, 600, // 位置与尺寸 0, // 父窗口句柄0 为桌面 WinStyle.e2n(WinStyle.Default), substrate: Substrate.Direct2D, // 推荐 Direct2D 渲染后端 bgMod: BackGroundMod.CoverNotDraw, ) win.show(true) }, { // destroy释放窗口资源 rwUnregister(winCtxt) }) }关键点回顾渲染后端通过Substrate枚举选择Direct2D推荐、GdiPlus、Pure纯窗口无渲染能力。rsMain在发布构建默认SysThreadAndWait、调试构建默认CJMainThread两种模式都能直接运行上述代码。如需更高自由度如自定义消息循环、消息过滤、加速键翻译文档建议参考rsMainInner的源码结构自行实现。八、深入阅读指引包 API 全表doc/api/rgf.rgf_core/readme.md函数细节doc/api/rgf.rgf_core/函数.md窗口基类与事件WinPure/WinCore文档见 doc/api/rgf.rgf_core/类实现见 src/rgf_core/rgf_base.cj主入口与消息循环实现src/rgf_core/rgf_base.cjrsMainInner、RunMode工具函数定时器/字符串/指针/监视器src/rgf_core/rgf_utils.cjC 侧函数声明与窗口类注册src/rgf_core/rgf_api.cj类型别名定义src/rgf_core/rgf_type.cj可运行的测试工程test/CT/base/src/main.cj、test/HLT/base/src/main.cj、test/HLT/pure/src/main.cj赞分享图形学桌面应用【免费下载链接】RGF_CJRGF是仓颉Windows系统下的通用渲染框架兼应用开发框架。RGF仓颉版后续简称RGF基于RGF(C/C版)封装优化而来。RGF为开发者提供轻量化、安全、高性能以及高度一致性的2D渲染能力以及常用的桌面应用开发工具并且提供对接Direct3D的相关接口以满足开发者对3D画面渲染的需求。在Windows开发方面RGF在子包内也提供开箱即用的Windows API确保熟悉Win32的开发者快速上手。此外RGF还提供一些常用功能的封装如XAudio2、MF以辅助开发者实现音频、摄像头等扩展功能的管理。项目地址https://gitcode.com/Cangjie-SIG/RGF_CJ点击查看免费下载相关推荐SFML窗口与事件循环全解从创建窗口到事件驱动主循环的最实用指南SFML窗口与事件循环全解从创建窗口到事件驱动主循环的最实用指南 SFML 是一款轻量高效的 C 跨平台多媒体库其中最核心的入门内容就是 窗口创建 与图形学音视频游戏开发Piston游戏引擎核心组件解析输入、窗口与事件循环Piston游戏引擎核心组件解析输入、窗口与事件循环 Piston是一个用Rust编写的模块化游戏引擎以其精简的核心设计和出色的灵活性而闻名。该引擎采用最小游戏开发Extrapolate未来路线图即将推出的AI增强功能与平台扩展计划Extrapolate未来路线图即将推出的AI增强功能与平台扩展计划 Extrapolate作为一款基于Next.js、Vercel、Replicate等技术上一篇OSSN插件开发入门如何为社交平台添加自定义功能下一篇BAAH开发者贡献指南如何为开源项目提交代码的完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考