# HG changeset patch
# User Radek Brich <radek.brich@devl.cz>
# Date 1210231285 -7200
# Node ID 4c8abb8977dc2249fc50e225849e0a018de3fade
# Parent  96d65f841791faf0d11d6f9f231c7cc7d51d40e8
update README
update Doxygen docs
scons option 'msvc' changed to 'mingw' as msvc is default
  and mingw must be turned on explicitly

diff -r 96d65f841791 -r 4c8abb8977dc DEVNOTES
--- a/DEVNOTES	Tue May 06 09:39:58 2008 +0200
+++ b/DEVNOTES	Thu May 08 09:21:25 2008 +0200
@@ -24,3 +24,23 @@
 -------------
 Sampler - generate points in screen plane
 Camera - transform point from sampler to a ray
+
+New Classes?
+------------
+
+scene.h   -- Scene, ...
+reader.h  -- Reader, WavefrontReader
+
+wf = new WavefrontReader()
+wf.setContainer(top)
+wf.setTransform(monkey_pos_matrix)
+wf.read("monkey.obj")
+// more transform&reads
+destroy wf
+
+Scene scene -- container with shapes, a camera and lights
+scene = new Scene()
+scene.setCamera(new Camera(eye, u, v, p))
+scene.addLight(new PointLight(pos, color))
+rt.setScene(scene)
+rt.render(w,h)
diff -r 96d65f841791 -r 4c8abb8977dc Doxyfile
--- a/Doxyfile	Tue May 06 09:39:58 2008 +0200
+++ b/Doxyfile	Thu May 08 09:21:25 2008 +0200
@@ -25,7 +25,7 @@
 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded 
 # by quotes) that should identify the project.
 
-PROJECT_NAME           = Pyrit Ray Tracer
+PROJECT_NAME           = Pyrit
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. 
 # This could be handy for archiving the generated documentation or 
@@ -239,7 +239,7 @@
 # member in the group (if any) for the other members of the group. By default 
 # all members of a group must be documented explicitly.
 
-DISTRIBUTE_GROUP_DOC   = NO
+DISTRIBUTE_GROUP_DOC   = YES
 
 # Set the SUBGROUPING tag to YES (the default) to allow class member groups of 
 # the same type (for instance a group of public functions) to be put as a 
@@ -542,7 +542,7 @@
 # excluded from the INPUT source files. This way you can easily exclude a 
 # subdirectory from a directory tree whose root is specified with the INPUT tag.
 
-EXCLUDE                = 
+EXCLUDE                = include/config.h src/raytracermodule.cc
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or 
 # directories that are symbolic links (a Unix filesystem feature) are excluded 
diff -r 96d65f841791 -r 4c8abb8977dc README
--- a/README	Tue May 06 09:39:58 2008 +0200
+++ b/README	Thu May 08 09:21:25 2008 +0200
@@ -5,39 +5,52 @@
 
 File Organization
 -----------------
-/bin      -- output directory for binary objects
+/build    -- output directory for binaries and other generated files
 /ccdemos  -- ray tracer demos in C++
 /demos    -- ray tracer demos in Python
 /include  -- header files
 /models   -- common models for use by demos
 /src      -- ray tracing library source code
 /tests    -- test programs for classes
+/tools    -- auxiliary programs
 
 Classes organization throughout header files is explained in DEVNOTES.
 
 
 Building
 --------
-Type 'scons all' to build everything and 'scons -h' for list of targets.
+Type 'scons pyrit' to build and 'scons -h' for list of targets.
 
 Requirements:
     SCons
     pthreads (see bellow)
+    libpng, zlib
     Python 2.4 or newer for Python module and demos
-    PIL (Python Imaging Library) for Python demos
     SDL for interactive C++ demos
