HACKING

   1 ======= CODING STANDARD FOR GERBV =======
   2
   3 $Id$
   4
   5
   6 Indentation
   7 -----------
   8 To hack in this code you need to set emacs (or whatever you use) to
   9 4 indentation steps and {} at the right places (see code).
  10 Not negotiable.
  11
  12 My ~/.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
  20 Curly Braces
  21 ------------
  22
  23 if () {
  24     blah1();
  25     blah2();
  26 } else {
  27     yada1();
  28     yada2();
  29 }
  30 If there is only one statement you don't need the braces.
  31
  32 for() {
  33     do_whatever1();
  34     do_whatever2();
  35 }
  36
  37 switch() {
  38 case foo:
  39     blah1();
  40     break;
  41 case bar:
  42     blah2();
  43     break;
  44 default:
  45     break;
  46 }
  47 Switch should always have a default case.
  48
  49
  50 ChangeLog
  51 ---------
  52 Minor changes (cosmetic, minor (up to 4,5 lines) not reported bugs)
  53 doesn't need a ChangeLog entry. A ChangeLog entry is needed when a
  54 reported bug is fixed (with bug report number) or when a feature is
  55 added. I (spe) use ChangeLog when writing release notes.
  56
  57
  58 Functions
  59 ---------
  60 The prototype should have return type on the same line as function name:
  61 int some_function(int par1, int par2);
  62
  63 The function implementation should have return type on a separate line
  64 (including eventual pointer star). The function implementation should
  65 have the function name in c-comments
  66 at the closing brace.
  67 int *
  68 some_function(int par1, int par2)
  69 {
  70     /* Implementation */
  71 } /* some_function */
  72
  73 In a function there should be maximum one empty line in a row.
  74 Between functions there should be two empty lines.
  75
  76
  77 ======= GERBV'S INTERNAL WORKINGS =======
  78
  79 Here are some rough notes about how gerbv works.  These notes were
  80 taken during the development of version 1.1.0, so things may have
  81 changed since then.  The idea behind these notes is to help new
  82 developers understand the program flow.  Please add/modify these
  83 notes as you work on gerbv and come to understand its workings.
  84
  85 ----------------------------------------------------------------
  86 Important datastructures (this list is not complete, but rather
  87 tries to touch upon the high points of the datastructures used):
  88
  89 screen -- 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
 131 gerb_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 ----------------------------------------------------------------
 138 Important files:
 139
 140 Here's a summary of gerbv's file hierarchy, from top to bottom:
 141
 142 1. gerbv.c -- holds main() and other top level fcns.
 143
 144 2. callbacks.[hc], interface.[hc] -- Hold GUI widgets (interface) and
 145    callbacks (callbacks).
 146
 147 3. 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
 153 4. 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
 157 Then 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 ----------------------------------------------------------------
 169 Important functions
 170
 171 gerber.c:parse_gerb:  Parses gerber, returns gerb_image.
 172
 173 gerbv.c:redraw_pixmap is the thing which actually
 174 draws the Gerber files on the
 175 screen.  It is called by several callbacks to draw the screen.  It takes a
 176 pointer to the screen widget (screen.drawing_area)
 177
 178 image2pixmap (gdk) or render_image_to_cairo_target (cairo)
 179 is the thing which actually does the drawing onto the drawing
 180 area.
 181
 182
 183 ----------------------------------------------------------------
 184 Use cases:
 185
 186 ====
 187 gerbv starts.  Global variable screen is declared.
 188  main() called.   Sets up screen.  Handles command line flags.
 189 Inits GTK, then goes into GTK event loop.
 190
 191 User does "file -> open Gerber(s)".  Callback XXXX is called.  It
 192 calls open_image to open the Gerber file.  Then redraw_pixmap is called
 193 to redraw the screen for the user.
 194
 195 open_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
 204 parse_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
 220 parse_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
 226 redraw_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