About Eagle3D
=============

Eagle3D is an application to create raytraced visualizations of PCB
layouts created by Eagle. You can get a free version of Eagle from
www.cadsoft.de

This package is independent from cadsoft.

How to build Eagle3D
====================

There are a couple of scripts in the tools directory. Just cd into
that directory and run the create_eagle_3d.sh shell script and you
should end up with three archives (.tar.gz, .tar.bz2, .zip).

To get the big overview png with all the macros call the render.sh
script in the tools/ directory.

You can also use make. The following make targets are available:

$ make all
    Creates all Eagle3D release archives

$ make lib
    Creates only the lib (.inc files)

$ make render
    Renders all the macros as small images and creates a big image
    with combines all of the macros into on big image. This step will
    need quite some time to finish. Creating the final output image
    needs also a lot of RAM. 2GiB is not enough in default settings
    so expect some swapping if you have less then 4GiB installed.

$make clean
    Removes all the created files. A clean source tree should be left.

Extending Eagle3D?
==================

There are not much rules when adding code to the ULP or the POVRay
macros. But please don't use tabs for indention and use four spaces
for indention. If you find parts of the code where these rules are
violated please fix it and send a patch.

There are some more rules regarding macro naming and usage of POVRay statements:

- A base macro always starts with the prefix of the inc file and ends in _GRND.
  So, a new macro in the ic.inc file would be name IC_MY_IC_PACKAGE_GRND. The
  resulting calls of this macros are then called IC_MY_IC_PACKAGE_*.
- The name of the source file is always the name of the base macro extended by
  a .inc.src
- Do not use the #declare statement in your macros as these add identifiers to
  the global scope of POVRay which may collide with other macros. Please use
  #local instead.
- Do not add anything besides your copyright to the pre.pre and pos.pos files
  in the source directories. Currently all things which you would like to be
  some sort of global definition should stay inside a single macro. We will 
  have a global file for such things in the future (see TODO)

Each .inc.src file in the src/inc/$LIBNAME directory stands for a single
macro. The file format is very simple. Each part of the file is separated from
the others by a line of '#'. The contents of each part are as follows:

<<<<
Part name (Currently ignored, only one line)
//Comments inserted before the macro (always prefixed by "//")
################################################################
Lines for the 3dpack.dat
################################################################
Main macro name (without parameter list, see naming conventions above)
Main macro parameter list
################################################################
//Comment for the sub macro (optional)
Sub macro name(parameter list)
Parameter list for main macro
################################################################
################################################################
Actual macro
>>>>

After adding your macro you can call tools/render.sh after building Eagle3D to
test the successfull integration. The scripts takes an additional parameter so 
that you can only render some of the macros.

$ render.sh IC_SMD_* 

This will result in only rendering macros which start with IC_SMD_.