1=======	CODING STANDARD FOR GERBV =======
2
3$Id$
4
5
6Indentation
7-----------
8To hack in this code you need to set emacs (or whatever you use) to
94 indentation steps and {} at the right places (see code).
10Not negotiable.
11
12My ~/.emacs are:
13(defun my-c-mode-hook ()
14  (turn-on-font-lock)
15  (setq c-basic-offset 4))
16
17(add-hook 'c-mode-hook 'my-c-mode-hook)
18
19
20Curly Braces
21------------
22
23if () {
24    blah1();
25    blah2();
26} else {
27    yada1();
28    yada2();
29}
30If there is only one statement you don't need the braces.
31
32for() {
33    do_whatever1();
34    do_whatever2();
35}
36
37switch() {
38case foo:
39    blah1();
40    break;
41case bar:
42    blah2();
43    break;
44default:
45    break;
46}
47Switch should always have a default case.
48
49
50ChangeLog
51---------
52Minor changes (cosmetic, minor (up to 4,5 lines) not reported bugs)
53doesn't need a ChangeLog entry. A ChangeLog entry is needed when a
54reported bug is fixed (with bug report number) or when a feature is
55added. I (spe) use ChangeLog when writing release notes.
56
57
58Functions
59---------
60The prototype should have return type on the same line as function name:
61int some_function(int par1, int par2);
62
63The function implementation should have return type on a separate line
64(including eventual pointer star). The function implementation should
65have the function name in c-comments
66at the closing brace.
67int *
68some_function(int par1, int par2)
69{
70    /* Implementation */
71} /* some_function */
72
73In a function there should be maximum one empty line in a row.
74Between functions there should be two empty lines.
75
76
77======= GERBV'S INTERNAL WORKINGS =======
78
79Here are some rough notes about how gerbv works.  These notes were
80taken during the development of version 1.1.0, so things may have
81changed since then.  The idea behind these notes is to help new
82developers understand the program flow.  Please add/modify these
83notes as you work on gerbv and come to understand its workings.
84
85----------------------------------------------------------------
86Important datastructures (this list is not complete, but rather
87tries to touch upon the high points of the datastructures used):
88
89screen -- top level struct of info about all Gerber images superimposed.
90  Global variable.  Individual Gerber images(layers) are accessed as
91  screen.file[i]->image.  This is a global variable, invoked by
92  "extern gerbv_screen_t screen" in every fcn which uses it.
93  Defined in gerbv_screen.h.
94
95  Selected members:
96  screen->drawing_area -- This is the window showing the layers (Gerbers)
97  screen->pixmap
98  screen->win -- various windows presented to the user.
99  screen->state
100  screen->file[idx] -- This holds info relating to the input
101                       layer (Gerber) files.  Defined
102                       as gerbv_fileinfo_t in gerbv_screen.h
103
104  screen->file[idx]->color
105  screen->file[idx]->name
106  screen->file[idx]->isVisible
107  screen->file[idx]->gerber_stats -- struct hold info about codes
108                                     encountered while reading gerber files.
109  screen->file[idx]->drill_stats -- struct hold info about codes
110                                     encountered while reading drill files.
111
112  screen->file[idx]->image -- Holds a parsed representation
113                     of each Gerber file in the project.  The data
114                     held in this struct is used in the drawing
115                     programs (image2pixmap) to draw the screen.
116                     Each layer lives on a separate index (idx).
117                     defined as gerb_image_t in gerb_image.h
118
119  screen->file[idx]->image->aperture -- Holds aperture info pertaining
120                                        to this Gerber layer.
121					Defined as gerb_aperture_t
122					in gerb_image.h
123  screen->file[idx]->image->format
124  screen->file[idx]->image->netlist -- This holds info relating
125                                       to the elements in the
126                                       layer (Gerber) files.
127                                       Defined as gerb_net_t
128				       in gerb_image.h
129
130
131gerb_state_t -- This variable keeps track of the state of the
132  CAM job as the Gerber file is parsed.  It is updated with
133  each code read in, and is also used duing parsing to hold
134  state information which can be modified by the incoming codes.
135  Its use is local to gerber.c
136
137----------------------------------------------------------------
138Important files:
139
140Here's a summary of gerbv's file hierarchy, from top to bottom:
141
1421. gerbv.c -- holds main() and other top level fcns.
143
1442. callbacks.[hc], interface.[hc] -- Hold GUI widgets (interface) and
145   callbacks (callbacks).
146
1473. render.[hc] -- holds the top-level rendering stuff with lots of looping
148   code, like redraw_pixmap,  image2pixmap, and
149   render_image_to_cairo_target.  This is the place that other,
150   non-GUI exporters should get called from (export_png, export_pdf,
151   etc).
152
1534. draw.[hc], draw-gdk.[hc] -- these hold the low level utilities
154   which draw objects onto screen.drawing_area.  Each is specific to
155   the corresponding rendering engine.
156
157Then on the side we have:
158
159*  gerb_file.[hc]. gerb_image.[hc], etc -- functions related to dealing
160   with the important structs in the program.  This can be expanded as we
161   include gerb_stats.[hc] etc.
162
163*  gerber.[hc]  drill.[hc]  pick_and_place.[hc]  -- files holding the
164   stuff which parses and processes the respective types of CAM files.
165
166*  Many others to be documented......
167
168----------------------------------------------------------------
169Important functions
170
171gerber.c:parse_gerb:  Parses gerber, returns gerb_image.
172
173gerbv.c:redraw_pixmap is the thing which actually
174draws the Gerber files on the
175screen.  It is called by several callbacks to draw the screen.  It takes a
176pointer to the screen widget (screen.drawing_area)
177
178image2pixmap (gdk) or render_image_to_cairo_target (cairo)
179is the thing which actually does the drawing onto the drawing
180area.
181
182
183----------------------------------------------------------------
184Use cases:
185
186====
187gerbv starts.  Global variable screen is declared.
188 main() called.   Sets up screen.  Handles command line flags.
189Inits GTK, then goes into GTK event loop.
190
191User does "file -> open Gerber(s)".  Callback XXXX is called.  It
192calls open_image to open the Gerber file.  Then redraw_pixmap is called
193to redraw the screen for the user.
194
195open_image does this:
196  1.  Calls gerb_fopen, which returns a file descriptor
197  2.  Calls parse_gerb, which returns a gerb_image_t*.
198  3.  Attaches new image to screen.file[idx]->image.
199  4.  Stores the filename in screen.file[idx]->name
200  5.  Sets the basename for the file.
201  6.  Sets the colors for the image.
202  7.  Return -1 upon error or 0 upon success.
203
204parse_gerb does this:
205  0.  Mallocs and creates a new state (gerb_state_t).  State is local
206      to parse_gerb.
207  1.  Creates a new gerb image (gerb_image_t) using new_gerb_image
208  2.  Attaches new netlist using curr_net = image->netlist;
209  3.  Reads chars from the opened Gerber file, and does a dispatch
210      based upon which char is found.  Example: for a G code,
211      parse_G_code is called.
212  4.  If the found char is a *, then wrap up processing for this
213      code by:
214      1.  Malloc memory for a new net element in the curr_net list.
215      2.  Update state and image members depending upon what this
216          code has been.
217  5.  Loop to next code.
218  6.  Returns built up gerb image (gerb_image_t *)
219
220parse_G_code (and parse_<*>_code) does this:
221  1.  Calls gerb_fgetint to get the number of the code, then does
222      a dispatch depending upon which number is found.
223  2.  Depending upon the code (number), state-> is modified.
224  3.  Return void.
225
226redraw_pixmap does this:
227  1.  Set up global drawing parameters
228  2.  Creates a new screen.pixmap
229  3.  Loops over visible files (images) in state.file_index list
230  4.  Calls image2pixmap (gdk) or render_image_to_cairo_target (cairo)
231      on each image.
232  5.  Redraws the top level window.
233  6.  Returns TRUE or FALSE to control idle function (???)
234
235
236