-    libpng and zlib for rendering to PNG file from C++ demos
+
+It should build with these compilers: GCC, IntelC, MSVC
+GCC is default in Linux, MSVC is default in Windows.
+
+
+Downloading model files
+-----------------------
+Not all models are included in distribution. To download the large
+Stanford models, type 'scons download-models', which will download
+end extract the archives to appropriate location.
+
+The download script uses 'tar' and 'wget' utilities.
+
+For Windows, these are available here:
+http://gnuwin32.sourceforge.net/packages/wget.htm
+http://gnuwin32.sourceforge.net/packages/libarchive.htm
 
 
 Pthreads
 --------
-Threads can be used to render rows of picture paralelly. Arbitrary number
-of threads can be used, even numbers like 17 are acceptable.
+Threads can be used to render rays paralelly. Arbitrary number
+of threads can be used.
 
-To completely disable this feature just remove "-DPTHREADS -pthreads"
-from flags in makefile.
-
-For Windows + Mingw32, get pthreads library here:
+For Windows, get pthreads library here:
 http://sources.redhat.com/pthreads-win32/
 
 
diff -r 96d65f841791 -r 4c8abb8977dc SConstruct
--- a/SConstruct	Tue May 06 09:39:58 2008 +0200
+++ b/SConstruct	Thu May 08 09:21:25 2008 +0200
@@ -54,13 +54,13 @@
 )
 if env['PLATFORM'] == 'win32':
 	opt.AddOptions(
-		BoolOption('msvc', 'use Microsoft Visual C++ Compiler, if available', True),
+		BoolOption('mingw', 'use Mingw and GCC compiler, if available', False),
 		('pythonpath', 'path to Python installation',
 			'C:\\Python%c%c' % (sys.version[0], sys.version[2])),
 	)
 else:
 	opt.AddOptions(
-		BoolOption('intelc', 'use Intel C++ Compiler, if available', True),
+		BoolOption('intelc', 'use Intel C++ Compiler, if available', False),
 	)
 
 
@@ -155,7 +155,7 @@
 if intelc and (not gcc or conf.env['intelc']):
 	Tool('intelc').generate(conf.env)
 	cc = 'intelc'
-elif msvc and (not gcc or conf.env['msvc']):
+elif msvc and (not gcc or not conf.env['mingw']):
 	Tool('default').generate(conf.env)
 	conf.Define("MSVC")
 	cc = 'msvc'
diff -r 96d65f841791 -r 4c8abb8977dc TODO
--- a/TODO	Tue May 06 09:39:58 2008 +0200
+++ b/TODO	Thu May 08 09:21:25 2008 +0200
@@ -1,6 +1,6 @@
 Bugs
 ====
- * (none known)
+ * Mingw + SSE does not work
 
 Future Plans
 ============
@@ -11,24 +11,3 @@
  * put everything into a namespace
  * stochastic oversampling
  * absorbtion of refracted rays in dense materials (can be computed using shape distance and some 'absorbance' constant)
