From 6547b1e7707c975ac68f7e4833836af146fce71c Mon Sep 17 00:00:00 2001
From: Jeroen Bakker <j.bakker@atmind.nl>
Date: Fri, 17 Aug 2012 12:53:04 +0000
Subject: Documentation of the Bokeh image operation :)

---
 .../operations/COM_BokehImageOperation.h           | 91 +++++++++++++++++++++-
 1 file changed, 87 insertions(+), 4 deletions(-)

(limited to 'source/blender/compositor')

diff --git a/source/blender/compositor/operations/COM_BokehImageOperation.h b/source/blender/compositor/operations/COM_BokehImageOperation.h
index fe86e162eb2..44c4c0cfe27 100644
--- a/source/blender/compositor/operations/COM_BokehImageOperation.h
+++ b/source/blender/compositor/operations/COM_BokehImageOperation.h
@@ -24,42 +24,125 @@
 #define _COM_BokehImageOperation_h
 #include "COM_NodeOperation.h"
 
-
+/**
+ * @brief The BokehImageOperation class is an operation that creates an image useful to mimic the internals
+ *of a camera.
+ *
+ * features:
+ *  - number of flaps
+ *  - angle offset of the flaps
+ *  - rounding of the flaps (also used to make a circular lens)
+ *  - simulate catadioptric
+ *  - simulate lensshift
+ *
+ * Per pixel the algorithm determines the edge of the bokeh on the same line as the center of the image and the pixel
+ * is evaluating.
+ *
+ * The edge is detected by finding the closest point on the direct line between the two nearest flap-corners.
+ * this edge is interpolated with a full circle. 
+ * Result of this edge detection is stored as the distance between the center of the image and the edge.
+ *
+ * catadioptric lenses are simulated to interpolate between the center of the image and the distance of the edge.
+ * We now have three distances:
+ *  - distance between the center of the image and the pixel to be evaluated
+ *  - distance between the center of the image and the outer-edge
+ *  - distance between the center of the image and the inner-edge
+ *
+ * With a simple compare it can be detected if the evaluated pixel is between the outer and inner edge.
+ */
 class BokehImageOperation : public NodeOperation {
 private:
+	/**
+	 * @brief Settings of the bokeh image
+	 */
 	NodeBokehImage *m_data;
 
+	/**
+	 * @brief precalced center of the image
+	 */
 	float m_center[2];
+	
+	/**
+	 * @brief 1.0-rounding
+	 */
 	float m_inverseRounding;
+	
+	/**
+	 * @brief distance of a full circle lens
+	 */
 	float m_circularDistance;
+	
+	/**
+	 * @brief radius when the first flap starts
+	 */
 	float m_flapRad;
+	
+	/**
+	 * @brief radians of a single flap
+	 */
 	float m_flapRadAdd;
 	
+	/**
+	 * @brief should the m_data field by deleted when this operation is finished
+	 */
 	bool m_deleteData;
 
+	/**
+	 * @brief detemine the coordinate of a flap cornder
+	 *
+	 * @param r result in bokehimage space are stored [x,y]
+	 * @param flapNumber the flap number to calculate
+	 * @param distance the lens distance is used to simulate lens shifts
+	 */
 	void detemineStartPointOfFlap(float r[2], int flapNumber, float distance);
+	
+	/**
+	 * @brief Determine if a coordinate is inside the bokeh image
+	 *
+	 * @param distance the distance that will be used. This parameter is modified a bit to mimic lens shifts
+	 * @param x the x coordinate of the pixel to evaluate
+	 * @param y the y coordinate of the pixel to evaluate
+	 * @return float range 0..1 0 is completely outside
+	 */
 	float isInsideBokeh(float distance, float x, float y);
 public:
 	BokehImageOperation();
 
 	/**
-	 * the inner loop of this program
+	 * @brief the inner loop of this program
 	 */
 	void executePixel(float output[4], float x, float y, PixelSampler sampler);
 	
 	/**
-	 * Initialize the execution
+	 * @brief Initialize the execution
 	 */
 	void initExecution();
 	
 	/**
-	 * Deinitialize the execution
+	 * @brief Deinitialize the execution
 	 */
 	void deinitExecution();
 	
+	/**
+	 * @brief determine the resolution of this operation. currently fixed at [COM_BLUR_BOKEH_PIXELS, COM_BLUR_BOKEH_PIXELS]
+	 * @param resolution
+	 * @param preferredResolution
+	 */
 	void determineResolution(unsigned int resolution[2], unsigned int preferredResolution[2]);
 
+	/**
+	 * @brief set the node data
+	 * @param data
+	 */
 	void setData(NodeBokehImage *data) { this->m_data = data; }
+	
+	/**
+	 * @brief deleteDataOnFinish
+	 *
+	 * There are cases that the compositor uses this operation on its own (see defocus node)
+	 * the deleteDataOnFinish must only be called when the data has been created by the compositor.
+	 *It should not be called when the data has been created by the node-editor/user.
+	 */
 	void deleteDataOnFinish() { this->m_deleteData = true; }
 };
 #endif
-- 
cgit v1.2.3