pcb-rnd hacking - how importers work

Introduction

This document describes the common aspects of import code, be it an import_ plugin or the load part of an io_plugin, importing a footprint, loading a board or a netlist.

Data structures

The board is stored in PCBType *. Some import code, like the one that loads a design (an io plugin's ->parse_pcb function), gets the target in an argument. (Other, non-import code usually operate on the global variable that represents the current board: PCBType *PCB.).

In either case, PCBType's most important field is PCBDataType *data, which holds lists and vectors to store all objects on the board. When the target is a buffer (e.g. io plugin's ->parse_element function), it's a DataType *buf which also have a PCBDataType *data containing the same data a board could.

A PCBDataType struct in turn has three sets of important fields:

lists for layer-independent objects (e.g. rat lines, vias, elements)
number of layers in use (LayerN) and an array of layers (see later)
rtree structures - these are used for looking up objects for locations

Each layer is a LayerType structure. A layer has the following fields:

lists for lines, texts, arcs, polygons
some generic layer attributes (colors, flags, key-value pairs)
an rtree struct for each object type.

Any code that needs to create objects should use the functions in create.[ch]. The functions that operate layer-independently usually get a destination as PCBDataType, so they can operate both on boards and buffers. A typical example is PinTypePtr CreateNewVia(DataTypePtr Data, ...) that returns NULL or the pointer to the new via that is already added to the corresponding list of Data and in the rtree.

Layer object creation is done referencing the layer as LayerType *. A typical example is LineTypePtr CreateDrawnLineOnLayer(LayerTypePtr Layer, ...) which returns NULL on error or a pointer to the new line object created (inserted in the layer's line list, added to the rtree).

Code should avoid manipulating the lists and rtree structures directly.

Figure 1. simplified map of object related data structures
diamond: variable; rectangle: struct; round: struct field

Extra steps around creating a new board

TODO: postproc, post*, other setup