gEDA Project Wiki

PCBType is the main data structure

PCBType contain all the general information used in the program and it contains a pointer to the DataType

The DataType contains the actual data that defines our printed circuit board.

DataType is what's stored in the Buffers when you do cut/paste.

The actual data is stored in the GList data elements. The rest is there for administrative purposes, to keep track of it all. Here I like to specially mention the rtree_t* data members. Although they have an administrative character the R-TREE data structure is heavily used in the PCB program.

struct GList {
  gpointer data;
  GList *next;
  GList *prev;
}; 

The GList struct is used for each element in a doubly-linked list.

Members:

gpointer ⇒

typedef void* gpointer;

An untyped pointer. gpointer looks better and is easier to use than void*.

From Wikipedia: The key idea of the r-tree data structure is to group nearby objects and represent them with their minimum bounding rectangle in the next higher level of the tree; the “R” in R-tree is for rectangle. Since all objects lie within this bounding rectangle, a query that does not intersect the bounding rectangle also cannot intersect any of the contained objects. At the leaf level, each rectangle describes a single object; at higher levels the aggregation of an increasing number of objects. This can also be seen as an increasingly coarse approximation of the data set.

A general r-tree will look like this:

The bottom row of records are called leafs.

The rtree data structure PCB uses is:

The r-tree data structure hold a copy of the where's what data. Meaning that it holds a list of every item on our canvas arranged in successively smaller boxes.

This is presently available in the home/cparker/drc_test branch. Hopefully merged in soon.

This is a type for keeping lists of things. It uses void pointers, so, you can keep lists of just about anything you want: pointers, complex data structures, whatever. A list can only hold one type of object. I implemented this, because I found myself implementing similar things over and over again for different types.

This explanation needs to be expanded on later, but, briefly, this list just keeps a big block of memory and copies data around inside it. If you hand it a data structure, it makes its own copy of that data structure. A future version might provide an option to take control of an existing structure, but, not right now.

Since a list only handles a single type of object, it can calculate where in the block of memory a given index should be. When you ask for an element, it will calculate the location of that element, and give you a pointer to it. Since it knows how many elements are in the list, when you insert at element, it can figure out how much data needs to be moved to make space for the new element.

Some objects are more complex than just a block of data. For example, an object might contain a pointer to a string. The object technically owns that string, but if you just make a copy of the object, the pointer will point to the same string. If the original object is deleted, now the list's copy will point to a string that no longer exists. To deal with this, complex objects require the definition of two functions, a clear function and a copy function.

The clear function should take care of “zeroing out” an object. If the object owns other bits of memory, the clear function should free them. It should essentially make the object blank.

The copy function should be used to copy an object's data, including data that the object owns that is stored elsewhere.

I'll eventually put some examples here, but for now, have a look at the unit tests at the end of src/object_list.c.