简介面向AutoCAD二次开发初学者这套ObjectARX自定义实体实例围绕一条自定义直线实体完整演示了ARX项目框架搭建、自定义类继承AcDbLine并重写dwgInFields/dwgOutFields、dxfInFields/dxfOutFields、worldDraw等关键函数以及实体注册、命令实现、编译加载到AutoCAD的整套流程。资源包含TestCmd与TestEntity两个工程目录命令入口与实体定义分离源码注释清晰可对照学习DWG/DXF序列化、屏幕绘制、数据完整性与调试等底层机制省去从零搭建环境的时间。压缩包共70个文件以C头文件、源文件和obj/ilk等编译中间文件为主附带dsp/dsw工程配置、arx/dbx插件产物整体仅5.08MB便于快速下载与查阅。目前已有1162人浏览学习作为小而完整的入门示例对后续开发复杂自定义实体有直接铺垫作用适合理解ObjectARX与AutoCAD内部图形系统的交互方式也是进一步扩展算法、属性与事件响应能力的基础。1. 自定义实体为什么是 ARX 的「分水岭」先看清它解决什么问题拿到一张带参数化符号的成套图纸图块一多改一个尺寸就要炸开重画、重新对齐卡顿到怀疑人生。这时候如果底层用的是 ARX 自定义实体双击、拖夹点、属性面板实时联动图纸体量再大也不会散架。ObjectARX 是 C 开发者做 VC 环境下的 AutoCAD 二次开发最直接的手段而自定义实体从 AcDbEntity 派生自定义类是 ARX 能力的天花板——它让你创建的图形不再是「死图元」而是自带行为逻辑的活对象。这篇笔记就用一个最简三角形实体把整个链路走一遍从类设计、绘制、保存到踩坑修复新手能照着搭熟手也能对一对边界处理。2. 自定义实体的体系结构从 AcDbEntity 派生到五个必须重载的方法2.1 先分清「普通图元」和「自定义实体」的本质差别ARX 里画一根线、一个圆用的是 AcDbLine、AcDbCircle这些是框架写死的类。你往图面上一扔它就是一个静态对象位置定了数据就定死了。想改只能用命令去改它的属性稍微复杂一点的参数联动——比如三角形的底边拉长、高度跟着夹点动——靠普通图元做要么写一堆外部逻辑在命令里改坐标要么炸开重组完全失去「对象感」。自定义实体从根本上换了一条路你从 AcDbEntity 派生一个新类把图形的几何逻辑封装在类内部。图形画出来之后它知道自己的基点和高度你拖夹点它自己重算另外两个顶点你改属性面板里的参数它自己触发重生成。这就是「数据与行为内聚」也是 ARX 自定义实体和普通图元的本质界限。2.2 五个核心方法的分工从绘制到持久化对象在 CAD 里的生命周期大致是创建 → 显示 → 保存 → 再打开 → 交互修改。每个环节都对应一个可以重载的虚函数。最常用的五个如下表方法名作用必须重载的原因worldDraw / subWorldDraw把实体画到屏幕上框架不知道你的图形长什么样dwgOutFields把成员数据写进 dwg 文件保存后重开数据不能丢dwgInFields从 dwg 文件读回数据与 dwgOutFields 严格对称subGetGripPoints返回夹点坐标数组鼠标悬停时要有可抓的点subMoveGripPointsAt夹点拖动的回调拖动后要自己更新几何这里最容易迷糊的是 worldDraw 和 subWorldDraw。前者是传统入口后者是 2007 之后推荐的子类化入口。简单说你直接用 worldDraw 会破坏基类的某些缓存逻辑subWorldDraw 是用更细粒度的回调替代它。两者重写一个即可我建议自定义实体一律走 subWorldDraw省掉一堆缓存相关的疑难杂症。2.3 引用计数与 AcDbObjectId新手最容易漏的「所有权」概念ARX 里所有数据库对象AcDbObject 派生类都用引用计数管理内存。你用 new 创建了一个自定义实体它还不是数据库的一部分引用计数的初始值是 0。把它 addAcDbEntity 到块表记录里引用计数变成 1这时候你把本地指针置空就行——千万不能 delete否则 CAD 会直接崩溃。对应的还有 AcDbObjectId它只是数据库对象的一个「索引号」不是指针。平时跨函数传递实体身份传 id 不传指针拿 id 用 acdbOpenObject 打开实体、用完立刻 close 再置空。这条规则是 ARX 开发的红线后面第五章的崩溃坑大半都来自这里。3. 环境准备与工程骨架VS 配置、ARX 向导与模块加载3.1 环境匹配第一关VS 版本与 SDK 版本的配对ObjectARX 的 SDK 和编译器版本是强绑定的。用错了组合编译出来的 arx 文件加载就报「不兼容的模块」或直接让 CAD 崩溃。常见做法是先确定你手里的 CAD 主版本再去 ObjectARX SDK 文档里找到它对应的 VS 版本范围。比如较新的 CAD 主版本要求 VS 2022 配合对应的 SDK老一点的 CAD 只能配 VS 2017 或 2019。我一般会在装 SDK 之前先把 VS 装好再装 SDK然后立刻用一个最简单向导工程编译测试确认 arx 能加载再往下写。顺序反了SDK 装完检测不到编译器又要折腾环境变量。3.2 工程骨架从向导工程开始别手搓SDK 自带的 ObjectARX 向导Wizard会生成一个完整的最小工程。它替你搞定了大部分编译配置include 路径、库文件、预处理器定义、导出函数入口。正规步骤是「向导生成 → 编译通过 → 改代码」不是「新建空项目 → 手动加配置」。向导生成的工程里最关键的三个文件rxinit.cpp— 入口点 acrxEntryPoint 所在也是 acrxRegisterApp 注册程序名的地方acedCmd.cpp— 定义具体命令的 ARX 命令函数用 acedRegCmds 注册StdArx.h— 预编译头包含几乎全部 ObjectARX 头文件3.3 注册命令与卸载逻辑加载成功后你能看到什么命令注册集中在入口点的 kInitAppMsg 分支卸载在 kUnloadAppMsg。一个合格的入口函数长这样extern C AcRx::AppRetCode acrxEntryPoint(AcRx::AppMsgCode msg, void* appId) { switch (msg) { case AcRx::kInitAppMsg: acrxDynamicLinker-unlockApplication(appId); acrxRegisterApp(ACRX_APP_NAME); acedRegCmds-addCommand(_T(OBJECTARX_SAMPLE), _T(MAKETRI), _T(MAKETRI), ACRX_CMD_MODAL, makeTriCommand); break; case AcRx::kUnloadAppMsg: acedRegCmds-removeGroup(_T(OBJECTARX_SAMPLE)); break; default: break; } return AcRx::kRetOK; }代码逻辑有三层加载时先解锁应用unlockApplication 是为了允许在 AutoCAD 运行时替换 arx 文件调试时很有用再注册全局程序名最后往命令栈里塞一个命令。卸载时按组名移除命令组即可。注意第一个和第三个参数都是_T(MAKETRI)——第一个是内部命令名第三个是用户输入的命令名可以不一样但通常保持一致免得命令明明存在却找不到。调试时要注意的细节acedRegCmds-addCommand必须在 kInitAppMsg 里调用不能放在命令函数里卸载时removeGroup的参数要和addCommand第一个参数完全一致否则命令组残留下次加载会报重复定义。4. 把三角形实体落地绘制、参数化与模型空间注册4.1 类定义与成员设计基点和高度是两个可变参数自定义实体的几何模型越简单越能看清套路。我们的三角形实体有两个本地成员一个基点坐标 m_basePt一个高度 m_height。三个顶点全部由这两个参数派生出来——这样设计的好处是夹点拖动时只需要改这两个值不用去处理三个顶点的联动。class TriEntity : public AcDbEntity { public: ACRX_DECLARE_MEMBERS(TriEntity); TriEntity(); TriEntity(const AcGePoint3d basePt, double height); virtual ~TriEntity(); // 绘制 virtual Adesk::Boolean subWorldDraw(AcGiWorldDraw* mode); // 序列化 virtual Acad::ErrorStatus dwgOutFields(AcDbDwgFiler* filer) const; virtual Acad::ErrorStatus dwgInFields(AcDbDwgFiler* filer); // 夹点 virtual Acad::ErrorStatus subGetGripPoints(AcGePoint3dArray gripPoints, AcDbIntArray apps, AcDbIntArray modes) const; virtual Acad::ErrorStatus subMoveGripPointsAt(const AcDbIntArray indices, const AcGeVector3d offset); // 访问器 AcGePoint3d basePoint() const { return m_basePt; } double height() const { return m_height; } void setBasePoint(const AcGePoint3d pt); void setHeight(double h); private: AcGePoint3d m_basePt; double m_height; };ACRX_DECLARE_MEMBERS 这个宏会在类里生成静态的 RxClassDesc 描述符ObjectARX 靠它识别这个类名、归档、运行时类型转换。少了它整个类在数据库里注册不了。成员变量两名足够基点决定三角形左下角位置高度决定顶点的 y 方向偏移——第三个顶点和右下角顶点全部由这两个值计算这样夹点拖动的重绘逻辑会非常干净。4.2 worldDraw 实现用 AcGiWorldDraw 画三角形Adesk::Boolean TriEntity::subWorldDraw(AcGiWorldDraw* mode) { // 根据基点和高度派生三个顶点 AcGePoint3d p0 m_basePt; AcGePoint3d p1(m_basePt.x m_height, m_basePt.y, 0.0); AcGePoint3d p2(m_basePt.x m_height * 0.5, m_basePt.y m_height, 0.0); // 画闭合的三角形轮廓 AcGePoint3dArray pts; pts.append(p0); pts.append(p1); pts.append(p2); mode-geometry().polyline(3, pts.asArrayPtr(), NULL, Adesk::kTrue); return Adesk::kTrue; }注意几个细节polyline 的第一个参数是点数pts.asArrayPtr()把 AcGePoint3dArray 转成原始指针数组最后一个参数 kTrue 表示闭合也就是从最后一个点自动连回第一个点。返回值 kTrue 表示「绘制完成不需要默认绘制逻辑继续干活」如果返回 kFalse基类的边框、代理图形等逻辑还会再跑一遍通常没必要。实际项目中如果实体会被频繁重生成建议把三顶点坐标存成成员变量只在参数变化时更新一次而不是每次绘制都现算。这一步对大型图纸的性能感知比较明显三角形无所谓但几百个虚线多边形叠加时差异就在帧率上了。4.3 序列化实现dwgOutFields 与 dwgInFields 的严格对称保存和读取是两个必须「长相一样」的函数。ObjectARX 没有自动序列化你写几个成员就必须在读取时按同样的顺序拿几个成员。顺序错了读出来的数据全是乱的而且是静默错乱——CAD 不报错只是图形位置漂移。Acad::ErrorStatus TriEntity::dwgOutFields(AcDbDwgFiler* filer) const { assertWriteEnabled(); Acad::ErrorStatus es AcDbEntity::dwgOutFields(filer); if (es ! Acad::eOk) return es; // 按成员变量逐一写出顺序必须与读取一致 filer-writePoint3d(m_basePt); filer-writeDouble(m_height); return filer-filerStatus(); } Acad::ErrorStatus TriEntity::dwgInFields(AcDbDwgFiler* filer) { assertReadEnabled(); Acad::ErrorStatus es AcDbEntity::dwgInFields(filer); if (es ! Acad::eOk) return es; // 与 dwgOutFields 顺序严格一致先点后高度 m_basePt filer-readPoint3d(); m_height filer-readDouble(); return filer-filerStatus(); }assertWriteEnabled和assertReadEnabled是 ARX 的「后悔药」机制的核心——在修改或读取数据前框架会检查当前对象是否处于正确的打开状态。如果是只读打开却要写数据直接触发断言帮你提前发现问题而不是拖到保存时才炸。序列化里最容易犯的错就是在 dwgInFields 里没有先调用基类的读取逻辑导致基类数据比如图层、线型全部丢失图形变成「裸对象」。写完后一定要做一次「保存-关闭-重开」的往返测试。文件能存、能取、能重开这三个都过了序列化才算及格。4.4 注册命令把对象真正放进模型空间有了类还差一个把它塞进数据库的命令函数。这是 ARX 新手最常翻车的地方——new 出来的对象不知道加到哪里或者加了之后忘了关闭引用。下面的代码是标准动作:void makeTriCommand() { // 拿到当前数据库的块表 AcDbDatabase* db acdbHostApplicationServices()-workingDatabase(); AcDbBlockTable* pBlkTbl NULL; db-getBlockTable(pBlkTbl, AcDb::kForRead); // 定位模型空间块表记录 AcDbObjectId msId; pBlkTbl-getAt(ACDB_MODEL_SPACE, msId); pBlkTbl-close(); AcDbBlockTableRecord* pMsRec NULL; acdbOpenObject(pMsRec, msId, AcDb::kForWrite); // 创建自定义实体加到模型空间 TriEntity* pTri new TriEntity(AcGePoint3d(0, 0, 0), 10.0); AcDbObjectId triId; pMsRec-appendAcDbEntity(triId, pTri); // 关闭记录和实体——append 之后所有权归数据库 pMsRec-close(); pTri-close(); acdbHostApplicationServices()-workingDatabase()-regenerate(); }过程的每一步都有对应的资源管理责任块表以只读打开用完立刻 close模型空间记录以写打开负责接收新实体实体 new 出来先 append 进记录再 close——注意这里不是 deleteclose 会触发引用计数减一但 append 的时候加一所以对象依然存活但由数据库托管。关闭顺序必须是「先关记录再关实体」反过来会让实体在写入时找不到所属记录。regenerate()是最后一步强制全图重生成。如果不调命令执行后图形可能不显示必须手动 regen 才出来。5. 实测踩坑与排查数据丢失、白屏、崩溃的常见问题5.1 现象命令执行后屏幕上什么都没有这是第一个绕不开的坎。命令跑了加了个实体但图面上看不到任何东西。原因大概率在两个地方。第一实体坐标超出了当前视图范围——基点设成 (0,0,0) 但当前视图 zoom 到别的区域去了。第二subWorldDraw 里没有正确绘制或者返回值写成了 kFalse导致框架认为你不想画。解决办法分两步先用zoom extents看整个图面排除视图范围问题然后在 subWorldDraw 里加一个临时acutPrintf(_T(draw called))输出确认回调有没有被触发。如果回调压根没触发问题在实体的类注册和命令注册上如果触发了但看不到检查 polyline 的坐标是否确实在合理数值范围内有些坐标差极小比如 1e-6 量级会导致图形肉眼不可见。5.2 现象保存后重开实体消失了dwg 文件里明明存了东西重开就是没有。这种情况十有八九是序列化函数写漏了成员或者读写顺序不一致。我遇到过最典型的一次dwgOutFields 里先写了高度再写基点dwgInFields 里却先读基点再读高度。数值全错位但偏偏图形「看起来」正常——因为基点和高度都是 double 类型错位之后只是数值变了没有类型不匹配的报错所以排查难度极大。解决办法是强制让两个函数并排写逐行对照。我自己的习惯是先写 dwgOutFields再拷贝一份改成 dwgInFields把 write 改成 read这样顺序天然一致。5.3 现象夹点能显示但拖动后图形错乱夹点出现了说明 subGetGripPoints 返回的坐标数组是有效的。但拖动时图形变形通常是 subMoveGripPointsAt 里更新几何的逻辑不完整。比如我最初只在拖动时更新了基点坐标忘了重新计算三条边结果图形拉成一个扭曲的四边形。还有一种更隐蔽的情况夹点数组里有两个点都映射到同一个顶点拖动其中一个另一个没跟着动图形就撕裂了。解决办法是定义夹点坐标时明确「哪个夹点对应哪个参数」而不是把派生顶点直接塞进去。我的做法是index 0 对应基点index 1 对应高度——subMoveGripPointsAt 拿到 offset 偏移量后只 update 对应的参数其余几何全部由参数计算推导。这样逻辑永远是一致的。5.4 现象双击编辑或属性修改时 CAD 直接崩溃崩溃问题里很大的比例来自对象引用计数。典型场景代码里用了acdbOpenObject打开实体处理完忘了 close或者对同一个指针 close 了两次第二次是一个悬空指针操作崩溃无提示。ARX 崩溃大部分时候不弹任何对话框直接程序消失。原因是 ObjectARX 框架会在结束事务时统一检查引用计数发现不匹配就 SegFault 退出。排查这类问题没有捷径只能靠「代码审查 调试器」。我自己的习惯是写一个辅助日志函数在每次 open/close 后记录指针地址和操作崩溃后看最后几行日志基本一眼定位。另外要注意同一个实体如果在同一次事务里被 open 两次第二次的 close 才是真正释放引用计数的第一次如果也 close就会把引用多减一次同样炸。5.5 现象arx 卸载时提示「仍然有实体引用本模块」开发调试时反复加载卸载 arx某次卸载直接报错提示还有实体正在使用。原因就是图纸里已有的自定义实体还在引用你的类而你要把包含这个类的模块卸掉。解决办法不是硬卸载而是先清理图面上的图纸实体删除图中所有 TriEntity可以遍历模型空间拿 AcDbEntity 判断 isKindOf再执行卸载。另外入口点的 kUnloadAppMsg 里也要记得把命令组移除干净否则命令残留比实体引用更隐蔽。如果你实在不想删图纸内容就把卸载操作交给 CAD 自己去判断用appload里「卸载」时它其实也会先检查报错就说明有实体依赖。配合class命令查看有多少驻留实例可以辅助判断是否还有存活对象。6. 进阶用法属性面板联动与夹点自定义的收尾技巧自定义实体只做到「画出来」只是及格线。真正让人愿意用还得打通属性面板和夹点交互这两条体验链路。属性面板显示自定义数据靠的是重载subGetClassID和subGetAttributes这一组回调。ObjectARX 的机制是属性面板在渲染某个实体的属性页时会向这个实体询问「你有什么自定义字段」你再把这些字段通过描述符机制暴露出去。典型的字段就是我们的 m_height把高度暴露成可编辑项用户在属性面板改数值内部触发setHeight自动重生成图形——这比手动拖夹点精确得多尤其适合输入精确尺寸的场景。我的实际做法会在 setHeight 里加一句void TriEntity::setHeight(double h) { assertWriteEnabled(); m_height h; // 通知数据库本对象已修改触发重生成 recordGraphicsModified(); }recordGraphicsModified是 ARX 提供的「标记图形脏」接口它会告知 AutoCAD 该实体的显示缓存已失效需要重画。不加这句你改了属性面板的数值图形却纹丝不动用户会以为数据没生效。夹点自定义方面之前第五章的三角形只有两个夹点——基点和一个高度控制点。实际项目中往往需要更多中点夹点、旋转夹点、对齐夹点。subGetGripPoints返回点数组时还可以通过modes数组给每个夹点指定类型。常见的类型包括kGripPoint普通移动、kGripRotate旋转、kGripStretch拉伸不同类型的夹点光标样式不同交互语义也不同。给三角形加一个「高度中点夹点」的话只需要在 subGetGripPoints 里多 append 一个点在 subMoveGripPointsAt 里判断 indices 里含有 2 时把偏移量换算成高度的增量即可。最后提醒一点整条链路走下来最容易让人崩溃的永远不是逻辑复杂度而是你以为写完的东西其实没被调用——类没注册、命令没注册、回调没触发三者任何一个断裂代码就像黑匣子一样静默失败。我从那以后每完成一个自定义实体都会强制走一遍「新建 → 绘制 → 保存 → 重开 → 夹点拖拽 → 属性修改」这六步验证清单全部通过才敢说「这个实体做完了」。希望这篇笔记能帮你少走几趟这些弯路直接把精力花在真正值得做的几何逻辑上。本文还有配套的精品资源点击获取 
长河君 · 2026/10/19 13:40:51 · 阅读 1.2k ObjectARX自定义实体完全指南：从AcDbEntity派生到夹点交互
简介面向AutoCAD二次开发初学者这套ObjectARX自定义实体实例围绕一条自定义直线实体完整演示了ARX项目框架搭建、自定义类继承AcDbLine并重写dwgInFields/dwgOutFields、dxfInFields/dxfOutFields、worldDraw等关键函数以及实体注册、命令实现、编译加载到AutoCAD的整套流程。资源包含TestCmd与TestEntity两个工程目录命令入口与实体定义分离源码注释清晰可对照学习DWG/DXF序列化、屏幕绘制、数据完整性与调试等底层机制省去从零搭建环境的时间。压缩包共70个文件以C头文件、源文件和obj/ilk等编译中间文件为主附带dsp/dsw工程配置、arx/dbx插件产物整体仅5.08MB便于快速下载与查阅。目前已有1162人浏览学习作为小而完整的入门示例对后续开发复杂自定义实体有直接铺垫作用适合理解ObjectARX与AutoCAD内部图形系统的交互方式也是进一步扩展算法、属性与事件响应能力的基础。1. 自定义实体为什么是 ARX 的「分水岭」先看清它解决什么问题拿到一张带参数化符号的成套图纸图块一多改一个尺寸就要炸开重画、重新对齐卡顿到怀疑人生。这时候如果底层用的是 ARX 自定义实体双击、拖夹点、属性面板实时联动图纸体量再大也不会散架。ObjectARX 是 C 开发者做 VC 环境下的 AutoCAD 二次开发最直接的手段而自定义实体从 AcDbEntity 派生自定义类是 ARX 能力的天花板——它让你创建的图形不再是「死图元」而是自带行为逻辑的活对象。这篇笔记就用一个最简三角形实体把整个链路走一遍从类设计、绘制、保存到踩坑修复新手能照着搭熟手也能对一对边界处理。2. 自定义实体的体系结构从 AcDbEntity 派生到五个必须重载的方法2.1 先分清「普通图元」和「自定义实体」的本质差别ARX 里画一根线、一个圆用的是 AcDbLine、AcDbCircle这些是框架写死的类。你往图面上一扔它就是一个静态对象位置定了数据就定死了。想改只能用命令去改它的属性稍微复杂一点的参数联动——比如三角形的底边拉长、高度跟着夹点动——靠普通图元做要么写一堆外部逻辑在命令里改坐标要么炸开重组完全失去「对象感」。自定义实体从根本上换了一条路你从 AcDbEntity 派生一个新类把图形的几何逻辑封装在类内部。图形画出来之后它知道自己的基点和高度你拖夹点它自己重算另外两个顶点你改属性面板里的参数它自己触发重生成。这就是「数据与行为内聚」也是 ARX 自定义实体和普通图元的本质界限。2.2 五个核心方法的分工从绘制到持久化对象在 CAD 里的生命周期大致是创建 → 显示 → 保存 → 再打开 → 交互修改。每个环节都对应一个可以重载的虚函数。最常用的五个如下表方法名作用必须重载的原因worldDraw / subWorldDraw把实体画到屏幕上框架不知道你的图形长什么样dwgOutFields把成员数据写进 dwg 文件保存后重开数据不能丢dwgInFields从 dwg 文件读回数据与 dwgOutFields 严格对称subGetGripPoints返回夹点坐标数组鼠标悬停时要有可抓的点subMoveGripPointsAt夹点拖动的回调拖动后要自己更新几何这里最容易迷糊的是 worldDraw 和 subWorldDraw。前者是传统入口后者是 2007 之后推荐的子类化入口。简单说你直接用 worldDraw 会破坏基类的某些缓存逻辑subWorldDraw 是用更细粒度的回调替代它。两者重写一个即可我建议自定义实体一律走 subWorldDraw省掉一堆缓存相关的疑难杂症。2.3 引用计数与 AcDbObjectId新手最容易漏的「所有权」概念ARX 里所有数据库对象AcDbObject 派生类都用引用计数管理内存。你用 new 创建了一个自定义实体它还不是数据库的一部分引用计数的初始值是 0。把它 addAcDbEntity 到块表记录里引用计数变成 1这时候你把本地指针置空就行——千万不能 delete否则 CAD 会直接崩溃。对应的还有 AcDbObjectId它只是数据库对象的一个「索引号」不是指针。平时跨函数传递实体身份传 id 不传指针拿 id 用 acdbOpenObject 打开实体、用完立刻 close 再置空。这条规则是 ARX 开发的红线后面第五章的崩溃坑大半都来自这里。3. 环境准备与工程骨架VS 配置、ARX 向导与模块加载3.1 环境匹配第一关VS 版本与 SDK 版本的配对ObjectARX 的 SDK 和编译器版本是强绑定的。用错了组合编译出来的 arx 文件加载就报「不兼容的模块」或直接让 CAD 崩溃。常见做法是先确定你手里的 CAD 主版本再去 ObjectARX SDK 文档里找到它对应的 VS 版本范围。比如较新的 CAD 主版本要求 VS 2022 配合对应的 SDK老一点的 CAD 只能配 VS 2017 或 2019。我一般会在装 SDK 之前先把 VS 装好再装 SDK然后立刻用一个最简单向导工程编译测试确认 arx 能加载再往下写。顺序反了SDK 装完检测不到编译器又要折腾环境变量。3.2 工程骨架从向导工程开始别手搓SDK 自带的 ObjectARX 向导Wizard会生成一个完整的最小工程。它替你搞定了大部分编译配置include 路径、库文件、预处理器定义、导出函数入口。正规步骤是「向导生成 → 编译通过 → 改代码」不是「新建空项目 → 手动加配置」。向导生成的工程里最关键的三个文件rxinit.cpp— 入口点 acrxEntryPoint 所在也是 acrxRegisterApp 注册程序名的地方acedCmd.cpp— 定义具体命令的 ARX 命令函数用 acedRegCmds 注册StdArx.h— 预编译头包含几乎全部 ObjectARX 头文件3.3 注册命令与卸载逻辑加载成功后你能看到什么命令注册集中在入口点的 kInitAppMsg 分支卸载在 kUnloadAppMsg。一个合格的入口函数长这样extern C AcRx::AppRetCode acrxEntryPoint(AcRx::AppMsgCode msg, void* appId) { switch (msg) { case AcRx::kInitAppMsg: acrxDynamicLinker-unlockApplication(appId); acrxRegisterApp(ACRX_APP_NAME); acedRegCmds-addCommand(_T(OBJECTARX_SAMPLE), _T(MAKETRI), _T(MAKETRI), ACRX_CMD_MODAL, makeTriCommand); break; case AcRx::kUnloadAppMsg: acedRegCmds-removeGroup(_T(OBJECTARX_SAMPLE)); break; default: break; } return AcRx::kRetOK; }代码逻辑有三层加载时先解锁应用unlockApplication 是为了允许在 AutoCAD 运行时替换 arx 文件调试时很有用再注册全局程序名最后往命令栈里塞一个命令。卸载时按组名移除命令组即可。注意第一个和第三个参数都是_T(MAKETRI)——第一个是内部命令名第三个是用户输入的命令名可以不一样但通常保持一致免得命令明明存在却找不到。调试时要注意的细节acedRegCmds-addCommand必须在 kInitAppMsg 里调用不能放在命令函数里卸载时removeGroup的参数要和addCommand第一个参数完全一致否则命令组残留下次加载会报重复定义。4. 把三角形实体落地绘制、参数化与模型空间注册4.1 类定义与成员设计基点和高度是两个可变参数自定义实体的几何模型越简单越能看清套路。我们的三角形实体有两个本地成员一个基点坐标 m_basePt一个高度 m_height。三个顶点全部由这两个参数派生出来——这样设计的好处是夹点拖动时只需要改这两个值不用去处理三个顶点的联动。class TriEntity : public AcDbEntity { public: ACRX_DECLARE_MEMBERS(TriEntity); TriEntity(); TriEntity(const AcGePoint3d basePt, double height); virtual ~TriEntity(); // 绘制 virtual Adesk::Boolean subWorldDraw(AcGiWorldDraw* mode); // 序列化 virtual Acad::ErrorStatus dwgOutFields(AcDbDwgFiler* filer) const; virtual Acad::ErrorStatus dwgInFields(AcDbDwgFiler* filer); // 夹点 virtual Acad::ErrorStatus subGetGripPoints(AcGePoint3dArray gripPoints, AcDbIntArray apps, AcDbIntArray modes) const; virtual Acad::ErrorStatus subMoveGripPointsAt(const AcDbIntArray indices, const AcGeVector3d offset); // 访问器 AcGePoint3d basePoint() const { return m_basePt; } double height() const { return m_height; } void setBasePoint(const AcGePoint3d pt); void setHeight(double h); private: AcGePoint3d m_basePt; double m_height; };ACRX_DECLARE_MEMBERS 这个宏会在类里生成静态的 RxClassDesc 描述符ObjectARX 靠它识别这个类名、归档、运行时类型转换。少了它整个类在数据库里注册不了。成员变量两名足够基点决定三角形左下角位置高度决定顶点的 y 方向偏移——第三个顶点和右下角顶点全部由这两个值计算这样夹点拖动的重绘逻辑会非常干净。4.2 worldDraw 实现用 AcGiWorldDraw 画三角形Adesk::Boolean TriEntity::subWorldDraw(AcGiWorldDraw* mode) { // 根据基点和高度派生三个顶点 AcGePoint3d p0 m_basePt; AcGePoint3d p1(m_basePt.x m_height, m_basePt.y, 0.0); AcGePoint3d p2(m_basePt.x m_height * 0.5, m_basePt.y m_height, 0.0); // 画闭合的三角形轮廓 AcGePoint3dArray pts; pts.append(p0); pts.append(p1); pts.append(p2); mode-geometry().polyline(3, pts.asArrayPtr(), NULL, Adesk::kTrue); return Adesk::kTrue; }注意几个细节polyline 的第一个参数是点数pts.asArrayPtr()把 AcGePoint3dArray 转成原始指针数组最后一个参数 kTrue 表示闭合也就是从最后一个点自动连回第一个点。返回值 kTrue 表示「绘制完成不需要默认绘制逻辑继续干活」如果返回 kFalse基类的边框、代理图形等逻辑还会再跑一遍通常没必要。实际项目中如果实体会被频繁重生成建议把三顶点坐标存成成员变量只在参数变化时更新一次而不是每次绘制都现算。这一步对大型图纸的性能感知比较明显三角形无所谓但几百个虚线多边形叠加时差异就在帧率上了。4.3 序列化实现dwgOutFields 与 dwgInFields 的严格对称保存和读取是两个必须「长相一样」的函数。ObjectARX 没有自动序列化你写几个成员就必须在读取时按同样的顺序拿几个成员。顺序错了读出来的数据全是乱的而且是静默错乱——CAD 不报错只是图形位置漂移。Acad::ErrorStatus TriEntity::dwgOutFields(AcDbDwgFiler* filer) const { assertWriteEnabled(); Acad::ErrorStatus es AcDbEntity::dwgOutFields(filer); if (es ! Acad::eOk) return es; // 按成员变量逐一写出顺序必须与读取一致 filer-writePoint3d(m_basePt); filer-writeDouble(m_height); return filer-filerStatus(); } Acad::ErrorStatus TriEntity::dwgInFields(AcDbDwgFiler* filer) { assertReadEnabled(); Acad::ErrorStatus es AcDbEntity::dwgInFields(filer); if (es ! Acad::eOk) return es; // 与 dwgOutFields 顺序严格一致先点后高度 m_basePt filer-readPoint3d(); m_height filer-readDouble(); return filer-filerStatus(); }assertWriteEnabled和assertReadEnabled是 ARX 的「后悔药」机制的核心——在修改或读取数据前框架会检查当前对象是否处于正确的打开状态。如果是只读打开却要写数据直接触发断言帮你提前发现问题而不是拖到保存时才炸。序列化里最容易犯的错就是在 dwgInFields 里没有先调用基类的读取逻辑导致基类数据比如图层、线型全部丢失图形变成「裸对象」。写完后一定要做一次「保存-关闭-重开」的往返测试。文件能存、能取、能重开这三个都过了序列化才算及格。4.4 注册命令把对象真正放进模型空间有了类还差一个把它塞进数据库的命令函数。这是 ARX 新手最常翻车的地方——new 出来的对象不知道加到哪里或者加了之后忘了关闭引用。下面的代码是标准动作:void makeTriCommand() { // 拿到当前数据库的块表 AcDbDatabase* db acdbHostApplicationServices()-workingDatabase(); AcDbBlockTable* pBlkTbl NULL; db-getBlockTable(pBlkTbl, AcDb::kForRead); // 定位模型空间块表记录 AcDbObjectId msId; pBlkTbl-getAt(ACDB_MODEL_SPACE, msId); pBlkTbl-close(); AcDbBlockTableRecord* pMsRec NULL; acdbOpenObject(pMsRec, msId, AcDb::kForWrite); // 创建自定义实体加到模型空间 TriEntity* pTri new TriEntity(AcGePoint3d(0, 0, 0), 10.0); AcDbObjectId triId; pMsRec-appendAcDbEntity(triId, pTri); // 关闭记录和实体——append 之后所有权归数据库 pMsRec-close(); pTri-close(); acdbHostApplicationServices()-workingDatabase()-regenerate(); }过程的每一步都有对应的资源管理责任块表以只读打开用完立刻 close模型空间记录以写打开负责接收新实体实体 new 出来先 append 进记录再 close——注意这里不是 deleteclose 会触发引用计数减一但 append 的时候加一所以对象依然存活但由数据库托管。关闭顺序必须是「先关记录再关实体」反过来会让实体在写入时找不到所属记录。regenerate()是最后一步强制全图重生成。如果不调命令执行后图形可能不显示必须手动 regen 才出来。5. 实测踩坑与排查数据丢失、白屏、崩溃的常见问题5.1 现象命令执行后屏幕上什么都没有这是第一个绕不开的坎。命令跑了加了个实体但图面上看不到任何东西。原因大概率在两个地方。第一实体坐标超出了当前视图范围——基点设成 (0,0,0) 但当前视图 zoom 到别的区域去了。第二subWorldDraw 里没有正确绘制或者返回值写成了 kFalse导致框架认为你不想画。解决办法分两步先用zoom extents看整个图面排除视图范围问题然后在 subWorldDraw 里加一个临时acutPrintf(_T(draw called))输出确认回调有没有被触发。如果回调压根没触发问题在实体的类注册和命令注册上如果触发了但看不到检查 polyline 的坐标是否确实在合理数值范围内有些坐标差极小比如 1e-6 量级会导致图形肉眼不可见。5.2 现象保存后重开实体消失了dwg 文件里明明存了东西重开就是没有。这种情况十有八九是序列化函数写漏了成员或者读写顺序不一致。我遇到过最典型的一次dwgOutFields 里先写了高度再写基点dwgInFields 里却先读基点再读高度。数值全错位但偏偏图形「看起来」正常——因为基点和高度都是 double 类型错位之后只是数值变了没有类型不匹配的报错所以排查难度极大。解决办法是强制让两个函数并排写逐行对照。我自己的习惯是先写 dwgOutFields再拷贝一份改成 dwgInFields把 write 改成 read这样顺序天然一致。5.3 现象夹点能显示但拖动后图形错乱夹点出现了说明 subGetGripPoints 返回的坐标数组是有效的。但拖动时图形变形通常是 subMoveGripPointsAt 里更新几何的逻辑不完整。比如我最初只在拖动时更新了基点坐标忘了重新计算三条边结果图形拉成一个扭曲的四边形。还有一种更隐蔽的情况夹点数组里有两个点都映射到同一个顶点拖动其中一个另一个没跟着动图形就撕裂了。解决办法是定义夹点坐标时明确「哪个夹点对应哪个参数」而不是把派生顶点直接塞进去。我的做法是index 0 对应基点index 1 对应高度——subMoveGripPointsAt 拿到 offset 偏移量后只 update 对应的参数其余几何全部由参数计算推导。这样逻辑永远是一致的。5.4 现象双击编辑或属性修改时 CAD 直接崩溃崩溃问题里很大的比例来自对象引用计数。典型场景代码里用了acdbOpenObject打开实体处理完忘了 close或者对同一个指针 close 了两次第二次是一个悬空指针操作崩溃无提示。ARX 崩溃大部分时候不弹任何对话框直接程序消失。原因是 ObjectARX 框架会在结束事务时统一检查引用计数发现不匹配就 SegFault 退出。排查这类问题没有捷径只能靠「代码审查 调试器」。我自己的习惯是写一个辅助日志函数在每次 open/close 后记录指针地址和操作崩溃后看最后几行日志基本一眼定位。另外要注意同一个实体如果在同一次事务里被 open 两次第二次的 close 才是真正释放引用计数的第一次如果也 close就会把引用多减一次同样炸。5.5 现象arx 卸载时提示「仍然有实体引用本模块」开发调试时反复加载卸载 arx某次卸载直接报错提示还有实体正在使用。原因就是图纸里已有的自定义实体还在引用你的类而你要把包含这个类的模块卸掉。解决办法不是硬卸载而是先清理图面上的图纸实体删除图中所有 TriEntity可以遍历模型空间拿 AcDbEntity 判断 isKindOf再执行卸载。另外入口点的 kUnloadAppMsg 里也要记得把命令组移除干净否则命令残留比实体引用更隐蔽。如果你实在不想删图纸内容就把卸载操作交给 CAD 自己去判断用appload里「卸载」时它其实也会先检查报错就说明有实体依赖。配合class命令查看有多少驻留实例可以辅助判断是否还有存活对象。6. 进阶用法属性面板联动与夹点自定义的收尾技巧自定义实体只做到「画出来」只是及格线。真正让人愿意用还得打通属性面板和夹点交互这两条体验链路。属性面板显示自定义数据靠的是重载subGetClassID和subGetAttributes这一组回调。ObjectARX 的机制是属性面板在渲染某个实体的属性页时会向这个实体询问「你有什么自定义字段」你再把这些字段通过描述符机制暴露出去。典型的字段就是我们的 m_height把高度暴露成可编辑项用户在属性面板改数值内部触发setHeight自动重生成图形——这比手动拖夹点精确得多尤其适合输入精确尺寸的场景。我的实际做法会在 setHeight 里加一句void TriEntity::setHeight(double h) { assertWriteEnabled(); m_height h; // 通知数据库本对象已修改触发重生成 recordGraphicsModified(); }recordGraphicsModified是 ARX 提供的「标记图形脏」接口它会告知 AutoCAD 该实体的显示缓存已失效需要重画。不加这句你改了属性面板的数值图形却纹丝不动用户会以为数据没生效。夹点自定义方面之前第五章的三角形只有两个夹点——基点和一个高度控制点。实际项目中往往需要更多中点夹点、旋转夹点、对齐夹点。subGetGripPoints返回点数组时还可以通过modes数组给每个夹点指定类型。常见的类型包括kGripPoint普通移动、kGripRotate旋转、kGripStretch拉伸不同类型的夹点光标样式不同交互语义也不同。给三角形加一个「高度中点夹点」的话只需要在 subGetGripPoints 里多 append 一个点在 subMoveGripPointsAt 里判断 indices 里含有 2 时把偏移量换算成高度的增量即可。最后提醒一点整条链路走下来最容易让人崩溃的永远不是逻辑复杂度而是你以为写完的东西其实没被调用——类没注册、命令没注册、回调没触发三者任何一个断裂代码就像黑匣子一样静默失败。我从那以后每完成一个自定义实体都会强制走一遍「新建 → 绘制 → 保存 → 重开 → 夹点拖拽 → 属性修改」这六步验证清单全部通过才敢说「这个实体做完了」。希望这篇笔记能帮你少走几趟这些弯路直接把精力花在真正值得做的几何逻辑上。本文还有配套的精品资源点击获取