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