GRX Cookbook 01: Implementing Custom AcDbEntity / OdDbEntity Classes with subWorldDraw & DWG Filing

1. Custom Parametric C++ Entity Architecture (`AcDbEntity`), `subWorldDraw` Viewport Caching & Binary DWG Filing

Standard DWG primitives (lines, arcs, blocks) cannot encapsulate complex domain-specific engineering behavior—such as a parametric HVAC damper that automatically adjusts its internal louvers when stretched, or a civil retaining wall that dynamically renders different detail levels depending on viewport scale. By deriving a custom C++ class from `AcDbEntity` in the GstarCAD 2027 GRX SDK and registering it with `ACRX_DXF_DEFINE_MEMBERS`, ISV developers create first-class database objects with custom binary serialization (`dwgInFields` / `dwgOutFields`) and hardware-accelerated graphics generation (`subWorldDraw`).

Critical Kernel & Memory Safety Rule: Always call `assertReadEnabled()` as the very first statement inside `subWorldDraw()` and `dwgOutFields()`, and call `assertWriteEnabled()` inside `dwgInFields()` and any setter method. Failing to invoke `assertWriteEnabled()` before mutating a member variable prevents GstarCAD's undo filer (`AcDbUndoController`) from recording the state delta—resulting in catastrophic database corruption when the user presses Ctrl+Z.

2. Verified C++17 GRX Implementation (AcDbEntity)

Compile the following native C++ source code against the GstarCAD 2027 GRX SDK using Visual Studio 2022 (Platform Toolset v143, Target Architecture x64, linking grx27.lib and gcdb27.lib) to implement GRX Cookbook 01: Implementing Custom AcDbEntity / OdDbEntity Classes with subWorldDraw & DWG Filing:

// GstarCAD 2027 GRX SDK — Custom Parametric Entity Implementation
#include "grxdefs.h"
#include "dbents.h"
#include "acgi.h"

class GcCustomPipeEntity : public AcDbEntity {
public:
    ACRX_DECLARE_MEMBERS(GcCustomPipeEntity);
    GcCustomPipeEntity() : m_radius(50.0) {}
    virtual ~GcCustomPipeEntity() {}

    virtual Adesk::Boolean subWorldDraw(AcGiWorldDraw* pWd) override {
        assertReadEnabled();
        pWd->geometry().circle(m_center, m_radius, AcGeVector3d::kZAxis);
        return Adesk::kTrue;
    }
    virtual Acad::ErrorStatus dwgInFields(AcDbDwgFiler* pFiler) override {
        assertWriteEnabled();
        AcDbEntity::dwgInFields(pFiler);
        pFiler->readPoint3d(&m_center);
        pFiler->readDouble(&m_radius);
        return pFiler->filerStatus();
    }
    virtual Acad::ErrorStatus dwgOutFields(AcDbDwgFiler* pFiler) const override {
        assertReadEnabled();
        AcDbEntity::dwgOutFields(pFiler);
        pFiler->writePoint3d(m_center);
        pFiler->writeDouble(m_radius);
        return pFiler->filerStatus();
    }
private:
    AcGePoint3d m_center;
    double      m_radius;
};

3. ObjectARX-to-GRX & .NET API Porting Matrix

When dual-targeting plugins for both AutoCAD and GstarCAD 2027 from a unified Git repository, reference the following symbol, header, and assembly mapping table:

4. Memory Management, Thread Safety & QA Checklist

• Deterministic Object Closure & Transaction Disposal: In C++ GRX, every acdbOpenObject() call that returns Acad::eOk must be paired with an explicit pObj->close() before starting a command or returning control to the editor. In C# .NET, always wrap StartTransaction() inside a using block and explicitly call tr.Commit().
• Document Locking from Modeless Contexts: Whenever modifying the active DWG database from a modeless WPF PaletteSet, WinForms dialog, or external COM event, acquire a write lock via doc.LockDocument() to prevent eLockViolation exceptions.
• Multi-Core Fiber & Main-Thread Discipline: The DWG database (`AcDbDatabase`) is not thread-safe for concurrent writes. Offload heavy geometric calculations or SQL/REST I/O to background worker threads, then marshal database mutations back to the main CAD UI thread.

Production Compilation, Packaging & Enterprise Deployment Guide

When deploying this developer recipe into commercial enterprise production, development leads should configure automated CI/CD build agents (GitHub Actions or Azure DevOps) using MSBuild command-line flags. Ensure that all dependent assemblies (such as GsMgd.dll and GsDbMgd.dll) have their reference property set to Copy Local = False (Private=False) to prevent deployment conflicts with the host GstarCAD 2027 application folder:

• Target Framework Alignment: For C# .NET plugins, target .NET Framework 4.8 or .NET 8.0 Windows Desktop runtime depending on your GstarCAD host version. For C++ GRX extensions, compile using Visual Studio 2022 (MSVC v143) with the platform toolset set to 64-bit (x64) and Character Set set to Unicode.
• Registry-Free Autoloading (.bundle): Package your compiled binary and menu CUIX files into an Autodesk/GstarCAD-compatible Application Package bundle folder (e.g., EnterprisePlugin.bundle/PackageContents.xml) and deploy directly to %APPDATA%\Autodesk\ApplicationPlugins or %PROGRAMDATA%\Gstarsoft\ApplicationPlugins for automatic silent loading without requiring administrative Windows registry rights.
• Automated Exception Trapping & Telemetry: Always wrap top-level command methods and event handlers inside structured try-catch or AutoLISP vl-catch-all-apply blocks to log diagnostic stack traces to corporate log repositories rather than letting unhandled exceptions crash the host drawing session.