- * implement efficient AABB-ray intersection using Plucker coordinates
-
-New Classes?
-============
-
-scene.h   -- Scene, ...
-reader.h  -- Reader, WavefrontReader
-
-wf = new WavefrontReader()
-wf.setContainer(top)
-wf.setTransform(monkey_pos_matrix)
-wf.read("monkey.obj")
-// more transform&reads
-destroy wf
-
-Scene scene -- container with shapes, a camera and lights
-scene = new Scene()
-scene.setCamera(new Camera(eye, u, v, p))
-scene.addLight(new PointLight(pos, color))
-rt.setScene(scene)
-rt.render(w,h)
diff -r 96d65f841791 -r 4c8abb8977dc include/common.h
--- a/include/common.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/common.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * common.h: common functions and definitions
+/**
+ * @file  common.h
+ * @brief Common functions and definitions
  *
  * This file is part of Pyrit Ray Tracer.
  *
diff -r 96d65f841791 -r 4c8abb8977dc include/container.h
--- a/include/container.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/container.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * container.h: Container class
+/**
+ * @file  container.h
+ * @brief Spatial container for shapes
  *
  * This file is part of Pyrit Ray Tracer.
  *
diff -r 96d65f841791 -r 4c8abb8977dc include/kdtree.h
--- a/include/kdtree.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/kdtree.h	Thu May 08 09:21:25 2008 +0200
@@ -1,9 +1,10 @@
-/*
- * kdtree.h: KdTree class
+/**
+ * @file  kdtree.h
+ * @brief KdTree class
  *
  * This file is part of Pyrit Ray Tracer.
  *
- * Copyright 2006, 2007  Radek Brich
+ * Copyright 2006, 2007, 2008  Radek Brich
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
diff -r 96d65f841791 -r 4c8abb8977dc include/material.h
--- a/include/material.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/material.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * material.h: material and texture classes
+/**
+ * @file  material.h
+ * @brief Material and Texture classes
  *
  * This file is part of Pyrit Ray Tracer.
  *
diff -r 96d65f841791 -r 4c8abb8977dc include/matrix.h
--- a/include/matrix.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/matrix.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * matrix.h: Matrix class, currently not used
+/**
+ * @file  matrix.h
+ * @brief Matrix class, currently not used
  *
  * This file is part of Pyrit Ray Tracer.
  *
diff -r 96d65f841791 -r 4c8abb8977dc include/mempool.h
--- a/include/mempool.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/mempool.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * mempool.h: memory pool
+/**
+ * @file  mempool.h
+ * @brief Memory pool for aligned allocation
  *
  * This file is part of Pyrit Ray Tracer.
  *
@@ -29,6 +30,9 @@
 
 #include "common.h"
 
+/**
+ * Memory pool template
+ */
 template <typename Type>
 class MemoryPool
 {
@@ -45,8 +49,18 @@
 #endif
 	};
 public:
+	/**
+	 * Construct memory pool with default alignment (16)
+	 * @see MemoryPool(size_t, size_t)
+	 */
 	MemoryPool(const size_t inisize):
 		cur(0), size(inisize), align(16) { init(); };
+
+	/**
+	 * Construct memory pool
+	 * @param[in] inisize  Initial capacity in Type count
+	 * @param[in] inialign Set memory alignement of items
+	 */
 	MemoryPool(const size_t inisize, const size_t inialign):
 		cur(0), size(inisize), align(inialign) { init(); };
 	~MemoryPool()
@@ -58,6 +72,10 @@
 #endif
 	};
 
