Merge pull request #43 from jberlin/master

update documentation, add missing functions saturate() and swatch()

Author: jberlin

README

@@ -21,23 +21,25 @@ Getting started
 ---------------
 Examining the demo applications in src/demo is a great way to see
 some usage examples of the library. The basic strategy is to subclass
-the SeExpression class and implement the methods that describe what
+the Expression class and implement the methods that describe what
 extra functions and variables your expression evaluation will need
 
-Be sure to check out the doxygen pages for an API overview.
-
+Be sure to check out the doxygen pages for an API overview:
+http://wdas.github.io/SeExpr/doxygen/
 
 Source code overview
 ====================
 
 src/
    SeExpr/   Library code
+   ui/       User Interface components for editing
    demos/    Demo Applications
    tests/    Regression Tests
    doc/      Doxygen generation
 
 SeExpr Developers
 =================
+Janet Berlin
 Brent Burley
 Lawrence Chai
 Andrew Selle

TODO.txt

@@ -386,6 +386,25 @@ static const char* hsltorgb_docstring =
     "hsl value (except for negative s values), the conversion is\n"
     "well-defined and reversible.";
 
+static Vec3d saturate(const Vec3d& Cin, double amt) {
+    const Vec3d lum(.2126,.7152,.0722); // rec709 luminance
+    Vec3d result = Vec3d(Cin.dot(lum) * (1-amt)) + Cin * amt;
+    if (result[0] < 0) result[0] = 0;
+    if (result[1] < 0) result[1] = 0;
+    if (result[2] < 0) result[2] = 0;
+    return result;
+}
+
+Vec3d saturate(int n, const Vec3d* args) {
+    if (n < 2) return 0.0;
+    return saturate(args[0], args[1][0]);
+}
+static const char* saturate_docstring =
+    "color saturate(color val, float amt)\n"
+    "Scale saturation of color by amt.\n"
+    "The color is scaled around the rec709 luminance value,\n"
+    "and negative results are clamped at zero.\n";
+
 double hash(int n, double* args) {
     // combine args into a single seed
     uint32_t seed = 0;
@@ -729,7 +748,9 @@ static const char* ccellnoise_docstring =
 double pnoise(const Vec3d& p, const Vec3d& period) {
     double result;
     double args[3] = {p[0], p[1], p[2]};
-    int pargs[3] = {(int)period[0], (int)period[1], (int)period[2]};
+    int pargs[3] = {max(1,(int)period[0]),
+                    max(1,(int)period[1]),
+                    max(1,(int)period[2])};
     PNoise<3, 1>(args, pargs, &result);
     return result;
 }
@@ -1177,6 +1198,13 @@ static const char* pick_docstring =
     "to the supplied weights.&nbsp; Any weights not supplied are assumed to\n"
     "be 1.0.";
 
+double swatch(int n, double* params) {
+        return choose(n, params);
+    }
+static const char *swatch_docstring=
+    "color swatch(float index, color choice0, color choice1, color choice2, [...])\n"
+    "Chooses one of the supplied color choices based on the index (assumed to be in range [0..1]).";
+
 double choose(int n, double* params) {
     if (n < 3) return 0;
     double key = params[0];
@@ -1644,6 +1672,7 @@ void defineBuiltins(ExprFunc::Define define, ExprFunc::Define3 define3) {
     FUNCNDOC(midhsi, 5, 7);
     FUNCDOC(hsltorgb);
     FUNCDOC(rgbtohsl);
+    FUNCNDOC(saturate, 2, 2);
 
     // noise
     FUNCNDOC(hash, 1, -1);
@@ -1684,6 +1713,7 @@ void defineBuiltins(ExprFunc::Define define, ExprFunc::Define3 define3) {
     FUNCNDOC(pick, 3, -1);
     FUNCNDOC(choose, 3, -1);
     FUNCNDOC(wchoose, 4, -1);
+    FUNCNDOC(swatch, 3, -1);
     FUNCNDOC(spline, 5, -1);
 
     // FuncX interface

src/SeExpr/ExprBuiltins.cpp

@@ -12,5 +12,5 @@ Licensor and its affiliates, except as required for reproducing
 the content of the NOTICE file.
 
 You may obtain a copy of the License at
-http://www.apache.org/licenses/LICENSE-2.0
 </pre>
+<a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>

src/SeExpr/generated/README

@@ -22,25 +22,26 @@
  *  - \subpage plugins -  Custom Function Plugins
  * \section demos Demo Applications
  *     - \subpage mytut (code at asciiGraph.cpp)
- *     - \subpage uitut (code starting at imageEditor.cpp)
- *     - Image Synthesizer  (code at imageSynth.cpp)
- *     - SeGrapher Qt Grapher (code starting at segraph.cpp)
- *     - Renderman Shadeop (code at seop.cpp)
+ *     - \subpage uitut (code at imageEditor.cpp)
+ *     - Image Synthesizer  (at imageSynth.cpp)
+ *     - SeGrapher Qt Grapher (at demos/segraph)
+ *     - Renderman Shadeop (at demos/rman)
+ *     - \subpage varblocks
  * \section mainapi Main API pages
- *  - SeExpression - Main class to parse a single expression
- *  - SeExprVarRef - Binding of an external variable to an expression context.
- *  - SeExprFunc - Define a custom function that calls C++ code
- *  - SeExprFuncX - Manual argument parsing C++ code
- *  - SeExprFuncNode - Node that calls a function (needed for SeExprFuncX arg parsing)
+ *  - Expression - Main class to parse a single expression
+ *  - ExprVarRef - Binding of an external variable to an expression context.
+ *  - ExprFunc - Define a custom function that calls C++ code
+ *  - ExprFuncX - Manual argument parsing C++ code
+ *  - ExprFuncNode - Node that calls a function (needed for SeExprFuncX arg parsing)
  * \section useful Useful classes and functions
- *  - SeVec3d - Class to hold and manipulate 3-vectors
- *  - SeExprBuiltins.h - Useful builtin functions that are also available in C++
- *  - SeExpr::SeCurve - Hermite interpolation curve.
+ *  - Vec - Class to hold and manipulate n-dimensional vectors
+ *  - ExprBuiltins.h - Useful builtin functions that are also available in C++
+ *  - SeExpr2::Curve - Hermite interpolation curve.
  *
  * \section internals Internals
- *  - SeExprNode - Parse Tree Node
- *  - SeExprParser.h - Entry point to bison/flex parser
- * 
+ *  - ExprNode - Parse Tree Node
+ *  - ExprParser - Entry point to bison/flex parser
+ *
  * \section Other
  *  - \subpage license
  */
@@ -50,10 +51,14 @@
 \htmlinclude tutorial.txt
 */
 /**
-\page uitut Simple Image Editor UI Tutorial
+\page uitut Image Editor Tutorial
 \htmlinclude uitutorial.txt
 */
 /**
+\page varblocks Using Variable Blocks
+\htmlinclude varblocks.txt
+*/
+/**
 \page userdoc User Documentation
 \htmlinclude userdoc.txt
 */