Index: trunk/doc/developer/data.html
===================================================================
--- trunk/doc/developer/data.html (revision 10429)
+++ trunk/doc/developer/data.html (revision 10430)
@@ -27,8 +27,8 @@
Relevant structs, variables and functions are in board.[ch].
data
-A pcb_data_t contains everything to describe a "subcircuit" related
-to an existing board:
+A pcb_data_t contains everything to describe the 2d geometry of
+an existing board:
- per-layer objects (e.g. lines, arcs, polygons)
- global objects (e.g. elements, vias)
@@ -36,11 +36,29 @@
Relevant structs, variables and functions are in data.[ch].
+
+However, it does not contain the layer stackup, but references to it.
+This means a data_t can be copied or moved from within one board to
+another, even with mismatching layer stack. When a pcb_data_t is within a
+pcb_board_t, the layer references are fixed, pointing to actual layers
+within the board's layer stack (e.g. "layer 3 in the stack"). Such a layer is
+also called a real layer. When a
+pcb_data_t is used outside of a board (e.g. as a buffer), a generalized,
+recipe-like layer description is used (e.g. "second copper layer counted
+from the top"). Such a layer is not a real layer, but can be bound
+to a real layer. The binding means that while it keeps it's recipe-like
+description, it is also referring to an actual layer of the stack of the
+current PCB structure. (This happens to subcircuits: they are specified
+with generalized, recipe-like layers that are bound to the board's layer stack
+once the subcircuit is placed on the board.)
buffers
Paste buffers are pcb_buffer_t; the main field is pcb_data_t.
Relevant structs, variables and functions are in buffer.[ch].
+
+A paste buffer doesn't have a layer stack. When data is copied from a board
+to a buffer, the layer references are generalized.
terminology: layers and layer groups
Layers are abstract canvases also serving as a logical grouping
@@ -83,11 +101,16 @@
fab - no layer struct, calculated on-the-fly from drill/hole data
+
pcb_data_t: global data
Global data affect all layers. The most trivial example is via:
-it has a hole and the same copper ring on all layers. The other global
+it has a hole and the same copper ring on all layers. Another global
object pcb_data_t holds is an element. An element can have pads
on two copper layers and pins that affect all layers the same way as vias.
+
+The third global object is subcircuit; using tis own layer list, it potentially
+can affect all layers of the board. The children objects of a subcircuit is
+a pcb_data_t, which allows arbitrary (loop-free) recursion in data.
pcb_data_t: layer-local data
The data struct has a pcb_layer_t for each logical layer, to host
Index: trunk/doc/developer/data1.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = application/octet-stream
Index: trunk/doc/developer/src/data1.dot
===================================================================
--- trunk/doc/developer/src/data1.dot (revision 10429)
+++ trunk/doc/developer/src/data1.dot (revision 10430)
@@ -17,7 +17,7 @@
pcb_buffer_t -> pcb_data_t
pcb_buffer_t [shape=box]
- DataType_lists [label="layer-independent lists:\nrats\nvias\nelements"]
+ DataType_lists [label="layer-independent lists:\nrats\nvias\nelements\nsubcircuits"]
DataType_rtrees [label="layer-independent rtrees"]
DataType_LayerN [label="LayerN: number of\nlayers in use"]
DataType_layers [label="an array of layers"]