+	/**
+	 * Allocate memory for one item of type Type
+	 * @return Pointer to allocated memory
+	 */
 	void *alloc()
 	{
 		if (cur == size)
diff -r 96d65f841791 -r 4c8abb8977dc include/octree.h
--- a/include/octree.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/octree.h	Thu May 08 09:21:25 2008 +0200
@@ -1,9 +1,10 @@
-/*
- * octree.h: Octree class
+/**
+ * @file  octree.h
+ * @brief Octree class
  *
  * This file is part of Pyrit Ray Tracer.
  *
- * Copyright 2007  Radek Brich
+ * Copyright 2007, 2008  Radek Brich
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
diff -r 96d65f841791 -r 4c8abb8977dc include/pixmap.h
--- a/include/pixmap.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/pixmap.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * pixmap.h: 2D image class
+/**
+ * @file pixmap.h
+ * @brief Pixmap class with PNG file format writer
  *
  * This file is part of Pyrit Ray Tracer.
  *
diff -r 96d65f841791 -r 4c8abb8977dc include/quaternion.h
--- a/include/quaternion.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/quaternion.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * quaternion.h: Quaternion class
+/**
+ * @file  quaternion.h
+ * @brief Quaternion class
  *
  * This file is part of Pyrit Ray Tracer.
  *
@@ -28,7 +29,7 @@
 #define QUATER_H
 
 /**
- * helper quaternion class
+ * quaternion class
  */
 class Quaternion
 {
diff -r 96d65f841791 -r 4c8abb8977dc include/raytracer.h
--- a/include/raytracer.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/raytracer.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * raytracer.h: Raytracer class
+/**
+ * @file  raytracer.h
+ * @brief The base class of the ray tracer
  *
  * This file is part of Pyrit Ray Tracer.
  *
@@ -71,7 +72,7 @@
 	static void *raytrace_worker(void *d);
 public:
 	Raytracer(): top(NULL), camera(NULL), lights(), bg_colour(0., 0., 0.),
-		ao_samples(0), num_threads(2), max_depth(3), use_packets(true)
+		ao_samples(0), num_threads(4), max_depth(3), use_packets(true)
 	{
 		pthread_mutex_init(&sample_queue_mutex, NULL);
 		pthread_mutex_init(&sampler_mutex, NULL);
diff -r 96d65f841791 -r 4c8abb8977dc include/sampler.h
--- a/include/sampler.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/sampler.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * sampler.h: screen sample generation and image reconstruction
+/**
+ * @file  sampler.h
+ * @brief Screen sample generation and image reconstruction
  *
  * This file is part of Pyrit Ray Tracer.
  *
@@ -34,70 +35,151 @@
 using namespace std;
 
 /**
- * sample
+ * A structure containing sample's coordinates.
  */
 class Sample
 {
-	friend class Sampler;
 public:
+	//@{
+	/**
+	 * Generated coordinates.
+	 *
+	 * These are coordinates for use by Camera.
+	 * Middle of the screen plane has [0,0],
+	 * top of the screen has y=-0.5, left pixels has x<0
+	 * and the rest of samples are aligned to regular grid,
+	 * so the vertical size is always one and horizontal size
+	 * can be wider depending on aspect ratio.
+	 */
 	Float x,y;
+	//@}
+
+	//@{
+	/**
+	 * Auxiliary coordinates used internally by sampler.
+	 *
+	 * Screen coordinates sx, sy are integer coordinates of screen pixels,
+	 * osa_samp is used by oversampling to remember current sample.
+	 */
 	int sx,sy,osa_samp;
+	//@}
 };
 
 /**
  * A abstract sampler.
- * It generates screen samples in coordinates between [-1..1] for height
- * and [-w/h..w/h] for width. It works in phases: initSampleSet returns
+ *
+ * It generates screen samples in coordinates between [-0.5..0.5] for height
+ * and [-w/h/2..w/h/2] for width. It works in phases: initSampleSet returns
  * number of samples for each phase, then samples can be generated using
  * nextSample method. The resulting colour of each sample should be returned
  * via saveSample method. The sampler should save the results to given buffer
- * and decide if other phase is needed. When the picture is complete,
+ * and decide if another phase is needed. When the picture is complete,
  * initSampleSet returns zero and picture can be read from buffer.
  */
 class Sampler
 {
 protected:
-	Pixmap pixmap;
-	bool packetable;
+	Pixmap pixmap;    ///< A pixmap for resulting image.
+	bool packetable;  ///< True if the generated samples are usable with ray packets.
 public:
+	/** Constructor with user provided image buffer. */
 	Sampler(Float *buffer, const int &w, const int &h):
 		pixmap(buffer, w, h), packetable(false) {};
+
+	/** With this constructor, image buffer is allocated as specified by w,h. */
 	Sampler(const int &w, const int &h):
 		pixmap(w, h), packetable(false) {};
+
 	virtual ~Sampler() {};
+
+	/** Switch to new user provided buffer. */
 	void resetBuffer(Float *buffer, int &w, int &h)
 		{ pixmap.setData(buffer, w, h); };
+
+	/**
+	 * Initialize the sampler.
+	 *
+	 * This must be called first when starting new image.
+	 */
 	virtual void init() = 0;
+
+	/**
+	 * Prepare for next phase.
+	 *
+	 * Must be called before reading samples.
+	 * @retval N approximate number of samples to be generated in the phase
+	 * @retval 0 last phase, image is complete
+	 */
 	virtual int initSampleSet() = 0;
+
+	/**
+	 * Generate next sample.
+	 *
+	 * @param[out] s  The sample.
+	 * @retval false  No more samples in this phase.
+	 */
 	virtual bool nextSample(Sample *s) = 0;
-	virtual void saveSample(Sample &samp, Colour &col) = 0;
+
+	/**
+	 * Save the color of the sample.
+	 *
+	 * @param[in] samp  A sample.
+	 * @param[in] col   Color resulted from ray tracing the sample.
+	 */
+	virtual void saveSample(const Sample &samp, const Colour &col) = 0;
+
+	/** True if generated samples are usable with ray packets. */
 	bool packetableSamples() { return packetable; };
+
+	/** Get the pixmap. */
 	const Pixmap &getPixmap() const { return pixmap; };
 };
 
 /**
  * Default sampler.
+ *
  * Implements basic adaptive subsampling and oversampling.
  */
 class DefaultSampler: public Sampler
 {
-	int phase;
-	int subsample;  // 0,1 = no, 1+ = size of sampling grid
-	int oversample; // 0 = no, 1 = 4x, 2 = 9x, 3 = 16x
-	int sx,sy,osa_samp; // current sample properties
+	int phase;      ///< Current phase
+	int subsample;  ///< Subsampling mode
+	int oversample; ///< Oversampling mode
+	//@{
+	/** Properties of last generated sample. */
+	int sx,sy,osa_samp;
+	//@}
 public:
+	/** Constructor with user provided image buffer. */
 	DefaultSampler(Float *buffer, const int &w, const int &h):
 		Sampler(buffer, w, h), phase(-1), subsample(0), oversample(0) {};
+
+	/** With this constructor, image buffer is allocated as specified by w,h. */
 	DefaultSampler(const int &w, const int &h):
 		Sampler(w, h), phase(-1), subsample(0), oversample(0) {};
+
+	/* Implement virtuals from Sampler. */
 	void init();
 	int initSampleSet();
 	bool nextSample(Sample *s);
-	void saveSample(Sample &samp, Colour &col);
+	void saveSample(const Sample &samp, const Colour &col);
 
+	/**
+	  * Set subsampling mode.
+	  *
+	  * @param[in] sub  0,1 = no, 1+ = size of sampling grid
+	  */
 	void setSubsample(int sub) { subsample = sub; };
+	/** Get subsampling mode. @see setSubsample */
 	int getSubsample() { return subsample; };
+
+	/**
+	  * Set oversampling mode.
+	  *
+	  * @param[in] osa  0 = no, 1 = 4x, 2 = 9x, 3 = 16x
+	  */
 	void setOversample(int osa) { oversample = osa; };
+	/** Get oversampling mode. @see setOversample */
 	int getOversample() { return oversample; };
 };
 
diff -r 96d65f841791 -r 4c8abb8977dc include/scene.h
--- a/include/scene.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/scene.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * scene.h: classes for objects in scene
+/**
+ * @file  scene.h
+ * @brief Classes for objects in scene (other than shapes).
  *
  * This file is part of Pyrit Ray Tracer.
  *
@@ -36,12 +37,13 @@
 #include "quaternion.h"
 
 /**
- * ray
+ * A ray
  */
 class Ray
 {
 public:
-	Vector o, dir;
+	Vector o;   ///< Origin
+	Vector dir; ///< Normalized direction
 
 	Ray(): o(), dir() {};
 	Ray(const Vector &ao, const Vector &adir):
@@ -50,18 +52,20 @@
 
 #ifndef NO_SIMD
 /**
- * packet of 4 rays
+ * Packet of four rays for SIMD accelerated packet tracing.
  */
 class RayPacket
 {
 public:
-	VectorPacket o, dir, invdir;
+	VectorPacket o;      ///< Packet of four origins
+	VectorPacket dir;    ///< Directions
+	VectorPacket invdir; ///< Inverted directions (1/dir)
 
 	RayPacket(): o(), dir() {};
 	RayPacket(const VectorPacket &ao, const VectorPacket &adir):
 		o(ao), dir(adir), invdir(mOne/adir) {};
 
-	// index operator - get a ray
+	/** Index operator: get ray 'i' */
 	Ray operator[](int i) const
 	{
 		return Ray(
@@ -72,7 +76,7 @@
 #endif
 
 /**
- * a camera
+ * General camera
  */
 class Camera
 {
diff -r 96d65f841791 -r 4c8abb8977dc include/serialize.h
--- a/include/serialize.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/serialize.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * serialize.h: object serialization functions
+/**
+ * @file  serialize.h
+ * @brief Object serialization functions
  *
  * This file is part of Pyrit Ray Tracer.
  *
@@ -33,6 +34,12 @@
 #include "container.h"
 #include "kdtree.h"
 
+/**
+ * Maps pointers to indices
+ *
+ * This helps when we are saving objects from random memory places
+ * to file stream
+ */
 class Indexer
 {
 	map <void *, int> indexmap;
@@ -40,7 +47,16 @@
 public:
 	Indexer(): indexmap(), index(0) {};
 	void reset() { indexmap.clear(); index = 0; };
+
+	/**
+	 * Make new index or return number of already indexed object
+	 * @param[in] o        object for indexation
+	 * @param[out] retidx  returned index
+	 * @retval true        if object was found
+	 * @retval false       if new index was made for the object
+	 */
 	bool get(void *o, int &retidx);
+
 	const int &operator[](void *o) { return indexmap[o]; };
 };
 
diff -r 96d65f841791 -r 4c8abb8977dc include/shapes.h
--- a/include/shapes.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/shapes.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * shapes.h: shape classes
+/**
+ * @file  shapes.h
+ * @brief Shape classes: Box, Sphere, Triangle and helpers
  *
  * This file is part of Pyrit Ray Tracer.
  *
diff -r 96d65f841791 -r 4c8abb8977dc include/simd.h
--- a/include/simd.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/simd.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * simd.h: abstraction of Intel SSE instruction set
+/**
+ * @file  simd.h
+ * @brief Abstraction of Intel SSE instruction set
  *
  * This file is part of Pyrit Ray Tracer.
  *
diff -r 96d65f841791 -r 4c8abb8977dc include/vector.h
--- a/include/vector.h	Tue May 06 09:39:58 2008 +0200
+++ b/include/vector.h	Thu May 08 09:21:25 2008 +0200
@@ -1,5 +1,6 @@
-/*
- * vector.h: Vector class with Colour alias
+/**
+ * @file  vector.h
+ * @brief Vector class with Colour alias
  *
  * This file is part of Pyrit Ray Tracer.
  *
@@ -64,7 +65,7 @@
 
 	bool operator==(const Vector &v) const { return x==v.x && y==v.y && z==v.z; };
 
-	// normalize
+	/** Normalize the vector */
 	Vector normalize()
 	{
 		const Float f = 1.0f / mag();
@@ -72,21 +73,23 @@
 		return *this;
 	};
 
-	// get normalized copy
+	/** Get normalized copy of vector */
 	friend Vector normalize(const Vector &v)
 	{
 		const Float f = 1.0f / v.mag();
 		return v * f;
 	};
 
-	// square magnitude, magnitude
+	/** Square magnitude */
 	Float mag2() const	{ return dot(*this, *this); };
+
+	/** Vector magnitude */
 	Float mag() const	{ return sqrtf(mag2()); };
 
-	// negative
+	/** Get negative vector */
 	Vector operator-() const { return Vector(-x, -y, -z); };
 
-	// accumulate
+	/** Accumulate. Useful for colors. */
 	Vector operator+=(const Vector &v)
 	{
 #ifdef NO_SIMD
@@ -99,7 +102,7 @@
 		return *this;
 	};
 
-	// multiply
+	/** Multiply by scalar */
 	Vector operator*=(const Float &f)
 	{
 		x *= f;
@@ -108,8 +111,7 @@
 		return *this;
 	};
 
-
-	// cut
+	/** Cut with scalar */
 	Vector operator/=(const Float &f)
 	{
 		Float finv = 1.0f / f;
@@ -119,7 +121,7 @@
 		return *this;
 	};
 
-	// sum
+	/** Sum of two vectors */
 	friend Vector operator+(const Vector &a, const Vector &b)
 	{
 #ifdef NO_SIMD
@@ -129,7 +131,7 @@
 #endif
 	};
 
-	// difference
+	/** Difference of two vectors */
 	friend Vector operator-(const Vector &a, const Vector &b)
 	{
 #if defined(NO_SIMD) || defined(MSVC)
@@ -140,13 +142,13 @@
 #endif
 	};
 
-	// dot product
+	/** Dot product */
 	friend Float dot(const Vector &a, const Vector &b)
 	{
 		return a.x * b.x + a.y * b.y + a.z * b.z;
 	};
 
-	// cross product
+	/** Cross product */
 	friend Vector cross(const Vector &a, const Vector &b)
 	{
 		return Vector(a.y * b.z - a.z * b.y,
@@ -154,24 +156,26 @@
 			a.x * b.y - a.y * b.x);
 	};
 
-	// product of vector and scalar
+	/** Get vector multiplied by scalar */
 	friend Vector operator*(const Vector &v, const Float &f)
 	{
 		return Vector(f * v.x, f * v.y, f * v.z);
 	};
 
+	/** Get vector multiplied by scalar */
 	friend Vector operator*(const Float &f, const Vector &v)
 	{
 		return v * f;
 	};
 
-	// scalar division
+	/** Get vector divided by scalar */
 	friend Vector operator/(const Vector &v, const Float &f)
 	{
 		const Float finv = 1.0f / f;
 		return Vector(v.x * finv, v.y * finv, v.z * finv);
 	};
 
+	/** Get f/v, i.e. inverted vector multiplied by scalar */
 	friend Vector operator/(const Float &f, const Vector &v)
 	{
 #ifdef NO_SIMD
@@ -181,20 +185,20 @@
 #endif
 	};
 
-	// vector plus scalar
+	/** Add scalar to the vector */
 	friend Vector operator+(const Vector &v, const Float &f)
 	{
 		return Vector(v.x + f, v.y + f, v.z + f);
 	};
 
-	// vector minus scalar
+	/** Subtract scalar from the vector */
 	friend Vector operator-(const Vector &v, const Float &f)
 	{
 		return Vector(v.x - f, v.y - f, v.z - f);
 	};
 
-	// cell by cell product (only usable for colours)
-	friend Vector operator*(const Vector &a,  const Vector &b)
+	/** Cell by cell product (only useful for colors) */
+	friend Vector operator*(const Vector &a, const Vector &b)
 	{
 #ifdef NO_SIMD
 		return Vector(a.x * b.x, a.y * b.y, a.z * b.z);
@@ -203,13 +207,13 @@
 #endif
 	};
 
-	// write
+	/** Write textual representation of the vector to stream */
 	friend ostream & operator<<(ostream &st, const Vector &v)
 	{
 		return st << "(" << v.x << "," << v.y  << "," << v.z << ")";
 	};
 
-	// read
+	/** Read the vector from stream */
 	friend istream & operator>>(istream &st, Vector &v)
 	{
 		char s[10];
@@ -224,9 +228,13 @@
 	};
 };
 
+/** Colour is a alias name of Vector. */
 typedef Vector Colour;
 
 #ifndef NO_SIMD
+/**
+  * Packet of four Vectors
+  */
 class VectorPacket
 {
 public:
diff -r 96d65f841791 -r 4c8abb8977dc src/sampler.cc
--- a/src/sampler.cc	Tue May 06 09:39:58 2008 +0200
+++ b/src/sampler.cc	Thu May 08 09:21:25 2008 +0200
@@ -303,7 +303,7 @@
 	return true;
 }
 
-void DefaultSampler::saveSample(Sample &samp, Colour &col)
+void DefaultSampler::saveSample(const Sample &samp, const Colour &col)
 {
 	Float *buf = pixmap.getFloatData()
 		+ 3*(samp.sy * pixmap.getWidth() + samp.sx);