Milton Documentation

Introduction

Milton is open-source and aims to maintain a polished, well-documented code base. Documentation for the source itself is available via Doxygen generated documentation. Thorough documentation is also available for the Milton scenefile format (which is probably a good place to start getting a high-level overview of how Milton is structured, especially if you're not interested in the source itself). In addition to the thorough API docs, we also provide a collection of introductory tutorials which walkthrough core Milton concepts in an attempt to familiarize the user with a high-level overview of an otherwise large and foreboding codebase.

Milton Tutorials

• Scenefile documentation and tutorials
• Path tracing example tutorial

Source Layout

Core Milton directory structure

Milton is logically broken up into several distinct components. The Doxygen generated documentation does a pretty good job at allowing you to traverse the source in the way it was meant to be traversed. In addition, we provide here an overview of the source layout.

At the top-level, there is exec, gui, milton, and tests, each with its own target (executable, library, etc.). Here's a descriptive breakdown of each directory and its purpose:

• milton contains all of the core framework and is probably where you'll want to start getting familiar with the code. milton's purpose is to build the core libmilton library which external programs can link against. Note, for the purposes of compiling external programs against milton, you must have the top-level milton directory in your path (with g++, you'd need to invoke something like g++ -Ipathtomilton -o myprogram main.cpp). All includes within milton are relative to the top-level directory for convenience. Also note the all-encompassing convenience header milton/milton.h, which indirectly includes all public milton headers throughout the main milton library. This header is provided such that you only have to include one file in order to use the milton library, without having to worry about including all of the different files you have to use for a particular application.
• gui contains everything you'd need to get a quick graphical application built atop the core milton library up-and-running. Specifically, it contains a multithreaded, OpenGL-capable Qt-based frontend. gui provides a hopefully easy-to-use wrapper, MiltonApp, which should be the only Gui interface that most Milton applications will need to use. gui compiles another library, libgui, which external applications may link against. Note that MiltonApp doesn't have to be graphical; it naturally supports a nox (aka non-graphical or no X-server) mode as well for rendering in batch or remotely over a network (where the execution environment might not be graphics-friendly). See MiltonApp or one of the applications in exec or tests which use MiltonApp for more details.
• exec contains the main executable that's packaged with Milton that'll work out-of-the box on supported platforms. exec compiles to an executable named milton; run milton --help from within exec for more details on how to invoke milton. exec also contains a plethora of built-in resources for scenefiles, including testing scenefiles that we've used during the development of Milton, as well as a small repository of various textures and meshes. Note that exec/main.cpp uses MiltonApp to parse commandline parameters and get a default Gui up-and-running. Also note that the Makefile in exec links against libgui and libmilton.
• tests contains a hodgepodge of tests aimed at ensuring the stability and accuracy of the core milton library. Note that tests also contains several fun, educational "applets" which specialize the notion of a Visualization to use Milton more as a framework and less as a standalone program. Examples include an OpenGL visualizer for the distributions of various built-in BSDFs and a visualizer for paths generated with the built-in BidirectionalPathTracer. Note that many of these test cases utilize MiltonApp (and thus both libgui and libmilton) as their main interface to Milton.

Within the core milton directory, the framework is broken down logically into subdirectories, accel, cameras, common, etc, some of which contain their own subdirectories (ex, common/math/simd). Milton uses several third-party libraries (located in milton/third-party), namely:

Qt	a cross-platform Gui and generic toolkit framework
boost	a set of advanced, portable C++ libraries (Milton makes heavy use of boost::any in particular)
tinyjson*	a minimalistic JSON parser based on boost.spirit
libobj*	a modern C++ library for parsing the Wavefront OBJ file format (by Ares Lagae)
libobj*	a modern C++ library for parsing the PLY file format (by Ares Lagae)

Note: libraries denotd with a * are included in the standard Milton subversion (svn) repository. Qt and boost are not included due to their size.