---

7.3 add api

The add api functions are useful for CAD programs which want to write DWG. All the other API’s are mostly to convert from and to DWG, so the main structures and links already do exist. With the add api you can easily create an empty DWG from scratch, add table entries (into fixed Tables or variables Dictionaries), and add entities. To set more entity fields use the dynapi.

For each almost each entity and table exists a function at to add it, with arguments to initialize some fields as in the VBA object model. The other objects are either created automatically, or handled separately.

All BITCODE_T strings are encoded as UTF-8, as with the dynapi. See strings. Most names are copied, since most names are considered to be constant. If not, you need to free them by yourself. Exceptions are dxfname (there exists a separate dxfname_u variant), the VX name, which does not exists anymore since r2000.

A very simple example using the add API is the example program See dwgadd.

Function: Dwg_Data dwg_add_Document (const Dwg_Version_Type version, const int imperial, const int loglevel)) ¶

Creates an initial template dwg structure in memory, suitable to be written to a DWG or DXF file, without any additional table records or entities. Creates ModelSpace, PaperSpace and most Tables and basic Dictionaries.

When writing DWG, a version of R_2000 is recommended, only R_1_2 - R_2000 are supported yet. For DXF you can try all versions R_13 - R_2018.

For each OBJECT and ENTITY type there exists a specific dwg_add_<OBJECT> function, which takes the owner and some default arguments. Entities are normally added to a block header, like modelspace, paperspace or any block. Objects are normally added to the dwg, or to some other object or entity. E.g.

Function: Dwg_Entity_LINE *line = dwg_add_LINE (Dwg_Object_BLOCK_HEADER *modelspace, ¶

dwg_point_3d *start_pt, dwg_point_3d *end_pt)

Function: Dwg_Entity_TEXT* dwg_add_TEXT (Dwg_Object_BLOCK_HEADER *restrict blkhdr, const char* restrict text_value, const dwg_point_3d *restrict ins_pt, const double height) ¶

Adds a TEXT entity to the ModelSpace, PaperSpace or a Block. Entity specific arguments are here the text, the point (as pointer to the struct of 3 doubles), and the text height.

Function: Dwg_Object_LAYER *layer = dwg_add_LAYER (Dwg_Data *dwg, const char *name) ¶

Adds a new layer the Layer Table, i.e. creates the new LAYER object, and adds it to LAYER_CONTROL object, the list of layers.

Names and strings are encoded as UTF-8 and will be translated to type BITCODE_T (i.e. versions specific TU or TV types, either UCS-2 unicode or single-byte codepage) internally, as with the dynapi. Only internally you will have to deal with 2 different DWG text representations: UCS-2 since r2007, single-byte before. see strings.

To understand the object model for the add API see some VBA Object model documentation, such as e.g. http://entercad.ru/acadauto.en/.

The new add API mostly handles the direct Dwg_Entity_ENTITY structs, not all the generic Dwg_Object structs. Thus you can access the object specific fields directly, the common fields, not so easily.

The DWG Document consists of 3 basic entity containers ModelSpace, PaperSpace and Blocks, plus Tables (Layers, Linetypes, ...), Dictionaries as generic replacements of Tables with a root Dictionary, the NOD ("Named Object Dictionary"), and more support objects and complex entity groups.

Helper functions:

Function: dwg_add_u8_input (Dwg_Data *restrict dwg, const char *restrict u8str) ¶

Convert UTF-8 strings to BITCODE_T fields. Returns a copy of the string. All external API’s only deal with UTF-8 strings.