Milton Scenefile Documentation
Introduction
Milton scenefiles are specified in the JSON (json.org) file format. Documentation for the format itself is available via auto-generated documentation. In addition to the thorough element-by-element docs, we also provide an introductory tutorial which walks through core concepts in an attempt to familiarize the user with a high-level overview of everything.
Here is a concise, valid scenefile that should give you a pretty good overview of what's going on:
Example scenefile:
At the top-level is the scenefile element, which every valid scene file must contain. The scenefile element may contain several main child elements (renderer, camera, output, and scene), all of which are optional except for the required scene element. The scene element contains all of the geometry and materials comprising the given scene (shape and material elements respectively).
Scenefile Tutorials
Scenefile Design
Many classes in Milton are customizable via a number of input parameters, and it would both be awkward and decrease readability to have those classes take in all possible combinations of inputs as parameters either via constructors or accessors / mutators. We chose to instead parameterize these classes at run-time via a common base class called a PropertyMap, which represents a key-value mapping between std::string keys and a set of well- defined primitive variant-value types (int, double, string, etc.). By taking advantage of boost::any, a template variant holder utility class provided by the boost library, all code dealing with parameters became both more extensible and more readable at the expense of static type-checking in several places. This allows parameters for most core Milton classes to be specified via the commandline or more commonly in the scenefiles themselves, and loose type-checking is instead done at run-time during scenefile parsing. This setup allows for a lot of flexibility, both within Milton and in terms of allowing external extensions. One could, for example, use the same built-in loading code and scenefile format but add his/her own BSDF type with its own arbitrary key-value inputs, and as long as the value-types in question are supported variants, without having to change anything within the Milton library itself.
Closely related to the loose nature of PropertyMaps is the Milton scenefile format. In order to fulfill our goals of having scenefiles that were going to be both concise, well-defined, and highly extensible via arbitrary key- value pairs, we ended up defining an implementation-independent context free grammar to capture the structure and types that would be used in Milton scenefiles as well as a concrete implementation of that grammar via the popular JSON format. Many aspects of the scenefile, including the camera, output, and renderer are all optional, and in the case that they aren't provided, reasonable defaults will be used. What's great about JSON is that its own design (and Javascript in general) was guided by the recursive definition of objects as lists of key-value pairs similar in spirit to our extensible PropertyMap paradigm.
Generated on 28 Feb 2009 for MiltonScenefileFormat by
1.5.6